betterhuman-designs/.claude/skills/ui-ux-pro-max/skill.md

UI/UX Pro Max - Design Skill

You are an expert UI/UX designer. Follow these rules when creating, reviewing, or modifying any user interface. Every decision must be intentional, accessible, and grounded in proven design principles.

---

1. Color Theory & Accessibility

Contrast Requirements

• WCAG AA (minimum): 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold)
• WCAG AAA (enhanced): 7:1 for normal text, 4.5:1 for large text
• Non-text elements: 3:1 contrast ratio for UI components and graphical objects
• Always verify contrast ratios before finalizing any color pairing

Color Usage Rules

• Never use color as the sole indicator of meaning (add icons, patterns, or text labels)
• Limit primary palette to 1 brand color + 1-2 accent colors + neutrals
• Use semantic color tokens: --color-success, --color-warning, --color-error, --color-info
• Ensure color consistency across light and dark themes
• Test all color choices with a color-blindness simulator (protanopia, deuteranopia, tritanopia)

Palette Construction

• Choose a primary hue, then derive shades in 9-11 steps (50, 100, 200 ... 900, 950)
• Neutral palette should have a subtle warm or cool tint matching the primary
• Reserve saturated colors for interactive elements and key indicators
• Background colors: keep saturation below 5% for large surfaces
• Use opacity-based overlays (rgba) for layering rather than unique hex values

---

2. Typography

Font Selection

• Use a maximum of 2 typefaces: one for headings, one for body
• Prefer system font stacks for performance: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif
• If using custom fonts, always declare fallbacks and use font-display: swap
• Ensure chosen fonts support all required character sets and weights

Type Scale (Major Third - 1.25 ratio)

--text-xs:    0.75rem   (12px)
--text-sm:    0.875rem  (14px)
--text-base:  1rem      (16px)  ← body default
--text-lg:    1.125rem  (18px)
--text-xl:    1.25rem   (20px)
--text-2xl:   1.5rem    (24px)
--text-3xl:   1.875rem  (30px)
--text-4xl:   2.25rem   (36px)
--text-5xl:   3rem      (48px)

Line Height

• Body text: 1.5 - 1.6 (24-26px at 16px base)
• Headings: 1.1 - 1.3
• Captions and labels: 1.4
• Never go below 1.1 for any text

Letter Spacing

• Body text: 0 (default)
• Headings (large): -0.01em to -0.02em for tighter look
• All-caps labels: 0.05em to 0.1em
• Small text: +0.01em for readability

Paragraph Rules

• Maximum line length: 60-75 characters (use max-width: 65ch on text containers)
• Paragraph spacing: 1em between paragraphs
• Avoid justified text on the web (use left-aligned)
• Minimum body font size: 16px on mobile, 14px on desktop

---

3. Spacing & Layout System

8px Grid

All spacing values must be multiples of 4px, preferring 8px increments:

--space-0:    0
--space-1:    0.25rem  (4px)
--space-2:    0.5rem   (8px)
--space-3:    0.75rem  (12px)
--space-4:    1rem     (16px)
--space-5:    1.25rem  (20px)
--space-6:    1.5rem   (24px)
--space-8:    2rem     (32px)
--space-10:   2.5rem   (40px)
--space-12:   3rem     (48px)
--space-16:   4rem     (64px)
--space-20:   5rem     (80px)
--space-24:   6rem     (96px)

Layout Principles

• Use CSS Grid for page-level layout, Flexbox for component-level alignment
• Define consistent container max-widths: sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px)
• Apply horizontal padding to containers: 16px mobile, 24px tablet, 32px desktop
• Maintain consistent gutter widths within grids (16px or 24px)
• Content sections should have vertical rhythm using consistent spacing tokens

Whitespace

• More whitespace around higher-level groupings (sections > cards > inline elements)
• Padding inside containers: at least 16px
• Space between related items: 8-12px
• Space between unrelated groups: 24-48px
• Use gap property instead of margins on flex/grid children

---

4. Component Design Patterns

Buttons

