css-architecture

CSS Architecture Skill

How to implement what frontend-design specifies. Covers design token strategy, Tailwind conventions, responsive patterns, dark mode, and animation architecture.

1. Design Token Strategy — CSS Custom Properties

Hierarchy (global → component)

/* Layer 1: Primitive tokens (raw values) */
:root {
  --color-slate-900: #0f172a;
  --color-slate-100: #f1f5f9;
  --color-amber-500: #f59e0b;
  --space-4: 1rem;
  --space-8: 2rem;
  --radius-md: 0.5rem;
  --font-sans: 'Inter Variable', system-ui, sans-serif;

  /* Layer 2: Semantic tokens (intent) */
  --color-bg: var(--color-slate-900);
  --color-surface: hsl(220 15% 12%);
  --color-text: var(--color-slate-100);
  --color-accent: var(--color-amber-500);
  --color-border: hsl(220 15% 20%);

  /* Layer 3: Component tokens */
  --button-bg: var(--color-accent);
  --button-text: var(--color-slate-900);
  --card-padding: var(--space-8);
}

Naming Conventions

• Primitive: --color-{hue}-{shade}, --space-{n}, --radius-{size}
• Semantic: --color-{role} (bg, surface, text, accent, border, error, success)
• Component: --{component}-{property} (button-bg, card-radius)
• Never skip semantic layer — primitives must not be used directly in components.

2. Tailwind Conventions

v3 Config (tailwind.config.ts)

import type { Config } from 'tailwindcss'
import { fontFamily } from 'tailwindcss/defaultTheme'

const config: Config = {
  content: ['./src/**/*.{ts,tsx,mdx}'],
  darkMode: 'class',  // or 'media'
  theme: {
    extend: {
      colors: {
        // Map to CSS custom properties so tokens work everywhere
        bg: 'hsl(var(--color-bg) / <alpha-value>)',
        surface: 'hsl(var(--color-surface) / <alpha-value>)',
        accent: 'hsl(var(--color-accent) / <alpha-value>)',
        border: 'hsl(var(--color-border) / <alpha-value>)',
      },
      fontFamily: {
        sans: ['var(--font-sans)', ...fontFamily.sans],
        display: ['var(--font-display)', ...fontFamily.serif],
      },
      borderRadius: { DEFAULT: 'var(--radius-md)' },
      animation: {
        'fade-up': 'fadeUp 0.4s ease-out',
        'fade-in': 'fadeIn 0.3s ease-out',
      },
      keyframes: {
        fadeUp: { from: { opacity: '0', transform: 'translateY(12px)' }, to: { opacity: '1', transform: 'none' } },
        fadeIn: { from: { opacity: '0' }, to: { opacity: '1' } },
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/container-queries'),
  ],
}
export default config