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 real interactive journey was not exercised, keep that evidence 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 patterns (opens in a new tab)W3C Web Accessibility Initiative · First-party catalog of accessible patterns, roles, states, and keyboard conventions.
- Introduction to the ARIA Authoring Practices Guide (opens in a new tab)W3C Web Accessibility Initiative · Official APG scope and distinction between informative guidance, normative standards, and design systems.
- HTML Standard — Interactive elements (opens in a new tab)WHATWG · Primary specification for native interactive elements and their behavior.
- Understanding Success Criterion 2.5.5: Target Size (Enhanced) (opens in a new tab)W3C Web Accessibility Initiative · W3C source for the enhanced 44 by 44 CSS-pixel threshold used as a V1 product requirement for primary targets.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “The UI vocabulary that turns a vague idea into a reliable instruction” step by step
# Apply the “The UI vocabulary that turns a vague idea into a reliable instruction” guide in your agent ## Objective 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.” ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Component, behavior, state, appearance, and implementation: give an AI system the information that actually changes the result. - Preserve the correct decisions already in place. ## Guide steps - 1. 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. - 2. Disambiguate with a behavioral question — One behavioral question reduces ambiguity better than ten visual adjectives. - 3. 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. - 4. 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. - 5. 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. ## Acceptance criteria — Checklist for a precise UI prompt - The user goal fits in one sentence and describes an outcome. - The canonical concept is named or explicitly left for disambiguation. - Trigger, content, behavior, and dismissal are specified. - Relevant primary, empty, loading, error, and edge states are covered. - Keyboard, focus, accessible name, and touch requirements are observable. - Appearance is separated from the behavioral contract. - Existing components, tokens, and dependencies must be reused. - The expected output includes acceptance criteria and remaining manual validation. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:543a6f884cd5c2fd37b663a9ee47ecf0e90ffec1c01b6d63245d4bd62b507faa
Diagnose a problem
Diagnose a “The UI vocabulary that turns a vague idea into a reliable instruction” guide gap
# Diagnose a failed application of the “The UI vocabulary that turns a vague idea into a reliable instruction” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. 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. - 2. Disambiguate with a behavioral question — One behavioral question reduces ambiguity better than ten visual adjectives. - 3. 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. - 4. 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. - 5. 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. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Checklist for a precise UI prompt - The user goal fits in one sentence and describes an outcome. - The canonical concept is named or explicitly left for disambiguation. - Trigger, content, behavior, and dismissal are specified. - Relevant primary, empty, loading, error, and edge states are covered. - Keyboard, focus, accessible name, and touch requirements are observable. - Appearance is separated from the behavioral contract. - Existing components, tokens, and dependencies must be reused. - The expected output includes acceptance criteria and remaining manual validation. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:cfe1ad58841bd71f4f0909d1e0d2dd2bdbe674e0e867dc04f1cef6cc78a9ac6f
Pack digest: sha256:442532babc25782232c3179a0a536dd298aa9d0b425e63127df05d000b047da7