Design systems as infrastructure, not decoration

The business case

The useful measure of AI-assisted delivery is how long it takes to reach a release your team can stand behind.

A page that appears in two minutes can still require hours of work if it uses the wrong components, misses important states, or introduces another way to solve a problem the product already handles. Multiply that across features and teams, and generation speed becomes a poor proxy for delivery speed.

Our goal is to reduce the decisions people have to explain again and the corrections they have to make afterward.

For someone designing a new flow, the system should provide patterns they can adapt. For an engineer, it should provide reliable APIs and examples. For an AI agent, it needs to make those same decisions discoverable during the task.

That leads to four questions:

• Can the tool find what already exists? A library is useful only if the agent can locate the relevant component and its current implementation.
• Does it understand when to use it? A dialog and a drawer can both contain a form. The choice depends on the task, context, and product conventions.
• Can it use it correctly? Imports, supported properties, dependencies, and required providers need to match the actual project.
• Can the team verify the result? A convincing screenshot doesn’t show whether a failed request preserves someone’s work.

Anthropic’s context engineering guidance describes the broader problem of selecting and maintaining relevant information for an agent. Our application of that idea is straightforward: give the tool the design decisions it needs for the task, with a way to inspect the result.

We expect this to matter most where teams repeatedly assemble forms, dashboards, account settings, and other related flows. A small product can start with a small system. Building a large library before the product needs it adds maintenance before it adds value.

Scope a minimum viable system

We start with a real flow and work outward from it. That keeps the system tied to what the product needs to do.

For a first pass, choose one frequently used flow, the components it depends on, and the states most likely to cause trouble. An account settings form might expose more useful gaps than a polished dashboard full of static cards.

Give tokens meaning

Design tokens are named values for decisions such as color, spacing, typography, and motion. We separate the raw values from the roles they serve.

A primitive such as color.brand holds a value. A semantic token such as color.action-primary explains how that value is used. Components should generally consume the role, so a change in brand or theme doesn’t require every usage to be reinterpreted.

Descriptions help where names leave room for doubt. A token should explain its purpose, appropriate context, and any important restrictions.

The Design Tokens Community Group’s stable 2025.10 format defines types, descriptions, and references for exchanging tokens between tools. It is a Community Group specification, not a W3C Standard. Use the published format where the toolchain supports it and check what survives each import and export.

For example, this small token file separates a brand value from its intended use:

{
  "color": {
    "brand": {
      "$type": "color",
      "$value": {
        "colorSpace": "srgb",
        "components": [0.118, 0.565, 1]
      }
    },
    "action-primary": {
      "$type": "color",
      "$value": "{color.brand}",
      "$description": "Background for the primary action. Use the approved foreground pairing and verify contrast for the intended content."
    }
  }
}

Keep theme mappings explicit. A semantic name alone doesn’t establish dark mode behavior or prove that a color pairing is accessible.

Make components understandable

A component needs more context than a name and a picture. The starting documentation should cover:

Generate API details from code where possible, then add the reasoning that types cannot express. A type definition can list a button’s variants. It cannot explain whether a particular action deserves primary emphasis.

Document complete patterns

Components solve only part of the problem. The system also needs examples of how those components work together.

Consider a save flow: validation, pending state, protection against duplicate submission, a recoverable failure, and a clear confirmation. Those decisions belong together. If every prompt has to reconstruct them, the system is leaving too much work to inference.

Include a few maintained examples with realistic content, long labels, empty results, and failure states. Show how components work together in complete flows, with the behavior and content requirements documented alongside them.

Templates should leave room for product judgment. They are examples to learn from and adapt, not layouts to force onto every problem.

Parity between design and code

We want a designer, an engineer, and an AI tool to be able to identify the same component and understand the same behavior. That requires explicit connections and maintained examples.

Start from what the product actually uses

Audit the current code alongside the Figma library. Agree on which components and tokens should carry forward, which are legacy, and which differences are intentional.

Production code can reveal details missing from design files. It can also contain old decisions that should be retired. Treat an automated audit as evidence to review before promoting anything into the system.

In a public LinkedIn experiment, Andy Weir describes reconstructing Figma foundations from production code using Claude Code and Figma Console MCP. He also reports incomplete variable bindings and naming cleanup. That is a useful example of an audit accelerating the starting work while leaving decisions for a person to resolve.

Connect Figma components to their implementations

Figma recommends structured components, variables, and clear layer names to improve the context an agent receives.

Where available, Code Connect adds implementation references to that context. Its CLI supports detailed property mappings and authored code examples. Its UI provides a quicker connection with basic usage context and custom instructions. Those are different levels of detail; a connection still needs to be checked against the current API.

