ui-design-system

Code-First Design System

Why This Matters

A design system should be built in code, not Figma. With AI-assisted development, tokens and components emerge from implementation – not from upfront planning. You give AI a design frame, develop the first iteration, and then ask it to refactor: separate large files into smaller ones, create reusable components, and extract colors, typography, and spacing into tokens.

This approach ensures every token and component is actually used in your codebase, avoids maintaining two parallel systems (Figma + code), and lets AI handle the mechanical work of consistency enforcement.

Interaction Method

If AskUserQuestion is available, use it for all prompts below.

If not, present each question as a numbered list and wait for a reply before proceeding. For multiSelect questions, accept comma-separated numbers (e.g. 1, 3). Never skip or auto-answer without explicit user consent.

---

Step 0: Before starting

1. Announce your execution plan: Before doing anything, state what you will do in this activity: "Here's what I'm going to do: 1) check for any saved design decisions from a previous session, 2) determine the current state of your design system, 3) define the architecture – depth strategy, tokens, semantic aliases, components, 4) guide incremental extraction if code already exists, 5) run a compliance audit, 6) produce the deliverable, 7) save design decisions for future sessions." This is a commitment device – harder to skip steps you just announced.

2. Conditional teaching: Ask the user if they are familiar with code-first design systems and atomic design patterns. If yes, give a one-sentence refresher. If no, explain it in simple terms: instead of designing a system in Figma first, you build tokens and components in code as you develop – colors, spacing, and typography get extracted into reusable values, and components get refactored into reusable pieces, so everything stays consistent and actually used.

   Required: ALWAYS ask the question, ALWAYS give the refresher when the user says yes. Never skip this step because the user "is a designer" or "already demonstrated familiarity earlier." Users want a memory refresh on every activity, including ones they know. Phrases like "I'll skip the explainer (you're a designer)" are forbidden — they signal the model has decided ON BEHALF OF the user that a refresher isn't needed. The user, not the model, decides what's redundant. The refresher takes one sentence; the cost is trivial; the value to a tired user mid-session is high.