Naming and Tiering Theme Variables

Default to two tiers and earn the third. A primitive tier holds raw values named for what they are (--gray-2, --space-4), a semantic tier holds roles named for what they do (--color-surface, --gap-section), and a component tier exists only where a component must deviate from its role and that deviation must stay themeable. References flow in exactly one direction — component reads semantic, semantic reads primitive, and nothing ever reads upward or skips a tier. That single rule is what makes a theme swap a one-line change instead of a search. This skill decides what a variable is called and which tier it lives in; color decides what value goes in it, and dark-mode consumes the override layering defined here rather than inventing its own. If the question is "which oklch value", you are in the wrong skill.

Read the existing token layer before adding a name to it. Find where the project declares theme values — :root custom properties, a Tailwind v4 @theme block, a JS/TS theme object, a Style Dictionary pipeline — and how it names them, then match that convention even when you would have chosen differently. A codebase with one imperfect naming scheme beats one with two good ones. Never stand up a parallel token file next to an existing one, and never introduce a second theme-switching mechanism on top of the one already wired.

Quick Reference

Core Principles

1. Name primitives for what they are, semantics for what they do, components for where they live. --blue-500 is a fact, --color-accent is a decision, --button-bg is a location. A semantic token named after its current value — --color-blue-button — is a landmine that detonates the first time the brand changes. Exception: neutrals may keep a value-shaped primitive name (--gray-*) even in systems that otherwise abstract everything, because the ramp position is the meaning.

2. Let references flow downward only, one tier at a time. A component reading --gray-2 directly cannot be re-themed, and a semantic token reading another semantic token creates an alias chain nobody can trace. Exception: a semantic token may alias one other semantic token when it names a genuinely narrower role — --color-border-input pointing at --color-border is a real refinement, not a rename.