Build or buy a design system: decide layer by layer

The familiar build-versus-buy question hides several decisions. A team might adopt an existing component foundation, generate brand tokens, write product-specific components, use hosted documentation, and keep governance in-house. Calling that arrangement either built or bought discards the information needed to operate it.

Each layer also fails differently. A token package can be correct while a component ignores it. A component library can be accessible in its own fixtures while the product composition creates a keyboard or labeling failure. Documentation might describe the intended system even though the deployed application still resolves an old package version. One label can't tell you who owns any of those mismatches.

The strongest relevant comparison in the frozen research treats buying mainly as adopting an existing component library and building as constructing components. That's useful at the component level. It's too coarse for an organization deciding who owns brand direction, token semantics, documentation, distribution, governance, and evidence.

Don't begin with a vendor list. First, record the estate the system must serve. A component package that fits a single React application may suit native mobile products, several brands, strict offline environments, or a product with unusual data-entry behavior poorly.

• Products and platforms: name the applications, frameworks, devices, and delivery environments in scope.
• Brands and modes: record whether the system must support one identity, several identities, light and dark modes, or customer theming.
• Representative consumers: name one or two real flows that exercise the decisions you care about, such as account creation, a dense data table, or a mobile approval flow.
• Current inconsistencies: identify repeated decisions that already create rework, defects, or uncertainty. Don't substitute a generic component checklist.
• Constraints: include accessibility obligations, localization, browser support, performance budgets, security restrictions, licensing, and release cadence.
• Owners: name who can approve brand decisions, component behavior, technical dependencies, documentation, and product acceptance.
• Change horizon: record known migrations, rebrands, platform changes, or acquisitions that could invalidate a choice.

This context also tells you whether defer is a responsible route. If a proposed shared abstraction has no repeated consumer, no owner, or no way to verify it, keeping the decision local may be safer than making a design-system promise the team can't maintain.

Treat the following matrix as a starting hypothesis, not a universal prescription. The likely route is where many teams can begin. Your recorded constraints and pilot evidence may point elsewhere.

The matrix exposes a common pattern. Upstream artifacts often suit configuration or generation. Teams may adopt commodity implementation mechanics, while product behavior and organizational authority stay local. Verification combines adopted tools with acceptance rules the team must define.

The route states what your team is taking responsibility for. Choose one primary route per layer, then record any narrower exceptions.

Use an external artifact or implementation largely within its supported contract. Adoption works best when the layer is relatively undifferentiated, the upstream project is active, its release and licensing terms are acceptable, and your needs don't require a deep override layer. You still own dependency review, upgrades, local integration, and replacement.

Keep an external engine or structure while supplying supported local values and options. Configuration fits when the extension surface meets your needs and stays within the provider's intended model. If every upgrade requires patches to internals, you're maintaining a fork in practice, whatever the package name says.

Produce a versioned artifact from a brief or governed source. Generation is useful when you can inspect, store, compare, and replace the output. It's a poor boundary when the result is opaque or the team treats generated output as proof that downstream behavior is correct.

Own the implementation and its lifecycle. Build when the layer carries important product differentiation, must enforce domain behavior that an external option can't express, or has constraints that make dependency risk unacceptable. Full control also means paying for maintenance, documentation, migration, support, and verification.

Leave the decision local or unresolved until a stated trigger occurs. Defer when reuse is hypothetical, the team lacks an owner, or the abstraction would freeze an immature pattern. Record what should reopen the decision, such as a second consumer, a repeated defect, a new platform, or an approved brand direction.

Score each route against five questions. Who can change the decision? Does the layer create product differentiation? Who handles maintenance and support? Which external dependency can block or redirect you? How would you replace the choice without rewriting unrelated layers? If a route can't answer the final question, you don't yet understand the commitment.

Use one record per layer. This is narrower than a general architecture or design-system decision record. It preserves why you sourced this layer this way and what you must show before expanding the decision.

