CSS Architecture

CSS Architecture for Modern Frontend Systems

Architect scalable, maintainable CSS systems using native CSS features and established architectural patterns. This skill makes the model organize cascade layers with @layer, leverage browser-native selectors (:has(), nesting, container queries), structure BEM naming conventions, integrate Tailwind v4's CSS-first approach, and write scoped styles that avoid specificity wars and maintenance debt.

TL;DR Checklist

• Define @layer order (reset → base → components → utilities) for explicit cascade control
• Replace preprocessor nesting with native CSS & nesting (97%+ browser support)
• Use container queries over viewport media queries for component-level responsiveness
• Apply BEM naming: .block__element--modifier with scope to prevent class leakage
• Configure Tailwind v4 with @theme in CSS instead of tailwind.config.js
• Use :has() selector for parent-state styling without JavaScript
• Document layer overrides — every !important must be justified and tracked

When to Use

Use this skill when:

• Architecting the stylesheet structure for a new application or redesigning an existing one's CSS organization
• Resolving specificity conflicts between third-party libraries and your own styles (use @layer)
• Building component-level responsive layouts that adapt to their container, not just the viewport (container queries)
• Integrating Tailwind CSS v4 with design system tokens via @theme directive
• Implementing parent-state styling based on child element states without JavaScript (:has())
• Setting up native CSS nesting for scoped component styles without SASS/LESS
• Configuring a BEM naming strategy for teams that need explicit class scoping
• Managing cascade complexity in large codebases with many developers

When NOT to Use

Avoid this skill for:

• One-off styling patches on small projects (< 500 lines of CSS total) — @layer overhead outweighs benefits
• Backend/API development where no CSS output is produced
• Design system token architecture (primitive → semantic → alias hierarchy) — use design-systems skill instead
• Component composition patterns (compound components, headless UI) — use component-architecture instead
• Performance optimization of CSS delivery (critical CSS extraction, purge unused rules) — a build concern handled separately

Core Workflow

1. Define Cascade Layers — Establish explicit override order using @layer. Every stylesheet must declare its layer membership to prevent specificity wars.

   Checkpoint: Verify layer declaration matches this precedence: reset → base → components → utilities. Third-party libraries should be explicitly placed, not defaulting to the un-layered cascade.

2. Structure Stylesheets by Concern — Organize files following ITCSS-inspired principles adapted for modern CSS:

   Layer	Purpose	Example Files
   @layer reset	Browser normalization, universal resets	_reset.css, _normalize.css
   @layer base	HTML element defaults, typography tokens	_typography.css, _elements.css
   @layer components	UI components with BEM naming	_buttons.css, _cards.css
   @layer utilities	Single-purpose helper classes	_spacing.css, _visibility.css

   Checkpoint: Confirm no component uses !important. If a !important is necessary, it must be documented with the reason and targeted to a specific selector.

3. Implement Component Styles — For each component, use native CSS nesting combined with BEM naming. Replace preprocessor nesting syntax with native &.

   Checkpoint: Verify all nested selectors compile correctly in target browsers (Safari 16.4+, Chrome 117+). Test that &:hover, &__element, and --modifier variants resolve properly.

4. Apply Container Queries for Responsiveness — Replace viewport-based media queries with container queries where components need independent responsiveness.

   Checkpoint: Confirm every container query has a corresponding container-type declaration on the parent element. Verify fallback styles exist for browsers without container query support.

5. Configure Tailwind v4 Integration — Use CSS-first theme configuration via @theme directive. Define design tokens, colors, and animations directly in CSS.

   Checkpoint: Ensure no tailwind.config.js file exists. All theme customization flows through @theme blocks. Verify utility classes reference correct token names.

6. Audit Specificity — Run a specificity audit to identify selectors above the threshold. Document any necessary overrides with @layer placement adjustments.

   Checkpoint: No selector should exceed a specificity of (0, 2, 3) in production stylesheets. Any higher specificity requires justification and documentation.

Implementation Patterns

Pattern 1: Cascade Layers (@layer) for Specificity Management

The @layer rule creates explicit cascade layers that override the default document order specificity rules. This eliminates specificity wars between your styles, third-party libraries, and utility frameworks.

/* ✅ GOOD — Explicit layer declaration with clear precedence */
@layer reset, base, components, utilities;

@layer reset {
  *, *::before, *::after {
    box-sizing: border-box;
    margin: 0;
    padding: 0;
  }

  html {
    line-height: 1.5;
    -webkit-text-size-adjust: 100%;
    tab-size: 4;
  }

  body {
    min-height: 100vh;
    text-rendering: optimizeSpeed;
  }
}

