# The semantic layer checklist

The tier that turns a palette into a design language. From tokenstoagents.ai/kit.

## The completeness test

Could someone build a correct screen using only semantic tokens, never touching a primitive? Run it on one real screen before you read further. Every place they'd have to dip into raw grays and reds is a place an agent will guess.

## Roles to cover

Work through these in order. Two dozen semantic tokens carry most products.

Text roles: primary, muted, error, inverse, link if links are styled distinctly, disabled.
Surface roles: page, raised, sunken if used, danger-subtle, selected.
Border roles: default, strong (focus and selection), error.
Feedback roles: danger, warning, success, info. One token per role. If your product only uses danger today, define only danger; empty categories invite decorative use.
Action roles: primary, primary-hover, secondary, disabled.
Spacing roles: inset (control, card, section), stack (tight, default, loose), inline gaps if your layouts need them.
Type roles: body, caption, heading scale, code if applicable.

## The naming grammar

Pick the axes and fix their order: category, role, variant, state. color.text.error, color.surface.danger-subtle, space.inset.card. Then close the vocabulary: one word per concept, synonyms banned. If "disabled" is the word, "muted," "inactive," and "dimmed" are not also words. Write the grammar in ten lines at the top of the token file; that paragraph is machine-readable context, and an agent that reads the rule applies the rule.

The prediction test: could an agent predict your next token's name from the last twenty? A grammar generalizes. A pile of precedents just accumulates.

## Descriptions that earn their bytes

Every semantic token carries a $description that states the role and its boundary, not the value. Bad: "Red 500." Good: "The danger role: destructive actions and error indicators. Never used decoratively." The description field is documentation delivered at query time, which is the only documentation an agent reliably reads.

## Enforcement

1. Alias direction: semantic tokens reference primitives, never the reverse, and never sibling semantics more than one hop.
2. Lint primitives out of application code. Primitives are for the token file; semantics are for use. A semantic tier that isn't enforced teaches every consumer, human and agent, that meaning is optional.
3. Deprecation by alias: renaming a role? Keep the old name as an alias with a deprecation note in its description for one release window, then remove. Compiled output stays stable while sources clean up.
4. Reviews move up a tier: design review approves role assignments ("should this use feedback.danger?"), not hex values. If reviewers are still debating values, decisions are leaking past the semantic layer.

## The 80 percent warning

A complete semantic layer is necessary, not sufficient. Values plus meaning still leave contracts (which token applies to which component part) and delivery (how the agent learns the rules) to the layers above. Teams that stop here get beautiful guessing at the component level. Keep going: component tokens where precision pays, then contracts, then the runtime files.