You have already won the argument. Your design lead agrees the design system is the substrate, the budget is approved, and now someone has to turn an existing, lived-in, partially-broken design system into a token-first, semantics-aware structure that AI agents can both read from and write back to. This is the unglamorous middle of the whole strategy, and it is where most re-platformings die - not because the target is unclear, but because the team tries to do it all at once, freezes feature work to do it, loses executive patience by week six, and quietly abandons it. This lesson is about not dying. It hands you a phased re-platforming plan: a way to migrate a real system to a token-first architecture in sequenced stages, each one shippable on its own, each one delivering value before the next begins, with the riskiest work isolated and the rollback always available. The artifact is the plan itself - executive-ready, defensible, and structured so that if leadership pulls the plug at any phase boundary, you have still left the system better than you found it.

Why Re-platform at All, and Why Now

Be honest with yourself before you write a single phase: re-platforming a design system is expensive, disruptive, and invisible to customers. If you cannot articulate why it must happen now, you should not start. The reason it must happen now, in 2026, is the substrate argument from the previous lesson made concrete: your current system was built for human consumers, and agents are now doing a growing share of production against it. A system that humans navigate fine - with its detached instances, its three competing color definitions, its components named for whoever last duplicated them - is precisely the ungrounded substrate that makes agents hallucinate. Re-platforming to token-first is how you make the system legible to the new majority of its readers.

The "token-first" part is the specific structural target. In a token-first system, every value the system expresses - color, spacing, typography, radius, motion, elevation - lives as a named token in a single source of truth, and every consumer (Figma, the codebase, Storybook, the agents) reads from that source rather than redefining the value locally. The "semantics-aware" part is the layer that makes it readable: tokens are not just blue-500 but color.action.primary, so an agent asking "what is the primary action color?" gets a semantic answer it can map to its intent, not a raw hex it has to guess the meaning of. And "read and write against" is the agentic ambition: not only can an agent read your primary color, it can propose a new component that uses the right tokens, and a human can review that proposal as a structured diff rather than a pile of generated guesses.

The Difference Between a Cleanup and a Re-platform

It matters that you call this a re-platform and not a cleanup, because the two are funded and planned differently. A cleanup renames frames and detaches fewer instances; it is hygiene, it is never finished, and it never gets real budget. A re-platform changes the architecture - it introduces a token source of truth that did not exist, restructures the system into primitive, semantic, and component layers, and rewires every consumer to read from the new source. It has a beginning, a middle, and an end. The strategist's job is to plan it as a project with phases and exit criteria, not as an open-ended grooming exercise, because only the former survives contact with a roadmap and a quarter.

The Cardinal Rule: Never Freeze the Product

The single most common way a design-system re-platform dies is the big-bang rewrite: the team announces a freeze, disappears for a quarter to build the new system, and re-emerges to find the product moved on without them, the new system already drifted from the live one, and leadership wondering what they paid for. Do not do this. The cardinal rule of the phased plan is that the product keeps shipping the entire time, and the re-platform proceeds underneath it in stages that each leave the system in a working, shippable state.

This is the strangler-fig pattern borrowed from software architecture, and it is the right mental model. You do not demolish the old system and build a new one beside it. You grow the new structure around the old one, route consumers to the new structure one at a time, and let the old structure wither only as the last consumer leaves it. At every moment there is one working system, not two competing ones. The token source of truth goes in first and the old hardcoded values keep working alongside it; then surfaces migrate to read from the tokens one at a time; then the old definitions are removed only once nothing reads them. If leadership stops the project at any point, you are left with a system that is partly migrated and fully working, not a half-built replacement next to a neglected original.

A re-platform that requires a product freeze is a re-platform that will be cancelled in week six. Plan it so the product never stops shipping and every phase boundary is a place you could stop and still be ahead.

The Five Phases of a Token-First Re-platform

Here is the spine of the artifact: five phases, sequenced so that risk decreases and value compounds, each with an explicit exit criterion. Adjust the boundaries to your system, but keep the sequence, because the sequence is what makes it safe.

Phase 0: Baseline and Audit

Before you move anything, measure what you have. Inventory every value the system expresses today and every place it is defined: how many distinct hexes claim to be the brand blue, how many spacing values are off the scale, how many components are detached from their source, how many hardcoded values live in the codebase. Instrument the agent-grounding failure rate from the previous lesson - the share of generated artifacts that use a non-system value - so you have a baseline to improve against. Phase 0 produces no migration; it produces the map and the baseline number that will prove the re-platform worked. Exit criterion: a documented inventory and a measured grounding-failure baseline.

