[DRAFT RFC] Separate token taxonomy from component-relative data

[NateBaldwinDesign]

[DRAFT RFC] Separate universal token taxonomy from component-relative data

Scoped under: RFC umbrella #714
Continues: #806 — Token Taxonomy, Vocabulary, and Formatting, #832 — Component Contract in Design Data Spec (RFC-A)

Summary

Proposes removing substructure and role from the token name-object taxonomy, renaming object to element (narrowing it to generic cross-component surfaces), adding attribute/affordance/visibility as new universal fields, and splitting state into interaction (transient) and interaction-context (persistent) — so that the shared taxonomy (packages/design-data/fields/, registry/) only ever holds terms that are genuinely universal and cross-platform, never component-relative or platform-specific ones.

The problem

Token taxonomy is a classification system for generic, reusable design concepts — things that mean the same thing no matter which component or platform they show up on. Component data is explicitly component-relative, and its terminology can vary by platform. These are two different vocabularies with two different owners, and the current spec lets them bleed into each other.

Concretely, today: a component field exists on tokens but is used by only 5 of 2,374 tokens. 41 of 57 tokens using anatomy have no component/structure anchor at all, and only pass validation because the registry has been reactively flagged standaloneScope: true to match whatever was already there — not because anyone decided those parts were genuinely ownerless. Neither of those was a deliberate design; they accreted.

variant is a subtler case, worth being precise about rather than folding into the same "it accreted" claim. registry/variants.json already tags subtle, subdued, and emphasized with category: "emphasis" — but so are accent, primary, secondary, quiet, and hero, which are legitimate variants (distinct component-identity choices) and aren't part of this proposal's split. So there was prior awareness that "emphasis" is a distinct axis from color/semantic role — it just never became a schema-level field boundary, only an informal tag inside one shared registry. The specific split this RFC proposes (subtle→default→emphasized as a continuous prominence scale, pulled into a new visibility field, versus accent/primary/secondary/quiet/hero staying in variant as discrete style choices) is a judgment call about which "emphasis"-tagged terms form a scale versus which are identities — the existing category tag doesn't resolve that on its own, and it's fair to ask whether the line was drawn in the right place.

Precedent — we've already agreed to this principle twice

This isn't a new argument. It's asking the repo to hold a line it already drew, twice, in discussions that are both marked Implemented.

#806 proposed pulling component, anatomy, variant, and state into token taxonomy as ordinary fields. The response at the time:

"Where I strongly disagree is the direction this takes in practice: it's pulling component data (component + component anatomy + component prop axes) into token taxonomy. That's the wrong layer of abstraction for foundational (global or semantic) tokens... Tokens should represent broad semantics... not component anatomy or component option surfaces."

And the resolution, months later:

"The implemented spec drew the boundary where you said it should be. Component data is not part of token taxonomy... The component, anatomy, variant, and state fields in a token name object are cross-reference fields — they point to the component schema for validation purposes, not define component data."

#832 — self-titled "[RFC-A] Component Contract in Design Data Spec," part of this repo's own lettered RFC series (referred to as "RFC-A" throughout the rest of this document) — is where that cross-reference mechanism actually got built (SPEC-018–022), specifically to fix a disjointness problem: component options and token taxonomy were two unconnected systems, so nothing caught component=button variant=foo when foo isn't a real button variant.

This RFC is not re-litigating either of those. It's the same principle, applied to fields #806/#832 didn't touch, plus a fix for places where implementation drifted from the boundary #806 already set.

Proposed changes

• Remove substructure (zero real usage today) and role (duplicative of structure/the proposed element).
• Rename object → element, narrowed to generic, cross-component surfaces only (text, visual, bar, control, plus the recognized outliers workflow-icon/ui-icon). Property sub-qualities currently folded into object (background, border, corner, overlay, etc.) move to a new field instead of staying in this one.
• Add attribute — sub-qualities of a property, paired with property (border, background, dash, shadow, corner, overlay, gradient) instead of overloading property with compound terms like background-color.
• Add affordance — cross-component behavior indicators (drop-target, focus-ring, selection-indicator, drag-handle).
• Add visibility — prominence level (subtle, subdued, emphasized), pulled out of variant where it's currently miscategorized as a color/semantic variant when it's really a different axis entirely.
• Split state into interaction (transient) and interaction-context (persistent) — see below.
• Update the property vocabulary: remove background-color, border-color, corner-radius, font-size (expressed instead as property + attribute pairs, e.g. color + background); add length, offset, angle, step, radius, aspect-ratio, stop.

