By now you have won the argument that the design system is the substrate, planned the re-platform to make it token-first and semantic, and mapped honestly where the cross-platform round-trip is lossy. There is one decision left that you cannot avoid and cannot get back easily once made: which architecture connects your design system to the code substrate that agents read from. Do you center on Storybook as the canonical catalog of coded components? On Figma Code Connect as the bridge between design and code? On a visual-development environment like Codux that edits real source against the live component library? Some combination? This is not a tool-preference question - it is an architecture question, and architecture decisions are expensive to reverse, which is exactly why you write them down. This lesson teaches you to choose the right substrate architecture for your team's specific context and to defend the choice in the format that makes architecture decisions survivable: an Architecture Decision Record (ADR). The artifact is the ADR itself - a one-to-two-page document that states the decision, the context, the options considered, the rationale, and the consequences, so that a year from now, when someone asks "why did we build it this way," the answer is written down and defensible rather than reconstructed from memory and politics.

Why an ADR, and Not a Slide

Most design-tooling decisions get made in a Slack thread, ratified in a meeting nobody minuted, and remembered differently by everyone six months later. That is fine for reversible choices. It is malpractice for an architecture choice, because architecture choices are the ones you live with: the connection between your design system and your code substrate shapes how every agent reads your components, how every designer hands off to engineering, and how much it costs to change tools later. When the choice is expensive to reverse and consequential for years, the cost of writing it down properly is trivial against the cost of not having a record when the original reasoning is contested.

The Architecture Decision Record is a format borrowed from software engineering precisely because engineers learned this lesson the hard way. An ADR captures, at the moment of decision, the context that made the decision sensible, the options that were genuinely considered, the rationale for the one chosen, and the consequences - including the ones you do not like. Its power is not that it makes the decision; it is that it makes the decision legible and accountable. A year later, when the context has changed and someone proposes ripping it all out, the ADR lets you ask the right question: has the context that justified this decision actually changed, or has someone just discovered a shiny new tool? Without the ADR, that conversation is vibes against vibes. With it, it is evidence against evidence.

What Makes This Specifically an Architecture Decision

Be precise about why this rises to architecture rather than tooling. A tooling decision is "we use Stark for contrast checking" - reversible in an afternoon, low blast radius, swap it whenever. An architecture decision is "Storybook is our canonical source of coded components and everything reads from it" - because that choice now constrains how Code Connect maps, how agents query, how engineering builds, and how every future tool must integrate. The test for whether something is an architecture decision is the cost and blast radius of reversing it. The substrate connection fails that test spectacularly: reversing it means re-wiring every consumer, re-mapping every component, and re-training every agent integration. That is architecture, and architecture gets an ADR.

The Three Roles in the Substrate

To choose well, you have to understand that Storybook, Figma Code Connect, and Codux are not competitors filling the same slot - they play different roles, and the architecture question is which roles you need and how they connect. Confusing them as alternatives is the most common analysis error, so separate them cleanly first.

Storybook is the canonical catalog of your real, coded components - their props, states, variants, and (with MDX) their documentation. In the agentic substrate, Storybook is the thing the Storybook MCP server exposes to agents, so it is frequently the center of gravity: it is where the components actually live as code, queryable. If you center your architecture on Storybook, you are saying the coded component catalog is the source of truth and design and agents both read from it.

Figma Code Connect is the bridge between the design representation and the code representation. It does not hold components; it maps a Figma component to its real code implementation so a designer or agent pulling from Figma lands on the actual coded component rather than generated div soup. Code Connect's role is reconciliation - keeping the design world and the code world pointing at the same thing. You need it whenever Figma is a primary design surface and you want agents and engineers reading from Figma to reach real code.

Codux is a visual-development environment that edits real source code against the live component library - a place where you manipulate components visually but the output is genuine code, not an export. Its role is to collapse the gap between visual editing and the code substrate, so that visual work and code stay in sync by construction rather than by reconciliation. Codux is attractive when you want designers and design engineers working visually but directly on the real components, with no handoff and no drift between a design tool and the code.

Storybook is where the components live, Code Connect is the bridge that keeps design and code pointing at the same component, and Codux is the room where you edit the real thing visually. The architecture question is not which one wins - it is which roles your team needs and how they connect.

The Three Archetypal Architectures

From those roles, three archetypal architectures emerge, and most teams should recognize themselves in one of them. The ADR's job is to pick the one that fits your context and say why.

Architecture A: Storybook-Centered, Figma as a Design Surface