The baseline is to connect the most-used components first and review those mappings when their implementations change. A screenshot remains useful for composition and visual comparison, alongside the component references.

Keep the underlying guidance portable

The product’s rules should remain understandable when the team changes tools.

Keep component documentation, patterns, and examples in maintained project files. Each AI platform then gets a short entry point that directs it to the relevant material.

These entry points are documented by Anthropic, OpenAI, Cursor, Microsoft, v0, and Lovable. They do not all load instructions or distribute components in the same way.

For example, current Claude Code documentation describes direct AGENTS.md support with version and file-precedence conditions. A small CLAUDE.md can also import shared guidance. Verify what loads in the team’s actual environment before relying on either approach.

Lovable documents copying component source into connected projects, with updates applied when accepted. That has different maintenance implications from importing a versioned package. The delivery method belongs in the setup documentation.

Use MCP where it makes information easier to retrieve

Model Context Protocol provides an interface between AI applications and external tools or context. For a design system, it can help an agent retrieve component documentation, examples, tokens, or test results during a task.

There are already useful implementations. Carbon MCP exposes Carbon resources. The shadcn MCP server supports browsing, searching, and installing registry items. Storybook’s MCP tools connect documentation, story creation, and testing, subject to configuration and framework support. Storybook currently labels its AI capabilities as preview.

Start with the access the team already has. An agent working inside a repository may be able to read the relevant source and documentation directly. A remote or shared system may benefit from an MCP connection.

The check is whether the agent retrieves the right information. Connecting a server doesn’t establish that it selected the correct component, read the relevant example, or followed the instructions.

Give Claude Code a clear route through the system

Anthropic recommends concise project instructions and skills for reusable procedures. Use the project instructions as an entry point and keep detailed component guidance close to its implementation.

This is an example CLAUDE.md excerpt for a fictional project. The paths need to be replaced with real, maintained files:

# Working on the interface

Before changing UI, read docs/design-system/index.md.
Find the relevant component source, API, and maintained example.
Use docs/design-system/patterns.md for flow behavior and content rules.
Use the installed component version; do not invent props or imports.
If a requirement is unsupported, describe the gap and propose an extension.
Report which sources you used, which checks ran, and any unresolved issues.

In this setup, the index identifies the installed library, required setup, current examples, legacy patterns to avoid, and the exact commands available for verification. Test those references in a fresh session to confirm the agent can use them without earlier explanations.

For a concrete task, the prompt could be:

Add an account settings form using the installed design system. Read the system index and existing form pattern first. Show your component choices and any gaps before implementing. Include validation, a pending state, duplicate-submit protection, a recoverable server error that preserves entered values, and success feedback. Follow the documented responsive and keyboard behavior. Run the relevant project checks and report what you verified.

The product request supplies the context for this task. The system supplies the decisions that should carry across tasks.

Governance that fits a small team

AI increases the number of people and tools that can produce interface code. A small team needs a clear way to decide which of those changes belong in the shared system.

Name an owner for system decisions and agree on a lightweight contribution process. A new component or variant should explain the user need, why existing options fall short, and which products will need to maintain it.

There also needs to be a practical way to make an exception. When a feature requires something new, the agent should surface the gap and propose an approach. The team can then choose a local experiment, an extension to an existing component, or a shared addition. Quietly duplicating a component hides that decision from everyone who comes after it.

Release the guidance with the code

Changing a component API should trigger a review of its examples, Figma connection, usage notes, and agent entry points. Otherwise, the tool can follow the documentation correctly and still produce code that doesn’t work.

Record the library version or commit associated with examples and make deprecated patterns easy to identify. Generated reference material should be regenerated as part of the release, so it doesn’t become another independently edited copy.

When design and code disagree, the agent should report the conflict. The team needs to resolve which behavior is intended before updating the related assets.

Put enforceable requirements into checks

Instructions guide an agent’s choices. Checks establish whether specific requirements were met.

Type checking can catch unsupported component properties. Import rules can identify dependencies the project doesn’t permit. Token linting can flag values that bypass an agreed styling policy. Interaction tests can verify important behavior.

Each check needs a defined scope and an exception process. A blanket ban on every raw number or CSS value would confuse useful constraints with ordinary implementation detail.

Anthropic’s documentation explicitly distinguishes model instructions from enforced behavior. We apply the same distinction to design systems: put judgment in guidance, and encode requirements that can be checked reliably in the project’s tooling and release process.

Review the whole experience

Combine component and interaction checks with visual review at relevant sizes and themes. Playwright supports screenshot comparisons, but a baseline still needs human review, and consistent rendering environments matter.