Phase 1: Establish the Token Source of Truth

Create the token file - DTCG-compliant, structured in primitive, semantic, and component layers - as the new single source of values, and populate it from the audit by choosing the one true value for each token where the system currently has several. Critically, in this phase the token file exists alongside the old hardcoded values; nothing has migrated to read from it yet. You are laying the foundation, not yet routing traffic onto it. This phase is safe because it changes nothing the product depends on - it adds a source, it does not remove one. Exit criterion: a validated, DTCG-compliant token file that expresses the full system, reviewed and agreed as the source of truth.

Phase 2: Wire the Highest-Traffic Surface

Now route the first consumer onto the tokens. Pick the highest-traffic, highest-value surface - the one agents generate most often, the one where drift hurts most - and migrate it to read from the token file. This is your pilot. It proves the source of truth works end-to-end, it produces the first measurable drop in the grounding-failure rate, and it gives you the proof point that funds the rest of the project. Pick deliberately: a surface big enough to matter and contained enough to migrate cleanly. Exit criterion: one real surface fully reading from the token source, with a measured improvement in grounding-failure rate over the Phase 0 baseline.

Phase 3: Roll Out Across Surfaces and Add the Semantic Layer

With the pilot proven, roll the migration across the remaining surfaces, one at a time, on a cadence that fits alongside feature work rather than blocking it. In parallel, this is where the semantic layer earns its keep: as each surface migrates, ensure it reads semantic tokens (color.action.primary) not primitives (blue-500), so the system becomes not just token-first but semantics-aware, which is what makes it legible to agents. This is the longest phase and the one that must coexist with the roadmap, so it is sequenced as a steady cadence, not a sprint. Exit criterion: all priority surfaces reading from semantic tokens, with the grounding-failure rate down across the board.

Phase 4: Enable Agent Write-Back and Retire the Old Definitions

The final phase closes the loop and removes the old structure. Expose the now-clean, documented, semantic system to agents through the Storybook MCP server and Figma Code Connect, so agents can not only read the tokens but propose changes against them - a new component that uses the right tokens, surfaced as a reviewable diff. Then, and only then, remove the old hardcoded definitions, because by now nothing reads them. Add CI enforcement so off-source values cannot re-enter, and drift detection so the system is governed against re-drift. Exit criterion: agents reading and writing against the system through the named pipes, old definitions removed, CI and drift detection in place.

The Semantics Decision: The Load-Bearing Choice

Within the plan there is one decision that does more than any other to determine whether agents can actually use the re-platformed system, and a strategist should call it out explicitly: how aggressively to build the semantic layer. The temptation, under deadline, is to migrate to primitive tokens and stop - to get everything reading from blue-500 and spacing-4 and call it token-first. That gets you a single source of values, which is real progress, but it does not get you legibility, because a primitive token tells an agent nothing about intent. An agent that reads blue-500 still has to guess whether it is the primary-action color, a link color, or a brand-accent, and guessing is exactly the hallucination you re-platformed to prevent.

The semantic layer is what closes that gap. color.action.primary aliasing to blue-500 tells the agent both the value and the intent, so when the agent needs the primary-action color it reads the semantic token directly. The strategic call is to treat the semantic layer as part of the re-platform's definition of done, not as a fast-follow that never arrives. A re-platform that lands token-first but semantically-flat has done the expensive structural work and skipped the cheap layer that makes it pay off for agents - the equivalent of laying the pipes and not connecting the water. The plan should make the semantic layer an exit criterion, not an aspiration.

The Artifact: A Phased Re-platforming Plan

Here is how to assemble the plan as an executive-ready document your design lead can fund and your team can execute. It is longer than a strategy memo because it is an operating plan, but it is still structured so a busy executive can read the first page and grasp the whole shape.

