tutortool/docs/design_handoff/README.md

# Handoff: Tutormanager — Anwesenheit & Notizen

## Overview

Tutormanager is an attendance + per-student notes tool for tutorien. The flagship use case is the FP-Tutorium (~19 students, Thursdays). Tutors run a short check-in routine at the start of each Projektstunde: open a slot, project a check-in URL on the beamer, watch students fill the seat map from their phones/laptops, lock the slot, and use the rest of the hour with a live seat plan that lets them jot per-student observations as they go.

The full architecture is described in `SPEC.md` (your existing approved spec). This handoff covers **only the frontend**. The HTML prototypes in this folder are **design references** — pixel-accurate mocks of the intended look and behaviour. The task is to **recreate them in SvelteKit** (`adapter-static`, SPA) per the approved stack, talking to the Rust/Axum backend defined in the spec.

## About the Design Files

The files in this bundle are design references created with React + inline JSX in static HTML. Don't ship them. Re-implement the same screens as Svelte components in the SvelteKit app, using your own component split and your own state stores. The HTML/CSS choices (paper background, ruled notebook, oxblood accent, Source Serif 4 + Inter + JetBrains Mono + Caveat) should transfer 1:1.

Open `Tutormanager.html` in a browser to view the canvas with all screens. `styles.css` holds the design tokens.

## Fidelity

**High-fidelity.** Colors, typography, spacing, and component states are final. Recreate pixel-perfectly in Svelte using the design tokens listed below.

---

## Design Tokens

All in `styles.css` as CSS custom properties. Bring them in verbatim (e.g. as a `app.css` imported in `+layout.svelte`).

### Colors

| Token | Value | Usage |
|---|---|---|
| `--paper` | `#f4efe6` | App background |
| `--paper-2` | `#ebe4d6` | Subtle alt rows, avatar bg |
| `--paper-3` | `#ded4c0` | Slightly stronger paper |
| `--rule` | `#c9bfa9` | Borders, dividers |
| `--rule-soft` | `#d9d0bb` | Softer dividers |
| `--ink` | `#1f1b16` | Primary text, primary buttons |
| `--ink-2` | `#3a342b` | Body text |
| `--ink-3` | `#6b6356` | Secondary / small |
| `--ink-4` | `#968b7a` | Tertiary, placeholders |
| `--accent` | `#8a2c1f` | Oxblood — accents, "absent", lock, stamps |
| `--accent-soft` | `#c66a5b` | — |
| `--highlight` | `#f1d36a` | Highlighter yellow |
| `--highlight-soft` | `#f5e3a4` | Marker underline fill |
| `--green` | `#4a6b3a` | "anwesend" / present |
| `--red` | `#8a2c1f` | "fehlt" / locked |
| `--amber` | `#b07d2a` | "offen" / open slot |

Card surface is `#fbf7ee` (slightly lighter than paper). Seat map background is `#f7f1e3`. Tables in seat map are `#e8dec5` with `var(--ink-2)` border.

### Typography

| Token | Stack |
|---|---|
| `--serif` | `"Source Serif 4", "Source Serif Pro", "EB Garamond", Georgia, serif` |
| `--sans`  | `"Inter", "Helvetica Neue", Helvetica, Arial, sans-serif` |
| `--mono`  | `"JetBrains Mono", "IBM Plex Mono", ui-monospace, "SF Mono", Menlo, monospace` |
| Marginalia | `"Caveat"` (used only for handwritten notes — see `.handwritten`) |

Load via Google Fonts (single `<link>`):
```
Source Serif 4 (300–700, italic), Inter (400/500/600), JetBrains Mono (400/500/600), Caveat (400/500/600)
```

Type scale (utility classes in `styles.css`):

- `.h1`  — Source Serif 4, 44/1.05, weight 500, letter-spacing -0.02em
- `.h2`  — Source Serif 4, 28/1.15, weight 500, letter-spacing -0.01em
- `.h3`  — Source Serif 4, 20/1.2, weight 500
- `.eyebrow` — JetBrains Mono, 11px, uppercase, 0.14em tracking, `--ink-3`
- `.body` — Inter, 14/1.5
- `.small` — Inter, 12, `--ink-3`
- `.tiny` — Inter, 11, `--ink-3`

### Spacing

8px-aligned grid. Common values seen in the design: 4, 6, 8, 10, 12, 14, 16, 18, 22, 24, 28, 32, 36.

### Radii

- 3–4px — most cards, inputs, buttons (paper feel — keep tight)
- 999px — pills
- 50% — avatars, seat circles

