design-system-governance

name	design-system-governance
description	Contribution model, review lanes, and release cadence for mobile design systems. Use this when establishing or revising how changes enter the system.

Design System Governance

Instructions

Governance is the set of rules that keep a shared design system shared. Without it, every team forks, every PR stalls, and tokens drift. Write the rules down, enforce them in CI, and keep them light enough that contributors use them.

1. Ownership Model

Pick one, and write it into CODEOWNERS:

• Centralized: a dedicated DS team owns tokens and components. Other teams open PRs; DS reviews and merges. Best for early-stage systems.
• Federated: product teams contribute under a DS maintainer council. Component reviews require a DS maintainer and the contributing team. Best once the system has > 3 contributing teams.
• Open-contribution with tiers: anyone can contribute patterns; primitives and tokens are centralized. Scales to many teams.

# CODEOWNERS
/tokens/           @org/design-system
/src/primitives/   @org/design-system
/src/patterns/     @org/design-system @org/contributing-team
/src/compositions/ @org/contributing-team

2. Contribution Lanes

Three lanes with explicit checklists. Write them as PR templates.

Lane A — Token change. Requires: design approval, contrast verification, migration note if semantic alias changes.

Lane B — New variant. Requires: variant matrix entry, snapshot matrix update, a11y contract update, changelog entry.

Lane C — New component. Requires: design spec link, anatomy doc, all-variant snapshots, a11y contract, per-platform API parity, docs page.

3. Review SLA

Commit publicly to review turnaround:

• Comment or approval within 2 business days of request.
• Reject fast: send contributors to an RFC thread rather than letting PRs stall.
• Use a maintainer rotation so no one person is the bottleneck.

4. RFC Process

For anything that touches the public API of the system (new token category, new component, API shape), require an RFC before code.

docs/rfcs/
├── 0001-introduce-motion-tokens.md
├── 0002-segmented-control.md
└── 0003-deprecate-neutral-tone-50.md

Template: problem, non-goals, proposal, alternatives, migration, open questions. Merge the RFC before the implementation PR opens.

5. Release Cadence

Pick a rhythm and stick to it. Minor releases every 2–4 weeks work well for active systems; patches as needed. Big-bang yearly releases demoralize everyone.

• Patch (x.y.Z): value tweaks, bug fixes, no API change.
• Minor (x.Y.0): additive tokens, components, variants.
• Major (X.0.0): removals, renames without alias, breaking API.

Automate release notes with Conventional Commits + changesets (or equivalent) so the changelog writes itself.

6. Deprecation Policy

Nothing is removed without a deprecation window:

1. Annotate with $deprecated: true and a replacement hint.
2. Emit compile-time warnings on native platforms (@Deprecated(...) on Compose, @available(*, deprecated, ...) on Swift, @Deprecated on Dart).
3. Ship for at least one minor version before removal.
4. Publish a codemod where feasible.

7. Metrics

Measure health to know where to invest:

• Adoption: % of screens using DS primitives vs. local re-implementations.
• Drift: count of hardcoded hex/px in consumer codebases.
• Escape velocity: time from RFC to merged implementation.
• Satisfaction: quarterly consumer survey (5 questions, no more).

Publish metrics quarterly. A DS that can't point to adoption numbers is flying blind.

8. Decision Log

Keep an ADR/ (Architecture Decision Record) folder:

docs/adr/
├── 001-style-dictionary-as-build.md
├── 002-three-layer-tokens.md
└── 003-compose-material3-baseline.md

Each ADR: context, decision, consequences. Revisited when consequences change.

9. Enforcement in CI

Governance that is not automated rots. Enforce:

• Token layer rules (lint).
• Changelog entry presence on PRs that change src/ or tokens/.
• RFC link required in PR description for major changes.
• CODEOWNERS review required.

10. Anti-Patterns

• "Benevolent dictator" governance — the DS stops when that person leaves.
• Private Slack decisions that never hit the ADR log.
• Releases "when ready" — loses consumer trust.
• No escape valve for urgent product needs — teams fork and never come back.
• Governance docs nobody reads because they are 40 pages long.

Checklist

• Ownership model (centralized / federated / open-tiered) is documented and reflected in CODEOWNERS.
• Contribution lanes have PR templates with explicit checklists.
• Review SLA is public and tracked.
• RFC process is mandatory for public API changes and stored in the repo.
• Release cadence is regular; changelog and SemVer bumps are automated.
• Deprecation requires $deprecated, compile warnings, one-minor window, and a codemod where possible.
• Metrics (adoption, drift, velocity, satisfaction) are published quarterly.