# Team Leader (Web) — Dev-mode v1.0 design pack

> **Slot 6 of the dev-mode v1.0 series — Step 3b, first of the 6 packs mirrored off the ANCHOR** (`staff-court-monitor-mobile`). Built 2026-06-18.
> **This pack covers Team Leader AND Trainee Team Leader** — one pack serves both: identical **nav + screens**, but per **CL-3** the Trainee TL is **assist-only** (Approve / Send-back / Route disabled — see "Trainee TL = assist-only" below; amends `PROJECT_PLAN §9 #4`). The TL is the **first approver above the filler** in the cascade (`FOUNDATION_SPEC §4`).
> **Persona:** **Priya Nair** · Team Leader (`TL`) in Game Zone **Ahmedabad-1**. Reports to Rohit Shah (Store Manager). Her team: Ramesh Kumar (Staff Court Monitor), Karan Patel (Senior Court Monitor), Suresh Rao (Cleaning Supervisor). Trampoline + Toddler Zone certified (can also fill).
> **Platform:** **Web (Next.js admin/manager panel) — 1440×900 baseline.** Web is this role's surface for this pack. TL is a dual-surface role (`SCREEN_LIST` marks TL `Both`); the **TL mobile companion is produced in the mobile sub-phase** — this pack is the web pixel target.
> **Chrome:** Maniax web shell per `DESIGN_SYSTEM §8.1` — navy **240px** sidebar (data-driven from `/me`) + 64px sticky topbar (branch badge + team indicator) + content well. Desktop **modals** (not bottom-sheets) for send-back-reason, assign, publish, photo viewer.

---

## What's in this pack

| File / folder | What |
|---|---|
| `README.md` | You are here — slot scope, persona, sidebar, out-of-slot. |
| `SCREENS.md` | Full web screen inventory (the FE burn-down checklist) with states/modals per screen. |
| `spec.md` | Per-screen acceptance detail (Given/When/Then) — verify/approve, send-back-to-filler, fill-as-TL, team-scoped roster, RBAC scope. |
| `api-contract.md` | Every endpoint this role consumes (`Method \| Path \| Roles \| Body \| Returns`) — incl. the **approve / send-back** endpoints the anchor pack did NOT have. |
| `HANDOFFS.md` | Cross-role touchpoints — TL receives submissions from fillers, approves up to SM, sends back to the original filler. |
| `flows/` | `verify-and-approve.md`, `send-back-to-filler.md` — multi-step walkthroughs. |
| `screens/` | Self-contained HTML mockups (web 1440×900) — the pixel target. |
| `states/` | loading / empty / error / forbidden(403) / locked / offline + **trainee-tl-assist-only** (CL-3) state variants. |
| `modals/` | send-back-reason · photo-viewer (lightbox) · assign-checklist · publish-roster confirm · **route-to-maintenance** (CL-2) · **reassign-monitor** (CL-4). |
| `handoff/README.md` | Definition of Done + blocking questions for this slot. |
| `handoff/tasks.md` | Task rows: Screen ID, file, states/modals, dependencies, Web-FE + Backend tasks, priority. |

## How to read this pack