### Shadows

Avoid heavy shadows. Use a `1px 0 rgba(0,0,0,.03)` underline on cards. The seat-map container uses a subtle inset border instead of a box shadow.

### Special textures

- `.paper-bg` — paper grain via inline SVG noise + 2 radial highlights. Applied to app root and large surfaces.
- `.ruled` — repeating-linear-gradient producing 28px-spaced horizontal rules. Used inside the note textarea so handwritten text sits on lines.
- `.marker` — gradient that paints `--highlight-soft` over the lower 32% of inline text — looks like a hand-drawn highlighter stroke. Use sparingly on h1/h2 keywords (one word per heading).
- `.stamp` — rotated -4°, oxblood border + tint, monospace caps. Used for "PRÄSENT".
- `.handwritten` — Caveat in oxblood, 18px. For marginalia / sketch annotations only.
- `UnderlineStroke` — a tiny SVG hand-drawn underline beneath section titles. See `shared.jsx`.

---

## Information Architecture

```
/                         → redirect to /admin or /admin/login
/admin/login              → Login (anonymous)
/admin                    → Dashboard (slots overview)
/admin/live/:slotId       → Hero · live seat map + notes panel
/admin/attendance         → Per-student / per-week matrix + export
/admin/rooms              → Layout editor (rooms list / canvas / props)
/admin/rooms/:roomId      → Same, with active room
/admin/students           → Students CRUD
/s/:code                  → Student check-in (mobile + desktop responsive)
```

The student check-in screen MUST be responsive: phone gets a single-column compact layout; ≥ 900px viewport gets the two-column laptop layout (map left, side panel right). Both are in this bundle.

---

## Screens

### 1. Login (`/admin/login`)

Centered 420px-wide card on `.paper-bg`. Brand wordmark "Tutor·manager" with oxblood `·`. Card title is `.h2` "Willkommen zurück" with an `UnderlineStroke` (110px wide). Two stacked inputs (E-Mail, Passwort), full-width primary button "Anmelden". Below the card a small Caveat marginalia "~ Donnerstags ab 14 Uhr ~".

### 2. Tutor shell

Two columns: 220px sidebar + main content.

**Sidebar** (`background: rgba(0,0,0,0.015)`, right border `--rule`):
- Brand wordmark + version
- "Kurs" card (course name + semester + weekday)
- Nav list: Dashboard / Live · Sitzplan / Anwesenheit / Räume / Studierende. Active item: 4px oxblood dot + `rgba(31,27,22,0.08)` background.
- Bottom: avatar circle + tutor name + email.

### 3. Dashboard (`/admin`)

- Header: eyebrow "Dashboard", `.h1` "Diese Woche, **Woche 04**" (the week number gets `.marker`), one-line subtitle. Right side: "Export" (ghost) + "Neuer Slot" (primary) buttons.
- 4 stat cards in a row: "Anwesend gerade 14 / 19", "Ø Anwesenheit 84%", "Bonus vergeben 186 Punkte", "Offene Notizen 7". Big numbers in serif 32px, accent color when meaningful.
- Slots table: columns Woche / Datum / Zeit / Raum / Status / Code / Eingecheckt / Aktionen. Status pills (open / closed / locked). Eingecheckt cell shows "n / total" + a 48×4px progress bar. Per-row primary action depends on status (Sperren / Öffnen / Anzeigen).

### 4. Live seat map + notes (HERO — `/admin/live/:slotId`)

Two-column grid: `1fr 380px`.

**Left column — seat map:**
- Header row: "Sitzplan" (`.h3` + UnderlineStroke 70px) on the left; legend dots on the right (anwesend / frei / ausgewählt).
- The seat map itself (see "Seat map component" below) at scale 0.85.
- Tally row at bottom: 3 stat blocks (Anwesend `n/total`, Fehlt n, Bonus heute "+n Punkte") + spacer + ghost button "Manuell eintragen".

**Right column — roster + note editor (a card):**
- Top: "Studierende" with present/absent count.
- Scrollable roster (max-height ~220px). Each row: 22px ink avatar circle, name, oxblood dot if has note, monospace check-in time (or "—" for absent). Selected row: `rgba(31,27,22,0.06)` bg + 3px ink left border. Absent rows: 0.55 opacity, dashed avatar border, strikethrough name.
- Bottom — note editor on `#fbf7ee`:
  - 32px ink avatar + selected student name (`.h3`) + "Sitzplatz {seat} · seit {time}" + "Präsent" stamp on the right.
  - "Notiz · Woche 04" eyebrow.
  - Textarea with `.ruled` background, Source Serif 4 15/28px, no border. Placeholder "Beobachtungen für diese Woche…".
  - Quick-tag chips below: "+ aktiv beteiligt", "+ stille:r Kämpfer:in", "+ verstanden ✓", "+ nochmal aufgreifen", "+ Rückfrage offen", "+ elegante Lösung".
  - Footer: "Auto-gespeichert · 14:23" left, "Notizen vergangener Wochen ↗" link right.

