Design System Versioning And Adoption

---
name: design-system-versioning-and-adoption
description: "Version a component library like the public contract it is (semver + changesets), ship breaking changes with codemods and loud deprecation, and drive adoption with metrics. Traverses the versioning branch of the design-systems decision tree: semver mapping → changesets/release flow → breaking-change/codemod policy → deprecation → adoption metrics. Reach for this when the user asks 'how do we version the library?', 'set up changesets', 'how do we ship this breaking change?', or 'how do we drive adoption / measure it?'. Used by design-systems-architect (policy) and design-tokens-and-component-engineer (release pipeline)."
---

# Skill: design-system-versioning-and-adoption

> **Invoked by:** `design-systems-architect` (the versioning/governance policy) and
> `design-tokens-and-component-engineer` (the release pipeline + codemods).
>
> **When to invoke:** "how do we version the library?"; "set up changesets/the release flow"; "how
> do we ship this breaking change without breaking consumers?"; "how do we drive/measure adoption?";
> any "how does this library get released and adopted" question.
>
> **Output:** a versioning & adoption plan — the semver mapping, the changesets/release flow, the
> breaking-change/codemod/deprecation policy, and the adoption metrics — so every change is
> versioned and consumers get a clean, mechanical upgrade path.

## Procedure

1. **Map semver honestly for a component library.** A library's contract is its component APIs and
   token names, plus *rendered output* consumers depend on. **Major:** a removed/renamed
   prop/token, a changed default that alters rendering, a raised peer-dependency floor, a
   markup/ARIA change that breaks a consumer's selectors/tests. **Minor:** a new component, prop,
   token, or variant (additive). **Patch:** a bug fix that preserves the contract. When in doubt
   between minor and major, it's major — the contract is sacred.
2. **Automate versioning with changesets (or equivalent).** Every PR that changes shipped code
   carries a changeset declaring its bump and a human-readable summary; release tooling aggregates
   them into the version bump + changelog. Nothing ships unversioned; the changelog writes itself
   from the changesets *(retrieval-dated 2026-07; verify the tool's API at use)*.
3. **Make every breaking change mechanical for consumers.** The sequence is: (a) ship a
   **deprecation** in a minor — the old API still works but warns, with the replacement named; (b)
   ship a **codemod** that rewrites consumer code automatically (rename the prop, swap the token);
   (c) write a **migration note**; (d) remove the deprecated API in the **next major**. A migration
   guide *alone* is homework you've handed the consumer — the codemod is the courtesy.
4. **Deprecate loudly, remove slowly.** A deprecated API lives at least one major cycle with a
   console/lint warning pointing to the replacement. Surprise removals are how a system loses
   consumer trust — and trust is the whole product.
5. **Set the contribution & governance model.** Who can add to the system, the review bar (a11y +
   API + docs + changeset required), and the promotion path from product-local to system. Keep the
   system opinionated: additions must be reused-and-stable, not one-offs.
6. **Instrument adoption — it's the success metric.** Pick 1–2 metrics: **% of surfaces on the
   current major**, **token coverage** (share of styles from tokens vs hardcoded), **component
   adoption** (system component vs bespoke), **escaped-hardcoded-value count**. A system nobody
   migrates to has failed regardless of its internal elegance.
7. **State the trigger conditions** — when the policy changes (e.g. "once >3 external teams consume,
   move to a scheduled release train instead of on-merge"; "if adoption stalls below X%, the
   blocker is usually migration cost — invest in codemods and defaults before new features").

## Worked example

> User: "We're renaming `<Button variant>` to `<Button tone>` and want to add changesets. How do
> we ship this without breaking the five apps consuming us?"

- **Semver:** renaming a public prop is **major**.
- **Release flow:** adopt changesets; every PR adds a changeset; releases aggregate to the bump +
  changelog.
- **Migration sequence:** (1) minor release — accept both `variant` and `tone`, `variant` logs a
  deprecation warning naming `tone`; (2) ship a codemod (`npx @ds/codemod button-variant-to-tone`)
  that rewrites `variant=` → `tone=` across a consumer's codebase; (3) migration note in the
  changelog; (4) next major — remove `variant`.
- **Adoption:** track "% of the five apps on the current major" weekly; the codemod makes the
  migration a one-command chore, so adoption should be fast.
- **Trigger:** if an app can't migrate (pinned old major), the deprecation stays until it does — do
  not remove on schedule if a consumer is stranded.

## Guardrails

- **When in doubt, it's a major** — under-calling a breaking change is how you break consumers silently.
- **Codemod, not just a guide** — make the upgrade mechanical; a guide alone offloads your work.
- **No unversioned change** — a changeset per shipped PR is the floor.
- **Deprecate at least a full major before removal** — loud warning, named replacement, slow removal.
- **Additive by default** — grow the system with minors; reserve majors for genuine contract breaks.
- **Adoption is the metric** — an elegant system nobody uses is a failed system; lower migration cost
  before adding features.
- **Retrieval-date the release tooling** (changesets/registry mechanics); the semver principle is durable.