Executive answer

Type: Explainer
Status: Active
Canonical for: Concise interpretation of the naming stream for non-specialist readers
Depends on: Research-bundle reconciliation, evidence ledger, and comparative matrices

Short answer

Semantic naming probably matters to AI agents, but current public evidence does not establish how large the effect is for design-system decisions.

• Demonstrated: mature systems expose the same words with materially different meanings, and many place hierarchy, appearance, consequence and context in one property. This creates genuine schema ambiguity before an agent is involved.
• Empirical adjacent evidence: controlled tool-selection studies show that names, descriptions, semantic overlap and alignment with a model’s learned conventions affect selection. This makes the design-system hypothesis plausible, not proven.
• Not established: no credible public experiment found in this review isolates a design-system variant name while holding implementation, visuals, documentation and task constant.

The evidence does not support “find a perfect replacement word.” A name is a compressed label and does not, by itself, express a contextual decision policy. A recurring candidate model visible across public practice combines a scoped name with an explicit property dimension, definitions, use/avoid rules, relationships and state kept separate. Its effect on design-system agent performance remains unproven.

What the systems show

The public APIs range from strongly overloaded to substantially factored:

• Carbon’s kind combines hierarchy (primary, secondary, tertiary), consequence (danger) and appearance (ghost). Its prose supplies the missing decision logic. Carbon Button
• Atlassian’s appearance combines prominence (primary, subtle), consequence (warning, danger) and product/experience identity (discovery, rovo). Atlassian Button
• GitLab separates category (visual emphasis), variant (action meaning) and states such as selected/loading/disabled. It also documents exceptions: a destructive action need not always be visually dominant. GitLab Button
• Spectrum separates variant, treatment and static-color, although its variant values still mix emphasis and consequence. Spectrum Web Components Button
• Shopify’s current web-component model explicitly separates tone, color intensity and variant. Polaris web components
• Radix makes variant explicitly visual and separates color, highContrast and loading state. It largely leaves usage intent outside the button schema. Radix Button

This demonstrates that a single variant axis is not inevitable. It does not demonstrate that more axes automatically produce better agent decisions; factored models can create invalid combinations unless constraints are supplied.

Strongest conclusion

Inferred: the central failure mode is not merely weak words. It is loss of semantic dimension and decision context. danger is easier to interpret inside tone than inside an undifferentiated variant; secondary remains relational even inside emphasis; and neither tells an agent whether a particular commerce task is governed by a local exception.

A candidate machine-facing representation can be evaluated against questions such as:

1. What dimension does this value belong to?
2. What concept does it denote locally?
3. When is it selected or avoided?
4. Which alternatives are confusable, and how are they distinguished?
5. Which combinations and contexts are valid?
6. What state and accessibility semantics remain invariant?

Naming versus metadata

Name alone carries the least explicit local information. Descriptions can add scope. Structured fields can make distinctions separately addressable and mechanically checkable. Relationships and constraints can express more than a glossary. These are differences in represented information, not a demonstrated performance ranking for design-system agents.

Descriptions affect related tool/schema behavior, but structured useWhen/avoidWhen fields have not been compared with information-matched prose, and per-value descriptions are not proven to override misleading design-system enum labels.

This does not imply that names are irrelevant. Tool-selection research indicates that models use names and descriptions as signals, and that semantic overlap and pretrained familiarity can bias selection. The prudent interpretation is: make names honest about their dimension, then do not force the name to carry the whole policy.

Direct evidence versus analogy

Choosing an enum value such as variant="secondary" is analogous to tool calling when an agent sees a finite schema and must map a natural-language request to one option. The analogy is strongest for zero-shot selection and competing enum values. It weakens when design requires layout judgment, visual context, product policy, multiple components, or iterative rendering. Tool benchmarks therefore motivate an evaluation; they cannot substitute for one.

Human and machine semantics

There is no established requirement for a separate, unnatural machine vocabulary. Humans also benefit when dimensions, definitions and exceptions are explicit. The tension appears when a concise historical label works only because expert users carry undocumented local knowledge.

Four cases should remain distinct:

1. A shared label has a shared meaning: keep it and attach one governed definition.
2. A shared label has a local meaning: preserve compatibility but add scope and decision rules.
3. Different audience labels refer to one concept: use stable identity plus labels or aliases.
4. One label hides multiple dimensions: aliases cannot repair the conceptual conflation.

Optimizing only the public name creates migration, retraining and new-ambiguity risk. Repairing only through metadata creates retrieval, drift and continued-human-shorthand risks. The evidence-balanced interpretation is that humans and agents need access to the same governed concepts; whether labels, aliases, metadata or API changes are needed must be evaluated per system.

Research boundary

This package compares architecture options but does not recommend renaming PDS variants, define a PDS API or provide a migration plan.