# Pattern: Dashboard

## Intent

A Dashboard provides an at-a-glance overview of key system metrics. Use it as the home or overview page of any management application. The pattern combines KPI stat cards, charts, and activity feeds in a structured grid layout.

---

## When to Use

- As the first page after login in management applications
- When the user needs to monitor multiple metrics simultaneously
- For executive or operational overview screens

---

## Anatomy

```
┌────────────────────────────────────────────────────────┐
│  Page Header: Title + CTA Button (e.g., "Download Report")
├────────────────────────────────────────────────────────┤
│  Stats Row: 4 KPI Cards (grid-cols-4 lg)               │
├───────────────────────────────┬────────────────────────┤
│  Chart Panel (col-span-4)     │ Activity Feed (col-3)  │
└───────────────────────────────┴────────────────────────┘
```

---

## Full Pattern Code

```tsx
import { Card, CardContent, CardHeader, CardTitle, Badge, Button, StatsCard } from 'xertica-ui/ui';
import { Users, DollarSign, Activity, TrendingUp } from 'lucide-react';

export function DashboardPage() {
  return (
    <div className="flex flex-col gap-6 p-6 w-full max-w-[1400px] mx-auto">
      {/* 1. Page Header */}
      <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
        <div>
          <h1 className="text-2xl font-bold tracking-tight">Dashboard</h1>
          <p className="text-muted-foreground">System overview</p>
        </div>
        <Button>Download Report</Button>
      </div>

      {/* 2. KPI Stats Row */}
      <div className="grid gap-4 grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">
        <StatsCard
          title="Total Revenue"
          value="$45,231.89"
          trend="+20.1%"
          icon={<DollarSign className="size-4 text-muted-foreground" />}
        />
        <StatsCard
          title="Active Users"
          value="+2,350"
          trend="+180 this month"
          icon={<Users className="size-4 text-muted-foreground" />}
        />
        <StatsCard
          title="Sales"
          value="+12,234"
          trend="+19% vs last month"
          icon={<Activity className="size-4 text-muted-foreground" />}
        />
        <StatsCard
          title="Retention Rate"
          value="89.3%"
          trend="+1.2%"
          icon={<TrendingUp className="size-4 text-muted-foreground" />}
        />
      </div>

      {/* 3. Chart + Feed Panel */}
      <div className="grid gap-4 grid-cols-1 lg:grid-cols-7">
        {/* Chart — takes 4 of 7 columns */}
        <Card className="col-span-1 lg:col-span-4">
          <CardHeader>
            <CardTitle>Overview</CardTitle>
          </CardHeader>
          <CardContent className="h-[350px]">
            {/* Mount a Recharts BarChart / LineChart here */}
            <div className="flex h-full w-full items-center justify-center rounded-md border border-dashed bg-muted/20 text-muted-foreground">
              Chart Area
            </div>
          </CardContent>
        </Card>

        {/* Activity Feed — takes 3 of 7 columns */}
        <Card className="col-span-1 lg:col-span-3">
          <CardHeader>
            <CardTitle>Recent Events</CardTitle>
          </CardHeader>
          <CardContent>
            <div className="space-y-4 text-sm">
              <div className="flex items-center gap-4">
                <Badge variant="outline">09:00</Badge>
                <span>John Smith logged in</span>
              </div>
              <div className="flex items-center gap-4">
                <Badge variant="outline">10:45</Badge>
                <span>Invoice #INV004 paid</span>
              </div>
            </div>
          </CardContent>
        </Card>
      </div>
    </div>
  );
}
```

---

## Composition Rules

1. **KPI cards always use the `StatsCard` pattern**: small title (`text-sm font-medium`), large value (`text-2xl font-bold`), supplementary trend text.
2. **Chart cards always occupy more grid space than feed cards** — use `col-span-4` vs `col-span-3` in a 7-column grid.
3. **Never hardcode pixel widths in grids** — use `lg:grid-cols-4`, `lg:grid-cols-7` with responsive overrides.
4. **Chart placeholder areas** use `border-dashed bg-muted/20` — never leave them blank.
5. **The max-width `max-w-[1400px]`** prevents the content from becoming too wide on large monitors.

---

## Related Patterns

- [Analytics Pattern](./analytics.md) — When you need time-series filtering and comparative views
- [CRUD Pattern](./crud.md) — When the dashboard links to data management pages

## Related Components

- [`Card`](../components/card.md) — Primary container for all dashboard sections
- [`Badge`](../components/badge.md) — Status and timestamp labels
- [`Chart`](../components/chart.md) — Recharts integration for graph areas
- [`StatsCard`](../components/stats-card.md) — Pre-built KPI card component