Dashboard Layout Builder

---
name: dashboard-layout-builder
description: Use when generating a B2B app dashboard layout — sidebar nav, header, KPI cards, table, charts. Triggers on "dashboard layout", "admin dashboard", "app shell", "settings dashboard".
---

# Dashboard Layout Builder

Generate a dashboard shell that looks credible on day one. Most dashboards start great and decay because new sections get bolted on without a layout system. Build the system first.

## Required inputs

1. **App purpose** — analytics, CRM, billing, settings, observability — drives the content blocks
2. **Navigation structure** — top-level sections (4-8), sub-sections per section
3. **Top KPIs** — 3-5 metrics that should be visible at a glance
4. **Primary content** — table? chart? feed? list of items?
5. **User menu items** — profile, settings, billing, sign out
6. **Framework** — React (default), Vue, vanilla

## Output format

A single component file (or set: Layout, Sidebar, Header, KpiCard, DataTable). Tailwind styling. Real semantic HTML — `<aside>`, `<header>`, `<main>`, `<nav>`.

## Layout structure

```
┌─────────────────────────────────────────┐
│ Header (sticky)                         │
├──────────┬──────────────────────────────┤
│          │                              │
│ Sidebar  │  Main content                │
│ (sticky) │  - Page header               │
│          │  - KPI cards                 │
│          │  - Charts                    │
│          │  - Table                     │
│          │                              │
└──────────┴──────────────────────────────┘
```

### Sidebar (`<aside aria-label="Primary">`)
- Width `w-64` desktop, collapsible to `w-16` icon-only
- Logo at top, then nav sections, account/team switcher at bottom
- Active route: `bg-gray-100` + accent left border (`border-l-2 border-indigo-600`)
- Mobile: off-canvas behind overlay, triggered by hamburger
- Icons from `lucide-react` or `heroicons` — 20px

### Header (`<header class="sticky top-0 z-10 bg-white border-b">`)
- Left: page title or breadcrumb (`<nav aria-label="Breadcrumb">`)
- Center: search (cmd-k pattern — `<dialog>` or Radix dialog)
- Right: notifications bell, user avatar dropdown
- Height `h-14` (56px)

### Main content (`<main>`)
- Page header with title, subtitle, primary action (top-right)
- KPI row: `grid md:grid-cols-2 lg:grid-cols-4 gap-4`
- Chart section (if applicable)
- Table or list

## KPI card pattern

```
<div class="rounded-lg border bg-white p-5">
  <div class="flex items-center justify-between">
    <p class="text-sm font-medium text-gray-500">Active users</p>
    <span class="inline-flex items-center text-xs text-green-600">
      <ArrowUp class="h-3 w-3" /> 12.4%
    </span>
  </div>
  <p class="mt-2 text-3xl font-semibold tracking-tight text-gray-900 tabular-nums">
    8,492
  </p>
  <p class="mt-1 text-xs text-gray-500">vs. last 30 days</p>
</div>
```

`tabular-nums` is critical — fixed-width digits prevent jumping when numbers update.

## Data table pattern

- Sticky header (`<thead class="sticky top-0 bg-gray-50">`)
- `<tbody class="divide-y divide-gray-200">` — clean rows
- Numbers right-aligned, text left-aligned, status pills as the third visual treatment
- Sortable: `<th aria-sort="ascending|descending|none">` — accessible sort
- Empty state: full-width row with icon + helper text + CTA
- Loading state: skeleton rows, not a spinner that overlays

For 100+ rows: virtualize (`@tanstack/react-virtual`). Don't render 10k rows.

## Charts

Don't draw charts inline — placeholder them. Recommend:
- `recharts` for React (declarative, decent defaults)
- `@tremor/react` if you want shadcn-style chart components
- `echarts` for power features
- `d3` only if you really know d3

Chart shell:
```
<div class="rounded-lg border bg-white p-5">
  <header class="flex items-center justify-between">
    <h3 class="text-sm font-medium text-gray-900">Weekly revenue</h3>
    <select>...</select>
  </header>
  <div class="mt-4 h-64">
    {/* chart here */}
  </div>
</div>
```

## Responsive

- `< 768px`: sidebar off-canvas, KPIs stack to 1 column, table becomes a card list
- `768-1024px`: sidebar collapsible, KPIs in 2 cols
- `> 1024px`: sidebar fixed open, KPIs in 4 cols, full table

## Accessibility

- `<nav aria-label="Primary">` and `<nav aria-label="Breadcrumb">` — distinguish multiple navs
- Active sidebar item: `aria-current="page"`
- Skip link: "Skip to main content" hidden until focused
- User menu: `<menu>` semantics or Radix `DropdownMenu` (handles keyboard for free)
- Cmd-K palette: focus-trapped `<dialog>` with proper labels
- Tables: `<caption>` (visually hidden) describing the data
- Loading skeletons: `aria-busy="true"` on the parent until loaded

## Dark mode

If supported: design two color sets, use `dark:` Tailwind classes, persist preference to localStorage. Default tokens:
- Background: `bg-white dark:bg-gray-950`
- Borders: `border-gray-200 dark:border-gray-800`
- Body text: `text-gray-900 dark:text-gray-100`
- Muted: `text-gray-500 dark:text-gray-400`

## Anti-patterns

- **Sidebar with 12 top-level items**: hierarchy is broken. Group into 5-7 sections.
- **Cards with `shadow-2xl` everywhere**: dated. `border` + subtle `shadow-sm` is the modern look.
- **Pie charts for trend data**: bar/line charts; pies are for parts-of-whole at a single point in time.
- **Spinner over the whole dashboard on load**: skeleton each region instead.
- **Tables with horizontal scroll on mobile**: become card lists below `md`.
- **Absolute-positioned sidebar that breaks zooming**: use sticky + flex.

## Output

Return the layout component(s) + KPI card + table example. Top comment lists:
- Sections built
- Breakpoint behavior
- Charting library recommendation (or "stubbed — pick one")
- A11y notes (nav labels, breadcrumb, skip link, sort semantics)