Skip to content

component-patterns.md

Latest commit

 

History

History
339 lines (251 loc) · 11.4 KB

component-patterns.md

File metadata and controls

339 lines (251 loc) · 11.4 KB

UI Component Patterns Reference

Buttons

Button Types

Type Purpose Visual Treatment
Primary Main action on page Solid fill, brand color
Secondary Supporting actions Outline or muted fill
Tertiary Low-emphasis actions Text-only, underline optional
Destructive Delete/remove actions Red color, confirmation required
Ghost Minimal UI, icon buttons Transparent, subtle hover

Button States

Default    → Resting state, clearly interactive
Hover      → Cursor over (desktop): darken 10%, subtle shadow
Active     → Being pressed: darken 20%, slight scale down
Focus      → Keyboard selected: visible outline ring
Disabled   → Not available: 50% opacity, cursor: not-allowed
Loading    → Processing: spinner replaces or accompanies label

Button Specifications

  • Minimum size: 44×44px (touch target)
  • Padding: 12-16px horizontal, 8-12px vertical
  • Border radius: 4-8px (consistent across app)
  • Font weight: Medium or Semibold (600-700)
  • Text: Sentence case, 2-4 words max

Button Label Patterns

✓ Save Changes        ✗ Submit
✓ Add to Cart         ✗ Click Here
✓ Create Account      ✗ OK
✓ Download PDF        ✗ Go
✓ Start Free Trial    ✗ Continue

Forms

Form Layout Guidelines

  • Single column preferred: Reduces cognitive load
  • Top-aligned labels: Fastest completion times
  • Logical grouping: Related fields together
  • Smart defaults: Pre-fill when possible

Input Field Anatomy

┌─ Label (required) ─────────────────────────┐
│                                            │
│  ┌────────────────────────────────────┐   │
│  │ Placeholder text...                 │   │
│  └────────────────────────────────────┘   │
│  Helper text or error message              │
└────────────────────────────────────────────┘

Input States