Storybook is the canonical coded catalog and the agent-facing source of truth via the MCP server. Figma is where design happens, and Code Connect bridges Figma components to the Storybook-cataloged code so designers and agents reading from Figma reach real components. This is the most common fit for a mature product org with a strong engineering culture, an existing Storybook, and Figma as the design tool. The components live as code, design references them, agents query them, and Code Connect keeps the two worlds reconciled. Its strength is that it builds on the asset most product teams already have (a coded component library) and exposes it cleanly to agents. Its cost is that it requires disciplined Code Connect mapping maintenance, or the design-code reconciliation drifts.

Architecture B: Codux-Centered, Collapsing the Handoff

Codux is the center: designers and design engineers edit the real components visually, the output is genuine code, and there is no design-tool-to-code handoff to reconcile because the visual editing IS the code editing. Storybook may still exist as the catalog, but the design-to-code gap is collapsed by construction rather than bridged. This fits a team with strong design-engineering capability that wants to eliminate handoff drift entirely and is willing to move design work into a code-adjacent environment. Its strength is that it removes a whole class of drift - there is no gap between the design and the code because they are the same artifact. Its cost is that it requires designers comfortable working closer to code and a willingness to adopt a less universal tool than Figma, with the lock-in and team-fit risks that implies.

Architecture C: Figma-First, Code Connect as the Primary Bridge

Figma is the primary design and increasingly the prototyping surface (especially with Figma Make in the mix), and Code Connect is the load-bearing bridge to whatever coded components exist. Storybook is present but secondary; the center of gravity is Figma, and the architecture invests heavily in Code Connect mappings to keep Figma-originated work landing on real code. This fits a design-led org where Figma is deeply entrenched, design drives more of the production, and the priority is making Figma-to-code (including agent generation from Figma) reliable. Its strength is meeting designers where they already are and leaning into Figma's 2026 agentic features. Its cost is that the substrate's reliability now depends on Code Connect coverage and on Figma's roadmap, which is a meaningful vendor-dependency to take on knowingly.

How to Actually Choose: The Decision Inputs

The ADR does not choose by which architecture is "best" in the abstract - there is no best, only best-for-this-context - so the rationale section must show the decision following from real inputs about your team. Five inputs do most of the work.

Where the components already live. If you have a mature coded component library in Storybook, Architecture A builds on it; throwing that away for a Codux greenfield is expensive. If your components are scattered or thin, you have more freedom. The existing substrate is the heaviest input because re-platforming it is exactly the costly work the previous lesson described.

Your design-engineering capability. Codux-centered architectures demand designers comfortable working close to code. If your team is that team, Codux's drift-elimination is a real prize; if your designers live in Figma and are anxious about code, pushing them into Codux is a change-management fight you may not win, and Architecture A or C respects where they are.

How entrenched Figma is. A design org where Figma is the universal language and every workflow assumes it should think hard before de-centering Figma; Architecture C leans in, A coexists, and a Codux-centered move is the biggest cultural lift.

Your agent strategy. If agents reading the substrate is the priority (and after the substrate lesson, it should be), weigh how cleanly each architecture exposes components to agents. Storybook via the MCP server is a mature, direct agent interface; Code Connect makes Figma-originated agent work reliable; Codux's agent story is more about keeping generated edits as real code. Match the architecture to where you most need agent grounding.

Your tolerance for vendor dependency. Architecture C takes on more Figma-roadmap dependency; a Storybook-centered architecture rests on an open, widely-adopted tool; Codux is a more specialized bet. The lock-in-and-data-sovereignty thinking from earlier in this level applies directly: name the dependency you are accepting and the escape hatch you are keeping.

The Artifact: The Architecture Decision Record

Here is the structure of the ADR you will write, following the established ADR convention so it is immediately legible to any engineer who has seen one. Keep it to one or two pages; an ADR that sprawls is not read and not maintained.

1. Title and status. A short, specific title ("Substrate Architecture: Storybook-Centered with Code Connect Bridge") and a status (proposed, accepted, superseded). Status is what lets an ADR be a living record rather than a buried memo.
2. Context. The situation that forces the decision: the substrate argument, where your components live today, your team's capability and Figma entrenchment, your agent strategy, and the constraints. This is where the five decision inputs go, stated as facts about your team, not opinions.
3. Decision. The architecture you are choosing, stated in one clear sentence: which of Storybook, Code Connect, and Codux plays which role, and which is the center of gravity. Decisive, not hedged - an ADR that will not commit is not an ADR.
4. Options considered. The three archetypal architectures (or your variants), each with its strength and cost stated honestly. This section is what makes the decision defensible: it proves you considered the alternatives and rejected them for reasons, not by default.
5. Rationale. Why the chosen architecture follows from the context. Tie each decision input to the choice: "because our components already live in a mature Storybook and our designers work in Figma, a Storybook-centered architecture with Code Connect respects both, where a Codux-centered move would force a code-adjacent workflow our team is not ready for."
6. Consequences. What you are accepting - including the costs and the vendor dependency. "We accept ongoing Code Connect mapping maintenance as the price of reconciliation, and we name Figma-roadmap dependency as a watched risk with this escape hatch." Naming the downsides is what makes the ADR honest and what protects you when a downside materializes - you predicted it.
7. Revisit conditions. The explicit signals that would justify reopening the decision (a tool's pricing changes, the team's capability shifts, an agent interface matures). This converts the ADR from a tombstone into a living decision with a defined trigger for review.

