CSS Architecture

Design scalable, maintainable CSS systems using modern cascade control, design tokens, and component-scoped styles.

Guiding Principle

"CSS architecture is not about preventing specificity wars — it's about designing a cascade that makes the right style always win without fighting."

---

Procedure

Step 1 — Audit Existing Styles [HECHO / INFERENCIA]

1. Run grep -r "@import\|@use\|require.*css\|import.*\.css" src/ to map all CSS entry points.
2. Identify CSS methodology in use: BEM, SMACSS, utility-first, or none.
3. Detect specificity hotspots: grep -r "!important" src/ --include="*.css" -l.
4. Check for existing design tokens: look for CSS custom properties in :root blocks.
5. Catalog responsive breakpoints: grep -r "@media" src/ --include="*.css" | grep -oP '\d+px' | sort -u.
6. Tag findings: [HECHO] for code evidence, [INFERENCIA] for patterns inferred from structure.

Step 2 — Design Token System

1. Primitives layer — Raw values: --color-blue-500: #3b82f6, --space-4: 1rem.
2. Semantic layer — Mapped meaning: --color-brand-primary: var(--color-blue-500).
3. Component layer — Component-local: --button-bg: var(--color-brand-primary).
4. Define token categories: color, spacing, typography, radius, shadow, motion, z-index.
5. Choose token format: CSS custom properties (universal) vs. JSON (multi-platform).
6. Document token taxonomy in tokens/README.md.

Decision: Token Format

Step 3 — Define CSS Layer Strategy

1. Declare all layers upfront in one @layer statement to establish order.
2. Layer order (lowest to highest priority):

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

3. Map existing stylesheets to layers.
4. Move all third-party CSS into reset or base layer to neutralize specificity.
5. Ensure utilities layer sits above components — utility classes should always win.

Step 4 — Component Scoping Strategy

1. Choose scoping approach per component type:
   • CSS Modules: React/Vue components — zero leakage, build-time hashed classes.
   • @scope: Native CSS scoping for web components and framework-agnostic code.
   • Shadow DOM: Complete isolation for custom elements / design system primitives.
   • BEM in layers: Legacy codebases — combine BEM naming with @layer components.
2. For design systems, define scope boundaries explicitly using @scope (.component-root).
3. Document which components use which scoping strategy.

Step 5 — Responsive Architecture

1. Define breakpoint scale and name semantically (sm, md, lg, xl, 2xl).
2. Use container queries for component-level responsiveness (not viewport-level).
3. Use viewport media queries only for layout-level changes (grid columns, sidebar).
4. Implement fluid typography with clamp() to reduce breakpoint-specific overrides.
5. Test with @container on key components before committing to approach.

Step 6 — Dark Mode Strategy

1. CSS Custom Properties approach (recommended):
   • Define semantic tokens with light values, override in [data-theme="dark"] or @media (prefers-color-scheme: dark).
   • Single source of truth: update the token, all components update.
2. Avoid duplicating component styles for dark mode — only token values should change.
3. Add color-scheme: light dark to :root for native form element theming.
4. Test: automated (Playwright prefers-color-scheme), visual regression, manual QA.

Step 7 — Tailwind v4 Configuration (if applicable)

1. Use @theme directive to define design tokens inside CSS (replaces tailwind.config.js).
2. Map custom tokens to Tailwind utilities via --color-*, --spacing-* conventions.
3. Use @utility for one-off custom utilities not worth tokenizing.
4. Use @layer components for multi-property component classes.
5. Set content paths in CSS with @source directive.

Step 8 — Verification

1. Check specificity: no selectors above (0,2,0) outside overrides layer.
2. Validate no !important outside utilities layer.
3. Run build to confirm no layer order surprises.
4. Visual regression test on key components.
5. Check dark mode parity across all components.
6. Measure CSS bundle size: target < 50 KB gzipped for initial load.

---

Decision Framework

Which Approach for the Project?

Token Granularity Decision

---

Anti-Patterns

1. !important as specificity band-aid — Signals broken cascade. Fix the layer strategy instead.
2. Semantic tokens pointing to other semantic tokens — --color-cta: var(--color-brand) creates fragile chains. Point to primitives.
3. Breakpoints in component files — Use container queries for component responsiveness; viewport breakpoints belong in layout files.
4. Global CSS in component scope — body {} or html {} inside a component's CSS file causes side effects. Scope everything.
5. Dark mode via class duplication — Duplicating .button and .button.dark doubles maintenance. Use token overrides.
6. Undeclared @layer order — Browsers sort unlisted layers in order of first appearance. Always declare the full order upfront.
7. Tailwind @apply in component files — Reintroduces CSS specificity problems. Prefer utility classes in markup or @layer components.
8. CSS custom properties without fallbacks — color: var(--color-text) fails silently in unsupported contexts. Always provide fallback.

---

Output Artifacts

• tokens/primitives.css — Raw design tokens
• tokens/semantic.css — Semantic token mappings
• styles/layers.css — Layer declaration and imports
• styles/base.css — Reset + base element styles
• tailwind.config.css — Tailwind v4 @theme block (if applicable)
• ADR-CSS-001.md — Architecture Decision Record for CSS strategy