README

Semantic naming in design systems for AI agents

Type: Navigation
Status: Active
Canonical for: Entry points, ownership and reading order for the semantic-naming research stream
Depends on: Canonical research terminology

Research question

How should the concepts, properties, variants, states, roles, tokens and relationships inside a design system be named and structured so that AI agents can correctly infer their intended meaning and use?

Research boundary

This package evaluates naming as one part of machine-consumable design-system semantics. It does not assume that renaming public APIs is the solution, and it makes no PDS recommendation or migration plan.

Use the cross-package canonical research terminology, especially the separation among component/tool names, property/parameter names and enum-value names.

Evidence labels

• Demonstrated: public implementation or direct empirical experiment.
• Documented: first-party guidance.
• Empirical adjacent evidence: relevant LLM/tool/schema experiment that does not directly test design systems.
• Inferred: conclusion derived from combined evidence.
• Not established: insufficient evidence.
• Contradicted: credible evidence conflicts with the proposition.

Research outputs

• executive-answer.md
• variant-naming-matrix.md
• semantic-collision-matrix.md
• property-model-matrix.md
• naming-taxonomy.md
• llm-schema-research.md
• controlled-vocabularies.md
• naming-architecture-options.md
• evidence-ledger.md
• research-bundle-reconciliation.md
• button-enum-naming-experiment-v0.2.md
• archive/README.md — superseded and merged research intermediates
• sources/README.md — preserved raw research inputs; not canonical conclusions

Reading order

Start with executive-answer.md, then use the three matrices for auditable comparisons. The research review and controlled-vocabulary report establish the adjacent evidence; the architecture options remain deliberately non-prescriptive.

For the latest evidence reconciliation and the active first experiment, read research-bundle-reconciliation.md and button-enum-naming-experiment-v0.2.md. The older evaluation protocol and the broader multi-axis design in the supplied attachment bundle are superseded because they mix semantic axes and experimental interventions. The source archive preserves those inputs for provenance without giving their older claims canonical status.

Central adversarial test

If the exact same component were exposed to an agent under a different name, would the agent make a different design decision?

If so, is renaming the best solution, or does the system need explicit semantics beyond the name?