Token Taxonomy, Vocabulary, and Formatting — Naming Convention Decomposition

[GarthDB]

Summary

This RFC proposes decomposing "naming convention" into three distinct, independently malleable layers — Token Taxonomy, Token Term Vocabulary, and Formatting Style — and restructuring the spec's name object to align with this framework. It also proposes integrating component anatomy into the design data model and separating it from token styling surfaces, which are currently conflated in the registry.

This builds on:

• #661 — Spectrum Design System Glossary (registry infrastructure)
• #646 — Token Schema Structure and Validation System (analytical model)
• #714 — Design Data Specification (umbrella)
• Nate Baldwin's "Naming conventions & shared taxonomy" onsite presentation (April 1, 2026)

Motivation

"Naming conventions" is too broad a term for use when discussing malleability across platform teams. A token name like accent-background-color-hover embeds multiple independent decisions:

1. Which concepts are represented and in what hierarchy → taxonomy
2. Which words describe each concept → vocabulary
3. How the words are rendered (casing, delimiters, abbreviations, order) → formatting

Each layer has a different malleability profile:

Layer	Shared?	Platform-malleable?
Token taxonomy	Yes — shared concept hierarchy	No — changing order/categories changes meaning
Token term vocabulary	Yes — canonical terms at foundation level	Partially — platforms can map terms (e.g. hover → highlighted for iOS)
Formatting style	Default exists for legacy compat	Yes — platforms own casing, delimiters, abbreviations

Additionally, the current spec's name object has a single property field that conflates multiple concepts (component anatomy, styling surface, CSS property). This makes structured querying and validation difficult.

Proposal

1. Restructured name object

The current name object fields:

property (REQUIRED), component, variant, state, colorScheme, scale, contrast

Proposed name object aligned with a semantic/layout token taxonomy:

Semantic fields (advisory validation against registry):

Field	Category	Description
property	Property	Narrowed: now just the CSS/styling attribute (color, width, padding, gap)
component	Component	Component scope (button, checkbox, etc.)
structure	Structure	Reusable visual patterns across components (base, container, list, accessory)
substructure	Sub-structure	Child within a structure (e.g. "item" in "list-item")
anatomy	Anatomy	Visible named part of a component (icon, label, track, handle)
object	Object	Styling surface (background, border, edge, visual)
variant	Variant	Variant within a component
state	State	Interactive or semantic state
orientation	Orientation	Direction/order (vertical, horizontal)
position	Position	Location relative to another object (affixed)
size	Size	Relative t-shirt sizing (small, medium, large)
density	Density	Space within/around component parts (spacious, compact)
shape	Shape	Overall component shape (uniform)

Dimension fields (strict validation against declared modes):

Field	Description
colorScheme	light / dark / wireframe
scale	Platform density (desktop, mobile) — distinct from semantic size
contrast	Contrast level (regular, high)
Additional keys	Platform-declared dimensions

2. Component anatomy vs. token objects

These are currently conflated in anatomy-terms.json (24 terms) but serve different purposes:

Component anatomy — the visible, named parts of a component as defined by designers. Appears in component specification diagrams. Should be declared per component in component schemas.

An audit of 65 S2 component docs found 133 unique anatomy terms across three tiers:

• Primitives (~25-30): Reusable across many components — icon, label, track, handle, fill, title, description, container
• Composites (~15-20): Another component used as a part — checkbox, close button, popover, avatar
• Component-specific (~40+): Unique to one component — loupe, gripper, tour step counter

Token objects / styling surfaces — where a visual property is applied on a UI element. NOT anatomy. Only 4 of 65 components list "background" as anatomy; for most, background is a styling surface, not a visible named part.

Current anatomy-terms.json terms like background, border, edge, visual belong in a separate token-objects.json registry.

3. Three registries

Registry	Purpose	Validates field
Component Anatomy	Visible parts of components (from designer specs)	anatomy
Token Objects	Styling surfaces referenced in token names	object
Taxonomy Categories	Allowed values within each concept category	structure, orientation, position, size, density, shape

Plus existing registries for component, variant, state (unchanged).

4. Formatting as serialization

The name object is unordered structured data. Concept ordering, casing, and delimiters are serialization concerns owned by the output formatter.

Default serialization (legacy format):

{component}-{structure}-{substructure}-{anatomy}-{object}-{property}-{orientation}-{position}-{size}-{density}-{shape}-{state}

Platform manifests can declare formatting rules:

• conceptOrder — ordered list of fields for serialization
• casing — kebab-case, camelCase, PascalCase, SCREAMING_SNAKE_CASE
• delimiter — character(s) separating concepts
• abbreviations — term → short form mappings

5. Platform dimension autonomy

Platform manifests should be able to:

