---
phase: screens
kind: level
level: dashboard
---

# Level — Dashboard screens (SmartDashboard)

Use this level when the user wants a **summary**, **KPIs**, **metrics**, or
**charts** for a module — typically the entry point of a back-office area or a
standalone analytics page.

## When to use

Trigger words: "dashboard", "overview", "metrics", "KPIs", "summary",
"tableau de bord", "vue d'ensemble", "indicateurs".

Mandatory when:
- The section code ends in `-dashboard`, `-overview`, `-summary`.
- The bound use cases are read-only and aggregate-driven ("monitor", "track",
  "see how many", "review").

Use `SmartDashboard` for **free-form analytics**. For a **navigational landing
page** (app/module/section launchpad with quickLinks), use the home types
instead (`levels/home-screens.md`).

## Special rule — entity is optional

`SmartDashboard` is the **only** screen type that may omit the screen-level
entity. Each widget targets its own entity instead.

## What to produce

```markdown
### SCR-HR-EMPLOYEES-ANALYTICS-001 — Vue d'ensemble RH (SmartDashboard)
- **Entité** : — (chaque widget porte la sienne)
- **Permission** : `hr.employees.read`
- **Cas d'usage liés** : UC-HR-EMPLOYEES-ANALYTICS-001
- **Widgets** :
  - active — Employés actifs (kpi, Employee, count, `status=active`, col 3)
  - onLeave — En congé (counter, Employee, count, `status=onLeave`, col 3)
  - newHires — Embauches 30j (counter, Employee, count, `hireDate>30d`, col 3)
  - totalDepts — Départements (kpi, Department, count, col 3)
  - byDept — Par département (chart-pie, Employee, `department.name`, col 6)
  - hireTrend — Embauches/mois (chart-line, Employee, `hireDate`, col 6)
  - recentLeaves — Congés récents (list, LeaveRequest, col 12, `hr.leave.read`)
```

The exact widget config-as-data shape is in `references/smartcomponents.md`.

## Choosing widgets

A good dashboard has 4 to 8 widgets:

1. **Top row** — 3-4 KPI/counter widgets answering the user's daily question
   ("how many active? how many issues? how many waiting?").
2. **Middle row** — 1-2 chart widgets showing trends and breakdowns.
3. **Bottom row** — 1 list widget for the most recent/urgent items (a teaser
   into the deeper module).

Use `col` (12-column grid) to size widgets: KPI cards `col 3` (4/row), charts
`col 6` (2/row) or `col 12`, lists `col 12`.

## Widget types

| Type         | Purpose                              | Required props          |
|--------------|--------------------------------------|-------------------------|
| `kpi`        | A big number with a label            | entity, aggregation     |
| `counter`    | KPI with a trend arrow               | entity, aggregation     |
| `chart-line` | Time series                          | entity, field (date)    |
| `chart-bar`  | Categorical breakdown                | entity, field           |
| `chart-pie`  | Proportional breakdown               | entity, field           |
| `list`       | Top-N rows of an entity              | entity                  |

## Aggregation expressions

Allowed aggregations: `count | sum | avg | min | max`.

- KPI/counter: `field` may be a filter expression (`status=active`, `hireDate>30d`).
- Charts: `field` is the grouping attribute (`department.name`, or `hireDate`
  for a time series).

## Permissions per widget

Each widget may declare its own permission. When set, the widget is hidden if
the actor lacks it — use this for cross-module dashboards (a payroll widget on
the HR dashboard requiring `payroll.read`).

## Common mistakes

- **No entity at the widget level** → nothing to aggregate.
- **More than ~10 widgets** → cognitive overload; split into two dashboards.
- **All widgets `col 12`** → wastes vertical space; mix sizes.
- **Charts with no meaningful `field`** → the breakdown is meaningless.