Level 0: No system
Colors are hardcoded. Every component picks its own font size. Spacing is whatever looks right in the moment. There are no shared variables, no token file, no style guide. Each developer builds their own visual patterns.
How it feels: Fast at first, then increasingly painful. Every new page looks slightly different from the last. Redesigns require touching every file. Dark mode is "not feasible right now."
Signs you are here: Hex values scattered across component files. No CSS variables or Tailwind theme extensions. Copy-pasted styles between components.
Upgrade to Level 1
Extract repeated values into a single file. Even a simple colors.ts or :root block with your five most-used colors is a massive improvement. You are not building a system yet. You are creating a single source of truth for values that currently live in 30 places.
Level 1: Shared palette
You have a central place where colors, fonts, and maybe spacing are defined. Components reference these shared values instead of hardcoding. But the names are appearance-based (--blue-500, --gray-100) rather than purpose-based, and there is no formal structure beyond "here are our colors."
How it feels: Better. Brand color changes are easier. But dark mode is still hard because you need to find every place a light color is used and swap it. Components reference palette values directly, so theming requires touching component code.
/* Level 1: Shared palette, appearance-based names */
:root {
--blue-500: #3B82F6;
--blue-600: #2563EB;
--gray-50: #F9FAFB;
--gray-100: #F3F4F6;
--gray-900: #111827;
}Upgrade to Level 2
Rename your tokens from appearance-based to purpose-based. --blue-500 becomes --color-accent. --gray-50 becomes --color-bg. Keep the old palette values as primitives, and add a semantic layer that references them. This single renaming exercise unlocks theming.
Level 2: Semantic tokens
Your tokens have semantic names. There is a clear distinction between the palette (primitives) and the tokens your components consume (semantic). Dark mode works by reassigning the semantic layer. Theming is possible without touching component code.
How it feels: Significantly better. Dark mode is a CSS-only change. Brand updates are a single-file edit. But the system is color-only. Typography, spacing, shadows, and border-radius are still ad hoc. And there is no governance around token additions.
/* Level 2: Semantic tokens with primitive backing */
:root {
/* Primitives */
--blue-500: #3B82F6;
--zinc-50: #FAFAFA;
--zinc-900: #18181B;
/* Semantic */
--color-bg: var(--zinc-50);
--color-text: var(--zinc-900);
--color-accent: var(--blue-500);
}Upgrade to Level 3
Extend your tokens beyond color. Add typography tokens (heading font, body font, weights, letter-spacing), spacing scale, shadow definitions (sm, md, lg), and border-radius values. A design system is not just colors. It is the complete visual language. For the full set of tokens you need, check design variables that actually matter.
Level 3: Complete token system
Your design system covers the entire visual surface: color, typography, spacing, shadows, border-radius, and possibly motion/easing curves. The three-layer architecture (primitives, semantic, component) is in place. Tokens are the single source of truth for all visual decisions.
How it feels: Professional. New components inherit the system automatically. Multi-brand support is architecturally possible. But the tokens live in your codebase only. They are not available to external tools, AI agents, or design tools. And there are no formal rules around who can add, modify, or deprecate tokens.
/* Level 3: Complete token system */
:root {
/* Colors: full semantic set */
--color-bg: #FAFAFA;
--color-surface: #F4F4F5;
--color-text: #18181B;
--color-muted: #71717A;
--color-accent: #6366F1;
--color-border: #E4E4E7;
/* Typography */
--font-heading: 'Space Grotesk', sans-serif;
--font-body: 'Inter', sans-serif;
--font-mono: 'Geist Mono', monospace;
/* Shape */
--radius-sm: 6px;
--radius-md: 8px;
--radius-lg: 12px;
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
--shadow-md: 0 4px 6px rgba(0,0,0,0.07);
/* Spacing */
--space-1: 4px;
--space-2: 8px;
--space-4: 16px;
--space-8: 32px;
}Upgrade to Level 4
Make your tokens available to AI tools. Export them to IDE rule files (.cursorrules, CLAUDE.md, .windsurfrules). Set up an MCP server or API endpoint that serves your tokens. When your AI coding agent can query your design system, every piece of generated code inherits your brand. This is where design seeds become powerful.
Level 4: Agent-ready system
Your design tokens are not just in your codebase. They are accessible to AI coding agents through rule files, MCP servers, or API endpoints. Agents generate code that uses your tokens by default. Human and AI contributors work from the same design language.
How it feels: Transformative. AI-generated code looks like your product, not like a generic template. New team members (human or AI) are productive immediately because the design language is explicit and machine-readable. Design drift is nearly eliminated.
Upgrade to Level 5
Add governance. Define who can add tokens, how tokens are reviewed, and how tokens are deprecated. Establish naming conventions that are enforced by linting. Create contribution guidelines for both human and AI contributors. Level 5 is about sustainability.
Level 5: Governed, sustainable system
The full package. Complete tokens, agent-readable, with formal governance. Token additions go through review. Naming conventions are linted. Deprecated tokens have migration paths. The system scales with the team and the product without degrading.
How it feels: Quiet. The system works. New features inherit it automatically. Design drift does not happen because the guardrails are structural, not procedural. For the governance playbook, see design tokens for AI.
Where most projects actually are
Be honest with yourself. Most projects are at Level 0 or Level 1. They have some shared colors, maybe a Tailwind config with custom extensions, but no semantic naming, no token layers, and no AI readiness. That is fine. Every system starts somewhere.
The point of the maturity model is not to shame you for being at Level 1. It is to show you the next step. You do not need to jump from Level 0 to Level 5 in one sprint. Each level is a meaningful improvement over the last. Going from Level 0 to Level 1 (extracting shared values) takes an afternoon. Going from Level 1 to Level 2 (semantic naming) takes a few hours of renaming.
SeedFlip as an accelerator
SeedFlip seeds start you at Level 3. Every seed exports a complete token system: semantic color tokens, typography, spacing, shadows, border-radius, and chart colors. From there, exporting to an IDE rule file gets you to Level 4, and the MCP server makes your tokens queryable by any AI agent in your workflow.
The jump from Level 0 to Level 3 that might take weeks of manual work takes ten seconds with a curated seed. The tokens are tested, accessible, and ready for both light and dark themes. You skip the tedious parts and start at the level where real leverage begins.
You are not behind. Wherever your project lands on this model, the upgrade path is clear and incremental. Extract shared values. Name them semantically. Extend beyond color. Make them agent-readable. Add governance. Each step compounds. The system gets better every time you level up, and it never has to be done all at once.