• Declare new dimensions (e.g. iOS framework: [UIKit, SwiftUI])
• Restrict foundation dimension modes (e.g. iOS scale: [mobile] only, excluding desktop)
• Map vocabulary (e.g. hover → highlighted)
• Configure formatting per platform

Examples

Legacy: accent-background-color-hover

{ "name": { "variant": "accent", "object": "background", "property": "color", "state": "hover" } }

Semantic/layout: base-padding-vertical-small

{ "name": { "structure": "base", "property": "padding", "orientation": "vertical", "size": "small" } }

With anatomy: slider-handle-width

{ "name": { "component": "slider", "anatomy": "handle", "property": "width" } }

Same token, different platform formatting:

accent-background-color-hover          (default, kebab-case)
ACCENT_BACKGROUND_COLOR_HOVER          (SCREAMING_SNAKE_CASE)
AccentBgColorHover                     (PascalCase + abbreviations)
accent-bgColor-hov                     (mixed case + abbreviations)

Relationship to prior RFCs

RFC	Relationship
#661 — Glossary	Registry infrastructure this builds on. Phase 5 (RFC #646 reconciliation) is subsumed by this work.
#646 — Token Schema	Analytical model that informed the original name object. This RFC evolves the name object with taxonomy alignment and anatomy integration.
#714 — Spec umbrella	This RFC adds taxonomy.md to the spec document set.
#715 — Distributed Architecture	Platform autonomy model for dimensions and formatting aligns with the distributed architecture vision.

Open questions

1. Anatomy audit scope — The 133 terms from S2 docs have significant data quality issues (compound entries, inconsistent naming). How much cleanup should block the spec work vs. be done incrementally?

2. property field migration — Making property REQUIRED but narrowing its semantics is a breaking change for existing cascade-format tokens. What migration path works for in-progress work?

3. Taxonomy scoping — The 8 categories above are for semantic/layout tokens. What other token type taxonomies need to be defined (color, typography, motion)?

4. structure vs component — Nate's presentation draws a clear distinction (structures are reusable visual patterns; components are specific UI elements). In practice, where does the line fall? Is a "card" a structure or a component?

5. Validation strictness — Should new taxonomy fields (orientation, position, density, shape) start as advisory warnings or strict errors?

6. Platform dimension restrictions — When iOS excludes desktop mode, should tokens with scale: "desktop" become invisible to iOS tooling, or should they resolve to the default?

Implementation phases

1. Component anatomy audit & schema integration — Clean up S2 anatomy data, add anatomy to component schemas, split anatomy-terms.json
2. Name object restructuring — Update spec, schema, create taxonomy.md
3. Formatting & serialization — Document ordering as serialization, design formatting config
4. Platform autonomy — Structure manifest extensions for dimensions, vocabulary, formatting
5. Registry ↔ spec validation bridge — Per-field validation rules with tiered strictness

[NateBaldwinDesign]

Plus 1 on decomposing “naming conventions” into taxonomy vs vocabulary vs formatting. That framing is solid, and it matches the breakdown we’ve been using in Foundations & Data squad discussions (taxonomy order vs term vocabulary vs formatting style).

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 ≠ component schemas (and we need to keep that boundary crisp)

Our Foundations work is explicitly trying to move away from component-specific tokens because they grow exponentially, become unmanageable, and are hard to reason about (as evidenced in research and work being done in the Semantic Token & Taxonomy Refinement initiative).
Tokens should represent broad semantics (reusable structural objects and visual properties), not component anatomy or component option surfaces.

Concretely: the “component-like” aspects of tokens should be limited to:

• generic structural objects (e.g. base / container / list) and repeatable patterns, and
• styling surfaces / properties (e.g. background / border / gap / width)

As soon as we bake component + anatomy + variant into the token taxonomy, we muddy broad semantics with component-specific options that are really component props / behaviors, not shared foundation semantics.

Anatomy belongs in component schemas, not token taxonomy

I agree with the separation you’re trying to make (anatomy vs styling surfaces). But the conclusion should be:

• Component anatomy is component schema data (docs/spec diagrams; per-component), not part of token naming taxonomy.
• Token objects / styling surfaces are token semantics (where a property is applied), and belong in token vocabulary/registry.

If we need a structured place to store per-component anatomy terms, that’s great — but it should live alongside component schemas, not inside token classifications.

Suggestion (to keep the good parts without collapsing layers)

1. Keep the taxonomy/vocabulary/formatting decomposition as the stable conceptual model.
2. Keep the “semantic taxonomy” scoped to semantic tokens (structure/property/etc.), and avoid making component/anatomy foundational requirements.
3. Treat component anatomy as separate component data (schema/docs) and reference it where needed — but don’t make it part of the token taxonomy itself.

This keeps the system “higher order” (shared semantics) instead of drifting back toward ground-level component modeling — which is exactly what the Foundations initiative is trying to avoid.