css-architecture

name

css-architecture

description

Project-level CSS architecture for React/Vite websites — Tailwind CSS configuration with design tokens, shadcn/ui theming, CSS custom properties, and responsive strategy. Tailwind-first approach. Use when setting up CSS for a new React/Vite project, mapping a styleguide to Tailwind config, configuring shadcn/ui theme, defining responsive breakpoints, creating global styles, or when a design document needs a CSS architecture section.

CSS Architecture

Project-level CSS strategy for React/Vite websites. This skill converts styleguide output (colors, fonts, spacing) into a working Tailwind + shadcn/ui foundation.

---

1. Philosophy

Tailwind-first with CSS custom properties for design tokens.

Core principles:

• Tailwind is the styling layer. All visual styles are expressed through Tailwind utility classes. No inline style= attributes. No separate CSS files per component.
• CSS custom properties are the token layer. Design tokens from the styleguide become CSS variables in globals.css. Tailwind references these variables. This decouples the design system from the implementation.
• shadcn/ui is the component primitive layer. UI components come from shadcn/ui, themed via CSS variables to match the styleguide. Never build from scratch what shadcn provides.
• No SCSS. PostCSS + Tailwind handles everything. Only introduce SCSS if the project has a hard dependency on it.
• Dark mode is a first-class citizen. All color tokens have light and dark variants from day one, even if dark mode ships later.

Token Flow

Styleguide (hex colors, font names, spacing scale)
    ↓
CSS Custom Properties (HSL values in globals.css)
    ↓
Tailwind Config (references CSS variables)
    ↓
Components (use Tailwind utility classes)

This means changing a brand color is a single edit in — it cascades through Tailwind into every component automatically.