1. Define the release unit
Start by naming what the decision covers. A design-system release is rarely one file. It may contain source tokens, generated CSS, DTCG data, framework mappings, component packages, registry items, design libraries, documentation, and migration notes. If the record says only "release 4.2," reviewers cannot tell whether all those outputs came from the same approved source.
- Source identity: repository, commit or immutable revision, and the source-system version.
- Changed public contracts: token names, values, modes, component APIs, variants, states, behaviors, assets, or written rules.
- Generated artifacts: exact filenames, package versions, registry items, downloads, design-library versions, or content hashes.
- Documentation set: release notes, migration guidance, deprecations, component documentation, and known exceptions.
- Distribution targets: the package registry, component registry, CDN, shared library, download route, or other channel consumers will use.
- Named consumers: representative applications, platforms, product surfaces, and local libraries selected for verification.
- Decision owners: the release owner and the person authorized to initiate and verify rollback.
Do not let a label stand in for identity
A version string helps only when it resolves to the reviewed content. Record an immutable revision or artifact digest where the distribution system permits it. If you cannot establish that identity, mark the field unresolved.
2. Build the change-reach register before testing
Choose tests based on the change's reach, not the size of its diff. A one-line semantic-token change may affect many components in two modes. A large documentation correction may affect no runtime surface. For every changed contract, follow aliases, transformations, artifacts, components, local libraries, and product surfaces until you reach named consumers.
| Question | Release evidence | |
|---|---|---|
| Source contract | What approved role, API, rule, or asset changed? | Source revision, authority, rationale, compatibility classification |
| Alias and mode reach | Which aliases, themes, modes, or platform mappings resolve from it? | Dependency trace with unresolved branches marked |
| Artifact reach | Which generated files, packages, registry items, or libraries should change? | Expected artifact identifiers and inspected output |
| Component reach | Which components, variants, and states consume the contract? | Named fixtures or component checks |
| Consumer reach | Which applications and surfaces should change? | Representative consumer, version, condition, and observation |
| Protected surfaces | What must remain unchanged? | Comparison or test showing the protected behavior |
Unknown reach does not mean there is no impact. Keep it visible as unresolved, assign a correction owner, and decide whether it is material enough to block. If the change is a contribution still awaiting source approval, complete the procedure in /learn/design-system-contribution-guidelines first. For token aliases or deprecations, use /learn/dtcg-design-token-aliases and /learn/design-token-deprecation-strategy instead of compressing those checks into a generic release box.
3. Gate the source decision
The source gate asks whether the change itself is approved and specified well enough to release. Record who had authority, why the change exists, which public contract it affects, its intended consumers, and any permitted exceptions. State whether migration or deprecation work is required, too.
- The source revision is fixed and reviewable.
- The changed contract is named precisely.
- The decision owner and rationale are recorded.
- Compatibility is classified against the project's documented policy.
- Breaking changes have migration or deprecation handling.
- Intended consumers and protected surfaces are named.
- Exceptions are bounded rather than implied.
Use Semantic Versioning only if the project has declared a public API and adopted SemVer as its versioning policy. Under SemVer, incompatible public API changes require a major increment, backward-compatible additions require a minor increment, and backward-compatible fixes require a patch increment. A design change is not automatically major or minor because it feels large. Classify it against the declared public contract.
Policy before arithmetic
Version numbers communicate a compatibility promise. They cannot supply a missing promise. If the public API or compatibility policy is undefined, resolve that governance gap instead of treating a version bump as a substitute.
4. Gate generated artifacts
Reproduce generation in the recorded environment, then inspect the output. Keep four statements separate: a warning from the tool, an expectation written before inspection, an observation from the resulting artifact, and the acceptance decision based on that evidence.
- 1
Pin the inputs
Record the source revision, generator and dependency versions, configuration identity, platform target, and relevant mode or theme inputs.
- 2
State the expected delta
List the symbols, values, modes, aliases, component contracts, or files expected to change. Also name outputs expected to remain stable.
- 3
Regenerate from the fixed source
Use the project's reproducible process. A locally edited output or an artifact left over from another revision cannot establish the release result.
- 4
Inspect the output
Check required symbols, resolved values, mode separation, filenames, metadata, and any platform transformation relevant to the changed contract.
- 5
Preserve artifact identity
Record the package version, content hash, registry identifier, immutable URL identity, or equivalent evidence that can later be matched to distribution and consumers.
A validator pass has a narrow boundary. It shows that an input passed the checks implemented by that validator for its stated target. It does not show that another transformation preserved the values or that an application consumed the intended output. Use /learn/how-to-validate-dtcg-design-tokens for DTCG validation and /learn/style-dictionary-dtcg-tokens for Style Dictionary transformation checks.
Start with an implementation-ready upstream system
A complete kit can supply the tokens, typography, spacing, component guidance, and DESIGN.md that enter this release process. Your team still owns packaging, consumer verification, approval, and rollback.
5. Gate distribution and documentation
Now prove that consumers can obtain the artifact you reviewed. Check the intended package, registry, shared library, CDN, or download route from a clean consumer context, then match its identity to the artifact record. Do not infer that match from a successful publish command.
- The distribution target resolves to the reviewed artifact identity.
- Installation or update instructions use the current route and version.
- Release notes name the actual changed contracts and affected consumers.
- Migration guidance covers every breaking contract in scope.
- Deprecation notices identify replacements and supported transition behavior.
- Component documentation describes the current API, states, limitations, and exceptions.
- Local-library expectations identify which downstream libraries must align with the release.
Documentation is part of the release because it carries the contract consumers use. Still, it is distinct from runtime proof. Accurate migration guidance cannot show that a package contains the intended file, while a correct package cannot show that its documentation describes the current behavior. Record both observations. For component documentation coverage and Storybook authority boundaries, use /learn/storybook-design-system-documentation.
6. Gate representative consumers
Choose consumers from the change-reach register. The sample should cover distinct transformation paths, modes, component states, viewports, platforms, and high-risk product surfaces. It does not need to include every screen, but you should be able to explain every omission from the recorded reach.
Write the expected result before opening the consumer. Name the application and version, artifact identity, component or surface, state, mode, viewport or platform, expected change, and protected behavior. Then record what you observed. This keeps a plausible render from quietly redefining the requirement.
| What belongs here | What does not | |
|---|---|---|
| Expectation | The result predicted from the approved contract before inspection | A description written after seeing the output |
| Observation | What happened in a named version, fixture, state, mode, and environment | A claim about untested consumers |
| Exception | An authorized, bounded divergence with owner and review condition | An unexplained mismatch |
| Decision | Accept, revise, or block, with the evidence used | A test log without an approval conclusion |
Storybook visual tests can provide component-level evidence by rendering stories, detecting visual changes, and supporting review in continuous integration. Their proof covers only the stories, configuration, browser conditions, and artifacts tested. They do not establish whole-product behavior. Use /learn/ai-ui-review-checklist for product task, resilience, and accessibility evidence, and /learn/design-system-accessibility-checklist when accessibility is in scope.
Include a protected surface
For each intended change, inspect at least one meaningful consumer that should remain unchanged. This catches alias fan-out, overly broad transformations, and local mappings that share more authority than the source contract intended.
7. Route failures to the owning layer
A failed consumer check does not automatically make the source decision wrong. Trace backward until the expectation and observation first diverge. Assign the fix at that point, then repeat the downstream checks affected by the correction.
| Typical signal | Next evidence | |
|---|---|---|
| Source decision | Intent, authority, compatibility, or expected behavior is ambiguous | Corrected approved contract and updated reach |
| Transformation | Source is correct but an emitted value, alias, mode, or symbol is wrong | Regenerated artifact from pinned inputs plus inspected output |
| Packaging or distribution | Reviewed output differs from what consumers install or fetch | Resolved distribution identity matched to the reviewed artifact |
| Documentation | Instructions, release notes, API details, or migration guidance describe another state | Corrected documentation tied to the same release identity |
| Component contract | The component consumes the wrong role or mishandles a supported variant or state | Corrected component fixture and relevant state evidence |
| Consuming application | A local override, stale dependency, composition, or product rule defeats the shared contract | Corrected named consumer and repeated protected-surface check |
Warnings and failures are different. A known generator warning may be acceptable if its consequence is understood and authorized. Missing evidence means the result is unknown. A confirmed regression means the result is known and wrong. Do not combine all three in one "issues" field.
8. Define rollback before approval
Rollback starts as a release condition, not an improvised response after distribution. Tie each trigger to the exact artifact and affected consumers. Name who can initiate restoration, which supported path they will use, and what evidence will prove that restoration worked.
- Trigger: the observable condition that requires rollback, such as a protected consumer regression or a compatibility break outside the approved scope.
- Release identity: the source revision and distributed artifact being withdrawn or superseded.
- Restoration target: the last supported artifact or forward correction approved for use.
- Affected consumers: the applications, libraries, platforms, or surfaces that must move.
- Rollback owner: the person authorized to coordinate the response.
- Restoration path: the supported package, registry, library, or deployment mechanism.
- Post-restoration evidence: the consumer checks, artifact identity, and protected-surface observations required to close the incident.
Rollback is more than republishing an old version
A restoration succeeds only when named consumers resolve the intended artifact and the failed conditions have been rechecked. If consumers cache, copy, transform, or locally override system artifacts, restoring the distribution target alone may be insufficient.
9. Choose accept, revise, or block
| Accept | Revise | Block | |
|---|---|---|---|
| Evidence state | All material gates have matching expectations and observations | A correctable mismatch remains, but the approved contract and safety boundary are clear | Material evidence is missing, contradictory, or shows a confirmed regression |
| Exceptions | Every exception is authorized, scoped, owned, and reviewable | Exception wording or implementation needs correction before approval | An unapproved exception changes a public contract or protected surface |
| Distribution | The exposed artifact matches the reviewed identity | Distribution or documentation can be corrected before release | The wrong or unidentified artifact is exposed |
| Consumers | Representative consumers and protected surfaces meet recorded expectations | A bounded consumer or component fix must be retested | A material consumer fails or the selected sample cannot support the claim |
| Rollback | Triggers, owner, restoration path, and verification are ready | Rollback details need completion before approval | No supported restoration path exists for the material risk |
Accept does not mean the design system is universally correct. It means the evidence supports the declared release scope. Revise sends specific work back to an owner and requires the affected gates to run again. Block stops distribution or approval because the current record cannot support the release.
10. Copy the release decision record
Keep the record beside the release evidence or in the system your team uses for decisions. Its format matters less than stable identities, explicit unknowns, and a final disposition another reviewer can reproduce.
release:
release_id: ""
release_owner: ""
rollback_owner: ""
proposed_version: ""
disposition: "accept | revise | block"
decided_at: ""
source:
system: ""
revision: ""
authority: ""
rationale: ""
compatibility_policy: ""
compatibility_classification: ""
changed_contracts:
- contract: ""
intended_change: ""
intended_consumers: []
protected_surfaces: []
aliases_modes_transformations: []
migration_or_deprecation: ""
unresolved_reach: []
artifacts:
- name: ""
type: "package | registry | library | file | download"
generator_version: ""
expected_identity: ""
observed_identity: ""
expected_delta: ""
observed_delta: ""
warnings: []
accepted: false
distribution_and_docs:
- target: ""
expected_artifact: ""
observed_artifact: ""
release_notes: ""
migration_guidance: ""
component_docs: ""
observation: ""
consumer_checks:
- consumer: ""
consumer_version: ""
artifact_identity: ""
surface: ""
state_mode_viewport: ""
expectation: ""
observation: ""
protected_behavior: ""
result: "pass | revise | block | unresolved"
exceptions:
- description: ""
scope: ""
authority: ""
owner: ""
review_or_expiry_condition: ""
corrections:
- failure_layer: ""
owner: ""
required_evidence: ""
status: ""
rollback:
triggers: []
affected_artifacts: []
affected_consumers: []
restoration_target: ""
restoration_path: ""
verification_required: []
unresolved_fields: []
decision_rationale: ""Ambient Sage v1 as an upstream intake example
Token specimen · real values
Ambient Sage
Live renderAmbient Sage's actual tokens — the same values its exports use.
For this example, record ambient-sage, public version v1, and the available DESIGN.md, DTCG, CSS, Tailwind, and shadcn outputs. Do not invent artifact hashes or claim that all outputs came from the same local run unless you observed that process. Name the exact project and mapping before entering a consumer result. Identity Forge supplies implementation-ready inputs; the consuming team remains responsible for packaging, testing applications, approving the release, and managing rollback.
Design system release questions
Is a successful build enough to release a design system?
No. It proves that the recorded build completed under its conditions. You still need evidence for artifact identity, distribution, documentation, representative consumers, protected surfaces, exceptions, and rollback.
Does every release need full product regression testing?
Not necessarily. Select representative consumers from the documented change reach. The sample should cover material transformation paths, modes, states, platforms, and protected surfaces. Keep unknown or omitted reach visible.
Can Storybook visual tests approve the whole release?
They can provide useful component-level visual evidence for the stories and conditions tested. They do not prove package identity, product tasks, unrepresented states, application composition, or whole-product behavior.
When should a release be revised instead of blocked?
Use revise when a bounded correction can bring the release back to its approved contract and the safety boundary remains clear. Block when material evidence is missing, the distributed artifact is unidentified or wrong, a protected surface regresses, or rollback is not viable.
Is an accepted exception the same as a passing result?
No. A pass matches the expectation. An exception is an authorized divergence with a defined scope, owner, and review or expiry condition. An unexplained mismatch is neither.
Who owns release approval when Identity Forge supplied the kit?
The consuming team does. Identity Forge can supply the design kit, guidance, and exports, but it does not publish the team's packages, test its applications, approve its release, or manage its rollback.
Before scheduling or approving the release, complete one change-reach row for the highest-risk changed contract. If you cannot name its artifact path, representative consumer, protected surface, and rollback trigger, the release record is not ready.
Sources
- Semantic Versioning 2.0.0: Semantic Versioning requires a declared public API and assigns major, minor, and patch increments according to compatibility changes in that API.
- Visual tests | Storybook docs: Storybook can turn stories into visual tests, support review of visual changes, and run those checks in continuous integration.
- Keeping design system contributions in check: A component matrix can make compliance work visible, expose bottlenecks, and support asynchronous review across contributors and stakeholders.
- Maintenance - Design System Checklist: Design-system maintenance includes current documentation, documented release cycles, aligned local libraries, decision logs, and contribution processes.
- Checklist for Design System Maintenance - UXPin: The broader maintenance baseline includes ownership, audits, accessibility, versioning, distribution, testing, automation, and documentation.
- Ambient Sage Design Kit: The public Ambient Sage v1 kit includes DESIGN.md and exports for DTCG, CSS, Tailwind, and shadcn, but those upstream artifacts do not establish results in a consuming project.