PixelPilot uiux-css-architecture.instructions.md

UI/UX CSS Architecture 2026

Tailwind v4, CSS Layers, utility-first vs component-first, CSS Modules, and best CSS organization patterns for every stack.

---

DECISION TREE — CSS Strategy

Stack choice?
├─ Vanilla HTML / static site
│   └─ CSS Layers + Custom Properties (this file, Step 1)
├─ React / Next.js / Vue / Nuxt
│   ├─ Need maximum speed + utility classes?
│   │   └─ Tailwind v4 (see Step 2)
│   ├─ Need scoped styles, co-located?
│   │   └─ CSS Modules (see Step 3)
│   ├─ Need type-safe styles?
│   │   └─ vanilla-extract (see Step 4)
│   └─ Building a component library?
│       └─ CSS Modules + design tokens
├─ Expo / React Native
│   └─ StyleSheet API + Unistyles (see Step 5)
└─ Everything above
    └─ Design tokens from uiux-tokens.md — always the foundation

---

STEP 1 — CSS LAYERS (Native, Every Project)

@layer prevents specificity wars. Load order = cascade order. No !important needed.

/* styles/tokens.css — import first, always */
@layer reset, tokens, base, components, utilities, overrides;

@layer reset {
  /* normalize + box-sizing (from uiux-components.md) */
  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
}

@layer tokens {
  /* ALL :root CSS variables from uiux-tokens.md */
  :root { --accent: #0066FF; /* etc */ }
  [data-theme="dark"] { --bg: #0A0B0E; /* etc */ }
}

@layer base {
  /* html, body, img, a defaults */
  body { font-family: var(--font-body); background: var(--bg); color: var(--text); }
}

@layer components {
  /* .btn, .card, .field, .nav, .footer — reusable components */
  .btn { display: inline-flex; /* from uiux-interactive.md */ }
}

@layer utilities {
  /* Single-purpose helpers */
  .sr-only { position: absolute; width: 1px; /* etc */ }
  .container { max-width: var(--container-max); /* etc */ }
}

@layer overrides {
  /* Per-page / per-component overrides — highest layer, cleanest specificity */
  /* Use sparingly — prefer component tokens over overrides */
}