ui/.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