Page header above the grid:
- Left side: eyebrow "Tutor:innen-Ansicht · Live", title "Woche 04 · **Donnerstag, 30. April 2026**" (date with `.marker`), subtitle line: course / room / time.
- Right side: monospace check-in code "K7QJ-MX2P" with the URL beneath, status pill (offen), Kopieren / Sperren buttons.

### 5. Anwesenheit (`/admin/attendance`)

- Header `.h1` "Kursmatrix · **SS 2026**". Right: 3 ghost export buttons (CSV / Markdown / SQLite Backup).
- Card with tab bar: "Pro Studierende:r" (active) / "Pro Woche" / "Notizen".
- Matrix table: # / Studierende:r / W01 / W02 / W03 / W04 / Anwesend / Bonus / arrow. Present cell is a 22px square with green check on `rgba(74,107,58,0.14)`. Absent: em-dash. Bonus column shows a single 24px oxblood circled check (no number — only "got bonus or not").

### 6. Räume — Layout-Editor (`/admin/rooms/:roomId`)

Three-column grid: 210px / 1fr / 240px.

- **Left**: rooms list (selectable, oxblood left border on active), "+ Neuer Raum" button at bottom.
- **Center** — toolbar + canvas + status bar:
  - Toolbar: 6 tool buttons (Auswählen / Sitz / Tisch / Tür / Fenster / Lücke), each with a small monospace glyph + label. Active tool is filled ink. Right side: zoom controls (− 78% +), "Raster: 24px".
  - Canvas: `#efe6d2` background with rulers along top (px ticks) and left, a centred seat map at scale 0.78. Selected element shows a rotating dashed oxblood ring + 4 small white drag-handle squares. Two Caveat marginalia annotations.
  - Bottom status bar: element counts, auto-save timestamp.
- **Right**: stacked cards.
  - "Auswahl" card: shows kind + id ("Sitz T2-3"), then editable fields (Bezeichnung, Tisch, X / Y in px, ∅ / Rotation). Below: "Aktionen" — Duplizieren (⌘D), An Tisch ausrichten, Löschen (⌫, oxblood text).
  - "Ebenen" card: tree-like list of layers — walls, 4 tables with their seats, podium, beamer, door, window. Selected layer (T2 group) gets oxblood text + tinted bg.

### 7. Studierende (`/admin/students`)

Header with title + search input + "CSV importieren" + "Hinzufügen". Card with table: # / Name (avatar + name) / Anwesend (n/4) / Bonus (single circled check or em-dash) / Notizen (oxblood dot + count) / Letzte Sitzung / arrow.

### 8. Student check-in — phone (`/s/:code`, viewport < 900px)

Four states (each on `.paper-bg`, ~360×760 viewport):

1. **Name picker**: eyebrow "Check-in · K7QJ-MX2P", title "Wer bist du?", search input, scrollable name list (avatar + name, divider lines). Footer hint "Nicht in der Liste? Sprich die Tutor:in an."
2. **Seat picker**: "Hallo, Carla 👋" eyebrow, title "Wähle deinen Sitz", scaled seat map (0.46), legend, info card "Du kannst deinen Sitz wechseln, solange der Slot offen ist."
3. **Confirmed**: title "Du sitzt auf **T1-3**" (T1-3 with `.marker`), "Präsent" stamp top-right, scaled map showing only own seat highlighted oxblood, status card with "OFFEN" pill + lock-time hint, ghost "Sitz wechseln" button.
4. **Locked / read-only**: title "Anwesenheit erfasst", scaled map (own seat still oxblood), info card with lock icon + "Check-in für diesen Slot ist geschlossen. Bonus wurde gutgeschrieben.", footer with next session date.

### 9. Student check-in — laptop (`/s/:code`, viewport ≥ 900px)

Three states:

