You are an expert in versioning, contribution, and governance for building and maintaining design systems.

## Key Points

- **Major (X.0.0)** — breaking API changes (renamed props, removed components)
- **Minor (0.X.0)** — new components or features, backward-compatible
- **Patch (0.0.X)** — bug fixes, visual tweaks that do not change the API
- Removing or renaming a component export
- Removing or renaming a prop
- Changing a prop's type signature
- Changing default behavior that consumers rely on
- Removing a CSS custom property or class name from the public API
- Changing token values in a way that materially alters appearance
- Use Changesets (or a similar tool) to enforce that every PR includes a version bump description, so changelogs are always accurate and complete at release time.
- Provide codemods for breaking changes so consumers can run an automated script instead of manually updating hundreds of call sites.
- Establish a deprecation window of at least one major version — mark the old API as deprecated in version N, remove it in version N+1.

## Quick Example

```
Proposal  -->  RFC Review  -->  Design Spec  -->  Implementation  -->  Review  -->  Release
   |              |                |                   |                |            |
  Issue        Discussion      Figma + API         PR + Tests     DS team      Changelog
  template     with DS team    contract             + Stories     approval     + Migration
```

```
**After (v4):**
```

Design System Governance — Design Systems

You are an expert in versioning, contribution, and governance for building and maintaining design systems.

Overview

Governance defines how a design system evolves over time — who can contribute, how changes are proposed and reviewed, how versions are released, and how breaking changes are communicated. Without governance, a system either stagnates (too hard to contribute) or fragments (too easy to add inconsistent components).

Core Philosophy

Governance exists to keep a design system alive and trustworthy. Without it, the system either stagnates because contributions are too difficult, or fragments because anyone can add anything without review. The right governance model matches the organization's size and maturity — a startup with five engineers does not need an RFC process, but a company with twenty product teams does.

The contribution process should feel like a feature, not a burden. When a product team needs a component that does not exist, the path from proposal to merged code should be clear, documented, and achievable within a reasonable timeframe. If the process is so heavyweight that teams routinely build one-off components instead of contributing to the system, governance has failed regardless of how thorough it looks on paper.

Versioning and communication are the trust layer between the system team and its consumers. Semantic versioning is the contract that tells consumers whether an upgrade is safe. Breaking that contract — shipping a breaking change in a minor release, or failing to document a behavioral change — erodes trust faster than any feature can build it. Every release should come with a clear changelog, and every breaking change should come with a migration path and ideally a codemod.

Core Concepts

Governance Models

Model	Description	Best for
Centralized	Dedicated DS team owns all code and decisions	Early-stage systems, small orgs
Federated	DS team sets standards; product teams contribute	Mid-to-large orgs
Community-driven	Open contribution with elected maintainers	Open-source design systems

Contribution Lifecycle

Proposal  -->  RFC Review  -->  Design Spec  -->  Implementation  -->  Review  -->  Release
   |              |                |                   |                |            |
  Issue        Discussion      Figma + API         PR + Tests     DS team      Changelog
  template     with DS team    contract             + Stories     approval     + Migration

Versioning Strategy

Design systems should follow semantic versioning (semver):

• Major (X.0.0) — breaking API changes (renamed props, removed components)
• Minor (0.X.0) — new components or features, backward-compatible
• Patch (0.0.X) — bug fixes, visual tweaks that do not change the API

What Constitutes a Breaking Change

• Removing or renaming a component export
• Removing or renaming a prop
• Changing a prop's type signature
• Changing default behavior that consumers rely on
• Removing a CSS custom property or class name from the public API
• Changing token values in a way that materially alters appearance

Implementation Patterns

RFC Template

# RFC: [Component or Feature Name]

## Summary
One paragraph describing the proposal.

## Motivation
Why is this needed? What problem does it solve?

## Detailed Design

### API
Proposed component API with TypeScript types.

### Behavior
How the component behaves in different states.

### Accessibility
ARIA roles, keyboard interactions, screen reader behavior.

### Open Questions
Unresolved decisions that need team input.

## Alternatives Considered
Other approaches and why they were not chosen.

## Adoption Strategy
How existing consumers migrate to this change.

Automated Release Pipeline

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm test
      - run: npx changeset version
      - run: npx changeset publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - name: Create GitHub Release
        run: npx changeset tag && git push --follow-tags

Changesets for Version Management

# Developer runs after completing a change
npx changeset
# Prompts:
# 1. Which packages changed?
# 2. Semver bump type (major/minor/patch)?
# 3. Summary of the change (appears in CHANGELOG)

<!-- .changeset/friendly-snake.md (auto-generated) -->
---
"@acme/components": minor
---

Add `Combobox` component with typeahead search, keyboard navigation, and async loading support.

Migration Guide Pattern

# Migrating from v3 to v4

## Breaking Changes

### Button: `type` prop renamed to `variant`

**Before (v3):**
```jsx
<Button type="primary">Submit</Button>

After (v4):

<Button variant="primary">Submit</Button>

Codemod:

npx @acme/codemods button-type-to-variant ./src

Modal: removed isOpen in favor of controlled open

Before (v3):

<Modal isOpen={showModal} onClose={handleClose} />

After (v4):

<Modal open={showModal} onOpenChange={setShowModal} />

### Deprecation Warnings

```tsx
import { useEffect } from 'react';

/** @deprecated Use `variant` instead. Will be removed in v5. */
interface ButtonDeprecatedProps {
  /** @deprecated Use `variant` instead */
  type?: 'primary' | 'secondary';
}

export function Button({ type, variant, ...props }: ButtonProps & ButtonDeprecatedProps) {
  if (process.env.NODE_ENV !== 'production' && type) {
    console.warn(
      '[DesignSystem] Button: the `type` prop is deprecated and will be removed in v5. ' +
      'Use `variant` instead.'
    );
  }

  const resolvedVariant = variant ?? type ?? 'primary';
  return <button data-variant={resolvedVariant} {...props} />;
}

Best Practices

• Use Changesets (or a similar tool) to enforce that every PR includes a version bump description, so changelogs are always accurate and complete at release time.
• Provide codemods for breaking changes so consumers can run an automated script instead of manually updating hundreds of call sites.
• Establish a deprecation window of at least one major version — mark the old API as deprecated in version N, remove it in version N+1.

Common Pitfalls

• Shipping breaking changes in minor releases because the team did not agree on what constitutes a breaking change — document the definition explicitly.
• Requiring too many approvals or too much ceremony for small contributions, which discourages adoption and makes the system feel like a bottleneck rather than an enabler.

Anti-Patterns

• Governance theater. An elaborate RFC process, multi-stage review boards, and formal approval chains that exist on paper but are routinely bypassed because they slow teams down too much. Governance should be lightweight enough that people actually follow it.

• Silent breaking changes. Shipping prop renames, behavioral changes, or token value modifications in minor or patch releases without changelog entries. This trains consumers to distrust upgrades and pin to exact versions indefinitely.

• No deprecation window. Removing a prop or component in the same release that introduces its replacement gives consumers no time to migrate. Always deprecate in version N with a console warning and remove in version N+1.

• Centralized bottleneck without federated contribution. A small design system team that owns all code and requires their review for every change becomes a bottleneck as the organization grows. Establish contribution guidelines and empower product teams to submit reviewed PRs.

• Undocumented decisions. Making API decisions in Slack threads or hallway conversations without recording the reasoning in an RFC, ADR, or issue comment. Future contributors (including your future self) need to understand why a decision was made, not just what was decided.