Layer: [foundations | tokens | components | documentation | distribution | governance | verification]
Decision state: [proposed | pilot | accepted | revise | rejected | deferred]
Authority: [person or group allowed to approve the layer's decisions]
Source and version: [artifact, package, service, repository, or local source]
Chosen route: [adopt | configure | generate | build | defer]
Scope: [decisions and consumers included]
Explicit exclusions: [what this layer does not provide or prove]
Alternatives considered: [route and candidate]
Rejected because: [constraint or evidence, not preference alone]
Local owner: [maintenance and mismatch owner]
Named consumers: [projects, flows, components, or surfaces]
Compatibility assumptions: [framework, modes, platforms, licenses, release policy]
Required proof: [checks that must pass before acceptance]
Replacement trigger: [event or failure that reopens sourcing]
Exit path: [how consumers can migrate or roll back]
Next review: [event, release, or date]
Disposition: [accept | revise | reject | defer]

Write assumptions as claims that can fail. "Works with our stack" is too vague. You can inspect a claim such as "Package version X supports the framework version used by consumer Y, including the required focus, error, disabled, and loading states." If it isn't verified yet, label it as an assumption instead of filling the gap with confidence.

A replacement trigger stops adoption from becoming permanent through inertia. Examples include an upstream breaking change outside your migration budget, an override count exceeding an agreed boundary, failure in a protected accessibility path, loss of required framework support, or a second product needing a contract the current layer can't express.

A pilot should answer a sourcing question, not stage a polished demo. Choose a consumer that's important enough to reveal real constraints but small enough to reverse. A settings form with validation, keyboard interaction, responsive layout, and both color modes usually teaches you more than an isolated button gallery.

1. 1

   Name the decision under test

   State which layer and route the pilot evaluates. Example: configure an adopted component foundation with generated semantic tokens for the account-settings flow.

2. 2

   Freeze inputs and versions

   Record the source artifacts, package versions, framework version, selected modes, and local mappings. Without them, you can't reproduce a later observation.

3. 3

   Write expectations first

   List the required components, states, content cases, viewports, keyboard paths, and controlled changes before implementation begins.

4. 4

   Implement one real slice

   Use the actual project and integration path where practical. Avoid a special fixture that removes the constraints the sourcing choice must survive.

5. 5

   Record observations separately

   For every expectation, capture what happened, under which condition, against which version, and with what evidence. Don't rewrite the expectation to match the result.

6. 6

   Exercise the exit path

   Revert or replace one bounded part of the integration. A route is safer when you understand how to remove it before broad adoption.

7. 7

   Choose a disposition

   Accept only within the tested boundary. Revise when the route remains plausible but the mapping or ownership must change. Reject when a required constraint can't be met. Defer when evidence is insufficient or the organization can't own the layer.

Teams often declare success when a package installs or a token file appears in the repository. That proves delivery and nothing more. Evaluate the pilot through four distinct states.

These states make failure routing faster. If delivery is wrong, fix distribution. If mapping is wrong, fix the project configuration or transformation. If adoption is wrong, remove the local substitute or correct the component contract. When the observed result is wrong despite the earlier states passing, investigate product composition, runtime behavior, content, environment, or an incorrect expectation.

Accessibility needs the same boundary discipline. A library's documented accessibility focus can inform selection, and an isolated component test can provide useful evidence. Neither proves that your product composition works with real labels, routing, focus movement, modes, zoom, content, and assistive technology. Test the representative consumer under the conditions named in your acceptance scope.

Identity Forge belongs upstream in this decision. It can supply the brand-system and implementation-artifact layer: semantic light and dark color tokens, typography, spacing, layout and motif guidance, DESIGN.md, and structured exports for several delivery routes. That can reduce the work needed to establish and communicate a visual direction.

Ambient Sage v1 is a public example. Its page exposes 28 semantic tokens across light and dark modes, Plus Jakarta Sans for heading and body roles, JetBrains Mono for technical strings, a DESIGN.md, and CSS, Tailwind, DTCG, shadcn, CLI, and MCP routes. You can inspect those upstream artifacts, but they don't prove compatibility with an arbitrary project.

The receiving team still has to decide how roles map into its architecture, whether adopted components consume those roles, which behavior and states the components support, who governs changes, how versions reach products, and what evidence permits release. Identity Forge doesn't replace those responsibilities. Installing an export doesn't establish that the team completed them.

This boundary helps when evaluating any generator. Ask whether its output is versioned and inspectable, which layer it claims to own, what remains unresolved, how local changes survive regeneration, and how you can replace the output. A generated artifact is valuable when it narrows decisions without hiding the ones that remain.

Finish with seven explicit dispositions. Accept, revise, reject, or defer each layer separately. A failed component pilot doesn't automatically invalidate the chosen brand foundations. A good token export can't rescue a component dependency that fails to meet required behavior. Keep those distinctions intact.

• Accept when the required evidence passes within the recorded scope and an owner accepts the remaining obligations.
• Revise when the route is viable but the mapping, contract, ownership, or proof requirement must change.
• Reject when a required constraint fails and you can't correct the layer without crossing the agreed boundary.
• Defer when the team lacks evidence, a real consumer, approval authority, or maintenance capacity. Name the trigger that will reopen the decision.

Record the next verification or replacement trigger beside the disposition. Then expand one boundary at a time: another consumer, platform, mode, brand, component family, or distribution route. This keeps the evidence attached to the conditions it actually covered.

• Design Systems: Build versus Buy: This practitioner comparison frames buying around adopting and theming an existing component library. It identifies activity, accessibility focus, overrides, releases, migrations, and hybrid implementation as evaluation concerns.
• Should We Use a Third-Party Design System or Build Our Own?: The captured community discussion identifies staffing, leadership support, organizational readiness, domain needs, maintenance, and an existing-product audit as practical inputs to a sourcing decision.
• Do Startups Need a Design System? (When to Build vs Buy vs Skip): The captured startup guide broadens the decision from build or buy to build, buy, or skip, organizing investment choices around company stage and system scope.
• Ambient Sage Design Kit: The public Ambient Sage v1 page exposes a DESIGN.md, 28 semantic light and dark tokens, typography and visual rules, and several implementation routes, including CSS, Tailwind, DTCG, shadcn, CLI, and MCP artifacts.
• Design system decision record template: The existing guide separates decision approval from downstream delivery, adoption, and observed product evidence. It records authority, impact, rationale, and verification.
• Design system release checklist: The existing release guide treats source decisions, generated artifacts, documentation, distribution, representative consumers, and rollback as separate release gates.
• Design token handoff checklist: The existing handoff guide traces token decisions through delivered artifacts, project mappings, named consumers, and observed results instead of accepting delivery as completion.