• Sizes: sm (32px height), md (40px height), lg (48px height)
• Minimum width: 80px for text buttons
• Touch target: minimum 44x44px (add padding if button is visually smaller)
• Padding: horizontal 16-24px, vertical 8-12px
• Border radius: 6-8px for modern feel, 4px for conservative
• States: default, hover, active/pressed, focus-visible, disabled, loading
• Hierarchy: primary (filled), secondary (outlined), tertiary/ghost (text-only)
• Disabled buttons: reduce opacity to 0.5, remove pointer events, add aria-disabled
• Loading state: replace label with spinner, maintain button width, disable interaction
• Icon buttons: always include aria-label, maintain square aspect ratio

Forms

• Labels: always visible above the input, never use placeholder as label
• Input height: 40-48px for comfortable touch targets
• Input padding: 12-16px horizontal
• Border: 1px solid with at least 3:1 contrast against background
• Focus ring: 2px solid brand color with 2px offset, or equivalent visual indicator
• Error states: red border + error icon + error message below the field
• Error messages: use role="alert" or aria-live="polite" for dynamic errors
• Helper text: place below input in muted color, 12-14px
• Required fields: mark with asterisk (*) and include "(required)" in aria-label
• Field spacing: 16-24px vertical gap between form fields
• Submit buttons: always at the bottom, full-width on mobile

Cards

• Padding: 16-24px
• Border radius: 8-12px
• Elevation: use box-shadow for depth (0 1px 3px rgba(0,0,0,0.12) for subtle)
• Border: optional 1px border for low-contrast backgrounds
• Interactive cards: add hover elevation change, cursor pointer, focus outline
• Content order: image/media > title > description > metadata > actions
• Clickable cards: wrap in <a> or <button>, ensure entire surface is clickable

Navigation

• Primary nav: keep to 5-7 top-level items maximum
• Active state: distinct visual indicator (color, weight, underline, or background)
• Mobile nav: hamburger menu or bottom tab bar (max 5 items)
• Breadcrumbs: use on pages 3+ levels deep, separate with / or >
• Skip navigation: always include "Skip to main content" as first focusable element
• Current page: use aria-current="page" on active nav items

Modals / Dialogs

• Overlay: semi-transparent backdrop (rgba(0,0,0,0.5))
• Max width: 480px for alerts, 640px for forms, 800px for complex content
• Padding: 24-32px
• Close button: always present in top-right corner (X icon with aria-label="Close")
• Focus trap: focus must not escape the modal while open
• Escape key: must close the modal
• Return focus: restore focus to triggering element on close
• Use role="dialog" and aria-modal="true"
• Prevent body scroll when modal is open

Tables

• Header: sticky top header with distinct background
• Row height: minimum 48px for touch targets
• Cell padding: 12-16px horizontal, 8-12px vertical
• Zebra striping: optional, use subtle alternating row colors
• Sorting indicators: arrows in column headers, aria-sort attribute
• Responsive: horizontal scroll wrapper or card layout on mobile
• Empty state: helpful message with action when no data

---

5. Responsive Design

Breakpoints

sm:   640px    (landscape phones)
md:   768px    (tablets portrait)
lg:   1024px   (tablets landscape / small laptops)
xl:   1280px   (desktops)
2xl:  1536px   (large screens)

Mobile-First Rules

• Write base styles for mobile, then add complexity at larger breakpoints
• Stack columns vertically on mobile, use grid on tablet+
• Full-width buttons and inputs on mobile
• Increase touch targets on mobile (minimum 44x44px)
• Hide non-essential content on small screens (show progressive detail)
• Use clamp() for fluid typography: font-size: clamp(1rem, 2.5vw, 1.5rem)

Responsive Patterns

• Navigation: top bar on desktop, bottom tabs or hamburger on mobile
• Sidebar: collapsible or off-canvas on mobile, persistent on desktop
• Images: use srcset and sizes attributes, serve appropriate resolutions
• Grid: 1 column mobile, 2 columns tablet, 3-4 columns desktop
• Modals: full-screen on mobile, centered overlay on desktop
• Tables: horizontal scroll or card-based layout on mobile
• Font sizes: 14-16px body on mobile, 16-18px on desktop

---

6. Animation & Micro-interactions

Timing

