/ui-patterns

name: ui-patterns
description: "Use this skill when the user needs to build a dashboard, settings page, data table, or any page layout. Also use when choosing component libraries, implementing responsive design, dark mode, or handling UI states (loading, empty, error). Covers component selection, page composition, and responsive implementation."

UI Patterns

This skill covers how to build pages and compose components for SaaS applications. It provides the structural decisions — which components to use, how to lay out pages, and how to handle every UI state. For visual styling (colors, typography, spacing systems), see the beautify skill. For user flow design, see ux-design. For accessibility requirements (semantic HTML, keyboard nav, ARIA), see ux-design/ACCESSIBILITY.md.

Component Library Selection

**Default: shadcn/ui + Tailwind CSS.** This is the correct choice for 90% of founder-built SaaS apps. shadcn/ui provides copy-paste components built on Radix primitives — you own the code, can customize freely, and avoid dependency lock-in.

Decision framework:

| Situation | Choice | Why | |---|---|---| | Public-facing SaaS product | shadcn/ui + Tailwind | Full design control, great defaults, accessible | | Internal admin tool / back-office | Ant Design or MUI | Dense data display, built-in table/form patterns, faster to ship | | Need one specific primitive (tooltip, dialog) | Radix directly | Skip the styling layer, use just the behavior | | Existing MUI/Chakra codebase | Stay with current lib | Migration cost rarely worth it mid-project | | React Native / mobile app | React Native Paper or Tamagui | Web component libs don't apply |

When using shadcn/ui: install components individually (`npx shadcn-ui@latest add button`), don't install everything upfront. Configure the `components.json` path aliases to match the project structure.

Page Composition Principles

Every SaaS page follows a predictable anatomy. Structure pages using these content zones:

**Page header** — Title, description, primary action button (top-right). Breadcrumbs above the title if nested. Height: 64-80px.

**Primary content** — The main purpose of the page. Takes 60-70% of width on desktop. This is the "spine" — the vertical column the user's eye follows.

**Secondary content** — Supporting information, filters, related items. Sidebar or below primary content. Takes 30-40% width or full-width below on mobile.

**Actions area** — Sticky bottom bar for forms, floating action button, or inline with content. Never hide primary actions in menus.

The page spine principle: every page has one dominant vertical column. On a dashboard, it's the metrics-to-activity flow. On a settings page, it's the form sections. On a list page, it's the table. Identify the spine and give it visual priority — other content supports it.

Standard page container: `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8`. For content-heavy pages (docs, settings forms): `max-w-3xl`. For full-bleed layouts (dashboards): no max-width, use the sidebar to constrain.

The State Matrix

Every data-driven component must handle five states. Missing any one of these creates a broken experience. When building any component that displays dynamic data, implement all five:

Loading State

Use skeleton loaders that match the shape of the real content. Never use spinners for inline content — spinners are only for full-page loads or button actions.

• Tables: render 5-8 skeleton rows with column-width-matched blocks
• Cards: render the card shell with pulsing placeholder blocks
• Lists: render 3-5 skeleton items
• Use `animate-pulse` with `bg-muted` blocks. Match heights and widths to actual content.

Empty State

The most neglected state. Every empty state needs: an icon or illustration, a headline explaining what will appear here, a description of how to populate it, and a primary CTA button.

No projects yet → "Create your first project" button
No search results → "Try different keywords" suggestion
No notifications → "You're all caught up" message (no CTA needed)

Empty states are onboarding moments. Use them to teach users what to do next.

Error State

Display what went wrong in plain language and provide a retry action. Never show raw error codes or stack traces.

• Inline errors: red text below the failed component + retry button
• Full-page errors: centered message with retry and "go back" options
• Network errors: "Connection lost. Retrying..." with auto-retry logic
• Always preserve user input on form errors — never clear fields

Success State

The normal content display. This is what most developers build first (and sometimes only). Ensure it handles variable content lengths — long titles, missing optional fields, various image aspect ratios.

Overflow State

What happens when there's too much data:

• Tables: paginate at 10-25 rows, show total count, provide page size selector
• Lists: infinite scroll or "Load more" button. Show count: "Showing 20 of 148"
• Text: truncate with ellipsis and "Show more" expand option. Use `line-clamp-2` or `line-clamp-3`
• Tags/badges: show first 3 + "+N more" pill

Responsive Strategy

Use mobile-first with Tailwind's breakpoint system. Default styles target mobile, then layer on complexity:

| Breakpoint | Width | Target | |---|---|---| | default | 0-639px | Mobile phones | | `sm` | 640px+ | Large phones, small tablets | | `md` | 768px+ | Tablets | | `lg` | 1024px+ | Small laptops, landscape tablets | | `xl` | 1280px+ | Desktops | | `2xl` | 1536px+ | Large monitors |

**What changes at each breakpoint:**

• **Mobile (default):** Single column. Bottom navigation. Cards stack vertically. Tables become card lists. Sidebar hidden behind hamburger. Modals go full-screen. Horizontal padding: 16px.
• **sm:** Minor adjustments. Two-column grids where appropriate. Slightly more padding.
• **md:** Sidebar can appear as collapsible overlay. Tables can show with horizontal scroll. Two or three colum