The ADR's defensibility comes from its honesty about the rejected options and the accepted costs. An ADR that only lists the chosen architecture's virtues is marketing; an ADR that says "here is what we gave up and here is the risk we are knowingly taking" is engineering, and it is the only kind that survives the meeting a year from now where the decision is challenged.

Anticipating the Failure Modes

A strategist writing this ADR should pre-empt three failure modes that recur in substrate-architecture decisions.

The shiny-tool reopening. Six months after the ADR, a new tool launches with a great demo and someone proposes throwing out the architecture. The ADR's revisit conditions are the defense: the decision reopens only if the named conditions changed, not because a demo was impressive. The ADR turns "this new thing looks cool" into "does it change a condition we said we would revisit on?" - which is the right question.

The role-confusion analysis. Someone frames the choice as "Storybook versus Code Connect versus Codux," as if they were three products competing for one slot, and the analysis goes nowhere because they are not substitutes. The ADR's options section pre-empts this by framing the choice as which roles you need and how they connect, not which single product wins.

The unstated vendor bet. The team picks Figma-first without naming the Figma-roadmap dependency, and when Figma changes pricing or direction, it feels like a betrayal rather than a known, accepted risk. The ADR's consequences and revisit sections pre-empt this by making the vendor bet explicit at the moment of decision - you took the dependency knowingly, with an escape hatch, so a change in Figma's roadmap triggers a planned revisit rather than a crisis.

What This Makes You as a Strategist

Writing this ADR is where a strategist demonstrates a specific maturity: the ability to make an expensive, hard-to-reverse decision decisively while being completely honest about its costs. Junior decision-makers either refuse to commit (endless evaluation, no decision) or commit without naming the downsides (and get blindsided when the downside arrives). The strategist commits and names the downsides in the same document, which is the only posture that is both decisive and defensible. The ADR is the instrument that forces and records exactly that posture.

And notice the chapter arc closing in. The substrate memo won the principle, the re-platform built the legible substrate, the cross-platform matrix mapped its reach and limits, and this ADR chooses the machinery that runs it. The decision you record here determines, concretely, how the agentic design system you have been arguing for actually connects to the code agents read from. Get the ADR right - decisive, honest about costs, with named revisit conditions - and the architecture is defensible for years. Get it wrong - made in Slack, never written down, framed as a product bake-off - and you will be reconstructing the reasoning under pressure in a meeting where the loudest opinion wins. The ADR is how a strategist makes sure that does not happen.

Key Takeaways

• The connection between your design system and your code substrate is an architecture decision, not a tooling preference, because it is expensive to reverse and consequential for years - which is exactly why it gets an Architecture Decision Record (ADR) rather than a Slack thread.
• Storybook, Figma Code Connect, and Codux play different roles and are not substitutes: Storybook is the canonical coded-component catalog (exposed to agents via the MCP server), Code Connect is the bridge that keeps design and code pointing at the same component, and Codux is the visual-development environment that edits real source against the live library. The analysis error is treating them as three products competing for one slot.
• Three archetypal architectures: Storybook-centered with Figma as a design surface and Code Connect reconciling (the common mature-org fit), Codux-centered to collapse the handoff by construction (for strong design-engineering teams), and Figma-first with Code Connect as the load-bearing bridge (for deeply Figma-entrenched design-led orgs, at the cost of more vendor dependency).
• The choice follows from five context inputs, not from an abstract "best": where the components already live, your design-engineering capability, how entrenched Figma is, your agent strategy, and your tolerance for vendor dependency. The ADR's rationale must tie the decision to these inputs.
• The ADR has seven parts: title and status, context (the five inputs as facts), decision (one decisive sentence), options considered (the archetypes with honest costs), rationale (decision follows from context), consequences (the accepted costs and named vendor dependency), and revisit conditions (the signals that reopen it). Its defensibility comes from honesty about rejected options and accepted costs.
• The ADR pre-empts three failure modes: the shiny-tool reopening (defended by revisit conditions), the role-confusion analysis (defended by framing the choice as roles-and-connections not products), and the unstated vendor bet (defended by naming the dependency and escape hatch at decision time). The mature strategist commits decisively and names the downsides in the same document.