Book a call

WritingAI-ready design systemsPart 10 of 20 in Making your design system AI-ready

How to make a legacy design system AI-ready: a phased migration plan

Almost nobody starts from a blank page. A phased plan for a five-year-old system that stays in use: measure, consolidate into one source of truth, make it machine-readable, add access, align Figma, and migrate old code with codemods and a lint ratchet.

Diagram: a legacy system's conflicting token files, packages and docs consolidate into one source of truth that generates every output.
On this pageThe situation most teams are in
  1. The situation most teams are in
  2. Four principles for the migration
  3. The phased plan at a glance
  4. Phase 0: baseline (weeks 1–2)
  5. Phase 1: one source of truth (weeks 2–6)
  6. Phase 2: machine-readable (weeks 5–10)
  7. Phase 3: access (weeks 8–12)
  8. Phase 4: Figma (weeks 8–14)
  9. Phase 5: guardrails and migrating old code (from week 3, ongoing)
  10. Who does what
  11. Troubleshooting
  12. The final checklist
  13. The whole series in one paragraph
  14. The short version
  15. Frequently asked questions
  16. Further reading

The short answer

Make a legacy design system AI-ready in phases, without a rewrite, while it stays in use. Phase 0: measure how agents do today. Phase 1: establish one source of truth: tokens in DTCG JSON, one current component per job, deprecations marked. Phase 2: make it machine-readable: token descriptions, component metadata, structured docs. Phase 3: give agents access: rules files in every repo, then an MCP server. Phase 4: align Figma: variables, component properties, Code Connect. Phase 5, throughout: guardrails and migration: lint that ratchets, codemods for the mechanical work, evals to prove progress. Each phase is useful on its own, and the order matters: access before cleanup just helps agents find the mess faster.

  • A mid-sized system can reach "reliably useful" in about three months of part-time work. The full migration of old code takes longer, and that's fine.
  • Prioritise by usage: the 20 components and 50 tokens agents touch most cover most screens.
  • Part 10 of 20 in the series on AI-ready design systems.

The situation most teams are in

If you've read the first nine parts, you know what an AI-ready design system looks like. But almost nobody starts from a blank page. Most teams have a system that's five or more years old, used by every product, with history baked in. That's where Kestrel's Harbor, our running example, started. Here's its starting point, drawn the same way as the target architecture in part 1.

Tokens
_colors.scss212 variables, no descriptions
Figma stylesHand-made, different names
Tailwind configDefault palette plus extras
Components
@kestrel/harborCurrent, 61 components
@kestrel/ui-oldStill in 40% of files
src/legacy/Copied components in each app
Docs
ConfluenceLast major update 2024
StorybookStories for 70% of components
Access
NothingEngineers paste reminders into prompts
Checks
Types onlyLoose prop types; no design system lint
Before. Illustration Outlined boxes are sources that disagree with each other or with the code. Every one is a place an agent can pick up the wrong answer.

And here's where it ended up after the work in this article. Nothing was rewritten from scratch. Most of the change is in where things live and what's generated from what.

