ui-patterns

# 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 column grids. Padding: 24px.
- **lg:** Full sidebar visible. Tables display normally. Multi-column layouts activate. Dashboard grids expand. Padding: 32px.
- **xl+:** Max-width containers center content. Extra whitespace on sides. Optional: wider sidebar, more columns.

**Key responsive patterns:**

| Desktop Pattern | Mobile Adaptation |
|---|---|
| Sidebar navigation | Bottom tab bar (5 items max) or hamburger menu |
| Data table | Stacked cards with key fields visible |
| Multi-column grid | Single column, stacked |
| Side-by-side panels | Tabbed or stacked sections |
| Hover tooltips | Tap-to-reveal or always-visible labels |
| Right-click context menu | Long-press menu or action row with icons |
| Modal dialog | Full-screen sheet sliding up from bottom |

For the sidebar-to-bottom-nav pattern: don't just hide the sidebar. Build a dedicated `BottomNav` component with 4-5 icon+label items. The items should map to the top-level sidebar sections, not be a 1:1 copy.

## Dark Mode

**When to implement:** If building an MVP for validation, skip dark mode. If building a product users will spend hours in (dashboards, dev tools, writing apps), implement from day 1. Adding dark mode later requires touching every component — it's significantly cheaper to build it in from the start.

**Implementation approach:**

1. Define all colors as CSS custom properties in `:root` and `.dark`
2. Use Tailwind's `dark:` prefix for overrides
3. If using shadcn/ui, this is already set up — just configure the theme in `globals.css`
4. Toggle with a class on `<html>` element: `document.documentElement.classList.toggle('dark')`
5. Respect system preference with `prefers-color-scheme` media query, but let users override
6. Persist preference in `localStorage`

**What changes beyond swapping background/text colors:**

- Shadows: reduce opacity significantly or remove entirely. Dark surfaces don't cast visible shadows — use subtle borders or lighter surface colors to create elevation instead.
- Borders: increase visibility. Use `border-border` (which maps to a lighter value in dark mode) rather than hardcoded colors.
- Images and illustrations: reduce brightness slightly (`brightness-90`). Avoid pure-white images on dark backgrounds.
- Status colors: adjust saturation down and lightness up. A red that works on white won't work on dark gray — it needs to be softer.
- Hover states: use `hover:bg-muted` rather than hardcoded opacity changes. Light mode hovers darken, dark mode hovers lighten.
- Focus rings: ensure visibility on dark backgrounds. Default blue rings work; custom colored rings may not.

## Common Mistakes

| Mistake | What to do instead |
|---|---|
| Building a custom component library from scratch | Use shadcn/ui. Customize after shipping. |
| Only implementing the success state | Build all five states (loading, empty, error, success, overflow) for every data component |
| Using spinners everywhere | Skeleton loaders for inline content, spinners only for page-level or button loading |
| Fixed layouts that don't respond to screen size | Mobile-first responsive with Tailwind breakpoints, test at 375px width |
| Hiding critical actions in dropdown menus | Primary actions get dedicated buttons, only secondary/tertiary go in menus |
| Pixel-perfect custom breakpoints | Use Tailwind's standard breakpoints — they cover real devices |
| Dark mode as an afterthought | Decide at project start: implement now or explicitly defer. Don't half-implement. |
| Tables on mobile with horizontal scroll only | Transform tables into card layouts on mobile, showing key data points |
| Modals on top of modals | One modal at a time. Use sheets/slide-outs for secondary actions from a modal. |
| Inconsistent spacing between sections | Pick a page section gap and stick with it: `space-y-8` for page sections, `space-y-4` within sections |