State Border Background Additional
Default Gray (#D1D5DB) White -
Focus Primary color White Shadow/glow
Filled Gray White Checkmark optional
Error Red (#EF4444) Light red tint Error icon + message
Disabled Light gray Gray (#F3F4F6) 50% opacity text

Validation Timing

  • On blur: Validate when user leaves field
  • On change (after error): Clear error as user types correct input
  • On submit: Final validation before processing
  • Never on focus: Don't show errors before user types

Error Message Guidelines

✓ "Email address is required"
✓ "Password must be at least 8 characters"
✓ "Please enter a valid phone number (e.g., 555-123-4567)"

✗ "Invalid input"
✗ "Error"
✗ "This field is required" (generic)

Form Best Practices

  • Mark optional fields, not required (fewer asterisks)
  • Show password requirements before errors occur
  • Use input masks for formatted data (phone, date)
  • Preserve data on errors (don't clear the form)
  • Provide clear success confirmation

Navigation

Navigation Patterns

Top Navigation Bar

┌─────────────────────────────────────────────────────┐
│ Logo    Nav Item  Nav Item  Nav Item    [Search] [User] │
└─────────────────────────────────────────────────────┘
  • Best for: Marketing sites, simple apps
  • Max items: 5-7 top-level links
  • Mobile: Collapse to hamburger menu

Sidebar Navigation

┌────────┬────────────────────────────────┐
│ Logo   │ Content Area                   │
├────────┤                                │
│ Nav 1  │                                │
│ Nav 2  │                                │
│ Nav 3  │                                │
│        │                                │
│ ────── │                                │
│ Nav 4  │                                │
│ Nav 5  │                                │
└────────┴────────────────────────────────┘
  • Best for: Dashboards, complex apps
  • Width: 200-280px expanded, 64px collapsed
  • Mobile: Overlay drawer

Bottom Navigation (Mobile)

┌─────────────────────────────────────┐
│           Content Area              │
│                                     │
├─────────────────────────────────────┤
│  🏠    🔍    ➕    💬    👤        │
│ Home  Search Add  Chat  Profile     │
└─────────────────────────────────────┘
  • Max items: 3-5 destinations
  • Best for: Primary app sections
  • Always visible: Persistent navigation

Breadcrumbs

Home > Products > Electronics > Headphones
  • Use for: Deep hierarchies (3+ levels)
  • Current page: Not clickable, different style
  • Separator: > or / or chevron icon

Tab Navigation

┌─────────┬─────────┬─────────┬─────────┐
│ Tab 1   │ Tab 2   │ Tab 3   │ Tab 4   │
└─────────┴─────────┴─────────┴─────────┘
│                                       │
│        Tab Content Area               │
│                                       │
└───────────────────────────────────────┘
  • Max tabs: 3-5 for clarity
  • Active indicator: Underline or background
  • Use for: Related content within same page

Cards

Card Anatomy

┌─────────────────────────────────┐
│ ░░░░░░░ Image/Media ░░░░░░░░░░ │
├─────────────────────────────────┤
│ Category Label                  │
│ Card Title                      │
│ Description text that may       │
│ span multiple lines...          │
│                                 │
│ [Action Button]  [Secondary]    │
└─────────────────────────────────┘

Card Guidelines

  • Consistent sizing: Use grid, equal heights
  • Content hierarchy: Image → Title → Description → Actions
  • Padding: 16-24px internal spacing
  • Border radius: 8-12px (matching buttons)
  • Shadow: Subtle elevation (0 2px 4px rgba(0,0,0,0.1))

Modals and Dialogs

Modal Structure

┌─────────────────────────────────────┐
│ Modal Title                    [×]  │
├─────────────────────────────────────┤
│                                     │
│ Modal content goes here.            │
│ Keep it focused on one task.        │
│                                     │
├─────────────────────────────────────┤
│           [Cancel]  [Confirm]       │
└─────────────────────────────────────┘

Modal Guidelines

  • Size: 400-600px width (desktop), full-width minus margins (mobile)
  • Overlay: Semi-transparent dark background (rgba(0,0,0,0.5))
  • Close options: X button, overlay click, Escape key
  • Focus trap: Keep keyboard focus within modal
  • Primary action: Right-aligned, visually prominent

Dashboards

Dashboard Layout Principles

  1. Most important metrics at top: KPIs, summary cards
  2. Progressive detail: Overview → Drill-down capability
  3. Consistent card sizes: Use grid system
  4. Minimal chartjunk: Only data-serving visuals
  5. Actionable insights: Highlight anomalies

Data Visualization Selection

Data Type Chart Type
Comparison across categories Bar chart
Trend over time Line chart
Part of whole Pie (≤5 slices) or Donut
Distribution Histogram
Correlation Scatter plot
Geographic Map
Single metric Big number + sparkline

Dashboard Best Practices

  • Limit to 5-9 widgets per view
  • Align to grid: Consistent gutters and sizing
  • Filter controls: Top or sidebar, always visible
  • Date range selector: Common need, make prominent
  • Export options: PDF, CSV for data tables
  • Responsive: Stack cards on smaller screens

Empty States

Empty State Components

┌─────────────────────────────────────┐
│                                     │
│         [Illustration/Icon]         │
│                                     │
│      No projects yet                │
│                                     │
│   Create your first project to      │
│   start organizing your work.       │
│                                     │
│       [Create Project]              │
│                                     │
└─────────────────────────────────────┘

Empty State Guidelines

  • Friendly illustration: Not just "No data"
  • Explain value: Why create something?
  • Clear CTA: Primary action to fix empty state
  • Keep it brief: 1-2 sentences max

Loading States

Loading Patterns

Duration Pattern
<1 second No indicator (feels instant)
1-3 seconds Spinner or progress indicator
3-10 seconds Skeleton screens + progress
>10 seconds Progress bar + explanation

Skeleton Screen

┌─────────────────────────────────────┐
│ ░░░░░░░░░░░░ ░░░░░░░░░░           │
├─────────────────────────────────────┤
│ ░░░░░░░░░░░░░░░░░░░░░░░░░         │
│ ░░░░░░░░░░░░░░░░░░░               │
│ ░░░░░░░░░░░░░░░░░░░░░░░           │
└─────────────────────────────────────┘
  • Match layout of loaded content
  • Use subtle animation (shimmer/pulse)
  • Show actual content structure