1. **Name picker**: centered 560px column. Header eyebrow + .h1 "Wer bist du?" + subtitle. Card with autofocused search and a 2-column grid of name buttons. Footer keyboard-shortcut tip.
2. **Seat picker**: two-column `1fr 360px`. Left: large seat map (scale 0.78) + legend below. Right side panel (subtle bg, left border): "Sitzung" block (course / date+time / room), "Eingecheckt als" with avatar + "wechseln" link, "Hinweise" bullet list, bottom yellow-tinted card "Bonus +3 Punkte sobald du einen Sitz wählst."
3. **Confirmed (with season)**: same two-column. Left: header "Du sitzt auf **T1-3**" + stamp, large map with own seat highlighted, two ghost buttons (Sitz wechseln / Drucken). Right side: "Slot-Status" with open pill, "Deine Saison" — 4-row weekly history list (W01–W04, date, seat code, green check or em-dash; current week in oxblood), oxblood-tinted card "Bonus gesamt 9 / 12 Punkte · 3 von 4 Tutorien besucht".

---

## Components to build

| Svelte component | Notes |
|---|---|
| `<StatusPill status="open" \| "closed" \| "locked" \| "present" \| "absent" />` | See `.pill` and `.pill.{state}` in `styles.css`. |
| `<UnderlineStroke width={110} color="..." />` | Inline SVG path — see `shared.jsx`. |
| `<Stamp>Präsent</Stamp>` | `.stamp` class. |
| `<Eyebrow>` / `<H1>` / `<H2>` / `<H3>` | Or just utility classes. |
| `<Tally label value total suffix accent />` | Stat block in serif. |
| `<StatCard label value suffix hint accent />` | Card variant for the dashboard. |
| `<Field label suffix mono />` | Labelled input with optional unit suffix in mono. |
| `<TutorShell active>` | Sidebar + main slot. |
| `<SeatMap variant="tutor" \| "student" \| "student-self" assignments selectedStudent ownSeat onSeatClick scale />` | The big one — see below. |
| `<NoteEditor studentId weekNr />` | Roster + ruled textarea + tag chips. |
| `<MarkerText>` | Inline span with `.marker`. |

### `<SeatMap>` — the central component

Top-down floor plan, absolutely-positioned layers inside a fixed-size design space (760×460 px) that gets transform-scaled by the `scale` prop.

**Static structural layers** (drawn in this order):
1. Inner ruled grid (24px graph paper, very low alpha).
2. Walls — 2px ink-2 border rounded 2px.
3. Window — 6×220px tall blue-tinted strip on the left wall with a horizontal split line. Mono "Fenster" label rotated -90°.
4. Door — gap in bottom wall (70×4px) covered with paper colour, an SVG door arc (`stroke-dasharray="2 2"`), and a "Tür" label.
5. Beamer — small black bar at top.
6. Podium / Pult — 190×38 ruled rectangle, mono caps "Pult · Tutor:in".
7. Tables — 4 rectangles (200×70px) at fixed coords. Filled `#e8dec5` with ink-2 border + italic serif label "T1"–"T4" centred at 0.35 alpha.

**Seats** — generated from tables: 5 per table.
- Top edge (y = table.y − 22): 2 seats at x = table.x + table.w*{0.28, 0.72}.
- Bottom edge (y = table.y + table.h + 22): 2 seats, same x ratios.
- Head (short edge, x = table.x + table.w + 26): 1 seat at table.y + table.h/2.

Seat = 36px circle button, 1.5px border. Per `variant`:

- **tutor**: occupied seat shows ink avatar with student initials in white. Selected: filled ink + 3px highlight-soft outer ring. Hover: `#e0d4b6` fill. Free: paper bg + ink-4 border.
- **student**: occupied = `#d6cdb5` (no name shown — privacy). Free = paper bg + ink-2 border. Own seat (after pick) = oxblood fill, white star ★ glyph.
- **student-self** (read-only): same colours, no clicks, own seat = oxblood + ★, others greyed if occupied.

Compass mark in bottom-right (mono "N" + small SVG arrow).

The layout JSON the backend stores must round-trip these elements: `[{id, label, x, y, width, height, type}]` with `type ∈ "seat" | "table" | "gap" | "door" | "window" | "wall" | "beamer" | "podium"`. The component takes that JSON as input — don't hardcode the room.

---

## Interactions & state

