UI

--- name: UI description: Design clear, consistent, and visually polished user interfaces. metadata: {"clawdbot":{"emoji":"🎨","os":["linux","darwin","win32"]}} ---

Visual Hierarchy

• One focal point per screen—eye knows where to go first
• Size, color, weight establish importance—primary action most prominent
• Group related elements—proximity implies relationship
• White space is not wasted space—breathing room aids scanning

Typography

• Maximum 2-3 font families—more creates visual noise
• Clear size scale: title > heading > body > caption—distinct steps, not gradual
• Line height 1.4-1.6 for body text—too tight or loose hurts readability
• Line length 45-75 characters—prevents eye fatigue
• Left-align body text—centered only for short headings

Color Usage

• Primary color for primary actions—one dominant brand color
• Semantic colors consistent: red=error, green=success, yellow=warning
• Don't rely on color alone—add icons, text, patterns for accessibility
• Neutral palette for most UI—color for emphasis, not everywhere
• Test color blindness scenarios—8% of men affected

Spacing System

• Use consistent scale: 4px, 8px, 16px, 24px, 32px, 48px
• Apply same spacing for same relationships—all card padding equal
• More space around groups than within—visual grouping through proximity
• Generous padding on touch targets—44px minimum for mobile

Alignment

• Grid system for consistency—8px or 4px base grid
• Align to invisible lines—elements share edges, not scattered
• Left edge strongest for LTR—anchor content predictably
• Optical alignment when needed—visual center differs from mathematical

Component States

• Default, hover, active, focus, disabled—all states designed
• Focus state visible and clear—keyboard users need this
• Disabled looks disabled—reduced opacity, no pointer cursor
• Loading state replaces content—not just overlay
• Error state in context—red border, inline message

Icons

• Consistent style throughout—don't mix outlined and filled
• Recognizable at small sizes—simple shapes work better
• Labels when meaning ambiguous—icon + text clearer than icon alone
• Touch target larger than visual icon—44px tap area, 24px icon

Imagery

• Consistent aspect ratios—don't stretch or skew
• Fallback for failed loads—placeholder, not broken image
• Alt text for content images—decorative images alt=""
• Compress appropriately—quality vs file size balance

Responsive Design

• Design for smallest screen first—enhance for larger
• Breakpoints based on content—not arbitrary device widths
• Touch targets larger on touch screens—hover states only on desktop
• Consider landscape orientation—especially for tablets

Dark Mode

• Not just color inversion—redesign depth and emphasis
• Reduce contrast slightly—pure white on black strains eyes
• Shadows don't work same—use lighter surfaces for elevation
• Test all states—errors, success, charts, images
• Respect system preference—but allow override

Motion and Animation

• Duration 150-300ms for transitions—fast but perceptible
• Ease-out for entering—starts fast, settles in
• Ease-in for exiting—accelerates out of view
• Consistent timing across similar interactions
• Purpose: guide attention, show relationships, provide feedback

Design Tokens

• Define tokens for colors, spacing, typography—single source of truth
• Semantic naming: color-error not color-red
• Enables theming and dark mode—swap token values
• Scales with product—change once, update everywhere

Common Mistakes

• Too many font sizes—stick to the scale
• Inconsistent spacing—creates unpolished feel
• Low contrast text—4.5:1 minimum for accessibility
• Buttons that don't look clickable—affordance matters
• Different styles for same component—cards should match cards