---
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, propose a `*-board` section in the menu (or reuse an existing one)
and create a SmartKanban screen.

## What to produce

```markdown
### SCR-HR-LEAVE-BOARD-001 — Tableau des demandes de congé (SmartKanban)
- **Entité** : LeaveRequest (ENT-008)
- **Permission** : `hr.leave.read`
- **Cas d'usage liés** : UC-HR-LEAVE-BOARD-001, UC-HR-LEAVE-BOARD-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`.

## 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 tokens. 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 generated `KanbanBoard.tsx` moves a card between columns and calls a
status-update API on drop. When the workflow has guards ("only the approver can
move submitted → approved"), document those as **business rules** of category
`workflow` (`/ba-create-business-rules`) — the runtime evaluates them and
disables the drop accordingly.

## Pairing with other screens

A kanban almost always 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).
