CSS Output & Performance
CSS Architecture
Organize tokens, base rules, components, utilities, and exceptions so a stylesheet remains easy to change. The chapter organizes tokens, base rules, components, utilities, variants, layers, selector weight, and the maintenance of exceptions.
CSS architecture is the set of boundaries and conventions that lets a team predict where a rule belongs, how it may be overridden, and when it can be removed.
A stylesheet becomes difficult to maintain when every rule can affect every page and no one knows which selector has authority. Layers can define category priority, semantic custom properties can centralize design decisions, and explicit component variants can replace page-specific overrides. The conventions matter only if the team follows and reviews them. This topic also connects with Cascade Layers and CSS Variables.
Choose stable boundaries
A maintainable stylesheet separates global foundations from local components. Names should describe roles and variants rather than the current color or page location.
Example
css
@layer reset, tokens, base, components, utilities;
@layer tokens {
:root {
--color-action: #0369a1;
--space-2: 0.5rem;
--space-4: 1rem;
}
}
@layer components {
.button { /* component contract */ }
.button--danger { /* explicit variant */ }
}Rules for a healthy codebase
- Keep selectors shallow and specificity intentionally low.
- Co-locate component states and responsive rules.
- Use custom properties for meaningful design decisions, not every literal.
- Document escape hatches and delete expired exceptions.
- Lint syntax and property mistakes in continuous integration.
- Track unused styles instead of assuming a class is safe to remove.
Stylesheet Layers
| Layer | Responsibility | Example |
|---|---|---|
| Tokens | Shared design decisions. | --color-accent, --space-3 |
| Base | Element defaults and document-wide behavior. | body, button, a |
| Components | Named interface patterns. | .card, .site-nav |
| Utilities | Small single-purpose overrides. | .visually-hidden |
Complete Example
Run the complete document below in the Try It editor. Resize the preview or interact with the controls where the example calls for it.
Complete runnable example
html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>CSS Architecture example</title>
<style>
* { box-sizing: border-box; }
body {
margin: 0;
padding: 2rem;
font-family: system-ui, sans-serif;
line-height: 1.5;
}
main { max-width: 70rem; margin-inline: auto; }
article, section, aside, form, .card, .panel {
padding: 1rem;
border: 1px solid #cbd5e1;
border-radius: 0.6rem;
}
@layer reset, tokens, base, components, utilities;
@layer tokens {
:root {
--color-action: #0369a1;
--space-2: 0.5rem;
--space-4: 1rem;
}
}
@layer components {
.button { /* component contract */ }
.button--danger { /* explicit variant */ }
}
</style>
</head>
<body>
<main><h1>Layered component styles</h1><button class="button">Default button</button><button class="button button--danger">Danger variant</button></main>
</body>
</html>Browser Support
Feature | Chrome | Edge | Firefox | Safari |
|---|---|---|---|---|
| Custom properties | 49 | 15 | 31 | 9.1 |
| Cascade layers | 99 | 99 | 97 | 15.4 |
Versions show the first stable desktop release with unprefixed support. Data source: MDN Browser Compatibility Data 8.0.8. A partial-support note is included where it changes how the example behaves.
Notes
- BEM, utility classes, CSS Modules, and scoped component styles are tools. Pick conventions that match the team and enforce them consistently.
- Test the example with real content, keyboard input, browser zoom, and the narrowest layout your project supports.
- Use a fallback when the support table shows that one of your required browsers predates the feature.
Conclusion
A small number of enforced boundaries matters more than adopting a fashionable naming system.
Choose the smallest architecture that solves the codebase’s real coordination problems. Record ownership, naming, layer order, and escape hatches close to the code. Periodically remove unused utilities and expired overrides so the system describes the current product rather than its history.