Naming architecture options
Type: Comparative view
Status: Active hypotheses
Canonical for: Non-prescriptive comparison of possible naming and metadata responses
Depends on: Research-bundle reconciliation, controlled-vocabulary findings, and public design-system examples
These are comparison options, not PDS recommendations.
| Option | Potential benefit | Main risk | Evidence status |
|---|---|---|---|
| Rename public variants | immediate cue; less prior conflict if well aligned | migration; new ambiguity; one word still compresses policy | adjacent evidence supports name sensitivity; design-system benefit not established |
| Semantic aliases / canonical IDs | compatibility plus stable concept identity; multilingual labels possible | aliases do not fix conflated concepts | supported by SKOS/schema patterns; agent effect not tested here |
| Rich descriptions | low API disruption; can define local exceptions | prose may be missed, stale or hard to validate | adjacent experiments show descriptions affect selection |
| Structured metadata | queryable useWhen, avoidWhen, examples, alternatives | authoring/governance cost; schema bloat | inferred from tool research and controlled vocabularies |
| Separate properties | makes dimensions visible and composable | invalid combinations and larger API surface | demonstrated in GitLab, Spectrum, Shopify and Radix APIs |
| Decision rules outside API | can include workflow/context logic without bloating props | retrieval and version-linking become critical | documented design-system guidance already supplies such prose; machine effect untested |
| Controlled vocabulary | stable concepts, aliases, definitions and relationships | ontology overhead; may become detached from code | established adjacent pattern, not a full selection engine |
Why combinations are likely
No option covers the entire problem. A factored property model without constraints admits nonsense; metadata attached to an overloaded value preserves conceptual confusion; a precise name without alternatives gives no boundary cases; an ontology without version links may describe components that no longer exist.
An evidence-compatible machine representation could include, without prescribing exact PDS fields:
- stable concept identifier and version;
- human label plus aliases;
- semantic dimension/type;
- definition and scope;
- positive and negative selection criteria;
- examples and counterexamples;
- alternatives and distinguishing conditions;
- allowed combinations/context constraints;
- links to implementation, Figma, stories, tokens and accessibility semantics.
That list is a research model to test, not a proposed PDS API.