1. The why and the now, in a paragraph. State the substrate argument and the cost of the current state (the grounding-failure baseline). Make clear this is a re-platform, not a cleanup, with a beginning and an end.
2. The cardinal constraint, stated up front. The product keeps shipping; no freeze; strangler-fig migration; every phase boundary is a safe stopping point. Executives fund plans that cannot blow up the roadmap.
3. The five phases, each with an exit criterion and a rough timebox. Phase 0 audit, Phase 1 token source, Phase 2 pilot surface, Phase 3 rollout plus semantics, Phase 4 write-back plus retirement. The exit criteria are the contract: each phase is done when its criterion is met, not when it feels done.
4. The measurement that proves it worked. The grounding-failure rate from Phase 0, re-measured after Phase 2 and again after Phase 3, so the project reports value at every stage rather than only at the end.
5. The semantics-as-definition-of-done callout. Explicitly commit that the re-platform is not done until the semantic layer is in place, so it is not silently dropped under deadline.
6. The rollback and the stop-points. For each phase, state what happens if leadership pulls the plug there - and show that in every case the system is left working and ahead. This is what makes the plan fundable: it has no catastrophic failure mode.
7. The resourcing and the coexistence-with-roadmap note. How many people, what cadence, and explicitly how the work proceeds alongside feature delivery rather than blocking it.

The plan's defensibility comes from two properties an executive can verify at a glance: every phase is independently valuable, and there is no phase whose failure breaks the product. A plan with those two properties is fundable even by a skeptical leader, because the worst case is "we stopped early and the system is partly better," not "we froze the roadmap for a quarter and have nothing to show."

Anticipating the Failure Modes

A strategist plans for how the re-platform fails, not just how it succeeds. Three failure modes recur, and the plan should pre-empt each.

The big-bang temptation. Someone, usually an engineer who loves clean architecture, will propose freezing and rewriting because it is faster in theory. It is not faster in practice; it is the mode that gets cancelled. The plan pre-empts this by making the strangler-fig sequencing non-negotiable and by showing the math: a phased migration that ships continuously beats a frozen rewrite that never ships, every time, on the only metric that matters - whether it lands at all.

The semantics skip. Under deadline, the team migrates to primitives, declares victory, and the agents keep hallucinating because the layer that gives them intent was skipped. The plan pre-empts this by making the semantic layer an exit criterion of Phase 3, so "we did token-first" cannot be claimed without it.

The re-drift. The re-platform lands, and six months later off-source values have crept back in because nothing stops them. The plan pre-empts this by making CI enforcement and drift detection part of Phase 4's exit criteria, so the system is governed against re-drift from the moment it is clean. A re-platform without governance is a re-platform you will be doing again in two years.

What This Makes You as a Strategist

The token-first re-platform is the lesson where the strategist stops arguing and starts operating. The substrate memo won the principle; this plan is how the principle becomes a system. And the craft on display here is not design craft in the usual sense - it is the craft of sequencing irreversible structural change so that it stays reversible at every boundary, ships continuously, and proves its value before it asks for more trust. That is a project-leadership skill, and it is increasingly what separates a designer who can have an opinion about the system from a strategist who can actually change it.

Notice that the artifact is a plan and not a migrated system, for the same reason the previous lesson's artifact was a memo and not a token file. The strategist's leverage is in designing the change and winning the resourcing, not in personally executing every migration. The plan is the instrument through which you make a large, risky, invisible structural investment legible and fundable to people who will never read a token file. Get the plan right and the system follows. Get it wrong - freeze the product, skip the semantics, forget the governance - and you join the long list of teams whose design-system re-platform is a cautionary tale told in a retro.

Key Takeaways

• A token-first re-platform makes the design system legible to its new majority of readers - the agents - by putting every value in a single source of truth, structured in primitive, semantic, and component layers, that every consumer reads from and that agents can read and write against.
• It is a re-platform, not a cleanup: an architectural change with a beginning, middle, and end, funded and planned as a project with phases and exit criteria, not an open-ended grooming exercise that never gets budget.
• The cardinal rule is never freeze the product. Use the strangler-fig pattern - grow the new structure around the old, route consumers over one at a time, retire the old only when nothing reads it - so there is always one working system and every phase boundary is a safe stopping point.
• The five phases: Phase 0 baseline and audit, Phase 1 establish the token source of truth alongside the old values, Phase 2 wire the highest-traffic surface as a pilot, Phase 3 roll out across surfaces and add the semantic layer, Phase 4 enable agent write-back via Storybook MCP and Code Connect and retire the old definitions with CI enforcement and drift detection.
• The load-bearing decision is the semantic layer: token-first but semantically-flat (primitives only) leaves agents guessing intent and still hallucinating. Make the semantic layer (color.action.primary) part of the definition of done, not a fast-follow that never arrives.
• The artifact is a phased re-platforming plan whose defensibility rests on two properties an executive can verify at a glance: every phase is independently valuable, and no phase's failure breaks the product - so the worst case is "stopped early and ahead," never "froze the roadmap with nothing to show."