loader/.cursor/skills/ui-design/references/components.md

# Component Reference

Use this reference when generating UI mockups. Each component includes best practices, required states, and accessibility requirements.

## Navigation

### Top Navigation Bar
- Fixed or sticky at top; z-index above content
- Logo/brand left, primary nav center or right, actions (search, profile, CTA) far right
- Active state: underline, background highlight, or bold — pick one, be consistent
- Mobile: collapse to hamburger menu at `md` breakpoint; never show hamburger on desktop
- Height: 56-72px; padding inline 16-24px
- Aliases: navbar, header nav, app bar, top bar

### Sidebar Navigation
- Width: 240-280px expanded, 64-72px collapsed
- Sections with labels; icons + text for each item
- Active item: background fill + accent color text/icon
- Collapse/expand toggle; responsive: overlay on mobile
- Scroll independently from main content if taller than viewport
- Aliases: side nav, drawer, rail

### Breadcrumbs
- Show hierarchy path; separator: `/` or `>`
- Current page is plain text (not a link); parent pages are links
- Truncate with ellipsis if more than 4-5 levels
- Aliases: path indicator, navigation trail

### Tabs
- Use for switching between related content views within the same context
- Active tab: border-bottom accent or filled background
- Never nest tabs inside tabs
- Scrollable when too many to fit; show scroll indicators
- Aliases: tab bar, segmented control, view switcher

### Pagination
- Show current page, first, last, and 2-3 surrounding pages
- Previous/Next buttons always visible; disabled at boundaries
- Show total count when available: "Showing 1-20 of 342"
- Aliases: pager, page navigation

## Content Display

### Card
- Border-radius: 8-12px; subtle shadow or border (not both unless intentional)
- Padding: 16-24px; consistent within the same card grid
- Content order: image/visual → title → description → metadata → actions
- Hover: subtle shadow lift or border-color change (not both)
- Never stack more than 3 cards vertically without visual break
- Aliases: tile, panel, content block

### Data Table
- Header row: sticky, slightly bolder background, sort indicators
- Row hover: subtle background change
- Striped rows optional; alternate between base and surface colors
- Cell padding: 12-16px vertical, 16px horizontal
- Truncate long text with ellipsis + tooltip on hover
- Responsive: horizontal scroll with frozen first column, or stack to card layout on mobile
- Include empty state when no data
- Aliases: grid, spreadsheet, list view

### List
- Consistent item height or padding
- Dividers between items: subtle border or spacing (not both)
- Interactive lists: hover state on entire row
- Leading element (icon/avatar) + content (title + subtitle) + trailing element (action/badge)
- Aliases: item list, feed, timeline

### Stat/Metric Card
- Large number/value prominently displayed
- Label above or below the value; comparison/trend indicator optional
- Color-code trends: green up, red down, gray neutral
- Aliases: KPI card, metric tile, stat block

### Avatar
- Circular; sizes: 24/32/40/48/64px
- Fallback: initials on colored background when no image
- Status indicator: small circle at bottom-right (green=online, gray=offline)
- Group: overlap with z-index stacking; show "+N" for overflow
- Aliases: profile picture, user icon

### Badge/Tag
- Small, pill-shaped or rounded-rectangle
- Color indicates category or status; limit to 5-6 distinct colors
- Text: short (1-3 words); truncate if longer
- Removable variant: include x button
- Aliases: chip, label, status indicator

### Hero Section
- Full-width; height 400-600px or viewport-relative
- Strong headline (h1) + supporting text + primary CTA
- Background: gradient, image with overlay, or solid color — not all three
- Text must have sufficient contrast over any background
- Aliases: banner, jumbotron, splash

### Empty State
- Illustration or icon (not a generic placeholder)
- Explanatory text: what this area will contain
- Primary action CTA: "Create your first...", "Add...", "Import..."
- Never show just blank space
- Aliases: zero state, no data, blank slate

### Skeleton Loader
- Match the shape and layout of the content being loaded
- Animate with subtle pulse or shimmer (left-to-right gradient)
- Show for predictable content; use progress bar for uploads/processes
- Never use spinning loaders for content that has a known layout
- Aliases: placeholder, loading state, content loader

## Forms & Input

### Text Input
- Height: 40-48px; padding inline 12-16px
- Label above the input (not placeholder-only); placeholder as hint only
- States: default, hover, focus (accent ring), error (red border + message), disabled (reduced opacity)
- Error message below the field with icon; don't use red placeholder
- Aliases: text field, input box, form field

### Textarea
- Minimum height: 80-120px; resizable vertically
- Character count when there's a limit
- Same states as text input
- Aliases: multiline input, text area, comment box

### Select/Dropdown
- Match text input height and styling
- Chevron indicator on the right
- Options list: max height with scroll; selected item checkmark
- Search/filter for lists longer than 10 items
- Aliases: combo box, picker, dropdown menu

### Checkbox
- Size: 16-20px; rounded corners (2-4px)
- Label to the right; clickable area includes the label
- States: unchecked, checked (accent fill + white check), indeterminate (dash), disabled
- Group: vertical stack with 8-12px gap
- Aliases: check box, toggle option, multi-select

### Radio Button
- Size: 16-20px; circular
- Same interaction patterns as checkbox but single-select
- Group: vertical stack; minimum 2 options
- Aliases: radio, option button, single-select

### Toggle/Switch
- Width: 40-52px; height: 20-28px; thumb is circular
- Off: gray track; On: accent color track
- Label to the left or right; describe the "on" state
- Never use for actions that require a submit; toggles are instant
- Aliases: switch, on/off toggle

### File Upload
- Drop zone with dashed border; icon + "Drag & drop or click to upload"
- Show file type restrictions and size limit
- Progress indicator during upload
- File list after upload: name, size, remove button
- Aliases: file picker, upload area, attachment