Why the split matters — with real examples, not hypotheticals

Property-level naming in this repo is, in practice, mostly platform-agnostic today — the real divergence risk is one level up, in variants and states. Component option keys like cornerRadius (swatch-group), containerPadding (tooltip, popover, contextual-help), iconSize (close-button), and maxWidth (tooltip) aren't platform-flavored in any meaningful sense: cornerRadius is iOS-native terminology (CALayer.cornerRadius), not a web borrowing, and the rest are just camelCase spellings of generic concepts (padding, size, width) every platform has its own version of. Property naming isn't where the real risk is.

Variants and states are where real divergence already shows up. registry/variants.json's confirmation, destructive, warning, error, and information entries are tagged category: "semantic", same as negative/positive/notice/informative/neutral — but their own descriptions self-identify as pattern-specific: "Confirmation dialog variant," "Warning dialog variant for cautionary alerts," "Informational dialog variant... alias for informative in alert contexts." error in particular reads as a dialog/alert-pattern label wearing a "semantic variant" hat, not a universal role, despite sitting in the same shared registry as the terms that are.

State-term divergence is shipped, not theoretical. registry/platform-extensions/web-components-interactions.json — production data, not a fixture — already maps the foundation's focus interaction term to Web Components' own "focused". taxonomy.md names this exact tension directly: "the vocabulary is shared with platform-aware compromises," giving hover → highlighted for iOS as its own illustrative example (spec prose, not yet a shipped manifest, but normative intent, not speculation on this RFC's part).

docs/proposals/006-vocabulary-gaps.md is a related but separate point, worth keeping distinct from the above: it's about token property names in the legacy corpus (card-background-well-color, stack-item-selected-background-color-highlight) still awaiting decomposition into property + attribute — a token-taxonomy cleanup, not a component-option naming question. taxonomy.md already names background-color as the anti-pattern the attribute split is meant to fix.

Cross-platform terminology divergence is also a documented finding from RFC-A (#832) itself, not a new claim. Its Phase 6.0 audit (audits/events.audit.md) found "SWC uses DOM event strings (change, sp-opened), RSP uses camelCase callback props (onChange, onOpenChange), and iOS uses closure params with different names (action, @Binding)," concluding "the naming model is not cross-platform stable" — which is why events were deferred from the component contract entirely, by an accepted governance decision, not left unresolved by oversight. This is the same shape of risk as variants/states, one layer further out.

How the architecture already handles platform divergence

None of this requires new machinery. The spec already has three independent, existing ways for a platform to diverge from the foundation's terminology, at three different layers:

1. Relabel a shared registry term. manifest.md's platform-extensions mechanism lets a platform declare {"extends": "<registry>", "extensions": [{"termId": ..., "platformTerm": ...}]} — but only as an annotation of an existing foundation id, never a new one. registry/platform-extensions/web-components-interactions.json is production data doing exactly this today: the foundation's focus is relabeled "focused" for Web Components.
2. Add or replace a whole component. extensions/components/ lets a platform add a net-new component, or fully replace an existing one by name — and component.schema.json's option-key shape (optionsMap) has no registry/enum constraint on option names at all, unlike variant values, which are checked against the shared registry via SPEC-040. A platform can already define a component with whatever option vocabulary it wants.
3. Declare component-scoped state/variant names freely. SPEC-022 validates a token's state (and would validate interaction/interaction-context under this proposal) against that component's own declared states[] — not a shared registry — the same way SPEC-019 already lets a component declare its own variant enum (e.g. Badge's "info" rather than the universal "informative").

Worth being precise about what this doesn't touch: cascade specificity is scored purely over mode-set fields (colorScheme, scale, contrast) per cascade.md — component/structure aren't specially weighted, so divergent terminology isn't a specificity risk.

What is true: all three mechanisms above only stay simple if the foundation vocabulary they build on is genuinely universal. Let component- or platform-relative terms into the shared registries directly, and mechanism (1) breaks down first — you can't cleanly relabel a "foundation" term that's already someone's local dialect. This RFC isn't proposing a fourth mechanism; it's protecting the assumption the existing three already depend on.

One concrete gap in mechanism (3), flagged rather than fixed here: a "universal" interaction registry only stays meaningfully universal if it's actively kept in sync as real cross-platform components show up. Today, if an Android component declared states: [{"name": "pressed", "trigger": "interaction"}], a token using interaction: ["pressed"] would validate cleanly — nothing forces "pressed" to be spelled "down", and it would just silently trip an advisory "not in the registry" warning without anyone connecting the two. The registry-value schema already supports fixing this via an aliases field (today's states.json uses it — "active" is declared aliases: ["pressed"]), so the mechanism exists; it's just not populated for a platform that has no real components in the corpus yet. Not proposing that fix here — we have zero real non-web/iOS components today, and RFC-A (#832) already set the precedent for waiting on real data rather than guessing (it deferred events for the same reason). Revisit once a real second-platform component set exists to map against.

What "foundational" vs. "platform-specific" means going forward

This RFC assumes a specific shape for where data lives, made explicit here rather than left implicit:

1. Tokens are platform-agnostic and serve the common case.
2. Some component data is also platform-agnostic.
   → (1) and (2) are foundational — the core of this repository.
3. Platforms can extend or override tokens within their own cascade layer, but only within the taxonomical classification this RFC (and Token Taxonomy, Vocabulary, and Formatting — Naming Convention Decomposition #806) establish — that's what keeps cross-platform cascade resolution working and prevents vocabulary drift.
4. Platforms can define entirely new component data for components that don't exist in the foundation.
5. Platforms can override or extend existing component data for their own platform.

(4) and (5) are already structurally supported today — mechanisms (1)–(3) above. This RFC doesn't need to build that capability, only keep the foundation side of the line from being muddied by (4)/(5)-shaped data leaking upward into (1)/(2).

A concrete illustration of (4)/(5): a token classified in this taxonomy as element: "text" + attribute: "color" is universal at the taxonomy level, but each platform's own component/rendering layer maps that same pair to a different idiomatic property name — color in HTML/CSS, textColor in UIKit, foregroundColor in SwiftUI, textColor in Android XML/View, or the color parameter on Jetpack Compose's Text(). That per-platform mapping is exactly (4)/(5)-shaped platform data — it's real, it already varies today across the platforms that exist, and it's precisely what this RFC's boundary is meant to keep out of the shared taxonomy.

The proposed state split is RFC-A's (#832) own distinction, propagated one layer up

RFC-A §3.3 already identified that state conflates two things:

"Persistent props (isDisabled, isSelected, isReadOnly, isInvalid) compose... Interactive states (hover, focus, pressed) compete... The single state field can't express both."

That's states[].trigger ("prop" vs "interaction") on the component declaration, which this RFC does not change. What this RFC proposes is taking that already-accepted distinction and applying it to the token side of the same cross-reference: state would split into interaction (transient, competing) and interaction-context (persistent, composing), so a token can express the same compose-vs-compete semantics RFC-A already gave components, instead of flattening it back into one array at the point of reference.

What this isn't saying

Some vocabulary overlap between component data and taxonomy is fine and expected (e.g. container/control as both a structure/element term and a component's own anatomy label) — that's a case-by-case call, not a violation. This also isn't about renaming any current component option. It's about what's allowed into packages/design-data/fields/ and registry/ going forward.

Open questions / follow-up work

• Data-quality finding, independent of whether this RFC is adopted: three components (select-box.json, stack-item.json, tree-view.json) currently declare states[].selected with trigger: "interaction", contradicting RFC-A's ([RFC-A] Component Contract in Design Data Spec #832) §3.3 example (isSelected is explicitly listed as a composing, prop-driven state). Should be corrected to trigger: "prop" regardless of this RFC's outcome — a direct, textual application of RFC-A, not a judgment call. Two more candidates were checked and are not clear errors: breadcrumbs.json's drag as trigger: "prop" (a plausible per-component implementation choice) and menu.json's default as trigger: "prop" (the canonical vocabulary table in state-model.md doesn't assign default a trigger at all).
• New validation rule to consider: nothing today checks that a token's state reference is placed in the field matching its component's declared trigger. If state splits into interaction/interaction-context, that gap becomes concrete rather than latent (a token could put a trigger: "prop" state name in interaction, or vice versa, and nothing would catch it). Would need a new SPEC rule cross-checking bucket placement against trigger, mirrored for CTRs the way SPEC-054 mirrors SPEC-022 today.
• Platform metadata: whatever replaces states.json should carry the existing platforms notes (iOS hover→highlighted, keyboard-focus→focused) forward into the platform-extensions/ mechanism rather than dropping them.
• Worth a second look in this light: docs/proposals/002-component-property-axes.md (still Draft) proposes importing component-schema-specific enums (style, staticColor, isEmphasized) directly into the universal taxonomy — exactly the conflation this RFC and Token Taxonomy, Vocabulary, and Formatting — Naming Convention Decomposition #806 argue against. Flagging for re-examination, not asserting it's wrong outright.

[NateBaldwinDesign]

I've created a draft PR for this discussion/RFC here: #1454

[NateBaldwinDesign]

One thing worth making explicit here, since it's a fair angle to attack this proposal from
either direction: there is real overlap between token taxonomy and component data, and the
diagram below is my attempt to map exactly where, rather than leave it as a vague gesture.

A few things fall out of checking this against the schema and the live corpus directly, rather
than going by feel:

Most of the apparent overlap is one generic mechanism, not several ad hoc ones.
SPEC-040
checks any name-object field (with a short reserved-list exception) against a matching
component.options.<field> enum, if one exists — see the
Options
section of the component format spec. size, orientation, and density look tightly coupled
to component data today — but that's because 46, 12, and 5 real components, respectively, happen
to declare those exact option keys. It's not a special mechanism built for those three fields;
it's the same generic rule that would fire on anything else the moment a matching option key
existed.

A smaller set of fields have dedicated, purpose-built cross-reference rules instead of the
generic one:
component
(name),
variant
(Options),
anatomy
(Anatomy (stub)),
and
interaction/interaction-context
(SPEC rules).
All four validate a token's value against that specific referenced component's own declared
data.

But those four aren't all the same kind of thing, and I don't want to conflate them.
component, anatomy, and variant fail the universality test
this RFC opens with:
a term is taxonomy if it means the same thing regardless of which component or platform uses it;
it's component data if it doesn't. A component's own variant enum is frequently custom
vocabulary (Badge's "info" vs. the universal "informative", already noted in the RFC).
anatomy values like track only mean something for one component's construction. component
is nothing but an identity pointer. None of those are universal.

interaction/interaction-context pass that same test cleanly: hover, focus, selected,
disabled mean the same thing on any component. SPEC-022 checking that the referenced
component happens to declare that state is validation, not evidence the concept itself is
component-relative — the same relationship property has to CTR (scope.property is required
there too, and nobody would argue color/width belong in component data).

That distinction matters beyond just labeling, because of what CTR already is. I checked
the relationship format spec
and its backing
relationship.schema.json:
scope.component, scope.part (anatomy), and scope.options.variant/interaction/
interaction-context are all named explicitly, and arbitrary option keys are supported
generically on top of that. For component/anatomy/variant specifically, that's not a
coincidental overlap — it's a structurally exact duplicate of what those three fields do when
baked directly into a token's own name object. That makes them legitimate candidates for
eventually being CTR-only, dropped from token name-objects entirely, once CTR is mature enough
to be the sole mechanism for that kind of scoping. This RFC doesn't propose that — it keeps
all three as-is, cross-reference fields, same as today. I'm flagging it as where I think this
eventually goes, not as part of what's on the table here.

One more relationship in the diagram is worth calling out as a different phenomenon
entirely: ColorRole and Visibility's arrows into Variant aren't a token-vs-component
boundary issue at all —
color-roles.json's
values (primary, accent, neutral, informative, negative, notice, positive) are
near-identical strings to
variants.json's
category: "semantic"/"emphasis"-tagged values. That's two token-taxonomy registries
overlapping with each other, not a token/component question. It's the same nuance already in
this RFC's "variant is a subtler case"
paragraph, just showing up again here from a different angle.

None of this changes what's actually on the table in this PR. It cleans up the fields whose
overlap is either generic-mechanism-driven (size/orientation/density, untouched here) or
genuinely universal despite validation (interaction/interaction-context, the split this PR
makes). It doesn't touch component/anatomy/variant's status as cross-reference fields, and
it doesn't attempt the CTR-only end state — that's a separate, later conversation.

[NateBaldwinDesign]

@GarthDB are there any issues you see with this proposal?