Deprecation-Alias Pattern for Renaming Public Names

Renaming anything consumed by name across a codebase — a design token, an API field, a config key — must not happen in one commit: a direct rename breaks every consumer simultaneously. Use a deprecation alias instead:

--color-brand-primary: var(--color-dark-blue-500);  /* new canonical name */
--color-accent: var(--color-brand-primary);         /* deprecated — use --color-brand-primary, remove in v3.0 */

Both names resolve to the same value during a migration window. The deprecation comment must carry three grep-able things: the word deprecated, the replacement name, and the removal version/date.

Migration order matters: migrate usages first, remove the alias declaration last — so the codebase compiles continuously and never hits a broken intermediate state. Remove only in a major version, after grep confirms zero remaining consumers. Searching var(--old) (the usage) rather than the bare name avoids matching the declaration itself.

Generalizes beyond CSS: the same alias-with-removal-date discipline is how you evolve any public contract without a flag-day break. The naming scheme just has to be distinct enough that grep is reliable.

Source: css-conventions skill §14.