software-ui-ux-designDesigns and audits UI/UX systems with usability and accessibility requirements. Use when shaping flows, design systems, interaction patterns, or WCAG-aware product behavior.
Independent GitHub snapshot · Automated classification · Original documentation governs
Use this skill to design or audit interfaces, flows, component systems, and AI-assisted frontend briefs. It owns design direction, interaction behavior, state coverage, and implementation-ready handoff, not user research or code remediation.
| Mode | Use When | Required Output |
|---|---|---|
| audit existing UI | product has usability, accessibility, consistency, or conversion issues | findings plus acceptance criteria |
| design new UI | flow or screen must be shaped from scratch | flow, states, components, handoff spec |
| design-system decision | team must choose primitives or token structure | recommendation with tradeoffs |
| AI frontend brief | Codex or Claude will generate UI | visual thesis, interaction thesis, verification plan |
| AI UX review | product includes chat, agents, or automation | transparency, control, failure handling guidance |
| style/palette/font selection | new surface needs a concrete design direction | generated design system from the offline database (scripts/search.py --design-system) |
Use this skill when the main task is:
Route elsewhere when the main task is:
| Need | Use Instead |
|---|---|
| user research and study design | ../software-ux-research/SKILL.md |
| code-level accessibility fixes | ../software-accessibility/SKILL.md |
| accessibility test automation | ../qa-testing-accessibility/SKILL.md |
| frontend implementation | ../software-frontend/SKILL.md |
| product strategy or roadmap | ../product-management/SKILL.md |
Consumer-grade product work is judged on the rows below, not just task completion. Every substantive design output should be reviewed against these.
| Dimension | Pass | Fail |
|---|---|---|
| Time to first value | <60s for primary user | multi-step setup wizard |
| Empty state | models populated state with one verb CTA | "No items yet" + grey illustration |
| Loading state | skeleton matching populated layout | centered spinner |
| Error recovery | names cause + offers specific next step in user voice | "Something went wrong" |
| Microcopy | one voice; numbers humanised; verbs in CTAs | system-speak, status codes, noun CTAs |
| Motion | functional (origin → destination, hierarchy) | decorative bounces on every state change |
| Touch feedback | every tappable element has press + commit states | silent commits |
| Optical alignment | icons, numbers, capitals optically balanced | pixel-grid measured equal but reads off |
| First-run delight | one non-functional moment that earns a smile | none |
| Recovery without restart | back, undo, edit-without-redo paths exist | "Are you sure?" gating every action |
If three or more rows fail, the screen is debt regardless of what metrics say. See consumer-craft-patterns.md for the full playbook.
For agent surfaces — anything that acts on the user's behalf over multiple steps — also score the four agent rows (steerability, action reversibility, cost visibility, memory legibility); a surface can pass every row above and fail all four. See references/ai-automation-ux.md#agent-surface-craft-bar.
python3 scripts/search.py "<product> <industry> <tone>" --design-system (see references/design-database-search.md); persist it with --persist for cross-session reuse.UI/UX design task
-> Confirm mode: audit, new UI, system decision, or AI frontend brief
-> Gather platform, primary journey, states, constraints, and quality bar
-> Define hierarchy, interaction model, and supporting states
-> Add accessibility, performance, and implementation handoff criteria
-> Specify verification path and evidence needed
-> Deliver acceptance criteria and unresolved tradeoffs
Design new work to WCAG 2.2 AA (conformance also covers 2.1 and 2.0), but the legally binding version differs by jurisdiction and surface (EU public sector, EAA, ADA Title II, Section 508, native apps). Check the jurisdiction table in references/wcag-accessibility.md#jurisdictional-baselines before stating what a product must meet; WCAG 3.0 drafts are not a shipping target.
Before finalizing any UI/UX design output:
scripts/contrast_check.py <fg> <bg> — never from estimation (a model-estimated ratio labeled "computed" is a fabrication) — and is measured against the surface the text actually renders on (row, card, modal), not only the page canvas; focus order listed element by element; target size ≥24×24 CSS px (WCAG 2.2 AA, SC 2.5.8) with the platform size (44pt iOS / 48dp Android) for primary controlsaria-live politeness level and batching rule — a visual pulse alone is invisible to screen readersEvery substantial output should include:
| Platform | Key Constraints |
|---|---|
| web | semantic structure, focus behavior, reflow, target size |
| iOS | system navigation, Dynamic Type, safe areas |
| Android | Material 3 patterns, edge-to-edge, predictive back, large-screen behavior |
When using AI to generate UI, define the visual thesis, page type, content structure, composition rules, and design-system constraints first; require real content instead of lorem ipsum and post-generation browser verification. Full brief template: references/ai-assisted-frontend-briefing.md.
modern or clean without defining composition, content density, or interaction constraints.prefers-reduced-motion fallback. CSS scroll-driven animations are invisible to users with reduced-motion preferences if the spec doesn't explicitly handle the case.Over-carding, multiple primary actions, meaning carried only by hover/gesture/animation, unverified AI-generated UI, asymmetric consent buttons, generic empty states, centered spinners, permission walls, robot-voice copy, and decorative motion. Full list with the fix for each: references/operational-playbook.md#common-anti-patterns-to-avoid.
References — read at most 2-3 per task; pick the cluster that matches the ask.
Workflow & systems
scripts/search.py)Heuristics, accessibility & inclusion
Visual craft
Patterns & surfaces
Conversion & AI
references/cro-framework.md — design-to-CRO hand-off (routes to marketing-cro) and vertical UI benchmarking
references/ai-assisted-frontend-briefing.md — briefing AI to generate UI
references/ai-automation-ux.md — UX for chat, agents, and automation; reversibility-tiered approval gates, interruption/steering, cost visibility, agent memory surfaces, the 4-stage human-agent frame, ACI tool design, and the agent-to-UI event contract
references/ai-design-tools.md — AI-assisted design tools: use, quality control, ethics
references/performance-ux-vitals.md — perceived performance, loading states, focus on content change (metrics route to software-frontend)
Scripts — offline design-database search engine (stdlib-only Python, vendored, MIT): scripts/search.py (CLI), scripts/core.py, scripts/design_system.py, and scripts/contrast_check.py (the only accepted source for contrast numbers in a spec), over CSV databases in data/. Flags, data files, DESIGN.md export, and the upstream trust note: references/design-database-search.md#scripts-and-data-files.
Templates
Gate before invoking any foundation below: Each foundation has a
When to Apply/When to Skipsection. If your task matches a skip-condition, route to the foundation it names instead — don't pull in primitives the task doesn't need.
When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.