Source
tokens/*.jsonDTCG, described · part 3
src/<Name>/Typed component, meta.json, stories, docs · parts 4–5
Generated
CSS, Tailwind theme, Figma variablesSame names everywhere
Agent manifeststokens / components .agent.json
AGENTS.snippet.md, lint configFrom deprecations
Docs site, llms.txtFrom docs/*.md
Access
AGENTS.md in every repoPart 6
harbor MCP serverPart 7
Figma MCP + Code ConnectPart 8
Guardrails
Lint · tests · evals · telemetryPart 9
After. Two kinds of source that people edit; everything else is generated, so nothing can silently disagree.

Four principles for the migration

1

Don't rewrite; re-home

Most legacy knowledge is fine; it's just in the wrong place. Move tokens into JSON, docs next to code, rules into metadata. Rewrites stall; moves finish.

2

One truth before many doors

An MCP server over three conflicting token files serves conflicts. Fix the source of truth (phase 1) before adding access (phase 3).

3

New code first, old code later

Hold new code, including all agent code, to the standard immediately. Migrate old code gradually, with codemods and a lint ratchet.

4

Measure every phase

Run the same evals before and after each phase. The numbers decide what's next, and they're what keeps sponsors interested.

The phased plan at a glance

PhaseWeeksMain workDone when
0 · Baseline1–2Agent's-eye audit, inventory, eval setScores recorded for 10–15 tasks
1 · One source of truth2–6Tokens to DTCG, duplicates resolved, deprecations markedEvery job has one token and one component; old ones say what replaces them
2 · Machine-readable5–10Token descriptions, component metadata, docs moved and restructuredManifests build in CI; coverage checks pass for the top 20 components
3 · Access8–12AGENTS.md snippet in all repos, MCP server, llms.txtAgents call the tools in every eval run
4 · Figma8–14Variables synced from tokens, properties mirror props, Code Connect for top componentsFive sample frames generate on-system code
5 · Guardrails & migrationStart week 3, ongoingLint on new code, codemods, ratchet, monthly evalsDeprecated usage falls every month; pass rates hold
Illustration Timings for a system the size of Harbor (about 60 components, 200 tokens) with two part-time maintainers and help from champions. Phases overlap on purpose.
W1W2W3W4W5W6W7W8W9W10W11W12
0 · Baseline
1 · Source of truth
2 · Machine-readable
3 · Access
4 · Figma
5 · Guardrails
The same plan over the first 12 weeks. Figma work and guardrails continue after week 12. Guardrails start early (lighter cell: warnings only), because every week without them adds more off-system code to migrate later.

Phase 0: baseline (weeks 1–2)

You can't show improvement without a starting number, and you can't prioritise without knowing where agents fail.

  1. Run the agent's-eye audit

    Three tasks, fresh sessions, transcripts saved, as in part 2. Note which files the agent found and which it never did.

  2. Inventory duplicates and drift

    List every component and its lookalikes across packages and legacy folders, with how often each is imported. List every token and where its values also appear raw. A design system audit covers the method.

  3. Build the eval set

    10–15 golden tasks from real tickets, scored with the script in part 9. Run each three times. Save the results with the date.

  4. Score readiness

    Use the 12-statement self-assessment in part 1. The lowest-scoring layer is usually where phase 1 should focus.

38%Harbor's baseline: eval runs passing lint and types
3Buttons, 4 dialogs and 2 date pickers in active use
4.6Hard-coded colours per agent run, on average

Illustration Harbor's numbers are made up but typical.

Phase 1: one source of truth (weeks 2–6)

This phase has the biggest effect on agents and on people, and it's mostly decisions, not code.

Decide where each kind of knowledge lives

KnowledgeLives in (edited by people)Generated from it
Token values and descriptionstokens/*.json (DTCG)CSS, Tailwind theme, Figma variables, agent manifest
Component APITypeScript types and JSDocProps tables, metadata props, Storybook controls
Usage judgement<Name>.meta.jsonAgent detail files, "Never use" list, lint config
Patterns and explanationsdocs/**/*.mdDocs site, .md pages, llms.txt
ExamplesStoriesDocs examples, metadata examples, visual tests
Figma ↔ code mapping*.figma.tsx (Code Connect)Dev Mode snippets, Figma MCP context
The source-of-truth map. Write it down and share it: half the arguments in a design system team are about where something should be changed.

Resolve duplicates with a simple decision

For each group of lookalike components (three buttons, four dialogs), decide once and record the decision in the metadata:

ComponentImportsDecisionReplacement
Button (harbor)1,240Keep–
BtnPrimary (harbor)310Deprecate, keep as wrapperButton variant="primary"
Button (ui-old)890Deprecate; codemodButton (harbor)
Modal (harbor)205DeprecateDialog or ConfirmDialog
AlertDialog (harbor)48Merge into ConfirmDialogConfirmDialog
Illustration Deprecate means the old component keeps working, warns, and names its replacement, as in versioning and deprecation.

Move tokens into DTCG

Convert the SCSS variables to DTCG JSON, keeping the old names as deprecated aliases so nothing breaks (the steps are in part 3). Make the generated CSS the only place product code gets values from. Then delete the old Tailwind palette and replace it with the semantic theme.

Tell agents to stay out of legacy folders now

Before any metadata exists, add a nested AGENTS.md in each legacy folder ("This folder is being removed. Don't copy patterns from here.") and the deprecated list in each repo's root AGENTS.md. This is an hour's work that stops agents spreading old code while the rest of the migration happens.

Phase 2: machine-readable (weeks 5–10)

