Design System

Build scalable, maintainable design systems with tokens, components, and theming architecture.

Prerequisites

Before building a design system, check for existing design context:

• Read .agents/design-context.md (see design-context) for colors, fonts, Base Size, Scale Ratio, Border Radius, Shadow Style, and Spacing System. Primitive tokens must derive from it, not from invented values.
• Scan the codebase for existing tokens (CSS variables, Tailwind theme, tokens.json) and extend them.
• Identify the framework (React, Vue, Svelte, vanilla) to determine component patterns.
• Don't re-derive what siblings own: color scales come from color-palette (--brand-*, --gray-*, --success-*, --warning-*, --error-*, --info-*), the type scale from typography (--text-xs … --text-5xl).

Step 1: Design Token Hierarchy

Tokens are the atomic values of a design system. Structure them in three layers:

Layer 1: Primitive Tokens (Raw Values)