ui-vocabulary

Turn “I can point at it but cannot name it” into a small, evidence-backed candidate set. Naming is a routing step: it precedes component selection, implementation, and polish.

Read wiki/concepts/ui-component-vocabulary.md for the current source hierarchy and wiki/design/design-system.md for Kevin's component rules.

1. Freeze the clues

Separate visible facts from behavior that still needs proof. Record only the dimensions that distinguish nearby patterns:

• platform and surface: web, macOS, mobile, desktop shell, or named design system;
• placement and anchor: inline, attached to a trigger, centered, edge-mounted, floating, or persistent in layout;
• invocation: click, hover, focus, typing, shortcut, scroll, or automatic event;
• persistence and dismissal: persistent, timed, outside-click, selection, or explicit close;
• job: inform, reveal, navigate, choose a value, invoke an action, or contain a separate task;
• focus and modality: whether it accepts focus, traps focus, blocks the rest of the surface, or preserves background interaction;
• visible anatomy: trigger, indicator, panel, handle, track, scrim, selection, error, or other named part;
• implementation clues: native element, accessibility role/state, framework primitive, or platform API symbol.

For a screenshot, mark invocation, dismissal, focus, and keyboard behavior as unknown unless another artifact proves them. For a live page, use agent-browser read-only and inspect the accessibility tree plus one reversible interaction.

Complete when the observed facts and unknown behaviors cannot be mistaken for one another.

2. Discover one to three candidates

Search local knowledge first. The main owner is wiki/concepts/ui-component-vocabulary.md; Component Gallery is useful for cross-system examples.

For a generic, non-confidential description, NameThatUI is an allowed discovery source. Its public API records the query and the site says aggregate misses help improve retrieval, so never send customer names, unreleased product language, repository paths, URLs, credentials, incident data, or pasted application copy. Abstract the clue first, then run:

node skills/engineering/ui-vocabulary/scripts/search.mjs \
  --public-query "little outline around the keyboard-selected button"

The script refuses common private-data shapes and returns discovery candidates, not final authority. If the query cannot be safely abstracted, stay local and search primary documentation directly.

Rank candidates by behavioral fit. Include an alias or platform-owned name when it materially changes implementation. Do not invent a universal name when web, Apple, or a component library uses different terms.

Complete when each remaining candidate has a supporting clue and one fact that would distinguish it from the others.

3. Verify the owning platform

Discovery does not make a term canonical. Verify the claim against the source that owns it:

• web semantics and keyboard behavior: WHATWG HTML, WAI-ARIA, ARIA APG, and WCAG; use MDN for implementation and compatibility context;
• Apple platforms: Apple Human Interface Guidelines and Developer Documentation for the exact SwiftUI/AppKit/UIKit symbol;
• framework-specific names: the framework's current official documentation;
• visual style labels: dated primary criticism, design-system documentation, or the named movement's original source where available.

Reconcile the visible behavior with the documented semantics. A DOM role or component name can be wrong in a shipping implementation.

Complete when the leading name, important alias, behavior, and API/semantic claim have direct authority or are explicitly marked provisional.

4. Return a vocabulary receipt

Lead with the useful name:

## Likely name: [component or style]

**Confidence:** high | medium | low
**Platform:** [web / macOS / ...]

[One-sentence job and behavior.]

**Why it fits**
- [observed clue]
- [observed clue]

**Do not confuse it with**
- **[nearby pattern]** — [single decisive behavioral difference]

**Verified names**
- User-facing: [name and aliases]
- Semantics/API: [native element, role, property, or framework symbol]
- Primary source: [direct link]

**Prompt-ready wording**
> Build/use a [precise name] that [behavior, state, keyboard, and dismissal rule].

**Unknown**
- [only the unresolved fact that could change the classification]

Include a debug prompt only when the user is implementing or repairing the pattern. Stop after identification when implementation was not requested.

Verification

Run the deterministic privacy and response-shape tests:

node --test skills/engineering/ui-vocabulary/scripts/search.test.mjs

Representative trigger cases:

• “What is the grey layer behind this modal called?” — should trigger.
• “Here is a screenshot; is this a popover, tooltip, or menu?” — should trigger.
• “Implement this already-specified Radix Popover” — should not trigger unless the requested behavior contradicts the name.

The skill remains probationary until representative screenshot, live-page, and DOM/code cases produce the correct primary-source-backed distinction.

Related Skills

• agent-browser — inspect rendered behavior and accessibility state.
• animated-component-libraries — select an implementation after naming.
• frontend-design — build the named interface.
• accessibility — audit semantics and keyboard behavior after implementation.