Keep the system useful as it grows
Evolve tokens and components through evidence, clear ownership, and manageable migrations.
Why this matters
Say your agent keeps inventing new grays, and every screen drifts a little further apart. A system stays useful when its defaults match what you're actually building. Governance is changing those defaults on purpose, with enough context that the next person — or agent — uses them right.
What to understand
Before you enforce anything, look at what's really there: where tokens live, how components are built, who uses them, what the guidance says. Hunt for a repeated cost — copied behavior, states you can't reach by keyboard, confusing navigation, an API that makes the right answer hard to write.
Treat a stray hex value or odd spacing as a clue, not a crime. It may be an intentional exception. Then choose: reuse what fits, extend a recurring meaningful need, create a genuinely different boundary, or keep a one-off local.
Watch for
- Enforcing consistency before looking at real usage.
- Calling every stray value drift without asking what breaks if it changes.
- "Make this reusable" with no proof of the variations it must cover.
- Settings props for imaginary future users.
- A temporary alias with no deletion date — two truths forever.
- A hand-copied list of tokens or variants going stale.
- Grouping fixes by screen instead of by shared cause.
Strong default
Ask your agent: "show me everywhere this value appears, and what breaks if I change it." Weigh what the person feels against upkeep. Fix the most harmful issues first — unreachable actions, lost input, unreadable feedback — before minor visual mismatches.
When this doesn't apply
Reuse is not always the answer. If it's specific and unlikely to repeat, keep it local, clear, and out of the shared API — don't promote it into a secret shared dependency. A short DESIGN.md saying why a component exists and when to use it beats a full prop list nobody reads.
In practice
| Choice | Use when | Check |
|---|---|---|
| Reuse | What exists fits in meaning and behavior. | It works with real content and states. |
| Extend | A recurring meaningful need is missing. | Everything already using it still behaves. |
| Create | The job or interaction is genuinely different. | It doesn't copy a good building block. |
| Keep local | It's specific and unlikely to repeat. | It stays clear and doesn't become a secret shared dependency. |
Say you're renaming a token or prop. List who uses it and what visibly changes. Give people a replacement and an order to move in.
Change: replace the old warning text role with warning-text-on-surface.
Reason: the old role was reused on two incompatible backgrounds.
Consumers: status banners and request detail notices.
Verify: light/dark text contrast and focused actions in both contexts.
Migration: update both consumers, then remove the unused role.Write down what changes the next decision: source paths, who owns it, valid variants, one ordinary example, known exceptions — in the docs you already have. Generate lists from source where you can. In audits, separate what you saw from what you suspect, and include how to reproduce it or where it lives.
Verify
After a shared change, open representative pages in both themes and key states. For fixes you're cleared to make, implement and recheck everyone who uses it. An update that looks safe in code can still break what people see or do.
Related skills
Use $system for this ongoing work and $craft when a solid system still needs a stronger visible composition.
Last updated on