### Form Layout
- Single column for most forms; two columns only for related short fields (first/last name, city/state)
- Group related fields with section headings
- Required field indicator: asterisk after label
- Submit button: right-aligned or full-width; clearly primary
- Inline validation: show errors on blur, not on every keystroke

## Actions

### Button
- Primary: filled accent color, white text; one per visible area
- Secondary: outline or subtle background; supports primary action
- Ghost/tertiary: text-only with hover background
- Sizes: sm (32px), md (40px), lg (48px); padding inline 16-24px
- States: default, hover (darken/lighten 10%), active (darken 15%), focus (ring), disabled (opacity 0.5 + not-allowed cursor)
- Disabled buttons must have a title attribute explaining why
- Icon-only buttons: need aria-label; minimum 40px touch target
- Aliases: action, CTA, submit

### Icon Button
- Circular or rounded-square; minimum 40px for touch targets
- Tooltip on hover showing the action name
- Visually lighter than text buttons
- Aliases: toolbar button, action icon

### Dropdown Menu
- Trigger: button or icon button
- Menu: elevated surface (shadow), rounded corners
- Items: 36-44px height; icon + label; hover background
- Dividers between groups; section labels for grouped items
- Keyboard navigable: arrow keys, enter to select, escape to close
- Aliases: context menu, action menu, overflow menu

### Floating Action Button (FAB)
- Circular, 56px; elevated with shadow
- One per screen maximum; bottom-right placement
- Primary creation action only
- Extended variant: pill-shape with icon + label
- Aliases: FAB, add button, create button

## Feedback

### Toast/Notification
- Position: top-right or bottom-right; stack vertically
- Auto-dismiss: 4-6 seconds for info; persist for errors until dismissed
- Types: success (green), error (red), warning (amber), info (blue)
- Content: icon + message + optional action link + close button
- Maximum 3 visible at once; queue the rest
- Aliases: snackbar, alert toast, flash message

### Alert/Banner
- Full-width within its container; not floating
- Types: info, success, warning, error with corresponding colors
- Icon left, message center, dismiss button right
- Persistent until user dismisses or condition changes
- Aliases: notice, inline alert, status banner

### Modal/Dialog
- Centered; overlay dims background (opacity 0.5 black)
- Max width: 480-640px for standard, 800px for complex
- Header (title + close button) + body + footer (actions)
- Actions: right-aligned; primary right, secondary left
- Close on overlay click and Escape key
- Never put a modal inside a modal
- Focus trap: tab cycles within modal while open
- Aliases: popup, dialog box, lightbox

### Tooltip
- Appears on hover after 300-500ms delay; disappears on mouse leave
- Position: above element by default; flip if near viewport edge
- Max width: 200-280px; short text only
- Arrow/caret pointing to trigger element
- Aliases: hint, info popup, hover text

### Progress Indicator
- Linear bar: for known duration/percentage; show percentage text
- Skeleton: for content loading with known layout
- Spinner: only for indeterminate short waits (< 3 seconds) where layout is unknown
- Step indicator: for multi-step flows; show completed/current/upcoming
- Aliases: loading bar, progress bar, stepper

## Layout

### Page Shell
- Max content width: 1200-1440px; centered with auto margins
- Sidebar + main content pattern: sidebar fixed, main scrolls
- Header/footer outside max-width for full-bleed effect
- Consistent padding: 16px mobile, 24px tablet, 32px desktop

### Grid
- CSS Grid or Flexbox; 12-column system or auto-fit with minmax
- Gap: 16-24px between items
- Responsive: 1 column mobile, 2 columns tablet, 3-4 columns desktop
- Never rely on fixed pixel widths; use fr units or percentages

### Section Divider
- Use spacing (48-96px margin) as primary divider; use lines sparingly
- If using lines: subtle (1px, border color); full-width or indented
- Alternate section backgrounds (base/surface) for clear separation without lines

### Responsive Breakpoints
- sm: 640px (large phone landscape)
- md: 768px (tablet)
- lg: 1024px (small laptop)
- xl: 1280px (desktop)
- Design mobile-first: base styles are mobile, layer up with breakpoints

## Specialized

### Pricing Table
- 2-4 tiers side by side; highlight recommended tier
- Feature comparison with checkmarks; group features by category
- CTA button per tier; recommended tier has primary button, others secondary
- Monthly/annual toggle if applicable
- Aliases: pricing cards, plan comparison

### Testimonial
- Quote text (large, italic or with quotation marks)
- Attribution: avatar + name + title/company
- Layout: single featured or carousel/grid of multiple
- Aliases: review, customer quote, social proof

### Footer
- Full-width; darker background than body
- Column layout: links grouped by category; 3-5 columns
- Bottom row: copyright, legal links, social icons
- Responsive: columns stack on mobile
- Aliases: site footer, bottom navigation

### Search
- Input with search icon; expand on focus or always visible
- Results: dropdown with highlighted matching text
- Recent searches and suggestions
- Keyboard shortcut hint (Cmd+K / Ctrl+K)
- Aliases: search bar, omnibar, search field

### Date Picker
- Input that opens a calendar dropdown
- Navigate months with arrows; today highlighted
- Range selection: two calendars side by side
- Presets: "Today", "Last 7 days", "This month"
- Aliases: calendar picker, date selector

### Chart/Graph Placeholder
- Container with appropriate aspect ratio (16:9 for line/bar, 1:1 for pie)
- Include chart title, legend, and axis labels in the mockup
- Use representative fake data; label as "Sample Data"
- Tooltip placeholder on hover
- Aliases: data visualization, graph, analytics chart