Relationship format (Component/Token Relationship — CTR)
Overview
A Component/Token Relationship (CTR) is an anonymous token that connects a component to a token. It replaces the former component-level tokenBindings list (component-declares-usage direction) and sits alongside the name-object scope fields on a token (component, variant, anatomy, state, and arbitrary option keys; token-declares-scope direction, validated by SPEC-018, SPEC-019, SPEC-020, SPEC-022, and SPEC-040).
Rather than encoding component/part/option context inside a token's name string, a CTR carries its value (or $ref alias) alongside an explicit scope object naming the component, part, property, and option scope it belongs to, plus an optional context string carrying a human-readable label (for example, a Figma Token Group label). CTR entries live under relationships/*.json, each file a JSON array of CTR objects (see relationship.schema.json).
NORMATIVE: This document defines the CTR foundation — shape, validation rules, and interim legacy-compatibility fields.
Shape
Each CTR is one of two subtypes, mirroring the token oneOf split (see token-format.md):
- Value-owning CTR (
ctrWithValue) — carries a literalvalue, like a token. - Relationship-only CTR (
ctrWithRef) — carries a$refalias to another token or CTRuuid, instead of an owned value.
[
{
"scope": {
"component": "button",
"part": "label",
"property": "color",
"options": { "variant": "accent", "state": ["hover"] }
},
"context": "Label color, accent variant, hover",
"value": "#0060e0",
"uuid": "5b1a8e2e-9e2f-4b7a-9b2e-1a2b3c4d5e6f"
},
{
"scope": {
"component": "checkbox",
"property": "corner-radius"
},
"$ref": "5b1a8e2e-9e2f-4b7a-9b2e-1a2b3c4d5e6f"
}
]
Scope fields
| Field | Required | Type | Description |
|---|---|---|---|
scope.component |
yes | string | Component name (kebab-case). MUST match the name of a declared component in the dataset (rule SPEC-051, mirrors SPEC-018). |
scope.part |
no | string | Anatomy part name. MUST match a declared anatomy part on the referenced component when present (rule SPEC-052, mirrors SPEC-020). |
scope.property |
yes | string | The stylistic attribute this relationship describes (e.g. color, width, padding). |
scope.between |
no | object | The two endpoints of a gap or padding: { "from": ..., "to": ... }. Either end may be omitted, and no other key is allowed. Each end SHOULD be a position (registry/positions.json), a generic anatomy term (registry/anatomy-terms.json) or an anatomy part the component declares, the same vocabulary as a space-between token endpoint (rule SPEC-101, mirrors SPEC-047). |
scope.object |
no | string | The styling surface; SHOULD be a term in registry/token-objects.json (rule SPEC-101). |
scope.position |
no | string | Location relative to another object or edge; SHOULD be a term in registry/positions.json (rule SPEC-101). |
scope.structure |
no | string | A reusable visual pattern; SHOULD be a term in registry/structures.json (rule SPEC-101). |
scope.qualifier |
no | string | A behavioral or layout modifier that is not a state, variant or position; SHOULD be a term in registry/qualifiers.json (rule SPEC-101). |
scope.icon |
no | string | Icon identity; SHOULD be a term in registry/icon-terms.json (rule SPEC-101). |
scope.options |
no | object | Option-scoped narrowing. Each options.<key> value MUST validate against the referenced component's options.<key>.values (rule SPEC-053 — the headline CTR rule, stricter than the token-side SPEC-040 warning). A boolean option (for example isSelected) takes true or false; use it, not state, for conditions the component models as an option. An array value matches when any listed value matches. A relationship with no pinned options is the default for its (property, context); a recipe uses the one that pins the most options matching the request. scope.options.state adds states to those of the token the relationship binds. options.state is the exception: an ordered array of state ids that must all be active, validated against the component's declared states (rule SPEC-054, mirrors SPEC-022); an element may be { "anyOf": [state, ...] } (see Any-of). The reserved key anyOf holds an any-of across option conditions (see Any-of). |
context |
no | string | Label for how this CTR is used (mirrors tokenBindings[].context; maps to a Figma Token Group label). A visual recipe binds on it, so it is an identity key; see Context. |
contextRole |
no | string[] | Registry term ids for the main word of context, in order (["background", "border"] for Background and border). See Context. |
contextPart |
no | string | The parenthesised part of context (Dot, icon to label). Exclusive with contextQualifier; needs contextRole. |
contextQualifier |
no | string | The parenthesised qualifier of context (semantic, minimum). Exclusive with contextPart; needs contextRole. |
Layer 1 (relationship.schema.json) only enforces shape: scope.options is an object, scope.options.state (when present) is an array of strings, and other option values are strings, numbers, booleans (for boolean options) or arrays of those. It does not enforce which option values are valid — that is a Layer 2 (Rust, sdk/core) relational rule, because it requires cross-referencing the component catalog.
Unsupported value shapes. An engine MUST refuse, when it loads a relationship record, a scope.options whose value has a shape it does not understand, and MUST NOT ignore that key. The error SHOULD name the file (when the record comes from one), the record and the key, and say that the data is newer than the engine. An engine that embeds its relationship data MUST apply the same check to it when it loads. The shapes an engine understands are: for state, an array whose elements are state strings or { "anyOf": [strings] }; for anyOf, a non-empty array of non-empty objects of option pins; for every other option, a string, a number or a boolean, or an array of those. An engine built before an any-of was added refuses such a record instead of applying it to every request, which is what ignoring an unknown pin would do. The numbers allowed are the numeric pins that exist in the data (scaleIndex). An engine MUST also refuse a record whose scope has a field it does not know, and MUST NOT ignore it: the fields an engine understands are listed in the table above (an engine that knows between or a descriptive field MUST also refuse a value that is not the shape given there), and dropping an unknown field that identifies a record would make two records that differ only by it look the same. The same error message applies.
Any-of
A record sometimes holds for "this or that": an indeterminate checkbox is drawn like a selected one, and hover and down can share a token. scope.options is an AND of pins, so two forms express the OR (proposal 017).
- Options.
scope.options.anyOfis an array of at least two objects, each an AND of option pins in the same form asscope.optionsand with at least one pin. The record applies when its other pins match and at least one alternative matches:{ "isEmphasized": true, "anyOf": [{ "isSelected": true }, { "isIndeterminate": true }] }means emphasized, and selected or indeterminate. An alternative MUST NOT holdstate,scale,colorSchemeoranyOf. - States. An element of
scope.options.statemay be{ "anyOf": [state, ...] }, with at least two states.["selected", { "anyOf": ["hover", "down"] }]means selected, and hover or down.
anyOf is reserved: a component MUST NOT declare an option named anyOf.
Meaning. A record with an any-of is equivalent to one record per combination of alternatives, all with the same $ref. An implementation may evaluate it directly or expand it, and MUST give the answer of the expansion. An alternative that contradicts a pin of the record (isSelected: true beside an alternative isSelected: false) matches no request. The record is ranked as its best matching expansion: the resolution steps of State model apply to each expansion, and a request that matches two expansions with the same token is not a tie.
Limits. A record MUST NOT use an any-of when it carries its own value and no $ref, because an any-of has no token to share between its expansions. A record expands to at most 64 variants. A record that carries a legacyKey MUST NOT use an any-of, because the legacy token name cannot express it.
Context
context is not only a description. A visual recipe selects a relationship by {property, context} and the match is on the exact string (trimmed), so the string is the identity key for recipes (rules SPEC-062, SPEC-067, SPEC-087) and for the changelog. Changing it changes which recipe bindings resolve.
Grammar. A context is a main word with an optional parenthesised detail: Spacing, Width (minimum), Spacing (icon to label), Non-semantic (Dot). The main word names the role of the value and SHOULD be a label or alias in registry/relationship-contexts.json (rule SPEC-091, matched ignoring case and stray whitespace). A compound main word joins registered words with and or commas (Background and border, Label, icon, and hold icon). The detail is either an anatomy part (Dot, icon to label) or a qualifier (semantic, minimum). Text after the closing parenthesis is tolerated but is not part of the grammar.
Structured fields. contextRole, contextPart and contextQualifier are optional and sit next to the string. They are generated from it and checked against it, never a second source of truth. The derived label is the role labels joined (A, A and b, A, b, and c, with the later labels lower-cased in their first letter) followed by (part) or (qualifier). When both exist the string MUST equal the derived label, or its main word MUST resolve through the registry aliases to the same terms as contextRole with the same parenthesised detail (rule SPEC-090). Text therefore agrees with contextRole: [label] and Drop shadow with [shadow]; contextRole always holds canonical ids. A record carries at most one of contextPart and contextQualifier, and either needs a contextRole. The string stays authoritative; replacing it with the fields is deferred. An alias is accepted in sentence case (Padding, Tab items); a case variant (Minimum Height) or an alias of a different term fails SPEC-090 until it is renamed or the fields are left off. A term for one item has a typed singular id (tab-item) in the item category; the plural alias (Tab items) belongs to the container term (navigation). Renaming changes which recipe bindings resolve, so it is done with the recipe references.
When a live record may omit it. A live record MAY have no context when a contexted record reaches it through $ref uuids, directly or through other records, because the recipe binds the contexted record and the alias chain supplies the value. A live record with no context that nothing contexted reaches cannot be bound by a recipe and SHOULD get one (rule SPEC-092). Deprecated records are exempt.
Options belong in scope.options, not in the context. A parenthesised part of a context MUST NOT equal a value of an option the component declares (a size value counts in its spelled form: m is medium), a boolean option name (emphasized) or its negation (non emphasized), and default MUST NOT appear beside records that name an option value (rule SPEC-093). Pin the option in scope.options instead: a record that pins no option is the default, so the default value needs no label. Width (default) beside Width (minimum) is a measurement, not an option, and is fine. Interaction states (down, focus) are not checked. Records of one component with the same property, context and $ref that differ only in the value of one declared option SHOULD be one record that pins an array (size: ["m", "l"]), except records that carry a legacyKey (rule SPEC-100).
SPEC-091, SPEC-092, SPEC-100 and SPEC-101 are warnings held at a baseline (sdk/core/tests/fixtures/recipe-lint-baseline.json), so existing data passes while new warnings fail the ratchet. SPEC-093 is an error: the data is migrated.
Value-owning vs. relationship-only
| Field | Subtype | Description |
|---|---|---|
value |
ctrWithValue |
Literal value owned by this CTR, same value-type narrowing as a token's value ($valueType). |
$ref |
ctrWithRef |
Alias target. MUST resolve to a token or CTR uuid in the dataset (rule SPEC-055, mirrors SPEC-001/SPEC-027). |
A CTR MUST NOT declare both value and $ref (enforced at Layer 1 via not: { required: [...] }, mirroring token.schema.json).
Identity
| Field | Required | Type | Description |
|---|---|---|---|
uuid |
yes | string (uuid) | MUST be present (rule SPEC-084) and globally unique across all relationship entries within the same cascade layer (rule SPEC-056, mirrors SPEC-004). It is the stable identity changelogs, platform overrides and $ref use, and MUST NOT change once assigned. |
A platform manifest overrides or removes a foundation relationship by this uuid, and a platform-local relationship (an extensions/relationships/ file or an inline extensions.relationships add) carries its own. Authors can generate ids with packages/design-data/scripts/backfill-relationship-uuid.mjs, which derives a UUIDv5 from the record's identity and never changes an existing uuid.
Legacy fields (interim)
To keep packages/tokens/src (the legacy generated output, produced by design-data migrate legacy-output / sdk/core/src/legacy.rs) byte-identical while this foundation lands, a CTR that has a legacy counterpart carries transitional fields so the existing legacy generator can still reproduce that output:
| Field | Required | Type | Description |
|---|---|---|---|
legacyKey |
no | string | Pins the exact flat key written to legacy output, mirroring the token name-object legacyKey escape hatch. |
setUuid |
no | string (uuid) | Identifies the legacy color-set entry this CTR belongs to. Only meaningful alongside legacyKey. |
setSchema |
no | string | Names the legacy color-set schema this CTR's set entry conforms to. Only meaningful alongside setUuid. |
NORMATIVE: A CTR that has no legacy counterpart SHOULD NOT carry legacyKey/setUuid/setSchema — these fields exist solely to bridge the interim period before the legacy generator is retired or rewritten to consume CTRs directly. Rule SPEC-057 (ctr-legacykey-present-if-legacy, warning) is an advisory placeholder documenting this intent; it does not attempt to detect "should have a legacy counterpart" automatically, since that determination belongs to the (future) generator-side migration work, not this foundation.
These fields are transitional. Once the legacy generator (or its replacement) reads CTRs directly, legacyKey/setUuid/setSchema are expected to be removed in a later spec version.
Relationship to componentBindings
The component-level tokenBindings field was removed; relationships are the only place a component declares which tokens it uses. The token-side componentBindings reverse index (see token-format.md#component-bindings) is derivable from relationships.
SPEC rules
The following rules are added to the Layer 2 rule catalog (rules/rules.yaml) by this chapter. New CTR rules start at SPEC-051 to avoid collision with the existing catalog (SPEC-001–SPEC-050).
| Rule ID | Name | Severity | Assert |
|---|---|---|---|
| SPEC-051 | ctr-component-exists |
error | CTR scope.component value MUST match the name of a declared component in the dataset. |
| SPEC-052 | ctr-part-valid |
error | CTR scope.part value MUST match the name of a declared anatomy part on the referenced component (when present). |
| SPEC-053 | ctr-option-valid |
error | CTR scope.options.<key> value MUST match a value in the declared options.<key>.values list for the referenced component (when that list exists). |
| SPEC-054 | ctr-state-valid |
error | CTR scope.options.state array elements MUST match the name of a declared state on the referenced component (when state declarations are present). |
| SPEC-055 | ctr-ref-resolves |
error | CTR $ref value MUST resolve to a declared token or relationship uuid in the dataset. |
| SPEC-056 | ctr-uuid-unique |
error | CTR uuid values MUST be unique across all relationship entries within the same cascade layer. |
| SPEC-057 | ctr-legacykey-present-if-legacy |
warning | Advisory placeholder: a CTR that round-trips through the legacy generator SHOULD carry legacyKey. Generator-side "should have a legacy counterpart" detection is deferred; this rule documents intent rather than enforcing it structurally. |
| SPEC-084 | ctr-uuid-required |
error | Every CTR MUST have a uuid. |
| SPEC-090 | relationship-context-fields-agree |
warning | contextRole/contextPart/contextQualifier MUST be consistent, and agree with the context string when it is present. |
| SPEC-091 | relationship-context-main-word-registered |
warning | The main word of context SHOULD be in registry/relationship-contexts.json. |
| SPEC-092 | relationship-live-record-has-context |
warning | A live CTR with no context SHOULD be reached by a contexted CTR through $ref. |
| SPEC-093 | relationship-context-names-option |
error | A context MUST NOT name an option value; pin it in scope.options. |
| SPEC-094 | relationship-state-repeated |
warning | A state SHOULD appear in at most one element of a scope.options.state array. |
| SPEC-095 | component-option-name-reserved |
error | A component MUST NOT declare an option named anyOf. |
| SPEC-096 | relationship-any-of-single-option |
warning | An anyOf SHOULD NOT pin the same single option in every alternative; use an array value. |
| SPEC-097 | relationship-any-of-redundant |
warning | An anyOf alternative SHOULD NOT repeat or contradict a pin of the record, or equal or contain another alternative. |
| SPEC-098 | relationship-any-of-undeclared |
warning | Each anyOf alternative SHOULD pin at least one declared option. |
| SPEC-099 | relationship-any-of-legacy-key |
error | A relationship that uses an any-of MUST NOT carry a legacyKey. |
| SPEC-100 | relationship-options-mergeable |
warning | Records that differ only in one declared option's value SHOULD be merged into one record that pins an array. |
| SPEC-101 | relationship-scope-vocabulary |
warning | scope.between, scope.object, scope.position, scope.structure, scope.qualifier and scope.icon values SHOULD exist in their registry vocabulary. |