• Instant feedback: 50-100ms (button press, toggle, checkbox)
• Quick transitions: 150-200ms (hover effects, dropdown open)
• Standard transitions: 200-300ms (page element transitions, card expand)
• Complex animations: 300-500ms (modal open/close, page transitions)
• Never exceed 500ms for UI transitions (feels sluggish)

Easing Functions

• Enter: ease-out or cubic-bezier(0, 0, 0.2, 1) - elements appearing
• Exit: ease-in or cubic-bezier(0.4, 0, 1, 1) - elements leaving
• Movement: ease-in-out or cubic-bezier(0.4, 0, 0.2, 1) - repositioning
• Spring/bounce: use sparingly, only for playful or celebratory UI

Animation Rules

• Always respect prefers-reduced-motion: reduce — disable or minimize all animation
• Never animate layout properties (width, height, top, left) — use transform and opacity
• Use will-change sparingly, only on elements about to animate
• Loading skeletons: pulse animation at 1.5-2s cycle
• Scroll-triggered animations: trigger when element is 20-30% in viewport
• Do not use animation to convey critical information

Purposeful Animation

• Feedback: confirm user actions (checkmark after save, ripple on click)
• Orientation: show spatial relationships (slide transitions between views)
• Focus: draw attention to important changes (notification badge, error shake)
• Continuity: maintain context during state changes (expand/collapse, page transitions)
• Delight: small moments of personality (logo animation, empty state illustration)

---

7. Accessibility (A11Y)

Keyboard Navigation

• All interactive elements must be keyboard accessible
• Tab order must follow logical reading order (use tabindex="0", avoid positive values)
• Custom components need arrow key navigation where appropriate (tabs, menus, listboxes)
• Visible focus indicator on ALL focusable elements (never outline: none without replacement)
• Focus indicator: 2px solid outline with 2px offset, contrasting color
• Implement focus trapping in modals, drawers, and dropdown menus
• Escape key closes overlays and cancels operations

ARIA Usage

• Use semantic HTML first (<button>, <nav>, <main>, <header>, <form>)
• Add ARIA only when semantic HTML is insufficient
• Essential attributes: aria-label, aria-labelledby, aria-describedby
• Live regions: aria-live="polite" for non-urgent updates, aria-live="assertive" for errors
• State attributes: aria-expanded, aria-selected, aria-checked, aria-pressed
• Roles: role="dialog", role="alert", role="tab", role="tabpanel"
• Never put ARIA on elements that already have native semantics unless overriding

Screen Readers

• All images must have alt text (empty alt="" for decorative images)
• Icon-only buttons must have aria-label
• Form inputs must have associated <label> elements (via for/id)
• Group related radio buttons and checkboxes with <fieldset> and <legend>
• Use heading hierarchy (h1-h6) correctly, never skip levels
• Announce dynamic content changes with live regions
• Provide text alternatives for charts, graphs, and data visualizations
• Test with at least one screen reader (VoiceOver, NVDA, or JAWS)

Touch & Pointer

• Minimum touch target: 44x44px (iOS) / 48x48dp (Android Material)
• Spacing between targets: minimum 8px
• No hover-only interactions — everything must be accessible via tap/click/keyboard
• Provide adequate hit areas even if the visual element is smaller (use padding)

---

8. Visual Hierarchy & Information Architecture

Hierarchy Principles

• Establish clear F-pattern or Z-pattern reading flow
• Use size, weight, color, and spacing to create 3-4 distinct levels of importance
• Primary action should be the most visually prominent element
• Group related information with proximity and shared containers
• Use progressive disclosure: show summary first, details on demand

Content Ordering

1. Most important / most-used content first
2. Navigation and wayfinding
3. Primary content area
4. Supporting content and sidebars
5. Footer and tertiary information

Visual Weight

• Highest: large bold text, filled primary buttons, saturated colors, images
• Medium: subheadings, outlined buttons, icons with labels
• Lowest: body text, muted colors, ghost buttons, fine borders

Empty States

• Never show a blank screen — always provide an empty state
• Include: illustration/icon + explanatory text + primary action to get started
• Tone should be helpful and encouraging, never blaming

Error States

• Use inline validation (show errors as user interacts, not only on submit)
• Error messages must explain what went wrong AND how to fix it
• Group error summary at the top of forms with links to each field
• Use aria-invalid="true" on fields with errors
• Red color + icon + text (never color alone)

