awesome-copilot/skills/penpot-uiux-design/references/component-patterns.md

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