Now make the single source of truth readable by machines. Work through the system in order of usage, not alphabetically: the 20 most-imported components and the 50 most-used tokens cover most screens.

  1. Describe semantic tokens

    "Use for… Not for… Use instead…" for every semantic token. Draft with an AI assistant from usage data, then have a designer review. CI fails on missing descriptions. (Part 3.)

  2. Tighten component types

    Union types for every option prop, JSDoc on every component and prop, safe defaults, @deprecated tags. (Part 4.)

  3. Write metadata files

    Purpose, useWhen, avoidWhen and rules for the top 20 components, validated against the schema. Merge duplicates you couldn't distinguish. (Part 4.)

  4. Move and restructure docs

    Move component docs from Confluence into docs/ next to the code, rewrite them to the template with self-contained sections, and delete or mark the old pages. (Part 5.)

  5. Build the manifests

    Add the agent-manifest outputs to the build and coverage checks to CI. From now on, deprecating something updates every output in one release.

Phase 3: access (weeks 8–12)

  1. Ship the AGENTS.md snippet

    Generate it from metadata, ship it in the package, and insert it into every product repo with the marker command. Add CLAUDE.md, Cursor and Copilot pointers where teams use those tools. (Part 6.)

  2. Add the MCP server

    If you're on React with good stories, try Storybook's MCP addon. Either way, add the small custom server for tokens, patterns and usage rules, and commit the MCP configs. (Part 7.)

  3. Publish llms.txt

    Add .md versions of docs pages and a generated llms.txt to the docs site, if it's reachable by the tools your teams use. (Part 6.)

  4. Rerun the evals

    This is usually where the biggest jump appears. Check transcripts: agents should call the tools before writing UI.

Phase 4: Figma (weeks 8–14)

Run this in parallel with phase 3, led by the system designer.

  1. Sync variables from tokens

    Replace hand-made styles with variables generated from the DTCG source, with code syntax and descriptions set; hide primitives from publishing. (Part 8.)

  2. Rename properties to mirror props

    Variant values and boolean properties named like code, for the top 20 components first. This is a breaking change for Figma files, so announce it and give designers a swap guide.

  3. Add Code Connect

    Mappings for the top 10–20 components, published from CI with each release.

  4. Introduce the "ready for build" checklist

    Attached instances, auto layout, bound variables, named frames, for frames that will be implemented.

Phase 5: guardrails and migrating old code (from week 3, ongoing)

Start guardrails early and keep them going. The migration of old code is the longest part of the work, and it doesn't need to finish before agents are useful. It needs to move steadily in the right direction.

The lint ratchet

Week 3Rules on, as warnings everywhere; count recorded
→
Week 4Errors on changed files: all new code must pass
→
MonthlyCI fails if the total count rises above last month's
→
CodemodsBulk fixes cut the count in steps
→
FinishErrors everywhere; old package removed
A ratchet only turns one way. New code is held to the standard immediately; the old count can only go down.

Codemods for the mechanical part

A codemod is a script that rewrites code automatically. For renames and simple replacements it's faster and more reliable than either people or agents doing it file by file. Here's one, using jscodeshift, that replaces Harbor's deprecated BtnPrimary with Button variant="primary":

// codemods/btn-primary.js
// Run: npx jscodeshift -t codemods/btn-primary.js src --parser=tsx --extensions=tsx
export default function transformer(file, api) {
  const j = api.jscodeshift;
  const root = j(file.source);
  const uses = root.findJSXElements("BtnPrimary");
  if (uses.length === 0) return file.source;

  // <BtnPrimary …> → <Button variant="primary" …>
  uses.forEach((path) => {
    const { openingElement, closingElement } = path.node;
    openingElement.name = j.jsxIdentifier("Button");
    openingElement.attributes.unshift(j.jsxAttribute(j.jsxIdentifier("variant"), j.stringLiteral("primary")));
    if (closingElement) closingElement.name = j.jsxIdentifier("Button");
  });

  // import { BtnPrimary } from "@kestrel/harbor" → import { Button } …
  root.find(j.ImportDeclaration, { source: { value: "@kestrel/harbor" } }).forEach((decl) => {
    const specs = decl.node.specifiers;
    const hasButton = specs.some((s) => s.imported?.name === "Button");
    decl.node.specifiers = specs
      .filter((s) => !(hasButton && s.imported?.name === "BtnPrimary"))
      .map((s) => (s.imported?.name === "BtnPrimary" ? j.importSpecifier(j.identifier("Button")) : s));
  });
  return root.toSource();
}

Run it on a branch, review the diff, run the check command, and merge. Then ship the codemod in the design system package (npx harbor codemod btn-primary) so product teams can run it themselves. Agents are good at the judgement cases codemods can't handle, such as choosing between Dialog and ConfirmDialog for each old Modal, especially with a skill that explains the decision (part 6). Review those changes like any other. More in design system migration.

Who does what

