Relationship format (Component/Token Relationship — CTR)

Overview

A Component/Token Relationship (CTR) is an anonymous token that unifies the two mechanisms that today independently connect components and tokens:

1. tokenBindings on a component declaration (component-declares-usage direction; see component-format.md#token-bindings).
2. Name-object scope fields on a token (component, variant, anatomy, state, and arbitrary option keys; token-declares-scope direction, validated today 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 (the same role tokenBindings[].context plays today — e.g. mapping to 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. It does not migrate existing token or component data; tokenBindings and componentBindings remain in the schemas and are NOT removed by this chapter (deferred to a future migration phase).

Shape

Each CTR is one of two subtypes, mirroring the token oneOf split (see token-format.md):

• Value-owning CTR (ctrWithValue) — carries a literal value, like a token.
• Relationship-only CTR (ctrWithRef) — carries a $ref alias to another token or CTR uuid, 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

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 typically strings. 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.

Value-owning vs. relationship-only

A CTR MUST NOT declare both value and $ref (enforced at Layer 1 via not: { required: [...] }, mirroring token.schema.json).

Identity

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:

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 tokenBindings / componentBindings

CTRs are designed to eventually supersede both tokenBindings (on components, see component-format.md#token-bindings) and the token-side componentBindings reverse index (see token-format.md#component-bindings), by combining both directions — and the token name-object scope fields — into a single first-class relationship record with an explicit context.

NORMATIVE: This chapter does NOT remove or deprecate tokenBindings or componentBindings. Both remain valid and required as-is. Migrating existing data onto CTRs, and any eventual removal of the superseded mechanisms, is out of scope for this foundation and deferred to a separate migration phase.

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).