# Home dashboard

Show a person what needs them and what happened since they were last here.

For: Everyone, as the first page they see on each visit.

Web page: https://candor.themethodic.com/screens/home-dashboard

Running example on sample data: https://candor.themethodic.com/apps/workspace

## Layouts

### Dashboard home

Pick it when: The default for a product with figures worth watching: what needs the person first, then the numbers, then what happened. A report people study is the reports and dashboards screen; this is the page they glance at.

Layout: A greeting with when the data was read, the needs-you line under it, a row of stat cards, a score ring beside its subscore tiles, and the activity below.

Items:

- **Page header** (`page-header`, free; https://candor.themethodic.com/docs/page-header.md): The greeting and where the person is, with the freshness stamp in its actions.
- **Freshness stamp** (`freshness-stamp`, Pro; https://candor.themethodic.com/docs/freshness-stamp.md): When the figures were read, or that they never were.
- **Needs you line** (`needs-you-line`, Pro; https://candor.themethodic.com/docs/needs-you-line.md): One sentence: how many things need the person, linked to them; nothing to do, only when it's known; and when the count couldn't be checked, why.
- **Stat card** (`stat-card`, Pro; https://candor.themethodic.com/docs/stat-card.md): One figure each: its value, its change against a named period and a small trend; a figure that couldn't be computed says why.
- **Score ring** (`score-ring`, Pro; https://candor.themethodic.com/docs/score-ring.md): A score out of its maximum, saying when it was computed and from what, with any projection drawn apart.
- **Subscore card** (`subscore-card`, Pro; https://candor.themethodic.com/docs/subscore-card.md): The parts of the score as tiles, each with its tone in a word and its findings counted.
- **Timeline item** (`timeline-item`, Pro; https://candor.themethodic.com/docs/timeline-item.md): One thing that happened, with who did it and when.
- **Dashboard grid** (`dashboard-grid`, Pro; https://candor.themethodic.com/docs/dashboard-grid.md): Lays the cards out by the page's own width.

```bash
npx candor-ui add page-header freshness-stamp needs-you-line stat-card score-ring subscore-card timeline-item dashboard-grid
```

### Quiet home

Pick it when: A product with little to measure, or a person who only acts on requests: say what needs them and what happened, nothing more.

Layout: A greeting, the needs-you line, and the activity since the last visit as one list.

Items:

- **Page header** (`page-header`, free; https://candor.themethodic.com/docs/page-header.md): The greeting and where the person is.
- **Needs you line** (`needs-you-line`, Pro; https://candor.themethodic.com/docs/needs-you-line.md): One sentence: how many things need the person, linked to them, or why it couldn't be checked.
- **Timeline item** (`timeline-item`, Pro; https://candor.themethodic.com/docs/timeline-item.md): One thing that happened, with who did it and when.

```bash
npx candor-ui add page-header needs-you-line timeline-item
```

### Phone column

Pick it when: Narrow screens: one column, read from the top, with the places on a tab bar.

Layout: One column: the needs-you line, the figures two by two, the score, then the activity, over a tab bar.

Items:

- **Needs you line** (`needs-you-line`, Pro; https://candor.themethodic.com/docs/needs-you-line.md): The first thing read: how many things need the person, or why it couldn't be checked.
- **Stat card** (`stat-card`, Pro; https://candor.themethodic.com/docs/stat-card.md): The figures, two by two.
- **Score ring** (`score-ring`, Pro; https://candor.themethodic.com/docs/score-ring.md): The score, saying when it was computed and from what.
- **Timeline item** (`timeline-item`, Pro; https://candor.themethodic.com/docs/timeline-item.md): What happened, newest first.
- **Tab bar** (`tab-bar`, Pro; https://candor.themethodic.com/docs/tab-bar.md): The places at the bottom of the screen, an urgent count read in the name.

```bash
npx candor-ui add needs-you-line stat-card score-ring timeline-item tab-bar
```

## Rules that matter most here

- **Unknown stays unknown** (https://candor.themethodic.com/principles#unknown-stays-unknown): The needs-you line says when it couldn't check, never "nothing needs you" in its place. An estimate is called an estimate, in words. A score says when it was computed and from what.
- **The agent is always named, by the app** (https://candor.themethodic.com/principles#agents-are-named): Each line of activity names the agent that did it, from the app's records, not from what a model wrote.

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build the home page with Candor UI: a PageHeader with a greeting and a FreshnessStamp in its actions, then NeedsYouLine, a KpiRow of StatCard figures, a ScoreRing beside a SubscoreCard of tiles, and the activity as TimelineItem rows.
This is the page people glance at on arrival; a report they study is a different screen (reports and dashboards).
Give NeedsYouLine the same count the navigation's urgent badge shows, from one source, scoped the same; when the count couldn't be checked, pass null with the reason.
Each StatCard names the period its change is against; a figure that couldn't be computed is null with why, never zero.
Say an estimate is an estimate in its label or value text, with what it's based on.
Give ScoreRing when it was computed and what it's computed from, and make its score the weighted mean of the SubscoreCard tiles' scores, each tile counting by its weight as /apps/workspace computes it: not their sum, and not a plain mean.
Name the agent on each TimelineItem from your records.
Lay a set of cards out with DashboardGrid and a minTileWidth, as /apps/workspace does for its workspace cards, so they follow the page's width; the figures sit in a KpiRow. On a phone the page is one column.

Start from the "Dashboard home" layout: A greeting with when the data was read, the needs-you line under it, a row of stat cards, a score ring beside its subscore tiles, and the activity below.
Candor items: page-header (https://candor.themethodic.com/docs/page-header.md), freshness-stamp (https://candor.themethodic.com/docs/freshness-stamp.md), needs-you-line (https://candor.themethodic.com/docs/needs-you-line.md), stat-card (https://candor.themethodic.com/docs/stat-card.md), score-ring (https://candor.themethodic.com/docs/score-ring.md), subscore-card (https://candor.themethodic.com/docs/subscore-card.md), timeline-item (https://candor.themethodic.com/docs/timeline-item.md), dashboard-grid (https://candor.themethodic.com/docs/dashboard-grid.md).
Install: npx candor-ui add page-header freshness-stamp needs-you-line stat-card score-ring subscore-card timeline-item dashboard-grid
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```