aio-uiux
From plugin aio-design-system ·
v1.0.2· Install:/plugin install aio-design-system@aiocean-plugins
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 → |
| 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:
- Visual hierarchy is clear (squint test)
- Spacing is consistent (uses system, not arbitrary values)
- Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)
- Interactive elements have all states (hover, focus, active, disabled)
- Touch targets are ≥44×44px on mobile
- Animations respect prefers-reduced-motion
- Text is readable (45-75 char line length, 1.4-1.6 line-height)
- Component is keyboard navigable
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 # All topics by category
$UX/list-topics.sh --category accessibility # Filter by category
$UX/list-topics.sh --search "color" # Search by keyword
$UX/list-topics.sh --count # Quick 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
| Topic | Core Idea | When to Use |
|---|---|---|
| Type Scale Systems | Mathematical size progression | Setting up heading/body sizes |
| Font Pairing | Combining typefaces harmoniously | Choosing fonts for a project |
| Vertical Rhythm | Consistent spacing rhythm | Page-level text layout |
| Fluid Responsive Typography | Type that scales with viewport | Responsive text without breakpoints |
| Readability & Legibility | Optimal reading experience | Body text, long-form content |
| OpenType & Variable Fonts | Advanced font features | Performance, design polish |
| Web Font Loading | Fast font delivery | Performance optimization, CLS prevention |
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
| Topic | Core Idea | When to Use |
|---|---|---|
| WCAG 2.2 Essential Guide | Web accessibility guidelines | Every project — baseline requirements |
| ARIA Patterns Reference | Widget roles and states | Custom interactive components |
| Keyboard Navigation | Tab order, focus management | Every interactive element |
| Screen Reader Optimization | Semantic HTML, live regions | Dynamic content, SPAs |
| Color & Motion Accessibility | Contrast, reduced-motion | Color decisions, animations |
| Form Accessibility | Labels, errors, validation | Every form |
| Testing Checklist | Automated + manual testing | Pre-launch, code review |
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
| Topic | Core Idea | When to Use |
|---|---|---|
| Animation Principles | Disney's 12 principles for UI | Understanding "why" behind motion |
| Motion Design System | Duration/easing token system | Setting up consistent motion |
| CSS Transitions | Property transitions, 60fps | Hover, focus, state changes |
| CSS Keyframe Animations | @keyframes, multi-step | Enter/exit, loading, attention |
| Scroll-Driven Animations | Scroll progress, reveal on scroll | Landing pages, storytelling |
| Page & View Transitions | View Transitions API | Route changes, shared elements |
| Micro-Animation Library | 25+ copy-paste CSS animations | Quick implementation reference |
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
| Topic | Core Idea | When to Use |
|---|---|---|
| Microcopy Patterns | Button labels, errors, empty states | Writing any UI text |
| Voice & Tone Guidelines | Consistent brand voice | Establishing content guidelines |
| Error Messages | What + why + how to fix | Error handling copy |
| Onboarding Copy | Welcome, tours, progressive | First-run experience |
| Conversion Copy | CTAs, headlines, social proof | Landing pages, signup flows |
| Inclusive Writing | Gender-neutral, plain language | All user-facing text |
13. Performance UX
Perceived performance, Core Web Vitals, optimization
| Topic | Core Idea | When to Use |
|---|---|---|
| Perceived Performance | Psychology of waiting | Making things feel fast |
| Core Web Vitals | LCP, INP, CLS | Performance auditing |
| Image Optimization | Formats, responsive, lazy | Every image implementation |
| Font Performance | font-display, preload, subset | Web font optimization |
| Critical Rendering Path | Above-the-fold, CSS containment | Page load optimization |
| Loading Patterns Library | Skeleton, spinner, progress CSS | Copy-paste loading patterns |
14. Modern CSS
Custom properties, container queries,
| Topic | Core Idea | When to Use |
|---|---|---|
| Custom Properties Architecture | CSS token system design | Any CSS architecture |
| Container Queries | Component-level responsiveness | Self-contained components |
| Parent selector, state-based | Advanced styling without JS | |
| Cascade Layers | @layer for specificity control | Managing CSS specificity |
| Modern Layout Techniques | Subgrid, nesting, logical props | Cutting-edge layout |
| Color Functions | oklch, color-mix, light-dark() | Modern color implementation |
| Scroll Snap & Popover | Scroll snap, popover, dialog | Native browser patterns |
15. Responsive Design
Mobile-first, fluid design, touch targets
| Topic | Core Idea | When to Use |
|---|---|---|
| Mobile-First Strategy | Progressive enhancement | Starting any responsive project |
| Breakpoint System | Content-based breakpoints | Defining responsive breakpoints |
| Fluid Design | clamp(), no-breakpoint layouts | Truly fluid interfaces |
| Responsive Patterns | Stack, sidebar, grid, table | Common responsive transformations |
| Touch Targets & Mobile UX | 44px minimum, thumb zones | Mobile-specific design |
| Responsive Images | srcset, picture, art direction | Image delivery optimization |
| Print Stylesheets | @media print, page breaks | Print-friendly pages |
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:
- Visual hierarchy is clear (squint test passes)
- Spacing uses system tokens, not arbitrary values
- Color contrast meets WCAG AA (test with browser devtools)
- All interactive elements have hover, focus, active, and disabled states
- Touch targets are at least 44×44px
- Animations respect
prefers-reduced-motion - Text line length is 45-75 characters
- Forms have visible labels, clear errors, proper autocomplete
- Empty states, loading states, and error states are designed
- Page is navigable with keyboard only
- Screen reader announces dynamic changes (aria-live)
- Images have meaningful alt text (or alt="" for decorative)
Sources & Further Reading
- Refactoring UI — Steve Schoger & Adam Wathan
- Laws of UX — Jon Yablonski
- Inclusive Components — Heydon Pickering
- Every Layout — Andy Bell & Heydon Pickering
- WCAG 2.2 — W3C
- Material Design 3 — Google
- Human Interface Guidelines — Apple
- A11y Project — Community
- web.dev — Google (performance, CSS, accessibility)
- Don't Make Me Think — Steve Krug
- The Design of Everyday Things — Don Norman
- 100 Things Every Designer Needs to Know About People — Susan Weinschenk
"Good design is obvious. Great design is transparent." — Joe Sparano