Governance Rules Template

What This Is

A framework for deciding what AI can do in your design system without asking. Most teams either let AI do everything (risky) or nothing (slow). This template defines the middle ground.

Trust Levels

Level 1: Intern (Auto-fix, no review needed)

Low-risk, easily reversible changes that follow deterministic rules.

Action	Example
Fix naming convention violations	colorBgPrimary renamed to color.bg.primary
Sort token files alphabetically	Reorder tokens within a category
Fix whitespace and formatting	Consistent indentation, trailing commas
Add missing component descriptions	Generate from component name + props
Flag raw hex values	Report, suggest token replacement

Approval: None. Auto-commit to feature branch.

Level 2: Junior (Auto-fix, notify team)

Medium-risk changes that are reversible but could affect dependent components.

Action	Example
Replace raw hex with existing token	#3B82F6 replaced with var(--color-bg-primary)
Add missing ARIA attributes	role, aria-label, aria-describedby
Fix simple accessibility issues	Missing alt text, label associations
Generate Storybook stories	Default story from component props
Update token documentation	Regenerate token table from source

Approval: Auto-commit, notify in Slack/PR comment. Revert if flagged within 24h.

Level 3: Mid-level (PR required, single reviewer)

Changes that modify behavior or add new patterns.

Action	Example
Create new semantic tokens	New token aliasing existing primitives
Add component variants	New variant following existing patterns
Generate component code	New component from spec
Modify component props	Add optional props to existing components
Update knowledge graph	New component relationships

Approval: PR with 1 reviewer (designer or engineer).

Level 4: Senior (PR required, team review)

Changes that affect the system architecture or cross-component behavior.

Action	Example
Rename existing tokens	Rename with migration path
Deprecate components	Mark as deprecated, suggest replacement
Change token structure	Add new category or property
Modify component API	Breaking prop changes
Update naming conventions	Convention changes affecting existing tokens

Approval: PR with 2 reviewers (1 designer + 1 engineer). Migration plan required.

Level 5: Principal (Human only)

Decisions that require design judgment, business context, or stakeholder alignment.

Action	Example
Create new design patterns	New interaction patterns
Define brand tokens	Brand colors, typography choices
Remove components	Delete from the system
Change theme architecture	New theme structure
Break backwards compatibility	Major version changes

Approval: Human decision. AI can propose, never execute.

Decision Matrix

Use this to classify any new automation:

Is the change reversible in < 5 minutes?
├── Yes → Is it a deterministic rule (no judgment)?
│   ├── Yes → Level 1 (auto-fix)
│   └── No → Level 2 (auto-fix, notify)
└── No → Does it affect other components?
    ├── No → Level 3 (PR, single reviewer)
    └── Yes → Does it change the system architecture?
        ├── No → Level 4 (PR, team review)
        └── Yes → Level 5 (human only)

Escalation Rules

Trigger	Action
AI confidence < 80%	Escalate one level
Change affects > 10 components	Escalate to Level 4 minimum
Token rename affects > 5 files	Require migration plan
Any accessibility regression	Block until human review
Health score drops > 5 points	Alert team, pause auto-fixes

How to Implement

1. Copy this template
2. Customize the actions per level for your team
3. Add to your CLAUDE.md or .claude/rules/governance.md
4. Start everything at Level 3 (PR required)
5. Move to Level 1-2 as trust builds over time

Review Cadence

• Weekly: Review all Level 1-2 auto-fixes. Any surprises?
• Monthly: Review Level 3-4 decisions. Adjust trust levels.
• Quarterly: Full governance review. What should move up or down?