RoleOwnsTime, roughly
Design system leadDecisions on duplicates and deprecations; the plan; reporting eval results to sponsors20–30% for the duration
Design technologist or system engineerToken pipeline, manifests, MCP server, lint, codemods, evals50–80% for phases 1–3
System designerToken descriptions, usage rules, Figma variables and properties, Code Connect review40–60% for phases 2 and 4
Champions in product teamsRunning codemods, reviewing agent output in their area, reporting gapsA few hours a month
Illustration A starting point for planning. Small systems can do this with one person part-time; see team structure.

Troubleshooting

SymptomLikely causeWhat to do
Agents still use legacy components after phase 3Legacy code vastly outnumbers new code, so search keeps surfacing itNested AGENTS.md in legacy folders; lint errors on changed files; prioritise codemods for the most-imported legacy items
Agents ignore the MCP toolsDescriptions don't say when to call them; rules file doesn't name them"Call before writing any UI" in the description; name the tools in AGENTS.md
Agents pick the wrong one of two similar componentsPurposes overlapRewrite both purposes with avoidWhen pointing at each other; consider merging
Token choices still wrong for some jobsMissing or vague descriptions for near-identical tokensRun the choice test from part 3; sharpen or merge
Figma-to-code ignores the systemDetached instances, raw values, no Code Connect for those componentsReady-for-build checklist; Code Connect for the components in that frame
Eval scores jump around between runsToo few runs; tasks too vagueRun each task more times; make the expected result specific
Teams see the lint rules as blockersErrors on old code they didn't touchErrors on changed files only; give them codemods, not just errors

The final checklist

When these are true, your system is AI-ready in the sense defined in part 1: agents can find the right thing, understand it, use it correctly, and know when they got it wrong.

  • One source of truth for tokens (DTCG JSON) and components (one current component per job), with everything else generated.
  • Every semantic token described, and primitives hidden from product code, agents and Figma publishing.
  • Every stable component has metadata: precise types, purpose, when to use, when not to, rules, example. Every deprecated one names its replacement.
  • Docs live next to the code, follow the template, and old pages are gone or excluded from search.
  • Every product repo has the generated AGENTS.md section and the MCP config.
  • Figma variables and properties match code, and the most-used components have Code Connect.
  • Lint, types and tests run in the agent's loop and in CI, with fix-it messages.
  • Evals run monthly, and the results are shared.

The whole series in one paragraph

AI agents amplify whatever your design system already is. They read literally, can't ask, forget everything between sessions, and copy what they find first. So write your decisions down where machines can read them (described tokens, typed and annotated components, self-contained docs), point every agent at them (rules files, MCP servers, Figma's server with Code Connect), and check the result automatically (lint with fix-it messages, tests and evals). Do it in phases, starting with one source of truth, and measure each step. The same work makes the system clearer for every person who uses it.

The short version

  • Migrate in phases, without a rewrite: baseline, one source of truth, machine-readable, access, Figma, with guardrails throughout.
  • Fix the source of truth before adding doors to it.
  • Prioritise by usage: the most-used components and tokens first.
  • Hold new code to the standard now; migrate old code with codemods and a lint ratchet.
  • Measure every phase with the same evals, and share the numbers.

Next: parts 11–20 answer the questions teams ask most, starting with Why does AI ignore my design system? Or see the whole collection under AI-ready design systems.

Frequently asked questions

How do I make an existing design system AI-ready?

In phases: measure how agents do today, establish one source of truth (DTCG tokens, one current component per job, deprecations), make it machine-readable (descriptions, metadata, structured docs), add access (AGENTS.md, an MCP server), align Figma (variables, Code Connect), and add guardrails and codemods throughout.

Do I need to rebuild my design system for AI?

No. Most of the work is moving knowledge into the right places and formats, resolving duplicates, and adding generated outputs and checks. Rewrites tend to stall; phased changes keep the system in use while it improves.

How long does it take to make a legacy design system AI-ready?

For a system of around 60 components and 200 tokens with two part-time maintainers, about three months to reach the point where agents are reliably useful. Migrating all old code to the new standard takes longer and can continue gradually.

What should I do first?

Run three real tasks with a coding agent and record what goes wrong, then add an AGENTS.md with your package name and a "never use" list. It takes about a day and usually fixes the worst failures.

How do I migrate legacy components safely?

Deprecate rather than delete: keep old components working with a warning that names the replacement, use codemods for mechanical changes, have people or agents handle judgement cases with review, and use a lint ratchet so the count of old usages can only go down.

Further reading