curiositech/design-system-generator

Design System Generator

Transform natural language descriptions into production-ready design tokens. Powered by 24 design trends, 31 AI-ready styles, and 2,800+ component examples.

DECISION POINTS

1. Confidence Threshold Rules

If trend match confidence >= 80%:
  → Generate immediately with primary trend

If confidence 60-79%:
  → Show top 2 matches, ask user to choose
  → Example: "Swiss-modern (65%) vs. Hyperminimalism (62%) - which feels right?"

If confidence < 60%:
  → Use vibe-matcher skill first for emotional clarity
  → Re-run trend matching with vibe context

2. Multi-Trend Disambiguation

If 2+ trends score within 10% of each other:
  ├─ Business/professional context?
  │   → Prefer: swiss-modern, hyperminimalism, dark-mode
  ├─ Creative/agency context?
  │   → Prefer: neobrutalism, maximalism, experimental-navigation
  ├─ Tech/developer context?
  │   → Prefer: terminal-aesthetic, glassmorphism, web3-crypto
  └─ Consumer app context?
      → Prefer: claymorphism, botanical-organic, gamified-design

3. Output Format Selection

If user mentions specific framework:
  ├─ "Next.js", "React", "Vite" → generate-tailwind.ts
  ├─ "Vue", "Angular", "vanilla" → generate-css-vars.ts
  └─ "Figma", "Style Dictionary" → generate-tokens.ts (DTCG)

If no framework mentioned:
  → Ask: "What's your tech stack?" or generate all three formats

4. Accessibility Requirements

If trend has accessibility warnings (glassmorphism, claymorphism):
  → Generate standard tokens first
  → Run contrast checker
  → If violations found:
      ├─ Adjust color values to meet WCAG AA
      ├─ Document overrides in comments
      └─ Warn user about visual changes

5. Scope Determination

If user mentions theming:
  ├─ "dark mode" → Generate with --scope=.dark
  ├─ "multiple brands" → Generate with --scope=[data-theme="name"]
  └─ "component library" → Use :root scope (default)

If existing design system mentioned:
  → Generate with theme.extend structure only

FAILURE MODES

1. Wrong Color Direction (Vibrant when user wanted muted)

Detection: User says "too bright", "too colorful", "more subtle" Symptoms: High saturation values, neon/electric colors in conservative context Fix: Re-run with lower-energy trend (swiss-modern instead of neobrutalism)

# Wrong
npx ts-node generate-tailwind.ts neobrutalism  # Generates #FF5252, #00E676

# Fixed  
npx ts-node generate-tailwind.ts swiss-modern  # Generates #374151, #6B7280

2. Compilation Chaos (Generated tokens break build)

Detection: Tailwind purge warnings, CSS custom property undefined errors Symptoms: Missing quotes in font names, invalid CSS values, circular references Fix: Validate output before deployment

# Check Tailwind compilation
npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch

# Check CSS syntax
npx stylelint tokens.css

3. Contrast Violation (Accessibility failure in production)

Detection: Lighthouse audit < 90, WAVE tool errors Symptoms: Text invisible on backgrounds, pale borders, low-contrast buttons Fix: Run contrast audit before finalizing

# Audit generated tokens
npx ts-node scripts/check-contrast.ts swiss-modern
# → Warning: text-gray-400 on bg-white = 2.1:1 (needs 4.5:1)

4. Semantic Mismatch (Token names don't match visual result)

Detection: Developer confusion, "primary" color isn't prominent Symptoms: brutal-red is actually orange, glass-white is gray Fix: Check trend mapping accuracy

# Verify semantic alignment
npx ts-node scripts/preview-tokens.ts neobrutalism
# Opens browser with all colors labeled

5. Scope Pollution (CSS variables leak across themes)

Detection: Theme switching doesn't work, colors persist incorrectly Symptoms: Dark mode shows light colors, component themes interfere Fix: Use explicit scoping

/* Wrong - leaks to global */
:root { --color-primary: #FF0000; }

/* Fixed - scoped properly */
[data-theme="brand-a"] { --color-primary: #FF0000; }
[data-theme="brand-b"] { --color-primary: #00FF00; }

WORKED EXAMPLES

Scenario: SaaS Dashboard for Developer Tools

Input: "Clean dashboard for developers, needs to feel professional but not boring"

Step 1: Trend Matching

npx ts-node scripts/match-trend.ts "clean dashboard for developers professional"

Result: swiss-modern (78%), terminal-aesthetic (45%)

Decision: 78% confidence is good, but "not boring" suggests terminal-aesthetic could add personality. Check both.

Step 2: Preview Both Options

• Swiss-modern: #374151 grays, Helvetica fonts, subtle shadows
• Terminal-aesthetic: #00E676 greens, monospace, sharp edges

Expert insight: For developer tools, terminal-aesthetic creates better brand differentiation while maintaining professionalism.

Step 3: Generate Tailwind Config

npx ts-node generate-tailwind.ts terminal-aesthetic > tailwind.tokens.ts

Step 4: Quality Check

// Generated output includes:
colors: {
  'terminal-green': '#00E676',
  'terminal-dark': '#0D1117', 
  'terminal-gray': '#21262D'
}

Step 5: Accessibility Verification

• terminal-green on terminal-dark = 7.2:1 ✅ (exceeds AAA)
• All text combinations pass WCAG AA

Result: Professional developer aesthetic with personality, fully accessible.

QUALITY GATES

Pre-deployment checklist for generated tokens:

• [ ] WCAG Contrast: All text/background combinations ≥ 4.5:1 (AA) or ≥ 3:1 for large text
• [ ] Tailwind Compilation: npx tailwindcss builds without warnings or errors
• [ ] CSS Validation: Custom properties have valid syntax (no missing semicolons, quotes)
• [ ] Browser Compatibility: Tokens render correctly in Chrome, Firefox, Safari latest versions
• [ ] Semantic Accuracy: Color names match visual appearance (red looks red, not orange)
• [ ] Component Coverage: Generated tokens support primary UI components (buttons, inputs, cards)
• [ ] Theme Isolation: Multiple themes don't interfere (test theme switching if applicable)
• [ ] Font Loading: Generated font families are available or have fallbacks
• [ ] Performance: CSS file size < 50KB, no unused custom properties
• [ ] Documentation: Token purpose and usage examples are clear to implementers

NOT-FOR BOUNDARIES

❌ DO NOT use for:

• Color exploration/mood boarding → Use vibe-matcher skill instead
• Existing design system refinement → Use design-system-documenter for optimization
• Component code generation → Use component-template-generator with these tokens
• Brand identity creation → Use color-theory-palette-harmony-expert for strategic color work
• Single token adjustments → Just edit the values directly
• Complex animation systems → Use web-design-expert for motion design
• Marketing site aesthetics → This generates systematic tokens, not one-off visual styles

✅ Perfect for:

• New project foundation setup
• Converting design descriptions to code
• Standardizing ad-hoc color usage
• Cross-format token consistency (Tailwind + CSS vars + DTCG)

Delegation Rules:

• If user needs emotional/conceptual clarity → vibe-matcher first, then return here
• If user has existing system → design-system-documenter for analysis
• If user needs components, not tokens → component-template-generator with generated tokens
• If user needs color strategy → color-theory-palette-harmony-expert for theory, then return here