design-system-creator

✅ Use for:

• Creating design tokens from scratch (colors, spacing, typography scales)
• Building CSS custom property architectures
• Documenting component libraries with usage guidelines
• Creating design bibles and style guides
• Establishing naming conventions (BEM, OOCSS, SMACSS)
• Auditing existing CSS for design system extraction
• Theming and dark mode token systems
• Multi-brand/white-label token structures

❌ Do NOT use for:

• Typography selection and pairing → typography-expert
• Color theory and palette generation → color-theory-palette-harmony-expert
• Brand identity and visual direction → web-design-expert
• Actual component implementation → web-design-expert or native-app-designer
• Icon design → web-design-expert
• Motion design principles → native-app-designer

The foundation of scalable design systems:

```css

:root {

/ 1. PRIMITIVE - Raw values /

--color-blue-500: #3b82f6;

--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.

1. Foundation

• Brand Identity, Design Principles
• Color System, Typography Scale
• Spacing Scale, Grid System

2. Components

For each component document:

• Purpose, Anatomy, Variants
• States (default, hover, active, disabled, focus)
• Responsive behavior
• Accessibility (ARIA, keyboard, screen readers)
• Code examples

3. Patterns

• Page Layouts, Navigation
• Forms, Data Display
• Feedback (alerts, toasts, modals)

4. Guidelines

• Writing (voice, tone)
• Imagery, Motion, Accessibility

→ 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.

1. Token Explosion

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.

2. Missing Semantic Layer

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

3. Documentation Drift

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

4. Utility Class Overload

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

5. Breaking the Scale

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

6. No Version Control

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

1. Audit: Review existing patterns and inconsistencies
2. Define: Establish tokens and foundational system
3. Build: Create component library with documentation
4. Document: Write comprehensive design bible
5. Test: Validate accessibility and responsiveness
6. Deliver: Package with examples and starter templates

| 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 |

• Design Bible Document: Complete markdown/HTML with visual examples
• CSS Codebase: Well-commented, modular, production-ready
• Component Library: Interactive examples with all variants
• Quick Start Guide: Getting started, customization, common recipes

→ 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

• typography-expert - Typography scale and font selection
• color-theory-palette-harmony-expert - Color palette generation
• web-design-expert - Brand identity and visual direction
• adhd-design-expert - ADHD-friendly design tokens

---

Remember: A design system is a living product that serves products.