Designing Systems

Agent Workflow (MANDATORY)

Before ANY design system work, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase – Find existing CSS variables, Tailwind config, colors
2. fuse-ai-pilot:research-expert – Verify latest OKLCH and Tailwind v4 patterns
3. mcp__context7__query-docs – Check Tailwind v4 @theme syntax

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

Critical Rules

1. OKLCH only – No hex or RGB for colors
2. Forbidden fonts – Inter, Roboto, Arial are BANNED
3. CSS variables – Never hard-code colors
4. Analyze first – Document existing system before changes
5. Dark mode – Always define both light and dark tokens

Architecture

styles/
├── tokens/
│   ├── colors.css       (~50 lines)
│   ├── typography.css   (~30 lines)
│   └── spacing.css      (~20 lines)
└── app.css              (~40 lines - @import + @theme)

→ See color-system.md for token examples

Reference Guide

Concepts

Templates

Templates are in generating-components skill for implementation examples.

Quick Reference

OKLCH Color Token

:root {
  --color-primary: oklch(55% 0.20 260);
  --color-primary-foreground: oklch(98% 0.01 260);
}

.dark {
  --color-primary: oklch(65% 0.20 260);
}

→ See color-system.md for full palette

Typography Scale

--font-display: 'Clash Display', sans-serif;
--font-sans: 'Satoshi', sans-serif;
--font-mono: 'JetBrains Mono', monospace;

→ See typography.md for approved fonts

Tailwind v4 @theme

@import "tailwindcss";

@theme {
  --color-primary: var(--color-primary);
  --font-display: var(--font-display);
}

→ See tailwind-best-practices.md for config

Best Practices

DO

• Use OKLCH for wide gamut colors
• Define semantic tokens (primary, success, destructive)
• Support dark mode from the start
• Follow 60-30-10 color distribution
• Use approved fonts only

DON’T

• Hard-code hex/RGB colors
• Use Inter, Roboto, Arial fonts
• Skip dark mode variables
• Create tokens without semantic meaning
• Mix color spaces (stick to OKLCH)