Design-token naming

UDTS names tokens so that an agent or linter can derive the token's class and contrast obligation from the name alone. The naming convention is hyphen-separated, prefix-loaded, and redundantly encoded in DTCG $extensions.udts.class so a validator catches mismatches.

When to use

• Designing a new token naming convention for a system that needs to be AI-legible.
• Auditing existing tokens that drift across naming styles (dot-paths, BEM, T-shirt-only, etc.).
• Adding a new component or token family — picking the prefix is the load-bearing decision.
• Code review: flag tokens whose prefix doesn't match their class, or tokens that hide their class in metadata instead of the name.

When NOT to use

• One-off internal tokens that never leave the file (CSS-variable convenience for a single component). The naming discipline isn't earned at that scope.
• Adapting an existing system that uses a different convention (Material 3 roles, Tailwind utilities, Radix layers). Don't propose UDTS naming as a rename project — use it for new systems or for the boundary layer.

The prefix-loaded convention

Every UDTS token name is <prefix>-<role-or-kind>-<modifier>-<stop>-<state>. The first segment — the prefix — declares the token's class (contrast-bound vs free, defined in apca-contrast) and kind (text / surface / border / ui / illustration / decorative / brand-spot, defined in the UDTS spec).