@layer base {
  :root {
    --color-brand-primary: #2563eb;
    --color-brand-secondary: #7c3aed;
    --font-family-sans: 'Inter', system-ui, -apple-system, sans-serif;
    --font-family-mono: 'JetBrains Mono', monospace;
  }

  h1 { font-size: clamp(2rem, 5vw, 3.5rem); line-height: 1.1; }
  h2 { font-size: clamp(1.5rem, 4vw, 2.5rem); line-height: 1.2; }
  p { font-size: var(--font-size-base, 1rem); line-height: 1.6; }

  a {
    color: var(--color-brand-primary);
    text-decoration: underline;
    text-underline-offset: 0.2em;

    &:hover { text-decoration-thickness: 0.15em; }
  }
}

@layer components {
  .btn {
    display: inline-flex;
    align-items: center;
    gap: 0.5em;
    padding: 0.625em 1.25em;
    border: none;
    border-radius: var(--radius-md, 0.375rem);
    font-size: var(--font-size-sm, 0.875rem);
    font-weight: 600;
    cursor: pointer;
    transition: background-color 150ms ease, transform 100ms ease;

    &:hover { transform: translateY(-1px); }
    &:active { transform: translateY(0); }
    &:focus-visible { outline: 2px solid var(--color-brand-primary); outline-offset: 2px; }

    &--primary {
      background-color: var(--color-brand-primary);
      color: white;

      &:hover { background-color: #1d4ed8; }
    }

    &--secondary {
      background-color: transparent;
      color: var(--color-brand-primary);
      border: 2px solid var(--color-brand-primary);

      &:hover { background-color: color-mix(in srgb, var(--color-brand-primary) 10%, transparent); }
    }

    &--full { width: 100%; justify-content: center; }
  }
}

@layer utilities {
  .sr-only {
    position: absolute;
    width: 1px; height: 1px;
    padding: 0; margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border-width: 0;
  }

  .truncate {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
  }
}

/* Override third-party library without !important — same layer, later wins */
@layer components {
  /* Third-party modal has .modal { margin: 20px; } — we override by placing ours in the same layer below */
  .modal { margin: 16px; border-radius: var(--radius-lg, 0.5rem); }
}

Pattern 2: Native CSS Nesting and :has() Selector

Replace SASS/LESS nesting with native CSS nesting (97%+ browser support as of 2025). Use the :has() selector for parent-state styling without JavaScript event listeners.

/* ✅ GOOD — Native nesting + :has() for parent state management */
.card {
  --card-padding: 1.5rem;
  --card-border-color: var(--color-border-subtle, #e2e8f0);

  display: grid;
  gap: var(--card-padding);
  padding: var(--card-padding);
  border: 1px solid var(--card-border-color);
  border-radius: var(--radius-lg, 0.75rem);
  background: var(--color-bg-elevated, white);

  /* Native nesting replaces .card__element pattern */
  & .card__header {
    display: flex;
    align-items: center;
    gap: 1rem;
    padding-bottom: calc(var(--card-padding) * 0.5);
    border-bottom: 1px solid var(--card-border-color);

    & img {
      width: 48px;
      height: 48px;
      border-radius: 50%;
      object-fit: cover;
    }
  }

  /* :has() for parent-state styling */
  &:has(.card__badge--danger) {
    --card-border-color: #ef4444;
    border-left: 3px solid #ef4444;
  }

  /* :has() with child state — no JavaScript needed */
  &:has(input[type="checkbox"]:checked) .card__check-icon {
    opacity: 1;
    transform: scale(1);
  }

  /* Nested modifier */
  &--compact {
    --card-padding: 0.75rem;
  }
}

/* :has() for form validation styling — parent responds to child state */
.form-group {
  position: relative;
  margin-bottom: 1.25rem;

  &:has(.input:focus) {
    --field-border-color: var(--color-brand-primary);
  }

  &:has(input:invalid:not(:placeholder-shown)) .form-message--error {
    display: block;
  }

  /* Nested elements via native nesting */
  & label {
    display: block;
    margin-bottom: 0.375rem;
    font-weight: 500;
    color: var(--color-text-primary, #1e293b);
  }

  & input, & textarea, & select {
    width: 100%;
    padding: 0.625rem 0.875rem;
    border: 1px solid var(--field-border-color, #cbd5e1);
    border-radius: var(--radius-md, 0.375rem);
    font-size: 1rem;
    transition: border-color 150ms ease, box-shadow 150ms ease;

    &:focus {
      border-color: var(--color-brand-primary);
      box-shadow: 0 0 0 3px color-mix(in srgb, var(--color-brand-primary) 20%, transparent);
      outline: none;
    }
  }
}

Pattern 3: Container Queries for Component-Level Responsiveness

Container queries let components respond to their container's size rather than the viewport. This is essential for component libraries and dashboard layouts where components appear in varying widths.

/* ✅ GOOD — Container queries with explicit container-type declaration */

/* Parent declares itself as a query container */
.card-grid {
  display: grid;
  gap: 1.5rem;
  /* Must set container type for children to use @container */
  container-type: inline-size;
  container-name: card-grid;
}

/* Component responds to its container, not the viewport */
@container card-grid (min-width: 400px) {
  .card-grid {
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  }
}

@container card-grid (min-width: 768px) {
  .card-grid {
    grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
  }
}

/* Individual component with its own container */
.product-card {
  container-type: inline-size;
  container-name: product-card;

  display: flex;
  flex-direction: column;
  gap: 0.75rem;

  /* Vertical layout in narrow containers */
  @container product-card (max-width: 280px) {
    .product-card__image {
      order: 1;
      height: 140px;
    }

    .product-card__details {
      order: 2;
    }
  }

  /* Horizontal layout in wider containers */
  @container product-card (min-width: 281px) {
    flex-direction: row;
    align-items: center;

    .product-card__image {
      width: 120px;
      height: 120px;
      flex-shrink: 0;
    }
  }
}

/* ❌ BAD — Using viewport media queries for component responsiveness */
/* This breaks when the same component appears in a sidebar vs. main content */
.product-card {
  /* Fragile — depends on screen size, not context */
}

@media (min-width: 768px) {
  .product-card { flex-direction: row; }
}

@media (min-width: 1024px) {
  .product-card { grid-template-columns: repeat(3, 1fr); }
}

Pattern 4: Tailwind CSS v4 with @theme Directive

Tailwind v4 replaces the JavaScript-based tailwind.config.js with a CSS-first configuration using the @theme directive. This enables hot-reload of theme changes and keeps design tokens visible in CSS files.

/* ✅ GOOD — Tailwind v4 CSS-first theme configuration */

/* src/styles/tailwind.css */
@import "tailwindcss";

/* Define your theme directly in CSS — no tailwind.config.js needed */
@theme {
  /* Brand colors */
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-200: #bfdbfe;
  --color-brand-300: #93c5fd;
  --color-brand-400: #60a5fa;
  --color-brand-500: #3b82f6;
  --color-brand-600: #2563eb;
  --color-brand-700: #1d4ed8;
  --color-brand-800: #1e40af;
  --color-brand-900: #1e3a8a;

  /* Typography scale */
  --font-family-sans: 'Inter', system-ui, -apple-system, sans-serif;
  --font-family-mono: 'JetBrains Mono', monospace;
  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;
  --font-size-3xl: 2rem;

  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  --spacing-2xl: 3rem;

  /* Border radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;
  --radius-2xl: 1rem;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);

  /* Animations */
  --animate-fade-in: fade-in 0.3s ease-out forwards;
  --animate-slide-up: slide-up 0.3s ease-out forwards;
  --animate-scale-in: scale-in 0.2s ease-out forwards;
}

/* Define keyframes directly in the stylesheet */
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slide-up {
  from { opacity: 0; transform: translateY(8px); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes scale-in {
  from { opacity: 0; transform: scale(0.95); }
  to { opacity: 1; transform: scale(1); }
}

/* Import design system tokens and component styles */
@import "./reset.css" layer(reset);
@import "./base.css" layer(base);
@import "./components/buttons.css" layer(components);
@import "./components/cards.css" layer(components);
@import "./utilities.css" layer(utilities);

Usage in JSX/HTML:

// ✅ GOOD — Tailwind v4 utilities reference CSS theme tokens directly
export function Button({ variant = 'primary', children }) {
  const classes = [
    'inline-flex items-center gap-2 px-4 py-2.5 rounded-md font-semibold text-sm',
    'transition-transform duration-100 hover:-translate-y-0.5 active:translate-y-0',
    variant === 'primary'
      ? 'bg-brand-600 text-white hover:bg-brand-700 focus-visible:outline focus-visible:outline-2 focus-visible:outline-brand-600 focus-visible:outline-offset-2'
      : 'bg-transparent border-2 border-brand-600 text-brand-600 hover:bg-brand-600/10',
  ].join(' ');

  return <button className={classes}>{children}</button>;
}

Pattern 5: BEM Naming Convention for Scoped Components

BEM (Block__Element--Modifier) provides explicit class scoping that prevents unintended style leakage. Use it when you need predictable, isolated component styles without CSS Modules or Shadow DOM.

/* ✅ GOOD — BEM naming with consistent convention */

/* BLOCK: Standalone component/abstract concept */
.nav { }

/* ELEMENTS: Parts of the block — no standalone meaning */
.nav__list { list-style: none; display: flex; gap: 1rem; }
.nav__item { position: relative; }
.nav__link {
  display: block;
  padding: 0.5rem 1rem;
  color: var(--color-text-primary);
  text-decoration: none;
  border-radius: var(--radius-md);
  transition: background-color 150ms ease;
}

/* MODIFIER: State or variation of the block/element */
.nav__link--active {
  background-color: color-mix(in srgb, var(--color-brand-600) 15%, transparent);
  color: var(--color-brand-600);
  font-weight: 600;
}

.nav__link--disabled {
  opacity: 0.4;
  pointer-events: none;
  cursor: not-allowed;
}

/* Nested BEM in compound components */
.dropdown {
  position: relative;
}

.dropdown__toggle {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.5rem 1rem;
  border: 1px solid var(--border-color-default, #d1d5db);
  border-radius: var(--radius-md);
  cursor: pointer;
}

.dropdown__menu {
  position: absolute;
  top: calc(100% + 4px);
  left: 0;
  min-width: 200px;
  padding: 0.5rem 0;
  background: white;
  border: 1px solid var(--border-color-default);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-lg);
  opacity: 0;
  visibility: hidden;
  transition: opacity 150ms ease, visibility 150ms ease;
}

/* Use :has() instead of JS for dropdown open state */
.dropdown:has(.dropdown__toggle:hover) .dropdown__menu,
.dropdown:focus-within .dropdown__menu {
  opacity: 1;
  visibility: visible;
}

/* ❌ BAD — BEM with too deep nesting creates specificity problems */
.nav.nav-main.nav-container.nav-item--primary.nav-item__link--active {
  /* This is a nightmare to maintain and overrides are impossible without !important */
}

Constraints

MUST DO

• Always declare @layer order at the top of your primary stylesheet before any other rules
• Use native CSS nesting (&) instead of preprocessor nesting wherever possible (Safari 16.4+ / Chrome 117+ support)
• Set container-type: inline-size on every parent element that will host container-query-driven children
• Write component styles with BEM naming when using flat CSS; use CSS Modules or Shadow DOM for frameworks that support them natively
• Use color-mix() for hover/active states instead of pre-calculated color variants
• Document every use of !important with a comment explaining why no alternative layer override works
• Test :has() selector fallbacks for browsers lacking support (iOS Safari < 17.4) using progressive enhancement

MUST NOT DO

• Never rely on selector depth or specificity to force styles — use @layer instead of adding more parent selectors
• Never use !important as a first resort — it breaks the cascade layer model and creates maintenance debt
• Never nest BEM selectors deeper than 2 levels (.block__element--modifier.child__sub) — this indicates component leakage
• Never mix container queries with viewport media queries for the same responsive breakpoint — pick one strategy per component
• Never use tailwind.config.js in a Tailwind v4 project — all theme configuration must live in CSS @theme blocks
• Never apply :has() selector to non-container parents in performance-critical paths (scroll listeners, high-frequency DOM updates)

Output Template

When implementing or reviewing CSS architecture, produce:

1. Layer Structure — List of @layer declarations with the precedence order and which files belong to each layer
2. Component Style Sheet — The component's CSS with BEM naming, native nesting applied, and any container query breakpoints
3. Tailwind Theme Block — The @theme configuration showing all custom tokens derived from the design system
4. Specificity Audit Report — List of selectors exceeding the (0, 2, 3) threshold with suggested layer adjustments
5. Browser Support Matrix — Feature support status for native nesting, :has(), container queries across target browsers

Related Skills

Live References

Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

• MDN: CSS Cascade Layers (@layer)
• MDN: CSS Nesting
• MDN: :has() Selector
• MDN: Container Queries
• Tailwind CSS v4 Documentation (CSS-first configuration)
• W3C: ITCSS — Scalable and Maintainable Architecture for Stylesheets
• CSS BEM Documentation