Builds comprehensive design systems and design bibles with production-ready CSS. Expert in design tokens, component libraries, CSS architecture...
Design systems architect and CSS expert specializing in creating comprehensive, scalable design bibles.
✅ Use for:
❌ Do NOT use for:
The foundation of scalable design systems:
:root {
/* 1. PRIMITIVE - Raw values (ALWAYS use OKLCH for colors) */
--color-blue-500: oklch(62.8% 0.195 252.5);
--space-4: 1rem;
/* 2. SEMANTIC - Purpose-driven */
--color-primary: var(--color-blue-500);
--space-component-padding: var(--space-4);
/* 3. COMPONENT - Specific usage */
--button-bg: var(--color-primary);
--button-padding: var(--space-component-padding);
}
→ See references/token-architecture.md for dark mode, multi-brand, and complete examples.
⚠️ CRITICAL: Always use OKLCH for color tokens, not hex or HSL.
OKLCH is perceptually uniform - equal L values mean equal perceived lightness. This is essential for:
:root {
/* OKLCH format: oklch(Lightness% Chroma Hue) */
/* Primary scale - same hue, varying lightness */
--color-primary-100: oklch(95% 0.05 252);
--color-primary-500: oklch(62% 0.19 252);
--color-primary-900: oklch(30% 0.15 252);
/* Dark mode: reduce L uniformly */
--color-bg-light: oklch(98% 0.01 252);
--color-bg-dark: oklch(15% 0.02 252);
}
Essential OKLCH Resources:
| Resource | Purpose |
|---|---|
| oklch.com | Interactive OKLCH color picker |
| Evil Martians: Why Quit RGB/HSL | Why OKLCH is the new standard |
| Harmonizer | Generate harmonious palettes in OKLCH |
OKLCH Benefits for Design Systems:
oklch() works in all modern browsers (2023+)For each component document:
→ See references/component-documentation.md for templates.
styles/
├── 0-settings/ # Tokens, custom properties
├── 1-tools/ # Mixins, functions
├── 2-generic/ # Reset, normalize
├── 3-elements/ # Typography, forms (unclassed)
├── 4-objects/ # Layout patterns
├── 5-components/ # UI components
├── 6-utilities/ # Helpers, overrides
└── main.css # Import all
→ See references/css-organization.md for BEM naming and full structure.
What it looks like: 500+ tokens with overlapping purposes Why it's wrong: Defeats constraints; developers can't choose Fix: Limit to 6-8 spacing tokens. If you need more, fix the scale.
What it looks like: Components reference primitives directly Why it's wrong: Can't theme, can't change brand without touching every component Fix: Three-tier tokens: Primitive → Semantic → Component
What it looks like: Design bible says one thing, CSS does another Why it's wrong: Developers stop trusting documentation Fix: Generate docs from CSS comments, or use Storybook
What it looks like: class="p-4 m-2 bg-blue-500 text-white..."
Why it's wrong: HTML unreadable, design intent lost
Fix: Use utilities sparingly; most styles in semantic component classes
What it looks like: padding: 13px; (why 13?)
Why it's wrong: Every exception erodes the system
Fix: If the scale doesn't work, fix the scale
What it looks like: "Which button is correct?" Why it's wrong: Multiple sources of truth Fix: Single source of truth with version numbers, deprecation warnings
| MCP | Purpose |
|---|---|
| 21st.dev | Scaffold components quickly with modern patterns |
| Storybook | Extract existing component structure (when available) |
| Figma | Sync design tokens from Figma variables (when available) |
| Stability AI | Generate placeholder images for documentation |
| Firecrawl | Research design system best practices |
→ references/token-architecture.md - Three-tier tokens, dark mode, multi-brand
→ references/css-organization.md - ITCSS, BEM, component file structure
→ references/component-documentation.md - Doc templates, quick reference cards
Remember: A design system is a living product that serves products.
