| name | aio-uiux |
| description | Web UI design and review advisor — applies UX psychology, interaction patterns, WCAG accessibility, and modern CSS to design new interfaces or critique existing ones. Use proactively when reviewing any frontend UI, scaffolding new components, or deciding layout/color/typography trade-offs.
|
| when_to_use | UI, UX, design, layout, color, typography, animation, accessibility, a11y, design system, responsive, dark mode, WCAG, visual hierarchy, micro-interaction, loading state, design tokens, web design, CSS, component design, interaction patterns |
| effort | medium |
| argument-hint | Component, page, or design challenge |
UI/UX Design Advisor
"Design is not just what it looks like and feels like. Design is how it works."
— Steve Jobs
Workflow: How to Use This Skill
When this skill is triggered, follow these steps. Do NOT just dump reference content — actively analyze the user's specific design challenge and provide targeted, actionable guidance.
Step 1: UNDERSTAND — Identify the Design Challenge
Before selecting references, understand:
- What is being built? (component, page, full app, design system)
- What's the context? (marketing site, SaaS dashboard, mobile app, e-commerce)
- What aspect needs help? (visual design, accessibility, UX flow, performance)
- What tech stack? (vanilla CSS, Tailwind, React, Vue, etc.)
- Who are the users? (general public, power users, accessibility needs)
If the user's message already contains enough context, proceed directly to Step 2.
Step 2: SEARCH — Find Relevant References
First, run semantic search with the user's design challenge to find the most relevant topics:
UX="${CLAUDE_PLUGIN_ROOT}/skills/aio-uiux/scripts"
npx tsx "$UX/search-uiux.ts" "<user's design challenge>" --top 5 --json
Read the full markdown file for each top result before proceeding. Then cross-reference with the routing table:
| Design Challenge | Start With |
|---|
| Building a new component | Component Patterns → Design Systems → Accessibility |
| Making something look better | Visual Hierarchy → Whitespace → Color → Typography |
| Choosing colors | Color Theory → Color Harmonies → Semantic Colors → Accessibility Contrast |
| Typography decisions | Type Scale → Font Pairing → Readability → Fluid Typography |
| Layout / spacing issues | Spacing Systems → CSS Grid → Flexbox → Content Width |
| Form design | Form Design → Form Accessibility → Error Messages → Validation |
| Navigation design | Navigation Patterns → Navigation Components → Mobile UX |
| Accessibility audit/fix | WCAG Guide → ARIA Patterns → Keyboard Nav → Testing Checklist |
| Animation / transitions | Animation Principles → Motion System → CSS Transitions → Micro-animations |
| Performance concerns | Perceived Performance → Core Web Vitals → Image Optimization → Font Performance |
| Dark mode | Theming & Dark Mode → Semantic Colors → Color Accessibility |
| Responsive / mobile | Mobile-First → Fluid Design → Responsive Patterns → Touch Targets |
| Design system setup | Design Tokens → Atomic Design → Component API → Tailwind Patterns |
| UX flow / user behavior | UX Psychology → UX Laws → Decision Making → Cognitive Load |
| Writing UI text | Microcopy → Error Messages → Voice & Tone → Conversion Copy |
| Modern CSS techniques | Custom Properties → Container Queries → :has() → Cascade Layers |
| Loading / empty states | State Management UX → Perceived Performance → Loading Patterns → Skeleton Screens |
| Buttons / CTAs | Buttons → Visual Hierarchy → Von Restorff Effect → Conversion Copy |
State which references you selected and why they fit.
Step 3: APPLY — Provide Targeted Guidance
For each relevant reference area, apply it to the user's specific situation:
- State the principle or pattern (one sentence)
- Show how it applies to their specific case
- Provide concrete code (CSS/HTML) when applicable
- Flag any accessibility requirements
Step 4: SYNTHESIZE — Combine Into Actionable Advice
Merge insights into:
- Specific implementation recommendation with code
- Priority order (what to fix/implement first)
- Key tradeoffs to consider
- Accessibility checklist for the specific case
Step 5: REVIEW — Check Against Quality Criteria
Verify the recommendation against:
Scripts
Before calling any script, resolve the scripts directory (version may vary):
UX="${CLAUDE_PLUGIN_ROOT}/skills/aio-uiux/scripts"
List Topics
$UX/list-topics.sh
$UX/list-topics.sh --category accessibility
$UX/list-topics.sh --search "color"
$UX/list-topics.sh --count
Semantic Search
Find relevant topics by meaning, not just keywords. Uses pre-computed embeddings (snowflake-arctic-embed-xs, 384-dim, runs locally).
npx tsx "$UX/search-uiux.ts" "how to design accessible forms"
npx tsx "$UX/search-uiux.ts" "dark mode color palette" --top 3
npx tsx "$UX/search-uiux.ts" "button component best practices" --json
Options:
--top N — Number of results (default: 5)--json — Output as JSON for programmatic use
Important
Always run semantic search first before selecting references. The search uses embeddings to find the most relevant topics for the user's specific design challenge — this is more reliable than guessing from the catalog. After searching, read the full markdown file for each selected topic.
Reference Catalog
01. Visual Design Foundations
Core principles of visual communication and composition
| Topic | Core Idea | When to Use |
|---|
| Gestalt Principles | How humans perceive visual groups | Organizing UI elements, creating clear relationships |
| Visual Hierarchy | Guide the eye through importance | Every layout — primary, secondary, tertiary emphasis |
| Golden Ratio & Composition | Mathematical harmony in layout | Hero sections, image cropping, layout proportions |
| Whitespace & Negative Space | Space as a design element | Feeling cramped, improving readability, luxury feel |
| Visual Weight & Balance | How elements attract attention | Balancing asymmetric layouts, focal points |
| Contrast & Emphasis | Difference creates focus | CTAs, important information, visual interest |
| Alignment & Grids | Order through alignment | Any layout — grids, optical alignment, consistency |
02. Typography
Type systems, font pairing, and text rendering
03. Color Science
Color theory, spaces, palettes, and accessibility
| Topic | Core Idea | When to Use |
|---|
| Color Theory Fundamentals | Color meaning and emotion | Choosing brand/UI colors |
| Color Harmonies | Complementary, analogous, triadic | Building color palettes |
| Color Spaces & Modern CSS | oklch, Display P3, color-mix() | Modern CSS color implementation |
| Systematic Palette Generation | Building 50-950 shade scales | Design system color setup |
| Semantic Color Systems | Primitive → semantic → component | Color token architecture |
| Color Accessibility & Contrast | WCAG, APCA, color blindness | Every color decision |
| Data Visualization Colors | Sequential, diverging, qualitative | Charts, graphs, dashboards |
04. Layout & Spacing
Grid systems, spacing tokens, and responsive layout
| Topic | Core Idea | When to Use |
|---|
| Spacing Systems | 4pt/8pt grid, spacing tokens | Every layout decision |
| CSS Grid Mastery | Two-dimensional layout | Page layouts, dashboards, galleries |
| Flexbox Patterns | One-dimensional layout | Component-level layout, alignment |
| Responsive Layout Strategies | Adapting to screen sizes | Every responsive design |
| Z-Index & Layering | Stacking context management | Modals, dropdowns, tooltips, toasts |
| Box Model & Sizing | Box-sizing, margins, logical props | Layout debugging, i18n |
| Content Width & Containers | Max-width, container patterns | Readable content, full-bleed layouts |
05. Accessibility (a11y)
WCAG 2.2, ARIA, keyboard navigation, screen readers
06. UX Psychology
Cognitive psychology and behavioral design for interfaces
| Topic | Core Idea | When to Use |
|---|
| Cognitive Load | Reduce mental effort | Complex interfaces, forms, onboarding |
| Attention & Perception | How users scan and notice | CTA placement, important info display |
| Decision Making | Choice architecture | Options, pricing, configuration |
| Persuasion & Influence | Ethical persuasion patterns | Landing pages, conversions, trust |
| Emotional Design | Visceral, behavioral, reflective | Brand experience, delight, trust |
| Habit Formation | Hook model, engagement loops | Product engagement, onboarding |
| Memory & Learning | Recognition, recall, mental models | Navigation, onboarding, help |
07. UX Laws
30+ evidence-based laws for interface design
| Topic | Core Idea | When to Use |
|---|
| Fitts's Law | Target size × distance = time | Button sizing, touch targets, CTA placement |
| Hick's Law | More choices = slower decisions | Menu design, option reduction |
| Jakob's Law | Users prefer familiar patterns | Convention decisions, innovation risk |
| Miller's Law | 7±2 chunks in working memory | Navigation, grouping, information architecture |
| Tesler's Law | Complexity can't be removed | Smart defaults, progressive disclosure |
| Doherty Threshold | 400ms for flow state | Loading optimization, perceived performance |
| Aesthetic-Usability | Beautiful = perceived usable | Visual polish investment |
| Von Restorff Effect | Distinctive items remembered | CTAs, badges, highlights |
| Peak-End Rule | Peaks and endings matter most | Onboarding, checkout, error recovery |
| Serial Position Effect | First/last items remembered | Navigation order, list design |
| Goal-Gradient Effect | Acceleration near completion | Progress bars, multi-step flows |
| More UX Laws | Postel's, Weber-Fechner, Prägnanz, + more | Comprehensive reference |
08. Interaction Design
Forms, navigation, states, and user flows
| Topic | Core Idea | When to Use |
|---|
| Form Design | Input types, validation, flow | Building any form |
| Navigation Patterns | Navbar, sidebar, tabs, breadcrumbs | Information architecture |
| State Management UX | Loading, empty, error, success | Every interactive component |
| Micro-interactions | Trigger, rule, feedback, loop | Adding polish, user feedback |
| Feedback Patterns | Toasts, alerts, progress, undo | System-to-user communication |
| Search, Filter & Sort | Search input, facets, results | Data-heavy interfaces |
| Drag, Drop & Gestures | Drag handles, touch gestures | Sortable lists, kanban, mobile |
09. Motion & Animation
Animation principles, CSS transitions, scroll-driven effects
10. Component Patterns
Design patterns for UI components
| Topic | Core Idea | When to Use |
|---|
| Buttons | Hierarchy, states, sizing | Every interactive UI |
| Forms & Inputs | Input types, states, validation | Building forms |
| Cards & Containers | Card anatomy, grid layouts | Content display |
| Modals, Dialogs & Sheets | When to use which overlay | Confirmations, forms, settings |
| Tables & Data Display | Sorting, filtering, responsive | Data-heavy interfaces |
| Navigation Components | Navbar, sidebar, tabs, breadcrumbs | App chrome, wayfinding |
| Feedback Components | Toasts, alerts, badges, progress | System feedback |
| Complex Components | Command palette, data grid, tree | Advanced interfaces |
11. Design Systems
Tokens, atomic design, theming, and popular systems
| Topic | Core Idea | When to Use |
|---|
| Design Token Architecture | Primitive → semantic → component | Setting up any design system |
| Atomic Design | Atoms, molecules, organisms | Component organization |
| Component API Design | Props, variants, composition | Building reusable components |
| Popular Systems Analysis | Material, Apple, Fluent, shadcn | Learning from the best |
| Theming & Dark Mode | CSS custom properties, themes | Dark mode, multi-theme |
| Design System Checklist | Everything a system needs | Starting or auditing a system |
| Tailwind Design Patterns | cva, tailwind-merge, config | Tailwind-based projects |
12. UX Writing
Microcopy, content design, and inclusive language
13. Performance UX
Perceived performance, Core Web Vitals, optimization
14. Modern CSS
Custom properties, container queries, :has(), cascade layers
15. Responsive Design
Mobile-first, fluid design, touch targets
Quick Reference Card
The 10 Most Impactful Design Decisions
- Visual Hierarchy — Guide the eye: size, color, weight, space
- Spacing System — Use 8pt grid, consistent tokens, generous whitespace
- Color Contrast — WCAG AA minimum: 4.5:1 text, 3:1 UI components
- Typography — Max 2 fonts, clear type scale, 45-75 char line length
- Component States — Every element needs: hover, focus, active, disabled, loading, error
- Touch Targets — Minimum 44×44px, use full clickable area
- Loading States — Skeleton screens > spinners > nothing
- Error Handling — What happened + why + how to fix
- Keyboard Navigation — Tab order, focus visible, escape to dismiss
- Motion — 200-300ms transitions, ease-out for enters, respect prefers-reduced-motion
Design Review Checklist
Before shipping any UI, verify:
Sources & Further Reading
"Good design is obvious. Great design is transparent."
— Joe Sparano