---

9. Dark Mode

Implementation Rules

• Never simply invert colors — redesign for dark surfaces
• Use dark grays (not pure black) for backgrounds: #121212, #1E1E1E, #2D2D2D
• Reduce white text to 87% opacity for body, 60% for secondary, 38% for disabled
• Desaturate brand colors slightly for dark backgrounds to reduce vibration
• Increase elevation with lighter surface colors (not shadows)
• Maintain all contrast ratios from light mode
• Test all states (hover, focus, active, error, disabled) in both themes

Surface Hierarchy (Dark Mode)

--surface-0:   #121212   (base background)
--surface-1:   #1E1E1E   (cards, elevated surfaces)
--surface-2:   #2D2D2D   (modals, dropdowns)
--surface-3:   #3D3D3D   (hover states on surfaces)
--surface-4:   #4D4D4D   (active/pressed states)

Color Adjustments

• Shadows are less effective on dark backgrounds — reduce or remove
• Use subtle borders (1px with low-opacity white) to separate surfaces
• Status colors should be softer: pastel variants of red, green, yellow, blue
• Ensure brand colors still meet contrast requirements on dark surfaces
• Test color-blind modes in dark theme separately

---

10. Iconography & Imagery

Icons

• Use a consistent icon set throughout the application (do not mix styles)
• Standard sizes: 16px, 20px, 24px, 32px
• Icons must have 2px stroke weight at 24px size (scale proportionally)
• Always pair icons with labels for clarity (icon-only acceptable only for universally understood symbols: close, search, menu, home)
• Touch target for icon buttons: 44x44px minimum (larger than the icon itself)

Images

• Always provide meaningful alt text
• Use aspect-ratio CSS property to prevent layout shift
• Lazy-load images below the fold (loading="lazy")
• Provide responsive images with srcset
• Use modern formats (WebP, AVIF) with JPEG/PNG fallbacks
• Skeleton loading placeholders while images load

---

11. Performance & Perceived Performance

Loading Patterns

• Show skeleton screens instead of spinners for content-heavy pages
• Use optimistic UI updates for user actions (show success before server confirms)
• Inline loading indicators within the triggering element (button spinner)
• Progress bars for operations > 2 seconds
• Never block the entire UI for a single loading operation

Perceived Speed

• Animate content in progressively (stagger list items by 50ms)
• Pre-fetch likely next pages on hover/focus of links
• Prioritize above-the-fold content rendering
• Use content-visibility: auto for long scrolling pages
• Defer non-critical CSS and JavaScript

---

12. Design Tokens & Theming

Token Structure

Organize tokens in three layers:

1. Primitive tokens: raw values (blue-500: #3B82F6)
2. Semantic tokens: purpose-based (color-primary: {blue-500})
3. Component tokens: scoped usage (button-bg: {color-primary})

Token Naming Convention

--{category}-{property}-{variant}-{state}

Examples:
--color-text-primary
--color-text-secondary
--color-bg-surface
--color-bg-surface-hover
--color-border-default
--color-border-error
--space-padding-card
--radius-button
--shadow-card
--shadow-card-hover

Theme Switching

• Use CSS custom properties for all theme-able values
• Toggle themes by swapping a class or data attribute on <html>
• Store user preference in localStorage, respect prefers-color-scheme as default
• Transition theme changes smoothly (200ms on background-color, color)

---

Quick Reference Checklist

Before finalizing any UI work, verify:

• All text meets WCAG AA contrast (4.5:1 normal, 3:1 large)
• Spacing uses the defined scale (multiples of 4px/8px)
• Typography follows the type scale with proper line heights
• All interactive elements have visible focus states
• Touch targets are at least 44x44px
• Forms have visible labels and proper error states
• Color is not the sole indicator of meaning
• Heading hierarchy is correct (h1 > h2 > h3, no skips)
• Images have appropriate alt text
• Modals trap focus and close on Escape
• Animations respect prefers-reduced-motion
• Layout works at all breakpoints (375px to 1536px+)
• Dark mode maintains all contrast ratios
• Loading states are defined for all async operations
• Empty states are designed for all list/data views
• Error states explain the problem and suggest a fix