Design system contribution guidelines: match the review to the impact

A contribution is a tangible, recordable change to the maintained system. It may correct guidance, change a token value, add a mode alias, alter a generated export, modify component behavior, introduce a pattern, or remove a public identifier. Nathan Curtis uses this distinction to separate contribution from participation. Conversations and feedback matter, but they don't change the system on their own.

Keep five events distinct in the record. Participation supplies information. A proposal asks the system owner to make a decision, while proposal approval authorizes a direction. Implementation changes one or more governed artifacts. Release makes the accepted result available to consumers. Combining these events creates false confidence, especially when an approved proposal hasn't reached a package or application.

Contribution tiers help because changes differ in cost and frequency. Nord, for example, distinguishes light, medium, and heavy contributions. But effort alone is an unreliable proxy for impact. Changing one semantic color value may take seconds and alter many components in two modes. A new pattern may take weeks to write but remain isolated until a product adopts it.

Choose the change class first. Then trace its reachable consumers. A change moves into a stronger review class when it crosses an authority boundary, changes a public contract, affects multiple modes or states, requires migration, or reaches products the contributor cannot observe.

Reviewers first need to know where the decision belongs. Start with the editable authority, then follow the delivery chain. A common chain runs from the source decision through generated artifacts, package or registry delivery, a shared component, a consuming application, and a local exception. Your system may use different layers, but each one needs a named owner who can correct it.

1. 1

   Name the authoritative source

   Identify the artifact allowed to decide the value, rule, behavior, or pattern. A rendered example may demonstrate a decision without owning it.

2. 2

   List generated artifacts

   Record every governed output expected to change, such as CSS variables, Tailwind configuration, DTCG tokens, documentation, or registry data. Don't assume formats remain equivalent merely because they share a generator.

3. 3

   Name actual consumers

   List packages, applications, pages, components, modes, and states known to consume the affected contract. Avoid labels such as all apps unless the inventory supports them.

4. 4

   Record local exceptions

   List deliberate overrides, forks, aliases, or platform adaptations. Assign each exception an owner instead of treating it as unexplained drift.

5. 5

   Route failures to their owning layer

   A wrong source decision belongs to the source owner. A stale export belongs to the delivery layer. A local override belongs to the consumer. Fixing the rendered symptom at the wrong layer creates another exception.

This map also limits attendance. A documentation correction with no semantic change doesn't need every product team. A mode-alias change used by three applications does need evidence from those consumers or a reasoned block. Invite people because they own a reachable decision or observation, not because they usually attend design-system reviews.

CMS contribution guidance asks proposers to check whether an artifact already exists, explain the local need, identify related solutions and other users, and provide supporting evidence. Keep that qualification work in a portable brief. Then extend the record across source authority, generated outputs, consumers, modes, exceptions, and final disposition.

Contribution title:
Contributor:
Decision owner:
Implementation owner:
Consumer owners:

Problem evidence:
Observed user or product need:
Existing system option checked:
Why the existing option is insufficient:

Change class:
Prior decision or behavior:
Proposed decision or behavior:
Rejected alternatives and reasons:

Authoritative source:
Generated artifacts expected to change:
Named packages and applications:
Affected components, pages, modes, states, and viewports:
Expected changed surfaces:
Expected unchanged surfaces:
Known local exceptions and owners:

Compatibility or public-contract effect:
Migration required:
Migration owner:
Release treatment:

Evidence required before acceptance:
Observations collected:
Missing evidence:
Unresolved questions:

Disposition: accept | revise | block
Disposition reason:
Approvers:
Accepted exceptions and owners:
Follow-up observation after release:

The expected unchanged surfaces field matters. Without it, reviewers tend to inspect only the visible target and miss collateral changes. For a primary-token update, the intended button may change while destructive, success, muted, and focus treatments should remain stable. Naming those protected surfaces makes the absence of change observable.

Proposal review determines whether the problem is real, the source layer is appropriate, the scope is bounded, and the proposed decision is preferable to the alternatives. It doesn't prove that an export regenerated, a component consumed the new value, or an application rendered the intended result.

• Accept the proposal when the problem, authority, scope, owners, and required evidence are clear enough to proceed.
• Revise the proposal when the direction may be sound but the affected contract, consumers, alternatives, or evidence plan is incomplete.
• Block the proposal when it duplicates an existing system capability without justification, assigns a decision to the wrong authority, lacks an owner for a material consequence, or creates an unacceptable breaking change.

Record rejected alternatives. This stops the same debate from restarting during implementation and gives future contributors context that a final token value or component API cannot carry. Keep the reasoning specific: name which requirement the alternative failed instead of saying it felt inconsistent.