- **Slot status transitions** (tutor): `closed → open → locked`. Opening generates the 8-char code (server-side per spec). Closed/locked rows show no code. The UI must atomically reflect "open ⇒ has code".
- **Seat click (tutor live view)**: selects that student in the roster; note editor scrolls/loads. Double-click could open the per-student timeline.
- **Note editor**: debounced auto-save (~600ms) → PUT note. Show "Auto-gespeichert · HH:MM" timestamp on success.
- **Quick tag chips**: on click, append the tag (with leading newline if note non-empty) to the note text, then save.
- **Student seat pick**: optimistic UI; on HTTP 409 ("seat taken"), revert and toast "Platz schon vergeben — bitte einen anderen wählen."
- **Seat change**: while `open`, click another free seat → confirmation toast → previous seat goes free immediately.
- **Locked**: pointer-events: none on seats; only own seat remains oxblood-highlighted.
- **Live polling**: poll the slot every 5–8s while open to refresh assignments and check-in count.
- **Marker animation**: the selection ring in the room editor uses `@keyframes spin 12s linear infinite`. Disable in `prefers-reduced-motion`.

---

## State management

Suggest one Svelte store per domain:

- `auth` — JWT token, current tutor.
- `course` — currently selected course (and tutors' available courses).
- `slots` — slots for the active course/week.
- `liveSlot` — assignments + notes for the slot currently shown in the live view; reactive on poll.
- `room` — layout JSON of the room being edited; also handles selection + tool state for the editor.

The check-in page is its own minimal app state: `{ code, slot, room, ownSeat, ownStudentId }`, no auth store.

---

## Copy

All UI is in **German**. Specific strings used in the design:

- "Anwesend", "Fehlt", "Bonus heute", "Eingecheckt", "Sitzplan", "Studierende", "Notiz · Woche {n}".
- "Manuell eintragen", "Sperren", "Öffnen", "Anzeigen", "Kopieren", "Speichern".
- "Wer bist du?", "Wähle deinen Sitz", "Du sitzt auf {seat}", "Anwesenheit erfasst".
- "Nicht in der Liste? Sprich die Tutor:in an.", "Du kannst deinen Sitz wechseln, solange der Slot offen ist."
- Status pill labels: OFFEN / GESCHL. / GESPERRT / ANWESEND / FEHLT.
- Stamp: PRÄSENT.

The sample course is "Funktionale Programmierung", semester "SS 2026", room "BC2 1.103", weekday "Donnerstag", tutorin "Lina Puchstein". Replace with real data from the backend.

---

## Assets

- **Fonts**: Source Serif 4, Inter, JetBrains Mono, Caveat — all from Google Fonts.
- **Icons**: tiny inline SVGs in `shared.jsx` (`Icon.check`, `Icon.x`, `Icon.lock`, `Icon.open`, `Icon.copy`, `Icon.edit`, `Icon.download`, `Icon.arrow`, `Icon.search`, `Icon.plus`). Re-use them as Svelte components or swap to Lucide if you prefer — they're trivial.
- **Paper grain**: inline SVG noise filter in `.paper-bg`. Copy verbatim.
- **No image assets**.

---

## Files in this bundle

| File | What's in it |
|---|---|
| `Tutormanager.html` | Entry point — design canvas hosting all artboards. Open in a browser. |
| `styles.css` | All design tokens + utility classes. Copy into the SvelteKit app. |
| `shared.jsx` | Sample course + students + room layout + `StatusPill`, `UnderlineStroke`, `Icon.*` |
| `seatmap.jsx` | `<SeatMap>` and the `<TutorLiveView>` hero — main reference. |
| `admin.jsx` | Tutor shell, Dashboard, Anwesenheit-Matrix, Studierende, Login. |
| `rooms.jsx` | Layout editor with toolbar, canvas, properties + layers panel. |
| `student.jsx` | Phone variants of the four student states. |
| `student-desktop.jsx` | Laptop variant of the three student states. |
| `design-canvas.jsx`, `browser-window.jsx`, `ios-frame.jsx` | Presentation chrome — for the design canvas only, do not port. |

The design canvas grouping (sections / artboards) is purely a presentation device. The actual app has the route structure listed under "Information Architecture".

---

## Implementation tips

- Start with `styles.css` and the type/colour tokens. Wire fonts.
- Build `<SeatMap>` early — it's the centrepiece and the only non-trivial component.
- The room editor's drag-and-drop is real work — the spec says layouts are stored as JSON. A DnD library (`svelte-dnd-action`) is fine; snap to a 24px grid. The visual shown is the *finished* state with one seat selected.
- Do **not** add visual flourishes (more icons, gradients, hero images). The look comes from restraint + the paper texture + the marker/stamp accents.
- Respect `prefers-reduced-motion` — disable the room-editor selection-ring spin and any hover scale.
- The handwritten Caveat marginalia is a flavour element. Keep them sparse — at most one per screen.