# UX Design

> Design or review a web, mobile, desktop, game, CLI, voice, or conversational user experience. Use when a feature changes navigation, interaction, content, onboarding, or screen states. Produce information structure, flows, empty/loading/error/success behaviour, content guidance, accessibility requirements, design constraints, and testable acceptance criteria.

- Skill: `ashermahonin/ux-design` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ashermahonin/ux-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ashermahonin/ux-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ashermahonin (https://skillmd.com/u/ashermahonin)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ashermahonin/ux-design

---


# UX Design

## Purpose

Turn a feature intent into a UX specification that implementation can verify. Cover information structure, interaction, content, accessibility, and the empty, loading, error, success, and permission states that affect the task.

## Product context

1. Read `references/ux-spec-template.md`.
2. Pull the platform matrix from `platform-detector` and the user journeys from `user-journey-mapper`.
3. Identify the surface being designed: marketing page, app screen, dashboard, HUD, modal, onboarding, settings, error path, voice flow, chat surface.
4. Use Context7 MCP for current platform UX guidelines: Apple HIG, Material Design 3, Microsoft Fluent, Web Platform best practices, WCAG, game-engine UI patterns.

## Design and validation

1. **Information architecture.** Map the surface's content hierarchy: what is primary, secondary, tertiary; what is hidden behind progressive disclosure.
2. **Interaction patterns.** Pick patterns from the platform's standard library before inventing new ones. Document every gesture, keyboard binding, focus order, touch target size.
3. **Screen states.** For each screen, design every state: default, empty, loading, partial-loading, error (network, validation, permission), success, offline. Skipping a state is a finding.
4. **Micro-copy guidelines.** Specify tone, voice, language register, action verbs vs. labels, error message format, confirmation pattern. Coordinate with `i18n-localization` if the product ships in multiple languages.
5. **Design tokens.** Reference or extend the project's design system: color, typography scale, spacing, radius, shadow, motion, sound. Tokens, not hardcoded values.
6. **Accessibility baseline.** Set per-surface a11y requirements (WCAG 2.2 AA minimum for web; platform-native a11y APIs for mobile/desktop; HUD readability for games). Hand off to `accessibility-audit` for verification.
7. **Acceptance criteria.** Per surface, write 5–15 checkable criteria the implementation can prove via `tdd-workflow` or visual regression.
8. **DESIGN.md sync.** If the project follows the `google-labs-code` DESIGN.md convention, update it; otherwise produce or extend the local design contract.

## Constraints

- Use Context7 MCP for current platform UX guidelines and any framework-specific UI library docs.
- Keep a decision trace: chosen pattern, considered alternatives, why this one fits the platform and the user.
- Refuse to ship a spec without all required screen states.
- Never approve a surface without explicit a11y handoff.

## Specification and evidence

- UX spec per surface (information architecture, interaction patterns, screen states, micro-copy, tokens, a11y, acceptance criteria)
- Updated or seeded design tokens / design system entries
- Acceptance criteria for `tdd-workflow` and visual regression
- Handoff to `accessibility-audit` and `i18n-localization`

## Acceptance checks

- No surface approved with missing screen states (empty/loading/error/success).
- No hardcoded color/spacing/typography; tokens only.
- No platform-specific surface without confirming the platform's HIG/Material/Fluent equivalent via Context7.
- No surface without an a11y baseline.

## Handoff

Hand off to `service-implementation` with: spec link, acceptance criteria, design tokens, screen-state matrix, a11y baseline, i18n note. Hand off to `accessibility-audit` and `i18n-localization` in parallel.

## References

- `references/ux-spec-template.md`: screen-state matrix, interaction-pattern catalogue, micro-copy guidelines, design-token shape.