ui-design · pymodel — Claude Code skill: what it does, how to install

---
name: ui-design
description: Accessible, responsive frontend UI and UX design.
---

# UI/UX Best Practices Frontend Design

Comprehensive UI/UX and frontend design best practices guide. Contains 42 rules across 8 categories, prioritized by impact to guide accessible, performant, and user-friendly interface development.

## When to Apply

Reference these guidelines when:
- Structuring HTML for accessibility and semantics
- Writing CSS for responsive layouts and visual hierarchy
- Optimizing images and fonts for Core Web Vitals
- Designing forms with proper validation and error handling
- Adding animations and interactive elements

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Accessibility & WCAG Compliance | CRITICAL | `access-` |
| 2 | Core Web Vitals Optimization | CRITICAL | `cwv-` |
| 3 | Visual Hierarchy & Layout | HIGH | `layout-` |
| 4 | Responsive & Mobile-First Design | HIGH | `resp-` |
| 5 | Typography & Font Loading | MEDIUM-HIGH | `typo-` |
| 6 | Color & Contrast | MEDIUM | `color-` |
| 7 | Forms & Validation UX | MEDIUM | `form-` |
| 8 | Animation & Performance | LOW-MEDIUM | `anim-` |

## Quick Reference

### 1. Accessibility & WCAG Compliance (CRITICAL)

- `access-semantic-html` - Use semantic HTML elements for screen readers
- `access-keyboard-navigation` - Ensure full keyboard navigation
- `access-focus-indicators` - Provide visible focus indicators
- `access-alt-text` - Provide meaningful alt text for images
- `access-aria-labels` - Use ARIA labels for icon-only controls
- `access-target-size` - Ensure minimum touch target size (24×24px)
- `access-heading-hierarchy` - Maintain logical heading hierarchy

### 2. Core Web Vitals Optimization (CRITICAL)

- `cwv-optimize-lcp` - Optimize Largest Contentful Paint under 2.5s
- `cwv-minimize-cls` - Minimize Cumulative Layout Shift under 0.1
- `cwv-improve-inp` - Improve Interaction to Next Paint under 200ms
- `cwv-responsive-images` - Serve responsive images with srcset
- `cwv-lazy-load-offscreen` - Lazy load offscreen images and iframes
- `cwv-critical-css` - Inline critical CSS and defer the rest

### 3. Visual Hierarchy & Layout (HIGH)

- `layout-visual-hierarchy` - Establish clear visual hierarchy
- `layout-whitespace` - Use whitespace to improve readability
- `layout-f-pattern` - Design for F-pattern reading behavior
- `layout-grid-system` - Use a consistent grid system
- `layout-single-cta` - Establish a clear primary action per task context
- `layout-proximity-grouping` - Group related elements with proximity

### 4. Responsive & Mobile-First Design (HIGH)

- `resp-mobile-first` - Design mobile-first with min-width queries
- `resp-fluid-typography` - Use fluid typography with clamp()
- `resp-container-queries` - Use container queries for components
- `resp-touch-targets` - Size touch targets for mobile (44×44px)
- `resp-viewport-meta` - Configure viewport meta tag correctly

### 5. Typography & Font Loading (MEDIUM-HIGH)

- `typo-font-display` - Use font-display to control loading behavior
- `typo-preload-fonts` - Preload critical web fonts
- `typo-readable-line-length` - Constrain line length (45-75ch)
- `typo-line-height` - Set appropriate line height (1.5-1.7)
- `typo-system-font-stack` - Use system font stack for UI elements

### 6. Color & Contrast (MEDIUM)

- `color-contrast-ratio` - Meet WCAG contrast ratio requirements (4.5:1)
- `color-not-only-indicator` - Never use color alone to convey information
- `color-dark-mode` - Support dark mode with prefers-color-scheme
- `color-semantic-palette` - Use semantic color names in design tokens

### 7. Forms & Validation UX (MEDIUM)

- `form-inline-validation` - Use inline validation after field blur
- `form-error-messages` - Write actionable error messages
- `form-labels-above` - Place labels above input fields
- `form-input-types` - Use correct HTML input types for mobile
- `form-autocomplete` - Enable browser autocomplete with correct attributes

### 8. Animation & Performance (LOW-MEDIUM)

- `anim-gpu-properties` - Animate only GPU-accelerated properties
- `anim-will-change` - Use will-change sparingly for animation hints
- `anim-reduced-motion` - Respect user motion preferences
- `anim-duration-easing` - Use appropriate animation duration and easing

## How to Use

Read `references/<rule-id>.md` for each rule above that matches the task: why it matters, then incorrect vs. correct code.