---
phase: screens
kind: level
level: kanban
---

# Level — Kanban screens (SmartKanban)

Use this level when an entity has a **workflow lifecycle** — a status enum with
at least 3 distinct states the user transitions between (draft → submitted →
approved → done, etc.).

## When to use

Trigger words: "kanban", "board", "workflow", "pipeline", "swimlane",
"approval flow", "tableau", "flux", "approbation".

**Mandatory** when (post-check rule 10):
- An entity has a `status` enum attribute with **≥3 options**.
- The entity does NOT belong to a portal / read-only module.
- No SmartKanban exists yet for this entity.

In that case, add a **second screen** — a SmartKanban — to the entity's existing
`*-list` section, **alongside** its SmartListView. The board reuses that section,
its permission and its entity; only the layout differs — it renders as the
`kanban` viewMode of the SAME list page (a Table ⇄ Kanban toggle, one route,
one FilterBar), never as a separate `/…/list/kanban` route. **Never create a
`*-board`/`*-workflow`/`*-pipeline` section**
(see `create-menu/levels/sections.md`).

## What to produce

The board is the **second** screen (`-002`) of the entity's `leave-list` section —
the SmartListView is `SCR-HR-LEAVE-LIST-001`, and the kanban reuses its `entity`
and `permission`:

```markdown
### SCR-HR-LEAVE-LIST-002 — Tableau des demandes de congé (SmartKanban)
- **Entité** : LeaveRequest (ENT-008)
- **Permission** : `hr.leave.read`
- **Cas d'usage liés** : UC-HR-LEAVE-LIST-001, UC-HR-LEAVE-LIST-002
- **Champ statut** : status
- **Colonnes** : draft (Brouillon, gray), submitted (Soumis, blue), approved (Approuvé, green), rejected (Refusé, red)
- **Carte** : titre = code, sous-titre = employeeName, champs = startDate, endDate, days
- **Navigation** : clic carte → SCR-HR-LEAVE-DETAIL-001
```

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

> **Downstream (PRD)**: this block stays the AUTHORED form, but it produces
> **no pagespec of its own** — `/ba-create-prd` (via `derive-kanban-spec`)
> folds it into the section's LIST pagespec as the first-order `kanban` block
> + `viewModes: [..., "kanban"]`, exactly like the SmartCard/cards folding
> (PRD-117). One route, one FilterBar: the board shares the list's filters,
> search, segments and URL state by construction. Column keys are re-anchored
> VERBATIM on the entity's status enum (`entité.md`) — author them as the enum
> values, not as labels.

## Column color guidance

| Status semantic         | Color    |
|-------------------------|----------|
| draft / pending         | `gray`   |
| submitted / in progress | `blue`   |
| approved / completed    | `green`  |
| rejected / cancelled    | `red`    |
| under review / on hold  | `orange` |

The generator maps these to design-token families — the SSOT of the mapping is
`lib/page-spec-kanban.ts` (`KANBAN_COLOR_FAMILY`: gray→neutral, blue→info,
green→success, red→error, orange→warning; never a hex). Stick to the table —
invented colors are ignored.

## Card content rules

- The title field is mandatory — pick the natural identifier (`code`, `title`).
- The subtitle is optional — pick the most-cited related entity name
  (`employeeName`, `customerName`, `assigneeName`).
- 2 to 4 card fields below the title — keep them short. Dates, numbers and short
  status fields work best.

## Drag-and-drop semantics — the workflow rules GOVERN the board

The generated board (the `kanban` viewMode of the list page) moves a card
between columns and posts the status change through the `move` action. The
governance chain is deterministic, end to end:

1. Author the transition graph as **business rules** of type `workflow` (or
   `state-transition`) with a `- **Flow**` block
   (`/ba-create-business-rules`): `draft → submitted (by: …, guard: …)`.
   The Flow tokens MUST be the entity's status enum values verbatim.
2. `/ba-create-prd` (`derive-kanban-spec`) projects the Flow edges into
   `kanban.transitions[]` on the list pagespec — a rule whose tokens don't
   map onto the enum is reported, never silently dropped into an open matrix.
3. The generated board inlines the matrix (`ALLOWED_TRANSITIONS`): while
   dragging, columns outside the allowed targets REFUSE the drop (visually
   dimmed, `aria-disabled`); columns with no outgoing edge are terminal —
   their cards are not draggable at all.
4. scaffold-business compiles the SAME matrix into the `move` service guard:
   a forged POST with a non-allowed transition throws with the rule's
   `Code d'erreur`. Front and back read one projection — they cannot drift.

No workflow rules → open matrix (any drop allowed, if a `move` action exists).
An explicit `transitions: []` on the pagespec makes the board read-only.

## Pairing with other screens

A kanban is **always authored as a second screen in the entity's `*-list` section**,
never its own. It coexists with:
- A `SmartListView` in the same `*-list` section (for power users who prefer the
  table layout).
- A `SmartForm` in a `*-detail` section (clicking a card opens the form) — name
  that form as the card click target.

## Common mistakes

- **Fewer than 2 columns** → invalid board.
- **A status field that does not match an entity attribute** → fails post-check
  rule 7.
- **More than 4 card fields** → overflows the card visually.
- **Used for a portal module** → portals are read-only; the kanban is wasted.
- **Missing for a workflow entity** → fails post-check rule 10 (a highly visible
  warning).