A controlled change checks whether the declared authority chain behaves as expected. Choose one observable change with bounded reach. Before editing, freeze the source version, named consumers, relevant modes and states, and protected surfaces. Then move through each layer once.

1. 1

   Capture the baseline

   Record the current source decision, generated identifiers, consumer version, representative renders or behavior, and known exceptions.

2. 2

   Change the authoritative source

   Make the approved decision only at the owning layer. Avoid simultaneous consumer fixes that would hide a broken mapping.

3. 3

   Regenerate declared artifacts

   Produce each expected output and compare it with the baseline. An unchanged artifact may reveal that the source is disconnected from that format.

4. 4

   Inspect named consumers

   Observe the affected components and surfaces in the relevant modes, states, and representative content. Record what changed and what remained stable.

5. 5

   Record overrides and failures

   For every mismatch, identify whether the source, generator, delivery route, shared implementation, or local consumer owns the correction.

6. 6

   Set the disposition

   Accept only when the required evidence supports the intended result. Revise when a correctable gap remains. Block release when a material protected surface fails or reachable impact is unknown.

Ambient Sage is a public Identity Forge kit with 28 semantic tokens across light and dark modes. Its published typography assigns Plus Jakarta Sans to heading and body roles and JetBrains Mono to technical strings. The kit page exposes DESIGN.md, CSS, Tailwind, DTCG, and shadcn delivery formats. These facts are enough to demonstrate the source side of a contribution record.

Suppose a contributor proposes changing one Ambient Sage semantic token value. The record can identify the public kit as the source artifact, light and dark as governed modes, and the published delivery formats as expected outputs. Once the actual proposal contains the current visual role and proposed value, the record can name those facts too.

Contribution title: Proposed Ambient Sage semantic-token value change
Change class: Token-value change
Authoritative source: Ambient Sage kit record
Known governed modes: Light and dark
Published delivery formats: DESIGN.md, CSS, Tailwind, DTCG, shadcn
Expected generated artifacts: To be confirmed against the proposed source change
Named consuming projects: Unresolved
Project-specific token mapping: Unresolved
Expected changed surfaces: Unresolved until consumers are named
Expected unchanged surfaces: Unresolved until scope is bounded
Rendered consumer observations: Not collected
Compatibility evidence: Not collected
Local exceptions: Unknown
Disposition: revise
Reason: Source-side facts are available, but no consuming project, mapping, render, or compatibility evidence is present.

The honest disposition here is revise. The available kit and exports don't prove that a particular project installed every format, retained identifier parity, mapped the intended role, or rendered both modes correctly. Identity Forge supplies implementation-ready artifacts, but it doesn't manage a team's contribution process, discover its consumers, approve changes, or validate downstream applications.

A removal needs stronger evidence because it changes the available paths through the system. The existence of a replacement doesn't show that every consumer can reach it. Record whether one old identifier maps to one replacement, several replacements, a compatibility alias, or no replacement. Then map direct and transitive consumers.

• Name the replacement relationship before announcing removal.
• Keep migration ownership with named teams or maintainers, not an unassigned consumer group.
• Regenerate every governed format that exposes the old or replacement identifier.
• Inspect supported modes and representative states after migration.
• Record temporary aliases and local exceptions with removal conditions and owners.
• Block final removal while a reachable consumer or required delivery format remains unknown.

For a detailed token-specific migration method, use the related design token deprecation strategy. The contribution record here should reference that migration evidence instead of duplicating it.

Contribution review doesn't require maximum ceremony for every edit. It requires enough evidence for the reachable effect. Classify one real proposal, complete the brief, run the controlled change, and mark the result accept, revise, or block. If you can't name the consumers yet, finding them is the next task, not a blank to fill with confidence.

• Defining Design System Contributions: Nathan Curtis distinguishes participation from tangible, recordable contribution and argues that small and large contributions require different approaches.
• Contributing - Nord Design System: Nord classifies contributions as light, medium, or heavy and varies its process according to the contribution level.
• Contribution Guidance - CMS Design System: CMS asks contributors to check existing solutions, explain the local need, identify related patterns and other users, and supply relevant research or design evidence.
• Keeping design system contributions in check: The article describes component matrices and compliance checklists as tools for making contribution progress, requirements, and bottlenecks visible.
• Fixing Design System Contribution: Ben Callahan's research records practical tensions among contribution speed, quality, governance, product delivery, incentives, and unofficial components.
• Ambient Sage Design Kit: The public Ambient Sage kit documents light and dark semantic tokens, Plus Jakarta Sans and JetBrains Mono typography roles, and DESIGN.md, CSS, Tailwind, DTCG, and shadcn delivery formats.