Rationale Layer

Annotate tokens with why, when, deprecated, and alternatives — and agents read it.

The rationale layer is a YAML sidecar next to your contract. It lets you annotate tokens and components with context that isn't in the source of truth itself — why a token exists, when to use it, whether it's deprecated, and what to use instead.

Agents reading the contract via MCP will prefer annotated tokens, refuse deprecated ones, and surface the reasoning when asked.

File

By default, Primitiv reads primitiv.rationale.yml from your project root. You can override the path in primitiv.config.js under rationale.path.

Example

# primitiv.rationale.yml

color.brand:
  why: "Primary action colour across all surfaces"
  when: "CTAs, primary navigation, focus rings"

color.primary.old:
  deprecated: true
  why: "Replaced by color.brand in v2 — the old hue failed WCAG AA on dark surfaces"
  alternatives: [color.brand]

spacing.md:
  why: "Default vertical rhythm between related elements"
  when: "Gaps inside a card, between form fields, between list items"

Fields

Field	Type	Purpose
`why`	string	The reason the token exists. Shown to agents alongside the value.
`when`	string	Use cases that fit this token. Helps agents pick the right one.
`deprecated`	boolean	Agents will refuse deprecated tokens and suggest alternatives instead.
`alternatives`	string[]	Token names to use instead of a deprecated one.

How agents consume it

When an agent calls get_design_context or get_token, the rationale fields for each token are returned alongside the value. Agents are instructed (via the MCP tool descriptions) to:

Prefer tokens with explicit why / when over un-annotated ones when the choice is ambiguous
Refuse to emit a deprecated token and surface the alternatives to the user instead
Cite the why when the user asks "why this token?"

Governance

The rationale layer is authored by humans — it is not inferred. Treat it as the part of your design system that documents intent, not structure. Keep it next to the code so reviewers see changes to intent in the same PR as changes to the token itself.