Accessibility also requires more than an automated pass. The W3C Web Accessibility Initiative makes clear that tools alone cannot determine accessibility. Keyboard use, focus order, understandable labels, error recovery, and the assembled experience still need knowledgeable evaluation.

A component can be well implemented and still be used in a confusing flow. Product judgment remains part of the review.

Measure it like infrastructure

We want to know whether the system helps people ship better work with less correction. Component counts and generated lines of code won’t answer that.

Our proposed evaluation uses a small set of representative tasks: adding a settings form, extending a results table, adapting a flow for a narrow screen, and replacing a retired component. Include failure states and an unfamiliar requirement, so the evaluation tests more than copying a template.

Run each task with the current setup and with the proposed system context. Keep the starting code, acceptance criteria, model, tool version, and available permissions comparable. Use fresh sessions, repeat the tasks, and retain failed runs.

Record what the agent actually retrieved, too. If it never read the component documentation, adding more documentation may leave the failure untouched. If it read a stale example, the release process needs attention. If it followed the example and the flow still confused people, the pattern itself may need redesign.

Vendor benchmarks can help identify ideas worth testing. Storybook publishes a benchmark of its MCP documentation tools using the Reshaped component library. That is evidence about its stated setup, not a forecast for a different product or team.

We haven’t published a controlled ProductBloom benchmark for this workflow. The evaluation above is our proposed method, and any future results should include enough setup detail for someone else to examine them.

We also want evidence beyond individual tasks: whether new surfaces adopt the system, whether corrections recur, and whether the maintained patterns help users complete their work. A fast implementation still has to be the right thing to build.

A starting plan

Put a small foundation through real work and find its weaknesses.

Audit one flow

Choose a flow the team understands and expects to change. Compare its Figma assets, production code, and existing documentation. Identify the components, tokens, content rules, and failure states it needs.

Record the current library version and capture the review work involved in a representative change. That gives the team a baseline before introducing new tooling.

Deliverable: an agreed inventory, a list of conflicts to resolve, and one task to evaluate.

Connect the essentials

Consolidate the relevant tokens and components. Document their APIs and usage decisions. Add a maintained example of the full flow, including its failure and recovery behavior.

Connect the Figma components where the available tooling supports it. Add a short agent entry point and confirm that a fresh session can find the intended files and examples.

Deliverable: a working system slice that people and the selected AI tool can use.

Build and inspect

Use the system on the next real change. Review the component choices, inspect the tool’s retrieval, and run the relevant checks. Compare the result with the acceptance criteria and the existing experience.

Add MCP or other integrations where they close an observed access gap. Avoid adding infrastructure before the team knows what it needs to retrieve.

Deliverable: a reviewed implementation and a specific account of what helped, failed, or remained unclear.

Revise and share

Repeat the evaluation, fix recurring gaps, and document the setup. Assign an owner, establish the release checklist, and publish the first revision notes.

Deliverable: a useful foundation, an honest evaluation, and the next changes worth making.

Work toward a shared baseline

The part we would like to develop with other teams is a portable way to describe what an agent needs to build with a design system.

Existing efforts already cover important pieces, including token exchange, component APIs, agent instructions, and tool access. Our proposal is to make the connections between those pieces easier to carry from one environment to another.

For a first discussion, we would expect a reusable system package to identify:

• Its version and dependencies, so the agent knows which implementation it is using.
• Its components and their design references, so design intent can be connected to actual code.
• Its usage decisions and patterns, including appropriate alternatives and known limits.
• Its runnable examples, showing setup, composition, and important states.
• Its verification methods, with clear limits on what each check establishes.
• Its change process, so additions, exceptions, and deprecations stay visible.

This is a proposal to compare and test, not an established industry standard. A useful next step would be for teams using different systems and AI tools to try the same small tasks, publish what each tool could retrieve, and show where context or behavior was lost.

We’re especially interested in whether this holds across frameworks, brands, and products with different accessibility and interaction requirements. Those are places where an approach that works in one project can need substantial adaptation.

Keep shaping this with us

Try the parts that fit your team. Tell us where the guidance helped, where it failed, and what you changed to make it work.

For examples, include the tool and version, the task, the relevant system setup, and the difference between what you expected and what happened. A small reproducible case gives other teams something they can examine and learn from.

We’ll use reviewed contributions to revise the guide, credit contributors who choose to be named, and keep a record of substantive changes. When an idea is still being tested or applies only to a particular setup, we’ll say so.

The next revision should be more useful because more people have put it through real work.

Revision notes

v0.1 · November 8, 2026 · Draft: Reworked the original article around design systems for AI-assisted delivery. Added component guidance, cross-tool setup, a proposed evaluation method, and a shared-baseline discussion. ProductBloom results will be added only when documented.