---
name: Dashboard Screen
description: Design recommendations for dashboard screens with metrics, charts, and actionable insights
---

# Dashboard Screen Design Guidance

When designing dashboard screens, consider the purpose and user needs. Dashboards can serve different functions: monitoring key metrics, analyzing data trends, or enabling quick actions. Choose the appropriate variation based on the primary use case.

## ⚠️ CRITICAL: Dashboard Title & Layout Rules

**1. ONE TITLE ONLY** - Use `ScreenTitle` at the top, then NO additional section headings

- ❌ WRONG: `<ScreenTitle>Dashboard</ScreenTitle>` + `<h2>Efficiency Metrics</h2>` + `<h2>Performance Data</h2>`
- ✅ CORRECT: `<ScreenTitle>Dashboard</ScreenTitle>` with no other titles
- Separate sections using spacing (`space-y-6` or `mb-6`), not titles

**2. Card Usage in Dashboards**

**Cards are frequently overused in dashboards.** Use cards strategically, not as default wrappers:

- ✅ **Use cards for:** Individual metric displays (KPIs - max 6), individual charts
- ❌ **DO NOT use cards for:** DataTables, entire sections, grouping charts, wrapping page content
- **IMPORTANT: Maximum 6 metric cards per dashboard** - Show only the most critical KPIs. Too many metrics reduce focus and impact.
- **For comprehensive card decision framework:** Call `read_skill` with `card-design` before implementing cards
- **Remember:** Not everything on a dashboard needs a card border - use spacing and typography for hierarchy

## Dashboard Variations

### Classic Dashboard (Metrics + Charts + Tables)

The classic dashboard focuses on presenting key information at a glance with a clear visual hierarchy.

1. **Metric Cards at the Top**: Display primary KPIs in card format at the top of the screen. **Show maximum 6 metrics - only the most critical KPIs.** Each metric card should show the metric value prominently (follow number formatting guidelines), include a label describing what the metric represents, and display trend indicators (up/down arrows, percentage changes) when relevant. Arrange in a responsive grid (2 columns on mobile, 3-4 on tablet, 4-6 on desktop). **For detailed metric card patterns and layout strategies, call `read_skill` with `card-design`.**

2. **Chart Components**: Place charts below the metrics to show trends and comparisons. Use appropriate chart types (line for trends, bar for comparisons, pie for distributions), include clear axis labels and legends, and make charts interactive when possible. **Each chart must be wrapped in its own Card + CardContent.** Charts default to `height="100%"` and include a built-in responsive container — pass an explicit height (e.g. `height={400}`) when inside a card, or use `aspect={16/9}` for proportional sizing. Group related charts together using spacing and layout, not by wrapping multiple charts in a single card.

3. **Data Tables**: Include detailed breakdowns in table format below charts. Use sortable columns, pagination or virtual scrolling for large datasets, and make rows clickable to navigate to detail views. **NEVER wrap DataTables in cards** - they need full width for mobile usability.

4. **Layout Structure**: Use a grid-based layout with consistent spacing. Visual hierarchy: metrics (top) > charts (middle) > tables (bottom). Ensure responsive behavior (stack vertically on mobile). **Create hierarchy through spacing and section organization, not by wrapping entire sections in cards.**

### Analytical Dashboard (Deep Data Insights)

The analytical dashboard focuses on exploration, filtering, and multi-dimensional data analysis.

1. **Filtering and Drill-Down**: Include prominent filter controls at the top (date ranges, categories, dimensions). Provide drill-down functionality in charts and tables. Show active filters clearly with ability to remove them, and persist filter state when navigating away.

2. **Interactive Charts**: Enable zooming and panning, support comparison modes (compare periods, compare categories), and allow users to toggle series on/off in multi-series charts.

3. **Date Range Selectors**: Include preset ranges (Today, This Week, This Month, This Year) and allow custom date range selection. Show comparison options (compare to previous period) and display the selected range prominently.

4. **Multi-Dimensional Views**: Allow switching between different data dimensions, provide pivot table capabilities when appropriate, and enable grouping and aggregation options.

5. **Exploration Workflows**: Provide breadcrumbs for navigation through drill-downs, include "Reset" or "Clear Filters" actions, and display data freshness indicators (last updated timestamp).

### Actionable Dashboard (Metrics + Highlights + Navigation)

The actionable dashboard focuses on enabling quick decisions and next steps.

1. **Metrics and Highlights**: Display critical metrics that require attention. Use color coding to indicate status (red for urgent, green for good), highlight anomalies or items requiring action, and show progress toward goals or targets.

