role-frontend:css-architecture

CSS Architecture

When to use

• Choosing a CSS methodology (BEM, ITCSS, CUBE CSS) for a new project or team
• Setting up CSS Modules, styled-components, Vanilla Extract, or Panda CSS
• Configuring Tailwind with custom design tokens
• Implementing a design token system with CSS custom properties
• Using modern CSS (container queries, :has(), @layer, native nesting, subgrid)
• Building responsive layouts with Grid/​Flexbox
• Adding dark mode support or scroll-driven animations
• Diagnosing specificity wars, paint performance, or layout thrashing

Core principles

1. Native HTML semantics before CSS tricks — right element reduces styling complexity
2. Flat specificity — BEM single-class selectors, @layer for ordering, never !important
3. Design tokens as single source of truth — global → semantic → component tiers
4. Zero-runtime CSS-in-JS for scale — Vanilla Extract or Panda CSS over styled-components in large apps
5. Container queries for components, media queries for pages — components should not know viewport size

Reference Files

• references/​methodologies-modules-css-in-js.md — BEM/​ITCSS/​CUBE CSS comparison, CSS Modules with composes, styled-components with ThemeProvider, Emotion, Vanilla Extract, Panda CSS, StyleX, Linaria
• references/​tailwind-tokens-modern-css.md — Tailwind config, group/​peer modifiers, dark mode, UnoCSS; design token three-tier system, CSS custom properties, responsive tokens; container queries, native nesting, :has(), @layer, subgrid, oklch color, fluid typography, scroll-driven animations, content-visibility
• references/​layout-responsive-dark-mode.md — CSS Grid named areas, auto-fill grid, Flexbox guidance, mobile-first responsive design, responsive images, dark mode system/​manual toggle, CSS performance (will-change, paint containment, critical CSS), animation GPU properties, anti-patterns table