Agent-Skills.md

Agent Skills: Software UI/UX Design

Designs and audits UI/UX with WCAG 2.2 accessibility. Use when designing flows, running heuristic reviews, or defining design systems.

UncategorizedID: vasilyu1983/ai-agents-public/software-ui-ux-design

Repository

vasilyu1983/ai-agents-public
vasilyu1983License: MIT
4911

Install this agent skill to your local

pnpm dlx add-skill https://github.com/vasilyu1983/AI-Agents-public/tree/HEAD/frameworks/shared-skills/skills/software-ui-ux-design

Skill Files

Browse the full folder contents for software-ui-ux-design.

Download Skill

Loading file tree…

frameworks/shared-skills/skills/software-ui-ux-design/SKILL.md

Skill Metadata

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."

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
  • reviewing AI/automation UX

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 |

Defaults

  • 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.

Workflow

  1. Confirm the mode: audit, new UI, design-system decision, or AI frontend brief.
  2. Gather states, constraints, and quality bars.
  3. 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.
  4. Define the primary flow and supporting states.
  5. Produce acceptance criteria and implementation-ready handoff details; check priorities 1-3 in references/ui-quality-priority-rules.md.
  6. 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 (updated March 2026 with 174 draft outcomes); Candidate Recommendation is anticipated Q4 2027 and full Recommendation 2028 or later — do not use it as a compliance target yet.

| 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: focus order, error recovery, target size (≥44×44pt), color contrast (AA minimum)
  • [ ] Consent and accept/reject buttons carry equal visual weight (DSA Article 25)
  • [ ] Motion fallback present for any scroll-driven or CSS animation (prefers-reduced-motion)
  • [ ] Microcopy uses user voice: names cause, offers specific recovery step
  • [ ] AI-generated UI verified in browser with real content, not lorem ipsum
  • [ ] Legal obligations checked for EU-facing surfaces: EAA accessibility, DSA dark-pattern rules

Output Contract

Every substantial output should include:

  • user/task context
  • primary flow
  • state coverage
  • accessibility and performance checks relevant to the platform
  • component or token guidance where needed
  • acceptance criteria suitable for implementation or review

Core Design Rules

  • one primary action per view
  • immediate feedback for interactions
  • explicit recovery paths for failure states
  • consistency in language and interaction patterns
  • design for the actual platform, not a generic rectangle

Platform Defaults

| 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 |

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.

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

Heuristics, accessibility & inclusion

Visual craft

Patterns & surfaces

Conversion & AI

Performance

Scripts — offline design-database search engine (stdlib-only Python, vendored from nextlevelbuilder/ui-ux-pro-max-skill, MIT)

  • scripts/search.py — CLI: --design-system, --domain <domain>, --stack <stack>, --persist
  • scripts/core.py — BM25 engine and CSV domain config
  • 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); not yet wired into scripts/core.py domain config, so scripts/search.py cannot query it directly — read these CSVs directly until the engine is extended
  • data/cip/*.csv — corporate identity pack reference data (industries, deliverables, mockup contexts); same caveat — not yet wired into the search engine

Templates

Related Skills

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.

Fact-Checking

  • 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.