Designing Systems

Designing Systems

Create consistent, scalable design systems with tokens.

APEX WORKFLOW

Phase 0: ANALYZE EXISTING (CRITICAL)

Task: explore-codebase
Prompt: "Find existing design tokens: CSS variables, Tailwind config,
color palette, typography, spacing patterns"

If design system exists: Document and extend it. If no design system: Create new following this guide.

Design Token Categories

Color System (OKLCH 2026)

/​* Primary palette - OKLCH for P3 wide gamut */
--color-primary-500: oklch(55% 0.20 260);
--color-primary-600: oklch(48% 0.18 260);

/​* Semantic mapping */
--color-background: var(--color-neutral-50);
--color-foreground: var(--color-neutral-900);
--color-muted: var(--color-neutral-100);
--color-border: var(--color-neutral-200);

/​* Dark mode */
.dark {
  --color-background: var(--color-neutral-900);
  --color-foreground: var(--color-neutral-50);
}

Typography Scale (1.25 ratio)

/​* FORBIDDEN: Inter, Roboto, Arial */
/​* USE: Clash Display, Satoshi, Bricolage Grotesque */

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

--text-sm: 0.875rem;   /​* 14px */
--text-base: 1rem;     /​* 16px */
--text-lg: 1.125rem;   /​* 18px */
--text-xl: 1.25rem;    /​* 20px */
--text-2xl: 1.5rem;    /​* 24px */

Spacing (4px grid)

--spacing-1: 0.25rem;  /​* 4px */
--spacing-2: 0.5rem;   /​* 8px */
--spacing-4: 1rem;     /​* 16px */
--spacing-6: 1.5rem;   /​* 24px */
--spacing-8: 2rem;     /​* 32px */

Tailwind v4 Config

/​* app.css - CSS-first config */
@import "tailwindcss";

@theme {
  --color-primary-*: oklch(55% 0.20 260);
  --font-display: 'Clash Display', sans-serif;
  --radius-lg: 0.75rem;
}

Validation

[ ] Existing tokens documented (Phase 0)
[ ] No forbidden fonts (Inter/​Roboto/​Arial)
[ ] OKLCH colors for wide gamut
[ ] Dark mode variables defined
[ ] Tailwind v4 @theme configured

References

• UI Visual Design: ../​../​references/​ui-visual-design.md (visual hierarchy, spacing system, 2026 trends)
• Color System: ../​../​references/​color-system.md
• Typography: ../​../​references/​typography.md
• Theme Presets: ../​../​references/​theme-presets.md
• Tailwind Best Practices: ../​../​references/​tailwind-best-practices.md