Shadcn Design Patterns

shadcn Design Patterns

Framework-agnostic design patterns for building beautiful, accessible UIs with shadcn's design philosophy.

When to Use This Skill

• Planning page or screen layouts
• Choosing the right component for a task
• Designing forms, dialogs, or complex interactions
• Making design decisions (colors, spacing, hierarchy)
• Building consistent, accessible UIs

Pair with implementation skills (ui-shadcn-flutter, shadcn-ui, etc.) for concrete code.

Core Philosophy

1. Minimalism - Clean, uncluttered interfaces
2. Composability - Build complex UIs from simple primitives
3. Accessibility-first - ARIA patterns, keyboard navigation
4. Semantic color - Named colors convey meaning (primary, destructive, muted)
5. Consistent spacing - Systematic gaps using scaling multipliers
6. Beautiful defaults - Components look good out-of-the-box

Quick Color Guide

Semantic colors:

• primary - Main actions, submit buttons, CTAs
• secondary - Supporting actions
• destructive - Delete, remove, dangerous actions
• muted - Subdued content, secondary text, disabled states
• accent - Highlights, selection, badges

Pairing rule: Always pair colors (primary + primaryForeground, card + cardForeground, etc.)

Quick Spacing Guide

Use systematic spacing:

• 8px - Tight (within elements)
• 16px - Standard (between sections)
• 24px - Loose (major sections)
• 32px - Wide (page sections)

Component Selection Guide

Dialog vs Sheet vs Popover

Use Dialog when:

• Requires user's full attention (confirmation, critical info)
• User must respond before continuing
• Content is self-contained
• Small to medium content (fits viewport)

Use Sheet when:

• Large amount of content (scrollable)
• Contextual to current page
• Can be dismissed easily
• Forms, filters, settings panels

Use Popover when:

• Small, contextual information
• Doesn't block interaction with page
• Hover cards, tooltips with rich content
• Quick actions (color picker, date picker)

Card vs OutlinedContainer

Card vs OutlinedContainer:

• Card: Elevated content, prominent grouping
• OutlinedContainer: Subtle borders, nested containers

Alert vs Toast:

• Alert: Inline, persistent messages
• Toast: Temporary notifications, auto-dismiss

Sheet vs Dialog vs Popover:

• Sheet: Large scrollable content, side/bottom panels
• Dialog: Modal, requires attention, blocking
• Popover: Small contextual content, non-blocking

Reference Documentation

For detailed patterns:

• design-guide.md - Color system, spacing, accessibility, composition
• layout-patterns.md - Forms, pages, modals, lists, tables

Rules

✅ DO:

• Use semantic colors (primary, destructive, muted)
• Pair colors correctly (primary + primaryForeground)
• Compose complex UIs from simple primitives
• Follow accessibility patterns (keyboard, focus, labels)
• Use consistent spacing throughout
• Provide empty states and loading states
• Make dangerous actions explicit (confirmation dialogs)

❌ DON'T:

• Use arbitrary colors outside the system
• Mix color pairings (e.g., primary bg + muted text)
• Create giant custom components (compose instead)
• Skip keyboard navigation support
• Use inconsistent spacing values
• Hide important actions behind multiple clicks
• Make destructive actions easy to trigger accidentally

Pair with Implementation Skills

This skill provides design patterns. For concrete implementation:

• Flutter: Use ui-shadcn-flutter skill for Flutter widget APIs
• React: Use standard shadcn/ui component documentation
• Other frameworks: Adapt patterns to available shadcn implementation primitives
• Follow accessibility patterns
• Use consistent spacing
• Provide empty states
• Confirm dangerous actions

❌ DON'T:

• Use arbitrary colors
• Mix color pairings
• Create giant monolithic components
• Skip keyboard navigation
• Use inconsistent spacing
• Make destructive actions easy to trigger

Converted and distributed by TomeVault — claim your Tome and manage your conversions.