Design System Governance: Rules for Scaling Without Breaking

Why governance matters now more than ever

Design system governance used to be a concern for large organizations with dedicated design teams. Now it affects every team that uses AI coding tools. When Claude, Cursor, or Windsurf generates code, it may introduce new CSS variables, create ad-hoc color values, or duplicate existing tokens with different names. Without governance rules, AI-generated code degrades your system at the speed of autocomplete.

The team that used to add one rogue token per sprint now adds five per day with AI assistance. Governance is not about slowing people down. It is about maintaining the structural integrity that makes the system useful in the first place.

Naming conventions

The single most impactful governance rule is a strict naming convention. If every contributor (human and AI) follows the same pattern, the system stays navigable at any size.

The token naming pattern

/* Pattern: --category-role[-variant][-state] */

/* Colors */
--color-bg
--color-surface
--color-surface-hover
--color-text
--color-muted
--color-accent
--color-accent-hover
--color-accent-soft

/* Typography */
--font-heading
--font-body
--font-mono
--font-weight-heading
--font-weight-body

/* Shape */
--radius-sm
--radius-md
--radius-lg
--shadow-sm
--shadow-md
--shadow-lg

/* Components */
--button-bg
--button-bg-hover
--card-bg
--card-border
--input-border-focus

The pattern is: --category-role for semantic tokens and --component-property for component tokens. Variants come after the role. States come last. This structure is predictable. Anyone (human or AI) can guess the token name without looking it up.

Naming rules to enforce

No appearance-based names. --color-light-blue is banned. --color-accent-soft is correct. Appearance changes. Purpose does not.

No abbreviations. --color-bg is an accepted abbreviation (background is universally shortened). --clr-bkg is not. Keep abbreviations to widely understood conventions.

No duplicate concepts. If --color-muted exists, do not create --color-secondary-text, --color-subtle, or --color-dimmed. One name per concept.

Token addition process

Every new token should answer three questions before it is added:

1. Does this role already exist? Check existing tokens first. --color-accent-soft might already cover the use case that someone wants to solve with a new --color-primary-light token.

2. Will this token have multiple consumers? If only one component needs it, it might be a component token (scoped) rather than a semantic token (global). Adding a global token for a single use case is token sprawl.

3. Does it follow the naming convention? If it does not fit the established pattern, either the name is wrong or the convention needs updating. Both are valid outcomes, but the discussion must happen before the token ships.

/* Token addition checklist */

1. Search existing tokens for overlap
2. Confirm multiple components will use it
3. Verify naming follows convention
4. Define both light and dark mode values
5. Document the usage context
6. Add to the token registry

Deprecation policy

Tokens outlive their usefulness. A redesign might eliminate the need for --color-surface-hover, or a naming convention change might replace --btn-bg with --button-bg. Without a deprecation policy, old tokens accumulate like dead code.

The deprecation workflow

Step 1: Mark as deprecated. Add a comment in the token file. Do not remove the token yet.

/* DEPRECATED: use --color-accent-soft instead */
--color-primary-light: rgba(99, 102, 241, 0.1);

/* Current */
--color-accent-soft: rgba(99, 102, 241, 0.1);

Step 2: Migrate consumers. Find every component using the deprecated token and switch to the replacement. This can be a single find-and-replace if the values are identical.

Step 3: Remove after one release cycle. Keep the deprecated token for one release (or sprint) after all consumers have migrated. Then remove it. The grace period catches any consumers you missed.

Governance for AI contributors

AI coding agents are the fastest-growing class of "contributors" to most codebases. They need governance rules too, but they consume rules differently than humans. The best format for AI governance is the IDE rule file.

/* In .cursorrules, CLAUDE.md, or .windsurfrules */

## Design Token Rules

NEVER create new CSS custom properties.
Use ONLY the tokens defined in tokens.css.
If a needed token does not exist, leave
a TODO comment and use the closest existing token.

NEVER use raw color values (hex, rgb, hsl).
ALWAYS reference token variables.

Token naming pattern: --category-role[-state]
Examples: --color-bg, --color-accent-hover, --radius-md

This gives the agent explicit constraints. It cannot add tokens unilaterally. It must use existing ones. And when a token is missing, it flags the gap instead of silently introducing a rogue value. For the complete approach to making design systems agent-compatible, see design tokens for AI.

Token sprawl: the silent killer

Token sprawl is when the number of tokens grows without corresponding growth in the UI's actual visual vocabulary. It looks like:

Synonym tokens. --color-muted, --color-subtle, --color-secondary all meaning the same thing.

Orphan tokens. Tokens defined in the file but referenced by zero components. They were created for a feature that shipped differently or was cut entirely.

One-off tokens. --sidebar-toggle-hover-bg used by exactly one element. This belongs in a component's local styles, not in the global token file.

The fix: regular token audits. Once a quarter (or once a sprint for fast-moving teams), run a usage scan. Find tokens with zero references and remove them. Find tokens with synonyms and consolidate them. Keep the set lean.

Contribution guidelines template

Here is a governance template you can drop into your project:

/* DESIGN TOKEN CONTRIBUTION GUIDELINES */

1. NAMING
   Pattern: --category-role[-variant][-state]
   Categories: color, font, radius, shadow, space
   No appearance-based names (no --light-blue)
   No abbreviations beyond accepted (bg, md, lg)

2. ADDING TOKENS
   Check for existing overlap first
   Must have 2+ consumers (or be a component token)
   Must define light AND dark values
   Must follow naming convention

3. MODIFYING TOKENS
   Check all consumers before changing a value
   Use the token audit script to find references
   Test in both light and dark mode

4. DEPRECATING TOKENS
   Add DEPRECATED comment with replacement name
   Migrate all consumers in the same PR
   Remove after one sprint

5. AI CONTRIBUTORS
   Must not create new tokens
   Must use existing tokens only
   Must flag missing tokens with TODO

This template covers the five most common governance failures. Naming inconsistency, unnecessary additions, unvetted modifications, abandoned tokens, and AI-introduced drift. Adjust the specifics to your team's workflow. For the full picture on building a sustainable design system, see design variables that actually matter. For how tokens map to IDE rule files, check design tokens to IDE rule files.

Governance is not about restricting creativity. It is about protecting the investment you have already made in your design system. Every ungoverned token is a potential inconsistency. Every inconsistency erodes trust in the system. And once trust erodes, developers stop using the system and go back to hardcoding values. Write the rules, enforce the naming, deprecate the dead weight, and your system scales with your team instead of against it.