1. Start with **`SCREENS.md`** — the bird's-eye of the 10 TL screens + auth entry + profile.
2. Use **`handoff/README.md`** DoD as your tick-list.
3. For each screen, read its **`spec.md`** section + the relevant **`flows/`** walkthrough + the **`api-contract.md`** rows.
4. Use **`HANDOFFS.md`** when wiring the verify→approve / send-back touchpoint (the TL is the **consumer** of the anchor's submit producer-side contract).
5. Open any `screens/*.html` in a browser at 1440px width to see the visual contract.

## Sidebar (7 nav items, 2 groups — `DESIGN_SYSTEM §7`)

> Trainee TL = **identical nav** (same screens) but **assist-only** rights (CL-3 — see below). Utility cluster (Notifications · Profile · Settings · Logout) + user chip are appended to every web sidebar.

| Group | Item | Lucide | Target screen |
|---|---|---|---|
| OVERVIEW | Dashboard | `layout-dashboard` | `TL-DASH` |
| OVERVIEW | My Team | `users` | `TL-TEAM` → `TL-USER-DETAIL` |
| OPERATIONS | Roster | `calendar-days` | `TL-ROSTER` → `TL-ROSTER-VIEW` / **Mid-Shift Reassign** (`TL-ROSTER-REASSIGN`, CL-4) |
| OPERATIONS | Checklists | `list-checks` | `TL-CHK-OVERVIEW` → Verify [+ **Route to Maintenance**, CL-2] / Assign / Fill |
| OPERATIONS | **Upload Check List** *(CL-1)* | `clipboard-list` | `TL-CHK-UPLOAD` (team-scoped builder) |
| OPERATIONS | Reports | `bar-chart-3` | `TL-REP-NEGATIVE` |
| OPERATIONS | Fill Checklist | `clipboard-check` | `TL-CHK-FILL` |

> **Topbar:** non-interactive **branch badge** (`Game Zone · Air Maniax Ahmedabad-1`) + a **team indicator** (`My Team · 3`) — TL is locked to one Game Zone and to their own team within it (`§4c`, `§5`). No Game-Zone selector (that is OH-only). The `TL-CHK-VERIFY` queue is reached from the Checklists overview; `TL-CHK-FILL` has its own nav item because TL may also fill.

## Change List v1.1 amendments applied to this pack

- **CL-1 — Upload Check List (team-scoped):** new sidebar item + `TL-CHK-UPLOAD` screen. A **team-scoped subset** of the `ChecklistBuilder` (`DESIGN_SYSTEM §6.21`): create/assign/edit templates that fill within the TL's **own team + Game Zone** only (branch / GZ-wide authoring stays with SM/OH). Stepper: Details → Sections & Items → Assign (role/ride/shift) → Review.
- **CL-2 — Route A-item → Maintenance + single-track Hold:** `TL-CHK-VERIFY` gains a **Route to Maintenance** action per A-item (spawns a `WorkOrder` to the Maintenance TL) and a **HeldBanner** (`DESIGN_SYSTEM §6.24`, `st-held` deep-orange `#C2410C`). While ≥1 A-item work-order is open the checklist is **HELD** — **Approve is locked** and cannot reach Done until **every** A-item is resolved (fixed/closed). There is no parallel "approve while actions pending" track (`FOUNDATION_SPEC §4 / §4a`). Held also surfaces on `TL-DASH` (Actions-held KPI + Held queue row) and `TL-CHK-OVERVIEW`.
- **CL-4 — Mid-shift reassign:** new `TL-ROSTER-REASSIGN` screen (AllocationBoard, `DESIGN_SYSTEM §6.23`). The TL re-targets a monitor to a different ride mid-shift; on save the new ride's **not-started** checklists auto-assign to the monitor, the old ride re-targets to its current holder, and both monitors' mobile `*-CHK-TODAY` update **live** (ride-changed banner). **In-progress / submitted** instances are never withdrawn (`FOUNDATION_SPEC §3a`). Certified-on-new-ride is gated.

### Trainee TL = assist-only (CL-3)

> Amends `PROJECT_PLAN §9 #4` (which previously gave Trainee TL identical rights). A **Trainee Team Leader** has the **same nav and the same screens** as a full TL — but the **Approve / Send-back / Route-to-Maintenance** actions are **disabled** (read/assist subset). Only a full Team Leader decides.

- The disabled state is driven by **RBAC**, not hardcoded UI: the `/me` resolver returns `checklist.approve = allowed:false` (and the route grant off) for the Trainee role; the app renders the buttons disabled. No `if role==='TRAINEE_TL'` branching.
- Documented as a dedicated variant: **`states/trainee-tl-assist-only.html`** (the verify screen with the three actions disabled + an assist-only banner) and a callout in `TL-CHK-VERIFY` + `TL-DASH`.
- Everything else (review items/photos, fill, roster view, reports, upload-list view) remains available so the trainee can assist.

## Hard constraints (re-affirmed)

- **Web 1440×900.** Navy 240px sidebar + 64px topbar + content well (`DESIGN_SYSTEM §8.1`). Desktop **modals / right-drawer**, never bottom-sheets.
- **Design tokens:** Maniax palette (`#F58220` orange / `#ED1C24` red / `#2E6DB4` blue / `#16284A` navy / `#7FB2E5` light-blue), **DM Sans**, **navy-on-orange** primary buttons, **green Approve / red Send-back** (action color = outcome color, `§6.4`), light-blue as fill-only. Per `DESIGN_SYSTEM.md`.
- **G is always green, A is always red-orange** everywhere (toggle, badge, item row, report). Status by label+icon+color, never color alone.
- **Approve / Send-back semantics:** Approve = `success` green; Send-back = `brand-red` (reason **required**). Send-back returns to the **original filler** (not the previous approver, `§9 #3`); after re-fill the cascade **restarts from TL** (`§9 #8`).
- **Derived Pending continues above TL:** once TL approves, the instance reads **Pending** to SM/OH until they each clear it (`§9 #5`); the TL sees the **real sub-state** (TL Approved / SM Approved / Done) on their own overview.
- **Online-only.** Network failure → "No connection — retry"; entered draft (reason text, fill responses) held in memory + re-POSTed on retry. No offline DB.
- **Dynamic RBAC.** Sidebar + permissions render from the `/me` response — no hardcoded role logic. TL sees only **own Game Zone + own team** (the `reportsTo` chain ⊆ Priya).
- **Local-disk photo storage** on the VPS; managers view photos via a lightbox (read-only) in verify + negative report.
- **English-only, single-tenant.** No language/tenant/theme switcher.

## What's NOT in this slot

- **Final approval (OH) / second-level approval (SM)** — TL is **first-level only** (Approve passes up to SM, `§4b`). SM/OH approval lives in their packs.
- **Cross-team / cross-Game-Zone data** — TL is scoped to their own team within Ahmedabad-1 (`§5`). Other teams / branches → 403.
- **Onboarding users, Game Zones, rides, roles** — OH/SM packs. TL can view team members (`TL-USER-DETAIL`) but not create/edit users.
- **Full roster build for the Game Zone** — TL builds **team-level** roster only (`TL-ROSTER`, Team scope per access matrix). Branch-wide roster + bulk upload + publish-for-GZ live in SM pack. (TL may publish its own team roster window → fires auto-assign for the team.)
- **Branch / Game-Zone-wide checklist template authoring** — TL authors **team-scoped** templates only (`TL-CHK-UPLOAD`, CL-1); GZ-wide / cross-team template CRUD lives with SM/OH. Auto-assign remains server-side; TL also does Team-level assign/override (`TL-CHK-ASSIGN`).
- **Maintenance work-order working** — the TL **routes** an A-item to the Maintenance TL (CL-2) but does not assign technicians, close, or outsource work-orders; those live in `maintenance-tl-web` / `technician-mobile`.
- **Positive / Overdue reports** — TL's report screen is the **Team Negative report** (`TL-REP-NEGATIVE`); positive/overdue roll up to SM/OH per `SCREEN_LIST`.
- **The TL mobile companion** is the mobile sub-phase deliverable (`SCREEN_LIST` TL = `Both`); this pack is the web pixel target.
- **Rotation, Capacity, Training, Events, School Visits** — out of Phase 1 (P3–P5).

---

## File references

- Pack root: `docs/design/dev-mode-v1.0/team-leader-web/`
- Anchor (mirrored): `docs/design/dev-mode-v1.0/staff-court-monitor-mobile/`
- Foundation: `docs/dev-mode-v1.0/FOUNDATION_SPEC.md` (schema, API conventions, auto-assign, cascade — TL = first approver)
- Dev plan: `docs/dev-mode-v1.0/DEV_EXECUTION_PLAN.md`
- Project plan: `docs/PROJECT_PLAN.md` · Screen list: `docs/design/SCREEN_LIST.md` · Design system: `docs/design/DESIGN_SYSTEM.md`
- Workflow: `docs/WORKFLOW_GUIDE.md` (Stage F — the TL approval step F1)
