UI/UX Specification

Agent Prompt Snippet

Ensure the project has a UI/UX specification covering interaction flows, component states, accessibility requirements, and design system token usage.

Purpose

A UI/UX specification is the design-to-engineering contract for a user interface. It defines the interaction flows (how users navigate from state to state), the wireframes or mockups (what each screen looks like), the component states (default, hover, focus, active, disabled, error, loading), the design system tokens (colors, typography, spacing), and the accessibility requirements (WCAG compliance level, keyboard navigation, screen reader behavior).

Without a UI/UX spec, engineers implement interfaces from mental models that differ from the designer’s intent and from each other. The result is UI that looks different on every page, interactive states that are missing or wrong, accessibility violations that are caught late and expensive to fix, and endless back-and-forth between design and engineering over “is this pixel-perfect?” The spec reduces all of this to a clear reference.

The UI/UX spec is not a Figma file. Figma files show static mockups; the spec explains behavior, states, and accessibility requirements that static mockups cannot capture. The spec answers: What happens when this button is clicked? What does this input look like when it has a validation error? What does the screen reader announce when this dialog opens? What keyboard shortcuts work on this page?

For AI agents building or reviewing UI code, the spec is especially critical. Without explicit state documentation and accessibility requirements, generated UI code commonly omits focus management, aria labels, and keyboard navigation—creating accessibility violations that affect real users.

Who needs this document

Persona	Why they need it	How they use it
Sam (Indie Dev)	Prevents shipping UI that looks unfinished or is inaccessible; provides a specification to implement against	Writes spec before coding UI; uses component state matrix as implementation checklist
Claude Code (AI Agent)	UI code without explicit state and accessibility requirements produces incomplete implementations	Reads spec before generating any UI code; generates all documented component states; applies ARIA patterns
Priya (Eng Lead)	Reviews UI implementations against spec; manages design-engineering handoff; enforces accessibility policy	Uses spec as UI review checklist; requires spec updates before UI feature PRs merge

What separates a good version from a bad one

Criterion 1: Every interactive component has all states documented

✓ Strong: “Button component states: Default (filled background, white text), Hover (background 10% darker, cursor: pointer), Focus (2px solid focus ring, accessible on all backgrounds), Active (background 20% darker), Disabled (50% opacity, cursor: not-allowed, aria-disabled=true, not focusable), Loading (spinner icon replaces label, pointer events disabled, aria-label=‘Loading…’). All states are shown in the Figma component library.”

✗ Weak: “Buttons have different states depending on context.” (Which states? What do they look like? What are the ARIA attributes for each state? Missing states become accessibility violations or confusing UX.)

Criterion 2: Interaction flows specify all paths, not just the happy path

✓ Strong: “Login flow: (1) User enters email → real-time format validation after blur, shows green check or red error inline. (2) User enters password → no real-time validation. (3) User clicks Submit → button enters Loading state, form inputs disabled. (4a) Success: redirect to dashboard. (4b) Invalid credentials: show ‘Incorrect email or password’ banner above form, re-enable inputs, focus the error banner for screen readers. (4c) Network error: show ‘Something went wrong, try again’ with retry button.”

✗ Weak: “Users log in with their email and password.” (No states, no error handling, no focus management. The engineer will implement only the happy path.)

Criterion 3: Accessibility requirements are concrete and testable

✓ Strong: “WCAG 2.1 AA compliance required. Specific requirements: all interactive elements reachable by Tab (no focus traps except modals). All images have alt text (decorative images: alt=’’). Contrast ratio ≥ 4.5:1 for text, ≥ 3:1 for UI components. Modals: focus moves to dialog on open, returns to trigger on close, Escape closes. Dynamic content updates announced via aria-live=‘polite’. CI enforcement: axe-core automated scan in Playwright tests, must pass before merge.”

✗ Weak: “The interface should be accessible.” (No compliance target, no specific requirements, no testing methodology. “Accessible” is not an engineering specification.)

Criterion 4: Design system tokens are specified, not colors

✓ Strong: “Colors use design tokens only: --color-primary-500 (interactive elements), --color-text-primary (body text), --color-surface-raised (card backgrounds), --color-danger-600 (error states). No hardcoded hex values in component CSS. Light/dark mode: all tokens have both light and dark values defined. Switching is handled by setting data-theme='dark' on <html>.”

✗ Weak: “Use the company brand colors.” (No tokens, no dark mode specification, no link between UI states and semantic color names. Engineers will hardcode hex values and dark mode will be inconsistent.)

Common mistakes

Specifying only the desktop view. Mobile-first design means every component needs responsive behavior documented. What does the navigation look like on a 375px screen? How does a 6-column grid collapse? What touch targets are large enough? These questions must be answered in the spec.

Missing empty states. Every list, feed, or data view has an empty state. An empty state that shows a raw empty page is a UX failure. Document the empty state for every data-displaying component: what illustration or message appears? Is there a call-to-action?

No loading states. UI code without documented loading states produces jarring layout shifts, blank areas during data fetching, and no feedback to users that something is happening. Every async operation needs a loading state specified.

Treating accessibility as a post-launch task. Accessibility retrofitting is 10x more expensive than building it in. The UI/UX spec is where accessibility requirements must be embedded—in every component state, every interaction flow, every navigation pattern.

How to use this document

When to create it

Write the UI/UX spec before the first UI implementation sprint. For new features, the spec is the exit criteria of the design phase—implementation begins only when the spec is complete and reviewed.

Who owns it

The product designer or UX lead owns the spec. Engineers are reviewers and flag implementation constraints. Accessibility compliance is the joint responsibility of designer and engineer.

How AI agents should reference it

get_standard_docs(type="web_app", features=[])
→ ui_ux_spec in documents[]
→ agent reads spec before generating any frontend component code
→ agent generates all documented component states (default, hover, focus, disabled, error, loading)
→ agent applies specified ARIA attributes to all interactive elements
→ agent uses design system tokens instead of hardcoded color values

The prompt_snippet — “Ensure the project has a UI/UX specification covering interaction flows, component states, accessibility requirements, and design system token usage” — tells the agent to verify all four dimensions are specified.

How it connects to other documents

The UI/UX Specification is downstream of the PRD (user scenarios drive interaction flow design) and the Requirements Specification (non-functional requirements include accessibility targets). It feeds the Internationalization Strategy (i18n affects text layout, text direction, and date/number formatting in the UI).