deploy: hr-portal-designs

2026-05-04 15:56:20 +00:00
commit 96d64f4b6f
16 changed files with 5629 additions and 0 deletions
@@ -0,0 +1,427 @@
+# 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