Designs and audits UI/UX systems with usability and accessibility requirements. Use when shaping flows, design systems, interaction patterns, or WCAG-aware product behavior.
Instrucciones de origen · Vista previa de solo lectura
name
software-ui-ux-design
description
Designs and audits UI/UX systems with usability and accessibility requirements. Use when shaping flows, design systems, interaction patterns, or WCAG-aware product behavior.
compatibility
Portable core. Works on Claude Code and Codex.
version
1.3
last_validated
2026-08-13T00:00:00.000Z
Software UI/UX Design
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.
Quick Reference
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)
When to Use This Skill
Use this skill when the main task is:
designing screens, flows, or component behavior
auditing an interface for design-level issues
choosing design-system patterns or component libraries
preparing a strong brief for AI-generated frontend work
clarify platform, primary user journey, and constraints first
one primary task flow per output
cover loading, empty, error, offline, and degraded states — these decide trust, not happy paths
semantic and accessibility constraints must be present in the handoff
for AI-generated UI, define visual and interaction thesis before code generation
verify current platform-guideline claims before final advice
aim for consumer-grade craft, not just "passes audit". A screen that meets WCAG and feels lifeless is not done.
Craft Bar
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 — add these four rows. They fail independently of the ones above, and a surface can pass every row of the table above while failing all four of these.
Dimension
Pass
Fail
Steerability
user can add, revise, or retract a requirement mid-run; composer stays live
only "Stop", or input disabled while working
Action reversibility
tiered auto / notify+undo / block by what the action does in the world
one confirm dialog for everything, or none
Cost visibility
estimate before, accrual during, receipt after — in the user's units
token counts only, or nothing until the invoice
Memory legibility
user can see, attribute, edit, and delete what the agent remembers
opaque personalization, or global wipe as the only control
Confirm the mode: audit, new UI, design-system decision, or AI frontend brief.
Gather states, constraints, and quality bars.
For new surfaces, generate a concrete design direction from the offline database: python3 scripts/search.py "<product> <industry> <tone>" --design-system (see references/design-database-search.md); persist it with --persist for cross-session reuse.
For AI-generated UI, add visual anchor, content plan, and browser-based verification path.
ASCII Flow
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
Accessibility Baseline
WCAG 2.2 is the current W3C standard (October 2023; became ISO standard October 2025) and the legally mandated baseline under the European Accessibility Act (in force June 2025), ADA/Section 508, and EN 301 549. WCAG 3.0 remains a Working Draft — the 3 March 2026 update published the majority of requirements plus a proposed conformance model for public review, and renamed "outcomes" to "requirements". Candidate Recommendation is anticipated Q4 2027 and full Recommendation 2028 or later — do not use it as a compliance target yet. Note its broader stated scope (static, dynamic, interactive, and streaming content; apps, tools, publishing) when designing token-by-token streaming agent surfaces: WCAG 2.2 remains the compliance baseline, but streaming UI is squarely in WCAG 3's forward scope.
Requirement
Minimum target
Notes
Web (EU B2C)
WCAG 2.2 AA
EAA enforcement active; CNIL precedent fines on cookie/consent dark patterns
Web (US public)
WCAG 2.2 AA
ADA / Section 508; court-tested
iOS / Android
Platform guidelines + WCAG 2.2 AA equivalent
Use native accessibility APIs; avoid custom reimplementations of standard controls
Rich media / APNG / video
WCAG 2.2 AA 1.4.2, 1.4.5, 1.2.x
Captions, audio description, no strobing
Verification Checklist
Before finalizing any UI/UX design output:
Platform confirmed (web, iOS, Android) and platform-specific constraints applied
All five state types covered: loading, empty, error, offline/degraded, and happy path
Primary action is singular per view; secondary actions visually subordinate
Craft Bar row pass/fail reviewed; fewer than 3 fails before shipping
Accessibility is computed, not asserted: every contrast ratio in the spec comes from running 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 (≥44×44pt)
Dynamic content announces itself: any live-updating region (new rows, status changes, streaming) has a specified aria-live politeness level and batching rule — a visual pulse alone is invisible to screen readers
Single-key shortcuts specify a remap/disable mechanism (WCAG 2.1.4) and focus-scoping rule
Press + commit states specified for every tappable element, not demonstrated once on the primary CTA and left implicit elsewhere
Undo/recovery semantics defined end-to-end: what happens to server state, audit trail, and concurrent users when an action is undone; every focus surface has a named normal-path exit (not just error-path)
Material 3 patterns, edge-to-edge, predictive back, large-screen behavior
AI Frontend Briefing Rules
When using AI to generate UI:
define the visual thesis
define the page type and content structure
specify composition rules and design-system constraints
require real content instead of lorem ipsum
require post-generation browser verification
Known Traps
Designing the happy path only and discovering later that loading, empty, error, permission, and degraded states contradict the main flow.
Confusing accessibility conformance with usable interaction design, especially for focus order, error recovery, and dense component systems.
Treating design-system consistency as a substitute for hierarchy, task clarity, or actual decision support in the interface.
Writing AI frontend briefs around adjectives like modern or clean without defining composition, content density, or interaction constraints.
Letting responsive behavior remain implicit, which pushes layout collapse, tap-target, and overflow problems into implementation.
Recommending patterns from another platform without checking whether web, iOS, or Android conventions support them cleanly.
Treating EU compliance as a legal afterthought. The European Accessibility Act (in force since 28 June 2025) and DSA Article 25 (dark-pattern prohibition) create design-level obligations with active enforcement (in September 2025 the CNIL fined Google €325M and SHEIN €150M for cookie-consent dark patterns). For any EU-facing B2C surface, accessibility and consent design are legal requirements, not preferences.
Specifying motion or scroll-driven animation without 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.
Designing agent surfaces where the only mid-run control is "Stop". Users change their mind in three distinct ways — adding a requirement, revising the goal, retracting part of it — and collapsing all three into a cancel button forces the most destructive option. Interruption is a normal interaction, not an error path.
Gating agent actions by model confidence instead of by real-world reversibility. High confidence on an irreversible action is still irreversible; confidence belongs in the display, never in the gating decision.
Shipping a "notify and undo" affordance whose undo does not actually work. That is an unrecoverable action wearing a recoverable-looking UI — worse than an honest confirmation dialog. If the undo can't be built, promote the action to a blocking gate.
Writing accessibility as checklist assertions ("AA minimum", "focus order logical") instead of computed, implementable constraints. Expert review rejects specs whose contrast was never calculated at the element's real size and whose live regions have no announcement behavior — checklist-level a11y reads as bolted-on and fails sign-off.
Spec depth inversely proportional to surface frequency: the daily-return screen (home, dashboard) written in one paragraph while one-time flows get pages. Detail budget should follow visit frequency.
Common Anti-Patterns
Over-carding and over-sectioning every surface until the primary task disappears into chrome.
Designing multiple primary actions per screen and then relying on color or emphasis tweaks to recover clarity.
Using hidden gestures, hover-only affordances, or animation to carry critical meaning.
Treating AI-generated UI as almost done before browser verification, semantic checks, and real-content pass.
Optimizing purely for visual novelty when the product needs trust, comprehension, and low cognitive load.
Asymmetric Accept vs Reject buttons in consent flows (different size, color, or visual weight). Under DSA Article 25 and CNIL enforcement practice, both options must carry equal visual weight; pre-ticked consent boxes and forced-consent walls are explicitly prohibited.
Showing AI-generated content in high-stakes surfaces (medical, legal, financial, safety-critical) without a mandatory human confirmation gate before action.
Generic empty states ("No items yet" + grey illustration). Empty states are the first impression of every feature — model the populated state, offer a verb-driven CTA, speak to motivation.
Centered spinners when the layout is known. Skeleton screens that match the populated layout feel faster even when actual load is identical.
Onboarding tour carousels with lottie illustrations. Skipped by everyone; replace with first-action UI and contextual coaching.
Permission walls on first launch. Defer; explain in-context at the moment the permission is needed.
Form labels inside fields that disappear on focus. Use labels above inputs; floating labels fail older users and screen readers.
Robot voice in error and confirmation copy ("Operation completed successfully", "An unexpected error occurred"). Use user-voice: name what happened, offer recovery.
Decorative motion on every state change. Spring-bouncing into existence is not joy; it's noise. Reserve pronounced motion for navigation transitions and primary commit moments.
Navigation
References — read at most 2-3 per task; pick the cluster that matches the ask.
Workflow & systems
references/design-database-search.md — offline searchable design database: 80+ styles, 160 palettes, font pairings, UX guidelines, 16 stacks (BM25 search via scripts/search.py)
references/ui-quality-priority-rules.md — priority-ordered quality rules (1=accessibility … 10=charts) plus professional-polish rules and app pre-delivery checklist
Upstream trust note (verified 2026-08-10): that repo shows 115,186 stars against only 493 watchers and 30 contributors on a repo created 2025-11-30 — a star-inflation signature. This says nothing about the vendored content, which was taken on merit and is unaffected. It does mean: never cite its star count as social proof, and re-diff before pulling any upstream update.
scripts/search.py — CLI: --design-system, --domain <domain>, --stack <stack>, --persist, --format designmd (exports the generated design system as a spec-conformant DESIGN.md — Google Labs' Apache-2.0 portable design-context format auto-read from project root by Claude Code, Cursor, Windsurf, Kiro)
scripts/core.py — BM25 engine and CSV domain config
scripts/contrast_check.py — WCAG contrast calculator (single pair, stdin batch, or tokens×surfaces cross product); the only accepted source for contrast numbers in a spec
scripts/design_system.py — design-system generation and Master + page-overrides persistence
data/*.csv and data/stacks/*.csv — style, color, typography, product, landing, chart, UX-guideline, icon, and per-stack databases
data/slides/*.csv — slide/deck design database (layouts, typography, charts, copy formulas, backgrounds, color logic, layout logic, narrative strategies); queryable via scripts/search.py --slide <domain> (wired into SLIDE_CONFIG in scripts/core.py)
data/cip/*.csv — corporate identity pack reference data (industries, deliverables, mockup contexts); queryable via scripts/search.py --cip <domain> (wired into CIP_CONFIG)
Gate before invoking any foundation below: Each foundation has a When to Apply / When to Skip section. If your task matches a skip-condition, route to the foundation it names instead — don't pull in primitives the task doesn't need.
Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
Verify current platform guidelines, accessibility baselines, and component-library claims before final advice.
Prefer official platform docs and standards over trend roundups.
If live verification is unavailable, mark external guidance as unverified.
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
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.
