CSS architecture for grown-ups

Tokens are the API

Every color, spacing, radius, font-size, z-index lives in a token; components consume tokens, never literals:

:root {
  --space-1: 4px; --space-2: 8px; --space-4: 16px;
  --color-bg: #fff; --color-fg: #111;
  --z-modal: 100; --z-toast: 200;
}
[data-theme='dark'] {
  --color-bg: #0b0d10; --color-fg: #e7ebf0;
}

• New visual tweak = new/changed token, reviewed like API. Hardcoded hex in components is a review blocker.
• Z-index is a token ladder (dropdown < sticky < modal < toast) — never z-index: 9999.

Layers to win specificity wars

@layer reset, tokens, base, components, utilities;

Third-party styles import into base; utilities win without !important; components stay mid-cascade. This one line ends most "why isn't my style applying" archaeology.

Scope by component, not by page

• One class per element (.card__title or co-located module class). Descendant selectors 4+ deep are a smell.
• Global element selectors only in reset/base. Anything else belongs to a component file.

Responsive: container over viewport when it's a component

Media queries for layout; container queries for reusable components that must adapt to where they're placed:

.card-wrap { container-type: inline-size; }
@container (min-width: 480px) {
  .card { display: flex; }
}

Dark mode without drift

• Tokens carry the theme (above). Components never branch on theme.
• Support prefers-color-scheme and manual override via data-theme; persist the choice.
• Test shadows/borders in dark mode — the classic broken spots.

Utilities vs components

• Utilities (flex, mt-2) for layout glue and one-offs.
• Component classes for anything reused with meaning (.btn, .card).
• If you repeat a utility combo 3+ times, promote it to a component class.

Motion

• Transitions on transform/opacity only (compositor-friendly).
• Wrap decorative animation in @media (prefers-reduced-motion: no-preference).

Definition of done (agent checklist)

• No raw hex/px outside token files
• Cascade layers declared; utilities import into their layer
• Every interactive state has hover and focus-visible styles
• Dark mode verified on the touched surfaces
• No !important outside layers rationale
• Container queries for component-local responsiveness