Skip to main content
HTML5ANDCSS3 logoHTML5ANDCSS3Tools and Tutorials

CSS Output & Performance

CSS Architecture

Written by Published

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

LayerResponsibilityExample
TokensShared design decisions.--color-accent, --space-3
BaseElement defaults and document-wide behavior.body, button, a
ComponentsNamed interface patterns..card, .site-nav
UtilitiesSmall 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 properties4915319.1
Cascade layers99999715.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.

PreviousCSS PerformanceNextDebugging CSS