Metadata

Sections marked as "Note" or "Example" are non-normative. Everything else is normative.

Tokens and collections MAY include the optional members listed in the table below.

Table: Optional metadata members and their intent.

Member	Purpose
$description	Human‑readable explanation; tools MAY display it but MUST NOT require it.
$deprecated	Either a boolean or an object with a $replacement JSON Pointer that MUST resolve to an existing token declaring the same $type; consumers SHOULD warn and MAY follow the replacement.
$lastModified	MUST be an RFC 3339 date-time string recording governance actions and establishes the lower bound for $lastUsed.
$lastUsed	MUST be an RFC 3339 date-time string for usage telemetry, MUST NOT precede $lastModified, and MUST be accompanied by a $usageCount greater than zero.
$usageCount	MUST be a non‑negative integer tracking adoption. Values greater than zero MUST appear with $lastUsed, while zero indicates no recorded usage and MUST NOT have a companion $lastUsed field.
$author	MUST be a non-empty string naming the contributor without leading or trailing whitespace.
$tags	MUST be an array of unique classification strings, each free of leading or trailing whitespace.
$hash	MUST be a non-empty stable identifier for change tracking and MUST NOT contain whitespace.

Consumers encountering a metadata member whose value violates these requirements MUST treat the member as absent.

Accessibility metadata

Tokens MAY include accessibility hints such as WCAG contrast ratios or user preference qualifiers (for example prefers-reduced-motion). Tools SHOULD use these hints to enforce inclusive design while continuing to honour the underlying token semantics.

{
  "link-color": {
    "$type": "color",
    "$value": { "colorSpace": "srgb", "components": [0, 0, 1] },
    "$extensions": { "org.example.a11y": { "wcagContrast": 4.5 } }
  },
  "fade-duration": {
    "$type": "duration",
    "$value": {
      "durationType": "css.transition-duration",
      "value": 200,
      "unit": "ms"
    },
    "$extensions": { "org.example.a11y": { "prefers-reduced-motion": true } }
  }
}

Semantic intent metadata

Extensions MAY attach intent descriptors to tokens (for example primary action or neutral surface) so that automation and machine-learning systems can reason about design intent.

{
  "$type": "color",
  "$value": { "colorSpace": "srgb", "components": [0, 0.5, 1] },
  "$extensions": { "org.example.ai": { "intent": "primary action" } }
}

INFO

For lifecycle planning guidance, see Changes.