UX: Personas, Flows and Screens

A proposal, not a decision. Every entity and relationship below is open to challenge; the open decisions are listed at the end.

Version 0.1, 6 September 2026. The experience track's design for the timetabling application, built against the API contract v0.1 and the Mevo Hagalil requirements. A working prototype of the screens marked "built" lives in apps/web against an in-browser stub.

Overview

The product replaces a magnet board and Tik-Tak with one screen the timetable coordinator can trust: the board, made honest. The grid stays the hero, teachers stay magnets, and every rule the coordinator carries in her head (R-05 to R-14) becomes a row she can switch on, weight, and see broken in plain Hebrew on the exact cell. Solving is a background job she can start, watch and cancel; repair is pinning and dragging with the engine validating every move. The design targets the deputy principal first, treats teachers and the principal as readers in version 1, and keeps the secretary's daily substitutions for later.

Summary

• One primary persona: the coordinator who builds the timetable in June to August and re-cuts it in September and after every staffing change. Four secondary personas, two in scope for v1 as read-only.
• Eight journeys, from Tik-Tak import to mid-year change. Import, solve, review, repair and publish are the spine; the rest feed it.
• Information architecture: six sections behind one top bar. The timetable, its violations panel and the solve dialog are one screen; everything else prepares data for it.
• Explainability is a sentence per violation, in Hebrew, naming the rule by requirement ID and the people and cells involved, with a button that shows those cells and a button that repairs only them.
• RTL is the default document direction with logical CSS; English is a toggle for the team and for later markets, not a second product.

Bottom line

Build the timetable screen, the violations panel, the constraints checklist and the staff availability editor first; they are what the coordinator uses daily and what no competitor does well. Import and publish can stay designed-only until the engine's Tik-Tak adapter exists. Ship Hebrew RTL as the only tested direction, with English behind a toggle.

Detailed explanation

Personas

Journeys

Each flow lists the screens it touches. Screen names are in the inventory below.

1. Onboard a school from Tik-Tak. Import screen: upload the export, map short names to full names (S-03: two אורלי, two ספיר, two קרן), confirm inferred homeroom teachers (S-02), confirm fixed blocks (S-06, S-07) and meeting slots (S-05). Result: the achieved timetable scored against the rules on the Dashboard. Screens: Import, Dashboard.
2. Staff and availability. Staff screen: table of everyone with role, homeroom, frontal, individual and staying hours (R-04), working days. Detail: a day-by-period grid where a click cycles available, prefer-not (R-10, soft) and unavailable (R-09, R-10, hard), a day header marks a whole day, each row carries a reason. Saving rescores the timetable at once. Screens: Staff.
3. Curriculum per grade. Weekly periods per subject per grade (R-13), double-period and co-teaching flags (R-12). Designed as a grade-by-subject table with pattern editing; the prototype reads the fixture only. Screens: Curriculum (designed).
4. Constraints as a checklist. Constraints screen: one row per requirement ID in Vegman's order, his Hebrew wording quoted, the engine constraint or constraints beneath it with on/off, hard/soft, weight and parameters, and the current violation count. Structural rules (R-01 to R-04, R-13) show where they are set instead. Open questions are linked by Q-ID. Screens: Constraints.
5. Solve. Solve dialog from the top bar: time limit, warm start from the current version, keep pinned cells. Live phase (queued, building model, searching, improving), elapsed time, hard and soft counts; cancel at any time keeps the best so far. Done opens the new draft version. Screens: Solve dialog, Timetable.
6. Review. Timetable screen in three views: one class (periods by days, like a printed page), one grade (three classes side by side, like the board), one teacher (her week, with unavailable slots shaded). Co-teachers are two magnets in one cell; trip blocks span periods 4 to 6; fixed programmes carry a lock. A corner mark shows a violation, red for hard, amber for soft. Hover explains. The Violations panel groups by rule and explains each case. Screens: Timetable, Violations panel.
7. Repair. Pin a cell or a whole view; drag a lesson onto another slot of the same class and the stub scores the swap before the drop, refusing one that creates a hard violation and reporting the soft delta with undo otherwise; "fix only this" pins everything except the lessons involved in one violation and re-solves for a few seconds. Editing a published version forks a draft. Screens: Timetable, Solve dialog.
8. Publish and export. Checks before publishing (no hard violations; teachers confirmed; availability current), publish to staff, export to Tik-Tak and XHSTT, print for the board, and a diff against the previous version. Screens: Publish (designed except publish itself).
9. Mid-year change. A teacher leaves or hours change in October: edit Staff, see the new violations on the Dashboard, pin everything that must not move, solve with warm start, review the diff, publish. Same screens, no new ones; the version history on the Dashboard is the audit trail.

Information architecture and navigation

One top bar: school name, six sections (Overview, Timetable, Staff, Rules, Publish, Import), the current version selector with status and score, the solve button, language and theme. No sidebar: the grid needs the width. Timetable is the working screen; the others prepare its inputs or consume its output. The Dashboard is the landing page and lists next actions derived from state (hard violations first, then soft, then missing availability, then the standing placeholder note about subjects, N-01). Versions are a list with scores; picking one loads it everywhere.

RTL and bilingual approach

Hebrew is the document direction (dir="rtl" on the root), so days run from Sunday on the right exactly as on the board and the period column sits on the right. All layout uses logical properties (inline-start, margin-inline-end), so the English toggle flips the whole interface without a second stylesheet. Every string lives in one dictionary with Hebrew and English keys; contract objects carry nameHe and name, and a helper picks by language. Numbers, IDs and times are set in a monospace face and never mirrored. Teacher short names on magnets are always the Hebrew board names, in both languages, because that is how the school knows them.

What explainability looks like

A violation is a sentence, not a code: "מור מתחילה בשיעור 1 ב-2 ימים; הכלל דורש 3." It names the rule by requirement ID and title, the people or classes, the day and period, and the cost. Three ways to see it: a corner mark on the cell, the hover card on the cell listing every violation that touches it, and the panel grouped by rule with counts and total cost. Two ways to act: show in grid (switches to the right class or teacher and outlines the cells) and fix (local repair with everything else pinned). The same scorer explains a drag before it lands. When the engine ships unsat-core explanations for infeasible hard rules, they slot into the same panel as a violation of the rule with no assignment.

Screen inventory