Semantic Color Tokens
Name colours by the job they do, so changing a theme is one edit rather than a sweep.
What it adds
A vocabulary of role-named colour tokens — surface, text, border, accent, danger, success — that components reference instead of literal values.
What your agent is told to do
5
What your agent is told to do
5-
1
Inventory every literal colour value in the codebase and group them by the job they are doing rather than by the shade they happen to be. Two different greys used as card backgrounds are one role; the same grey used as a background and as a border is two.
-
2
Define the role names once and map each role to a value per theme. A role may resolve to a light grey in one theme and a near-black in another; what must not change is which components reference it.
-
3
Stop shared components accepting raw colour values. A primitive that takes a hex string as a prop guarantees that some product screen will hardcode a colour the themes never learn about.
-
4
Separate decorative colour from semantic colour explicitly — a chart series, an avatar fallback, and a category tag are decorative and may cycle freely, while danger and success carry meaning and must never be reassigned for visual variety.
-
5
Migrate the legacy palette names through an alias layer that maps each old name to its new role, mark the aliases deprecated, and remove them once usage reaches zero. Do not rename in place across the codebase in one commit; anything you miss fails silently as an unresolved variable.
Edge cases it handles
7
Edge cases it handles
7- A role must map to a different value in each theme, and the mapping must be complete — a role defined only for light mode leaves components with an unresolved value in dark mode, which usually renders as fully transparent or as the inherited parent colour.
- Shared components must reject raw hex values outright rather than passing them through, because a single accepted literal is invisible to every theme that follows.
- Decorative colour and semantic colour must stay separate. Reusing the danger token as the sixth chart series means a routine chart makes users read failure into ordinary data.
- Legacy palette names have to be migrated through an alias layer with a deprecation window, since a direct rename breaks any reference the search missed and does so without an error.
- Roles proliferate quietly. Without a rule for when a new role is justified, the set drifts into forty near-identical names and the abstraction stops paying for itself.
- Third-party and embedded UI will not honour the tokens; decide whether to theme it through its own configuration or accept that it looks foreign, but do not fork it.
- The underlying colour space and ramp generation belong to OKLCH Theme Tokens — this brief owns only the names and the per-theme mapping, and must not restate the maths.
Definition of done
8
Definition of done
8- No shared component contains a literal colour value.
- Every role resolves to a defined value in every theme, with no unresolved references.
- Decorative and semantic colours are separately named and separately governed.
- Legacy palette names resolve through documented aliases marked as deprecated.
- A theme change requires editing the role mapping only, not any component.
- The rule for introducing a new role is written down.
- The feature matches the existing design system.
- No existing functionality is broken.
Related features
Z-Index Registry
Z-Index Registry
Keep every stacking value in one file so nobody has to guess a bigger number.
What it does
A single source of named z-index tokens, with reserved ranges per layer and a check that blocks raw values.
How it works
- 1 Find every z-index in the codebase, including inline styles and values buried in third-party overrides, and list them with the component that owns each. The count is usually higher than anyone expects and several will be arbitrary large numbers.
- 2 Reserve a range for each layer rather than assigning single values, so a new dropdown can slot between existing ones without renumbering everything above it. Leave real gaps between ranges.
- 3 Name each token after the layer it belongs to and derive the ordering from Elevation Layer Map. That feature decides what covers what; this one holds the numbers and stops them being invented locally.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/z-index-registry
Spacing Scale
Spacing Scale
Reduce the app's spacing to a small set of steps that repeat across every surface.
What it does
A named spacing scale covering gaps, padding, and section rhythm, with every existing value in the app mapped onto it.
How it works
- 1 Collect every spacing value currently in the codebase and count how often each appears. The result is usually a handful of genuine intentions surrounded by dozens of near-misses that were nudged once and never revisited.
- 2 Define a scale that is fine at the small end, where control padding lives, and coarse at the large end, where section separation lives. A linear scale gives too many indistinguishable large steps and too few small ones.
- 3 Separate the tokens used inside a component from the ones used between components and between page sections, and name them so the difference is obvious. The same number serving both purposes means a change to button padding also changes the gap between sections.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/spacing-scale
Shadow Scale
Shadow Scale
Replace ad hoc shadows with a small set tied to what each surface actually is.
What it does
A fixed ladder of shadow tokens, each named for an elevation role rather than a blur radius.
How it works
- 1 Collect every shadow currently declared anywhere in the app and group them by what they sit on — a resting card, a hovered card, a dropdown, a dialog, a toast. Most apps have a dozen near-identical values that collapse into four or five roles.
- 2 Name each step for its role, not its appearance. A token called menu tells the next person which surfaces may use it; a token called shadow-md-2 does not.
- 3 Use a single light source for the whole scale, so offset, blur, and spread grow together as elevation rises. Two shadows lit from different directions on the same screen read as a rendering bug.
Copy the prompt
No account needed
Add this feature to my app:
https://addthisfeature.com/x/shadow-scale
How it works
-
1
Copy the link
Grab the Markdown instruction URL for this feature.
-
2
Give it to your AI
Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
-
3
It inspects, then implements
Your agent reads your existing app first, then adds the feature to fit it.
Works with your stack
These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.
Need it tighter than that? Customize the feature and tell it exactly what you're running.