hr-portal/.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