Restructure Your Design System as AI Context

Workflow area: Design Systems · Tier: Advanced · Hands-on time: ~45 minutes

Design systems were built for human readers: a docs site, some component pages, tribal knowledge filling the gaps. AI generation tools don't read docs sites — they consume structure. When Figma Make, an MCP-connected coding agent, or a First Draft generation reaches into your system, what it finds is variable names, component properties, exemplar files and whatever rules you wrote down. If those are inconsistent or implicit, generation output will be plausible-looking off-system UI: look-alike buttons, near-token colors, layouts that rhyme with your patterns without being them. The stewardship flip is total — your design system is no longer just a kit for designers; it is the context window for every machine that generates on your product's behalf, and it must be authored like one.

When to use — and when not to

• Use it before scaling generation tools across the teamadopting Figma Make or agentic design-to-code with a messy system industrializes off-system output; fix supply before scaling demand.
• Use it when pb-26 reviews keep failing generated UIrecurring compliance violations mean generators can't find or can't parse your system; that's a supply-side defect.
• Use it alongside an engineering token effortStyle Dictionary pipelines and Code Connect mappings multiply the payoff: one semantic layer serving designers, developers and models.
• Skip the big-bang rewriterestructure the components generation actually touches (forms, cards, navigation, buttons) and expand by traffic; a two-year taxonomy project serves no one.
• Skip it without library governanceif anyone can publish unreviewed components, structure decays faster than you build it; establish review-before-publish first (pb-25 helps make the case).

The recipe

1. 1.

   Audit the system as a model would read it. Export your library's component list, variable collections and naming as text, and run the audit:

   Copy

   Here is our design system's component inventory and variable
   collections. Evaluate it as machine-consumable context for AI
   generation tools:
   1. NAMING: which names are ambiguous, inconsistent, or presuppose
      tribal knowledge? (e.g. "Card2", "btn-new-FINAL")
   2. TOKEN GAPS: which values appear as raw hex/px anywhere
      components are defined, instead of bound variables?
   3. STRUCTURE: which components lack defined properties/variants
      for states a generator would need (hover, error, disabled)?
   4. DUPLICATES: near-identical components a generator would
      confuse. 
   Rank findings by how badly each would mislead generation.
   

   Combine with your pb-25 drift audit; the overlap is large and the fixes are shared.

2. 2.

   Rename semantically, one convention, no exceptions. Adopt a scheme where every name states role and hierarchy: button/primary, input/text/error, card/product/compact. Kill pet names and version suffixes — a model cannot know "Enterprise Card v3 FINAL" is the real one. Semantic names are the cheapest, highest-yield fix in the whole playbook: they are simultaneously documentation, search keys and generation guidance.

3. 3.

   Bind everything to variables, and name the variables by intent. Every color, space, radius and type value in every component binds to a variable; variables get semantic names (color/surface/raised, space/inset/comfortable) not value names (gray-100, 16px). Intent-named tokens let a generator choose correctly by meaning — and they flow through Style Dictionary to code, so the model-facing vocabulary and the codebase vocabulary become the same vocabulary. With Code Connect mapping components to their code implementations, the loop closes: design structure, generated UI and shipped code all speak one language.

4. 4.

   Publish exemplar screens — the few-shot layer. Rules tell; exemplars show. Build and publish a small set of canonical screens (a form page, a dashboard, a list-detail flow, an empty state) assembled perfectly from the system: real components, bound tokens, correct patterns, annotated intent. Point generation tools at these as context. This is few-shot prompting in design-file form, and it does more work than any prose guideline — models imitate what they're shown far more reliably than they obey what they're told.

5. 5.

   Write the generation-rules file. The explicit contract for any tool generating on your system — versioned, owned, short enough to live in a context window:

   Copy

   GENERATION RULES — [SYSTEM NAME] v1.0
   1. Use ONLY published components from [LIBRARY]. If no component
      fits, use primitives + tokens and FLAG the gap — never invent
      a look-alike of an existing component.
   2. All values from variables. No raw hex, px, or font sizes.
   3. Patterns: forms single-column, labels above fields; primary
      action bottom-right in dialogs, one per surface; destructive
      actions use button/danger + confirm dialog.
   4. Every screen includes: empty, loading, and error states.
   5. Accessibility: [IMPORT pb-32 CONSTRAINT BLOCK].
   6. Voice: strings follow [pb-27 VOICE SYSTEM]; terms from the
      term base [pb-29].
   7. Exemplars: match the composition patterns in [EXEMPLAR PAGE
      LINKS] — when rules and exemplars conflict, flag it.
   

6. 6.

   Prove it with a generation test — before and after. The acceptance test: prompt the same screen brief through your generation tool against the old structure and the new one, then run both outputs through the pb-26 compliance review. The after-output should use real components and bound tokens with near-zero look-alikes. If it doesn't, the failures name your remaining gaps — fix, regenerate, repeat. Keep this test as a regression check whenever the system or the rules file changes.

Make it yours

• Style Dictionary as the single token source: define tokens once, transform to Figma variables and code constants — the rules file then references a vocabulary that is provably identical on both sides of handoff.
• Code Connect for component provenance: mapping Figma components to code components means generated code inherits the same on-system guarantee as generated frames — and MCP consumers (pb-34) resolve your components to real imports instead of bespoke divs.
• Claude Project as the system's context bundle: publish the rules file, component inventory and exemplar screenshots into a shared Project so every ad-hoc generation your teammates run in chat carries the system with it — not just the tools formally wired to the library.

Quality check

• Names are self-evident to a strangera person (or model) with zero tribal knowledge picks the right component by name alone; ambiguity you can spot, a generator will act on.
• Zero raw values inside published componentsthe drift audit (pb-25) comes back clean on the restructured set.
• Exemplars are flawless and currentthey are the strongest signal you publish; one off-system exemplar teaches every future generation the wrong lesson.
• The rules file is versioned, owned and shortan unowned rules file forks and rots; one that can't fit in a context window can't do its job.
• The generation test passes and stays passingon-system output from a cold prompt is the definition of done, re-verified after every meaningful system change.