2. **Action Cards with Navigation**: Include cards that link to relevant app sections with clear call-to-action buttons. Group related actions together and show action status or completion indicators. Make cards visually distinct from metric cards. **Use the `href` prop on Card for clickable navigation cards (see card-design skill for clickable card patterns).**

3. **Quick Actions and Shortcuts**: Provide frequently used actions prominently, show recent actions or quick links, and display contextual actions based on current state.

4. **Recent Activity or Notifications**: Show recent changes or updates, display notifications or alerts that need attention, and make it easy to dismiss or act on notifications.

5. **Decision-Making Support**: Provide recommendations or suggestions, show priority indicators for tasks, and include context about why actions are needed.

## Common Guidelines

1. **Loading States**: Show loading states when fetching data. Use skeleton screens that match the final layout, display partial data when some metrics load faster than others, and prioritize metric cards over charts. **For loading state card patterns, call `read_skill` with `card-design`.**

2. **Empty States**: Handle cases when there's no data to display. Show helpful messages explaining why there's no data, provide actions to populate data, and avoid showing empty charts or tables without context.

3. **Data Refresh**: Allow users to update dashboard data. Include a refresh button, show auto-refresh indicators when applicable, and display last updated timestamp.

4. **Responsive Layouts**: Stack components vertically on small screens. **IMPORTANT: Metric cards should show 2 columns minimum on mobile (never single-column) — see card-design skill for mobile-first grid patterns.** Simplify tables or use card-based layouts on mobile for data-heavy content.

5. **Visual Consistency**: Use consistent spacing between components, group related metrics and charts visually, apply consistent card styling (use semantic tokens only — see card-design skill), and maintain consistent typography hierarchy.

6. **Visual Hierarchy**: Make the most important information most prominent. Use size, color, and position to establish hierarchy, and balance information density with readability.

## Dashboard Layout Best Practices

### What Gets Wrapped in Cards

✅ **Individual metric displays** - Each KPI metric gets its own card (max 6 total)
✅ **Individual charts** - Each chart wrapped in Card + CardContent
✅ **Isolated info panels** - Standalone supplementary information (rare on dashboards)

### What NEVER Gets Wrapped in Cards

❌ **DataTables** - Need full width, already have internal structure
❌ **Multiple charts together** - Each chart gets its own card; group using grid/spacing
❌ **Entire dashboard sections** - Use spacing and typography for section separation
❌ **Filter toolbars** - Already have their own visual structure
❌ **Section headers** - Use ScreenTitle and spacing, not card containers

### Creating Visual Hierarchy Without Cards

Instead of wrapping everything in cards, use:

- **Spacing:** `space-y-6` or `space-y-8` between sections
- **Typography:** Section titles with `text-lg font-semibold mb-4`
- **Grid gaps:** `gap-4` or `gap-6` to separate items
- **Background colors:** Only when semantic meaning is needed (e.g., warning banners)

### Example: Good Dashboard Structure

```tsx
<ScreenWrapper className="space-y-6">
  {/* ONE TITLE ONLY - no additional section headings */}
  <ScreenTitle title="Sales Dashboard" />

  {/* Metric cards - MAX 6 KPIs, each in its own card */}
  <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
    <Card><CardContent><CardDescription>Revenue</CardDescription><CardTitle size="lg">$45,231</CardTitle></CardContent></Card>
    <Card><CardContent><CardDescription>Orders</CardDescription><CardTitle size="lg">1,482</CardTitle></CardContent></Card>
    <Card><CardContent><CardDescription>Customers</CardDescription><CardTitle size="lg">892</CardTitle></CardContent></Card>
    <Card><CardContent><CardDescription>Conversion</CardDescription><CardTitle size="lg">3.2%</CardTitle></CardContent></Card>
    {/* Max 6 metrics - only the most important KPIs */}
  </div>

  {/* Each chart in its own card */}
  <Card><CardContent><AreaChart height={400} ... /></CardContent></Card>
  <Card><CardContent><BarChart height={400} ... /></CardContent></Card>

  {/* Table - NO section title, NO card wrapper, spacing separates it */}
  <DataTable data={...} columns={...} />
</ScreenWrapper>
```

**Key principles:**

- **ONE title per dashboard** - Use ScreenTitle only, no section headings
- Cards are for **individual items** (metrics, charts), not for **grouping sections** or **layout organization**
- **Maximum 6 metric cards** - Focus on the most critical KPIs only
- Use **spacing** to separate sections, not titles or card wrappers