{"id":"l-css-4-4","courseId":"css-mastery","lang":"en","kind":"lesson","summary":"Organise a growing stylesheet with cascade layers, token tiers, single-class components and a small set of utilities, so a team can change CSS without fear.","html":"

Waypoint’s front end started with one developer and one styles.css. Two years later there are five developers, forty components, a sponsor microsite that reskins the schedule, and a stylesheet nobody dares to delete from. Every bug fix is a new override, every override is a little heavier than the last, and the !important count only goes up.

\n

That’s not a discipline problem. It’s an architecture problem, and everything in this course so far gives you the pieces to fix it.

\n

The layer stack is the architecture

\n

Start the entry stylesheet with one statement that names every kind of CSS you have, in priority order:

\n
main.css
@layer reset, tokens, base, layouts, components, utilities;\n\n@import url(\"reset.css\") layer(reset);\n@import url(\"tokens.css\") layer(tokens);\n@import url(\"base.css\") layer(base);\n@import url(\"layouts/schedule.css\") layer(layouts);\n@import url(\"components/session-card.css\") layer(components);\n@import url(\"components/speaker.css\") layer(components);\n@import url(\"utilities.css\") layer(utilities);
\n

Each layer has one job:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
LayerContainsExample
resetNormalising browser defaults*, *::before { box-sizing: border-box; }
tokensCustom properties only--color-brand, --space-m
baseBare element styles, low specificity:where(a) { color: var(--link); }
layoutsPage and region structure.schedule { display: grid; gap: … }
componentsOne block per component.session-card { … }
utilitiesSingle-purpose overrides.u-hidden, .u-visually-hidden

Because layers decide conflicts between kinds, selectors within each layer can stay flat: one class for a component, :where() for base styles. Nobody needs an ID or a three-class chain to win, so nobody writes one.

\n
\n Three token tiers connected by arrows: palette values such as violet 600 feed semantic tokens such as color brand, which feed component tokens such as card accent. A sponsor wrapper overrides card accent. Beside them, the layer stack from reset to utilities.\n \n --violet-600\n \n \n --color-brand\n \n \n --card-accent\n \n .theme-sponsor\n \n Layer order\n 1 reset\n 2 tokens\n 3 base\n 4 layouts\n 5 components\n 6 utilities\n later wins\n
Tokens flow from raw values to roles to components; layers decide which kind of rule wins
\n

Tokens in three tiers

\n

A flat list of 200 custom properties is as hard to maintain as 200 hex codes. Tier them:

\n
    \n
  1. Palette: raw values, named by what they are. --violet-600: oklch(52% 0.22 290);
    2. \n
  2. Semantic: roles, named by what they’re for. --color-brand: var(--violet-600); --surface: light-dark(…);
    3. \n
  3. Component: a component’s public dials, defaulting to semantic tokens. --card-accent: var(--color-brand);
    4. \n
\n

Keep tier 1 small and boring: a dozen hues with a handful of steps each covers most products. The interesting decisions happen in tier 2, where a designer and a developer agree on what “brand”, “surface” or “danger” means in each theme.

\n

Components only read tiers 2 and 3. Then a rebrand changes tier 1, dark mode changes tier 2, and a sponsor page changes tier 3 on a wrapper:

\n
CSS
@layer tokens {\n  :root {\n    --color-brand: oklch(52% 0.22 290);\n    --card-accent: var(--color-brand);\n  }\n  .theme-sponsor {\n    --card-accent: oklch(55% 0.11 210);\n  }\n}
\n

Every card inside .theme-sponsor turns teal: border, badge, hover state, all of it, because they all read --card-accent.

\n

Component rules

\n

A handful of conventions keeps forty components predictable:

\n\n\n

Utilities: few and final

\n

Utilities are single-purpose classes the HTML can apply directly: .u-hidden, .u-visually-hidden, .u-flow (vertical rhythm). Put them in the last layer and they win over any component without !important. Keep the set small and boring. If you find yourself writing .u-mt-17, you’re building a second styling language inside the first; a design-token-driven utility framework is a valid choice, but make it a deliberate one, not drift.

\n

Scoping with @scope

\n

When a component must not leak styles into nested content, such as a CMS-rendered abstract inside a card, @scope limits rules to a subtree and can stop at an inner boundary:

\n
CSS
@scope (.session-card) to (.cms-content) {\n  p { margin-block: 0.5rem; }\n}
\n

The paragraph rule applies inside cards but not inside .cms-content. @scope became Baseline in March 2026, so it’s a recent tool; layers and single-class components already solve most scoping problems, and @scope handles the remaining “donut” cases.

\n\n

Your turn

\n

The exercise is a small slice of the old stylesheet: ID selectors, !important, a component with its own margin. Refactor it into layers with a token for the card accent, a sponsor theme, layout-owned spacing and a utility that wins cleanly. The final lesson looks at what all this CSS costs the browser, and how to keep animations and layouts fast.

\n","toc":[{"id":"sec-1","text":"The layer stack is the architecture","level":2},{"id":"sec-2","text":"Tokens in three tiers","level":2},{"id":"sec-3","text":"Component rules","level":2},{"id":"sec-4","text":"Utilities: few and final","level":2},{"id":"sec-5","text":"Scoping with @scope","level":2},{"id":"sec-6","text":"Your turn","level":2}],"takeaways":["A layer order such as reset, tokens, base, layouts, components, utilities decides conflicts between kinds of CSS, so selectors can stay at one class.","Tokens work best in tiers: raw palette values, semantic roles like --color-brand, and component-level properties like --card-accent that a parent can override.","Components should not set their own outer margins; the layout around them owns the spacing, usually with gap.","Keep utilities few and single-purpose, in the last layer, so they win without !important."],"further":[{"title":"Cascade layers (MDN guide)","url":"https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers"},{"title":"@scope (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@scope"},{"title":"Organizing your CSS (MDN)","url":"https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Organizing"}],"quiz":[{"q":"

A sponsor page needs every session card’s accent in teal instead of violet. In a token-based architecture, what’s the right change?

","options":[{"text":"Add .sponsor-page .session-card { border-color: teal !important; }.","why":"That overrides one property with brute force; the badge, hover state and anything else using the accent stay violet."},{"text":"Copy the card’s CSS into a .session-card--sponsor variant with teal values.","why":"Duplicated component CSS drifts the first time someone edits the original."},{"text":"Set --card-accent: teal on the sponsor page’s wrapper.","why":"Correct. The card reads --card-accent everywhere it uses the accent, and custom properties inherit, so one declaration re-themes every part of every card inside."}],"answer":2},{"q":"

Why shouldn’t .session-card set margin-bottom: 16px on itself?

","options":[{"text":"Because margins don’t work on grid items.","why":"Margins work on grid items; the problem is who decides the spacing."},{"text":"Because spacing depends on where the card is placed, so the layout around it should own it, for example with gap.","why":"Correct. The same card sits in a grid, a sidebar and a carousel; each context needs different spacing, and a built-in margin fights all of them."},{"text":"Because margins are slower to render than gap.","why":"There’s no meaningful performance difference; this is about ownership and reuse."},{"text":"Because logical properties should be used instead.","why":"margin-block-end would have the same problem; the issue is the component spacing itself, not the property name."}],"answer":1},{"q":"

Where should a .u-hidden { display: none; } utility live so it always beats component display rules without !important?

","options":[{"text":"In the last declared layer, such as utilities.","why":"Correct. Later layers win for normal declarations, whatever the specificity of the component selector."},{"text":"In the reset layer, so it applies early.","why":"Early layers lose to later ones; any component setting display would override it."},{"text":"Unlayered, at the top of the stylesheet.","why":"Unlayered styles do beat every layer, but leaving rules unlayered on purpose makes the order invisible and invites more unlayered patches."}],"answer":0}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"
\n
\n
\n

Sponsor Talk: Shipping at Scale

\n Draft\n
\n
\n
\n

CSS Architecture at Scale

\n Platform\n
\n
","css":"h3 { margin: 0 0 8px; }\n\n#schedule .session-card {\n padding: 12px;\n margin-bottom: 16px;\n border-left: 6px solid #6d28d9;\n border-radius: 10px;\n background: #f8fafc;\n}\n#schedule .session-card .badge {\n display: inline-block;\n padding: 0.1em 0.6em;\n border-radius: 999px;\n background: #ede9fe;\n}\n.theme-sponsor .session-card {\n border-left-color: #0e7490 !important;\n}\n.u-hidden { display: none !important; }\n"},"solution":{"html":"
\n
\n
\n

Sponsor Talk: Shipping at Scale

\n Draft\n
\n
\n
\n

CSS Architecture at Scale

\n Platform\n
\n
","css":"@layer reset, tokens, layouts, components, utilities;\n\n@layer reset {\n h3 { margin: 0 0 8px; }\n}\n\n@layer tokens {\n :root {\n --color-brand: #6d28d9;\n --card-accent: var(--color-brand);\n }\n .theme-sponsor {\n --card-accent: #0e7490;\n }\n}\n\n@layer layouts {\n .schedule {\n display: grid;\n gap: 16px;\n }\n}\n\n@layer components {\n .session-card {\n padding: 12px;\n border-inline-start: 6px solid var(--card-accent);\n border-radius: 10px;\n background: #f8fafc;\n\n .badge {\n display: inline-block;\n padding: 0.1em 0.6em;\n border-radius: 999px;\n background: #ede9fe;\n }\n }\n}\n\n@layer utilities {\n .u-hidden { display: none; }\n}\n"},"checks":[{"id":"layer-order","test":"const all = []; const walk = (rules) => { for (const r of rules) { all.push(r); if (r.cssRules) walk(r.cssRules); } }; for (const s of document.styleSheets) walk(s.cssRules); const stmt = all.find((r) => r instanceof CSSLayerStatementRule); if (!stmt) return false; const names = [...stmt.nameList]; const want = ['reset', 'tokens', 'components', 'utilities']; const idx = want.map((n) => names.indexOf(n)); return idx.every((i) => i >= 0) && idx.every((v, i) => i === 0 || v > idx[i - 1]);"},{"id":"no-ids-or-important","test":"const all = []; const walk = (rules) => { for (const r of rules) { all.push(r); if (r.cssRules) walk(r.cssRules); } }; for (const s of document.styleSheets) walk(s.cssRules); const src = [...document.querySelectorAll('style')].map((s) => s.textContent).join(''); return !src.includes('!important') && !all.some((r) => r.selectorText && r.selectorText.includes('#'));"},{"id":"accent-token","test":"return style('#regular', 'border-left-color') === 'rgb(109, 40, 217)' && style('#regular', '--card-accent').trim() !== '';"},{"id":"sponsor-theme","test":"return style('#sponsored', 'border-left-color') === 'rgb(14, 116, 144)' && style('.theme-sponsor', '--card-accent').trim() !== '';"},{"id":"token-drives-card","test":"const w = $('.theme-sponsor'); w.style.setProperty('--card-accent', 'rgb(1, 2, 3)'); await tick(16); const c = style('#sponsored', 'border-left-color'); w.style.removeProperty('--card-accent'); await tick(16); return c === 'rgb(1, 2, 3)';"},{"id":"utility-wins","test":"return style('#sponsored .badge', 'display') === 'none' && style('#regular .badge', 'display') === 'inline-block';"},{"id":"layout-owns-spacing","test":"const a = $('#sponsored').getBoundingClientRect(); const b = $('#regular').getBoundingClientRect(); return parseFloat(style('#regular', 'margin-bottom')) === 0 && parseFloat(style('#sponsored', 'margin-bottom')) === 0 && Math.abs(b.top - a.bottom - 16) < 1;"}],"title":"Refactor the card into an architecture","prompt":"

Refactor this slice of the old stylesheet. Keep the HTML as it is.

\n
    \n
  1. Declare layers including reset, tokens, components, utilities in that order (you may add layouts or others in between), and put every rule in a layer.
    2. \n
  2. No ID selectors and no !important anywhere.
    3. \n
  3. The card’s accent border reads a --card-accent token that defaults to #6d28d9; .theme-sponsor sets it to #0e7490.
    4. \n
  4. .u-hidden still hides the Draft badge.
    5. \n
  5. Cards have no margins of their own; the .schedule layout puts 16px between them.
    6. \n
\n","hints":["Start with the layer statement, then move each existing rule into the layer that matches its job.","Tokens: :root { --card-accent: #6d28d9; } and .theme-sponsor { --card-accent: #0e7490; }. The card uses border-inline-start: 6px solid var(--card-accent);.","Spacing: delete the card’s margin and give .schedule display: grid; gap: 16px;. Put .u-hidden in the utilities layer, without !important."],"explanation":"

The layer statement moves conflict resolution out of selectors: .u-hidden in the last layer beats the component’s display: inline-block with plain (0,1,0) specificity, so neither IDs nor !important are needed. The card reads --card-accent instead of a hard-coded color, so .theme-sponsor re-themes every card inside it with one custom property, and any future part of the card that uses the accent follows automatically. Moving spacing to .schedule { gap: 16px; } lets the same card drop into a sidebar or carousel without fighting a built-in margin.

\n","checkLabels":{"layer-order":"Layers reset, tokens, components, utilities are declared in order","no-ids-or-important":"No ID selectors and no !important","accent-token":"Regular cards use the violet --card-accent token","sponsor-theme":"Sponsor cards are teal through the token","token-drives-card":"Changing --card-accent re-themes the card","utility-wins":"The u-hidden utility still hides the Draft badge","layout-owns-spacing":"Cards have no margins; the layout spaces them 16px apart"}},"words":711,"readMinutes":3}