Reference guide · AI & interfaces
12 min read
Updated
The UI vocabulary that turns a vague idea into a reliable instruction
Component, behavior, state, appearance, and implementation: give an AI system the information that actually changes the result.
Direct answer
To describe an interface to an AI system, start with the user outcome, name the concept if you know it, then specify the trigger, content, behavior, states, and constraints. End with observable criteria. “Open a non-modal popover on click, keep keyboard focus logical, close it with Escape, and return focus to the button” is more reliable than “add a small modern popup.”
01
Separate the five layers of a UI request
Words such as “menu,” “popup,” “smart field,” or “panel” often describe several concepts. Before choosing a primitive, decompose the request. The goal explains what the person is trying to accomplish. The concept provides a shared name. Behavior states what happens. States expose variations. Appearance controls presentation without redefining the function.
This separation prevents two common errors: choosing a component because it looks similar and asking an AI system to rebuild an entire interface for a local change. A tooltip and popover can both appear near a trigger, but they do not carry the same content or interaction. A drawer and sidebar can occupy the same edge, but one is temporary while the other shapes the page persistently.
- Goal: what the user must be able to accomplish.
- Concept: the canonical pattern or component under consideration.
- Behavior: trigger, focus, dismissal, navigation, and scrolling.
- States: initial, active, loading, error, empty, disabled, and edge case.
- Appearance: hierarchy, density, color, typography, space, and motion.
02
Disambiguate with a behavioral question
When a term remains uncertain, ask the question that changes the contract. Must the content be interactive? Does the page behind remain usable? Can the person type? Does a choice launch an action or select a value? Is the surface persistent or temporary?
These discriminants are more robust than a visual description. They also allow the agent to abstain instead of inventing a name. If several answers remain plausible, request up to three candidates with their main difference before implementation begins.
- Tooltip or popover: simple information, or interactive content?
- Dropdown menu or select: launch an action, or choose a value?
- Select or combobox: closed list, or input with suggestions?
- Dialog or drawer: centered blocking decision, or edge-attached temporary task?
One behavioral question reduces ambiguity better than ten visual adjectives.
03
The structure of an executable UI prompt
Begin by asking for inspection of the existing system when the agent works in a repository. Then name the local change and what must be preserved. Describe the user scenario, followed by the expected behavior in observable order. Add technical constraints only when they are verified in the project.
Finish with a short checklist. Every criterion should be observable in the interface or demonstrable by a test. “The experience feels intuitive” cannot be verified. “Escape closes the surface and focus returns to the opening button” can.
Inspect existing components and tests first.
Goal: let a person choose a recent command without leaving the screen.
Concept: combobox inside a non-modal popover.
Content: search field, at most ten results, explicit empty state.
Behavior: open on click, filter while typing, arrow keys navigate,
Enter selects, Escape closes, focus returns to the trigger.
Constraints: reuse installed tokens and primitives; do not rebuild the page.
Verification: complete keyboard path, visible focus, accessible label, 44 px touch targets,
and no overflow at 320 px.04
A visual name does not define accessibility
Prefer native HTML elements when they already carry the required behavior. ARIA roles expose semantics to assistive technology; they do not automatically add keyboard behavior, focus management, or state. The ARIA Authoring Practices Guide offers useful patterns and examples, while explicitly stating that it is neither a complete normative standard nor a production-ready design system.
For every interactive surface, check the accessible name, tab order, expected keys, visible focus, focus restoration, change announcements, and high-contrast behavior. Appearance must never be the only signal for a selected, invalid, or disabled state.
- Use the native HTML control when its contract matches.
- Add ARIA to expose exact semantics, not to repair a clickable div.
- Test keyboard and screen reader behavior on the rendered interface, not only the expected DOM.
- Preserve touch targets, visible focus, and sufficient contrast.
05
Verify generated UI as a contract
Review the result in three passes. The first confirms the mission: can the person complete the task? The second inspects behavior: states, focus, dismissal, reversal, scrolling, and responsive layouts. The third verifies integration: reused components, bounded file scope, and relevant tests.
Screenshots help with visual composition, but they prove neither keyboard behavior nor hidden states. Combine static inspection, real interaction, and automated assertions. If a device, browser, or human review was not performed, keep it as an open gate instead of inferring it from a neighboring test.
- Mission: the primary scenario completes without an unexpected detour.
- Behavior: every relevant state and exit is reachable.
- Accessibility: name, keyboard, focus, announcements, and contrast are verified.
- Responsive: content and actions remain usable at target widths.
- Integration: no unrelated changes and no invented dependency.
Keep this
Checklist for a precise UI prompt
- 01The user goal fits in one sentence and describes an outcome.
- 02The canonical concept is named or explicitly left for disambiguation.
- 03Trigger, content, behavior, and dismissal are specified.
- 04Relevant primary, empty, loading, error, and edge states are covered.
- 05Keyboard, focus, accessible name, and touch requirements are observable.
- 06Appearance is separated from the behavioral contract.
- 07Existing components, tokens, and dependencies must be reused.
- 08The expected output includes acceptance criteria and remaining manual validation.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- ARIA Authoring Practices Guide patternsW3C Web Accessibility Initiative · First-party catalog of accessible patterns, roles, states, and keyboard conventions.
- Introduction to the ARIA Authoring Practices GuideW3C Web Accessibility Initiative · Official APG scope and distinction between informative guidance, normative standards, and design systems.
- HTML Standard — Interactive elementsWHATWG · Primary specification for native interactive elements and their behavior.
Continue