Browse all of Kata

Claude Design brief — the Konjo Teach tab

Source docs/design/2026-09-03-teach-tab-redesign-brief.mdMarkdown

On this page

Generated 2026-09-03 from the shipped code — src/features/teach/screens/TeachHomeScreen.tsx, src/navigation/AppNavigator.tsx (the TeachStack function) and the screens they mount — plus a founder interview held the same day. It describes what the code does, not what anyone hoped it would do. When the Teach tab changes, regenerate this file from the code and re-date it; do not patch it by hand. The predecessor brief for Studio went stale and was killed for exactly that reason (2026-08-02-claude-design-studio-brief.md). Every token name, hex and path below is checked mechanically by scripts/verify/design-doc-check.mjs.

How to use: paste everything from the line below to the end of the file into Claude Design as one message. It is self-contained. Nothing in it requires reading the repository.


Redesign the Konjo Teach tab — three takes on "The Floor"

1. Goal

Konjo is a martial-arts training app. Students train with it; instructors teach with it; dojo owners run the business from a separate desktop dashboard called Konjo Studio. This brief is about the Teach tab in the mobile app — the instructor's surface.

Produce three distinct takes on one direction, called The Floor: the Teach tab optimised for the moment an instructor walks onto the mat with a class starting in minutes. The three takes share one architecture (§6) and one vocabulary (§9), and differ on treatment (§7). For each take, design the same three screens so parts can be mixed between takes:

  1. Teach home — in two states: a class live or starting soon; nothing scheduled today.
  2. Class Mode — the single run-class flow: the Check in step and the Teach step on a phone, and the Teach step on a tablet.
  3. Student profile — one student, with at least one non-happy state (a fading student or one who has never attended).

Design at 390pt (phone) and ~1024pt (tablet), both as first-class layouts. Design in light theme; the palette below has a dark pair for every token and the design must survive the swap, but you only need to render light. Fill every screen with Blue Heron Martial Arts demo content (§11) and make each screen prove it handles at least one unhappy path.

2. Who this is for

Dana Whitfield — instructor. Brown belt, teaches three evenings a week, is also the dojo's head instructor. On the floor: one hand free, twenty students, constant interruption. Quits at anything needing a paragraph of reading or more than about three taps. This is the person every screen is designed for first.

Morgan Reyes — owner who also teaches. Black belt (shodan), owns Blue Heron. Uses the same Teach tab as Dana; nothing is hidden from them, and a few things they can edit that Dana can only read. Money, payroll, CRM and mass messaging are not here for Morgan either — those live in Studio on a desktop. Same layout for both people, never a separate "owner" screen.

A newly added instructor with no class assigned yet. Has the tab, can read everything, cannot run a class until a head instructor puts them on one. Today they meet a gold dead-end card and nine greyed rows. Propose better (§8).

Avery Nakamura — front desk. Never sees the Teach tab at all. Not a user of this design; named so you do not design for them.

The student is never a user of Teach. Students have their own tabs.

3. What the Teach tab is today

The tab bar has four base tabs — Train, Events, Learn, Social — and a fifth, Teach, that appears only for instructors. It sits between Train and Events. The tab icon carries a red count badge for open follow-ups (capped at "9+").

3.1 Teach home, top to bottom, as shipped

Title "Teach" (left-aligned display type; no header actions). Then, scrolling:

A status hero, one card whose copy depends on the instructor's next class at their home dojo:

State Eyebrow Title Subtitle Button
A class is live now LIVE NOW (red dot) class name "Started 6:00 PM" Run class
Starts within the hour STARTS IN 12 MIN / STARTING NOW class name time Start class
Later today or this week NEXT CLASS class name "Tue at 6:00 PM" Open class
Nothing scheduled, can run classes YOUR SCHEDULE "Nothing scheduled right now" "Add classes to your schedule to run them from here." Open schedule
Nothing scheduled, not yet on a class roster INSTRUCTOR ACCESS "You've reached instructor rank" "Ask your dojo head to add you to a class to start teaching." none — gold card, not tappable

If two classes are live at once the hero splits into two side-by-side cards. A third live class is not shown.

Under the hero, when there is a class: a gold "Trial visitor expected" banner if a prospect has a trial booked that day (name · time · age bracket); a bordered "plan strip" showing the attached lesson plan ("Green Stripe Prep · 4 blocks") with Change and Remove, or "+ Add plan"; and a bordered row "See what this class needs" that opens the gap engine for that class.

Then four sections of identical-weight rows (icon · label · sublabel · chevron). Twelve rows. Nine of them are greyed out for an instructor not yet on a class roster.

Section Row Sublabel Opens
Your work My follow-ups (red count badge) "2 overdue · 3 more waiting" / "Tasks assigned to you" the follow-ups screen
Run class Take attendance "Pick a class and mark competency" a class picker → roster → grid → debrief
Run class What each class needs "Gaps by class, rank, and student" the gap engine
Run class Scan check-ins "Scan student QR codes to mark attendance" camera scanner (never greyed)
Run class Report an incident (feature-flagged) "Create a protected safety or conduct record" incident form
Plan & curriculum Class plans "Build, share, and schedule lesson plans" plan library
Plan & curriculum Curriculum calendar "Theme weeks, months, and quarters" quarter/month/week planner
Plan & curriculum Test requirements "What's required for each belt at your dojo" per-belt requirements editor
Schedule & insights Class schedule "Weekly classes, cancellations, attendance" week view + recurring editor
Schedule & insights Teaching analytics "Coverage, gaps, and student profiles" four-lens analytics
Schedule & insights Attendance history "Attendance by student and by class" attendance drill-down
Schedule & insights Coverage "Request, claim, and assign class subs" substitutes screen

3.2 Running a class — there are two flows today

Path A — Class Mode. The hero's button opens a full-screen, three-step flow with a persistent step bar (1 Check in · 2 Teach · 3 Wrap up, freely tappable):

  • Check in — a grid of large tiles (belt dot + name) for every dojo member eligible for the class. Tap to mark present; a live count updates. Shows the trial-visitor banner and a red "staff instructions" banner for any student with an active injury, accommodation or behaviour flag. Cannot add someone who is not on the roster.
  • Teach — grade mastery 0–5 with six large tap targets ("MasteryDial", one tap sets the level, legible at arm's length). Toggle By student (one student, all techniques on tonight's plan) or By technique (one technique, all present students). "+ Add item" pulls an off-plan technique in. A small warning glyph appears where the student's own 1–5 confidence and the instructor's 0–5 mastery disagree by two or more. Each dial tap saves optimistically; an offline queue holds writes and shows synced / pending / error / conflict per cell.
  • Wrap up — confirm who was present; assign each staff member a role (lead · assistant · substitute); mark each plan block covered / not covered; record who taught; optional link to per-student notes, feedback and homework; Finish.

Path B — Take attendance → Class Organizer → Debrief. The "Take attendance" row (and tapping a class in the schedule) opens a different roster: searchable, grid or list view, students grouped by checked in · said "I'm here" · booked · regular · other, with a Save button. Save opens the Class Organizer: rows are checked-in students, columns are the plan's techniques, each cell a recency tint with a small − 3 + stepper. It is tablet-first; below 700pt wide it collapses into one expandable card per student. It is the only place a walk-in visitor not on the roster can be added ("Late student"). Done opens Debrief: a class-wide notes field (auto-saves), then each attended student with a staff-only note and an optional direct-feedback composer that can attach homework (the student is notified when homework is sent).

Both paths write the same attendance and mastery records. Both end at Debrief. The founder did not know both existed. This redesign keeps one flow, Class Mode, and folds the Organizer grid into it as the tablet layout of the Teach step (§6).

3.3 The other four check-in paths

Besides the two above: students tap "I'm here" on their own Train tab within 90 minutes of class (shows to the instructor as said "I'm here"); an instructor scans a student's personal QR code with the phone camera ("Scan check-ins"); a front-desk kiosk tablet, managed from Studio, checks people in as they arrive. All five write the same attendance table. A check-in taken by mistake can be removed.

3.4 Follow-ups — the work queue

The newest, most polished screen. A list of tasks assigned to this instructor, mostly generated by the system: a student is fading (no attendance past the dojo's threshold), a student is ready to test (every requirement for their next rank graded 3 or better — computed nightly, one task per student), an incident needing follow-up, occasionally a hand-assigned task. Six sections: Overdue · Due today · Upcoming · Someday (no due date — most of them) · Snoozed · Done (last 7 days).

Each card leads with the person's name and says only what it can prove ("Last attended 23 days ago" or "No attendance recorded yet", never "is fading" above "never attended"). Actions are bordered buttons, not swipes: Call · Text · Email (or "no phone on file"), Complete (with Undo toast), Snooze (Tomorrow / In 3 days / Next week, with Undo), Not needed (requires a typed reason; the only filled button on the screen), Reopen from Done, Bring back from Snoozed. Incident tasks are read-only here — they require written evidence and are finished in Studio. Tapping the name opens the student's attendance detail.

3.5 Attendance (read side)

Attendance opens a two-segment screen: Students (searchable dojo roster, avatar + belt dot + "last attended" with a warning tint after 14 quiet days) and Classes (recurring classes). A student opens student attendance detail: last attended · last 30 days · since promotion · all-time, per-class chips, the chronological list of sessions attended (absences are deliberately not listed), and a contact card with tap-to-call / text / email. A class opens its dated sessions (headcount, booked-but-absent count; cancelled sessions greyed), then one session's roster with a separate "Booked but didn't attend" group.

There is no student profile in Teach. Attendance detail has no belt, no mastery, no notes. A mastery-by-category "student profile" sheet exists but is reachable only from inside Analytics.

3.6 Plan & curriculum

  • Class plans — a library in three tabs (Mine · My dojo · Shared with me). A plan has a title, description, target belt range and ordered time blocks, each with techniques and notes. Plans can be shared to named instructors. A plan is attached to one dated class ("Schedule plan", next 7 days only). A plan can carry breakouts — sub-groups with their own mini-plan and belt range.
  • Curriculum calendar — quarter → month → week cells; tap a cell to write a module (title, notes, techniques, linked plans). Head instructor edits; others see a read-only banner.
  • Test requirements — per target belt, toggle which techniques are required (overriding the curriculum default) and add typed non-technique requirements (fitness reps, board break, sparring rounds, application scenario, free note). Head instructor edits; others read. A head instructor can also mint a custom technique for this dojo and add it to the test in one step.
  • Gaps (today labelled "Focus" in code and "What each class needs" on the card) — for one recurring class, what the eligible roster still needs for their next test, where gap = required and (mastery below 3 or not drilled in about 21 days). Three lenses: Class (what most of the room is missing), By rank, By student. Toggle Next belt vs Cumulative. "Build plan from gaps" seeds a new plan from the top gaps. The loop: gap → plan → taught → attendance refreshes recency → gap clears.

3.7 Insights

  • Teaching analytics — four lenses (Overview · Trends · Retention · Requirements) with a 30 / 90 / 365-day range, plus a student mastery lookup. Known limit: techniques never taught do not appear, so "under-taught" is really "least taught".
  • Attendance — §3.5.

3.8 Subs (today "Coverage")

Four sections: Open sub requests at the dojo (any instructor may Claim; a head instructor or owner may Assign; requester or head may Cancel); My upcoming classes (next 14 days, each with Request a sub or its request status); My classes (which recurring classes I teach or assist — this roster feeds the previous section); My unavailability (date ranges). The screen has no back button today.

3.9 Schedule

A week strip with per-day dots; tap a day to see its classes; tap a class for a sheet: Cancel class (with reason; notifies eligible students), Take attendance, Send announcement (head instructor / owner only, pre-filled with the class). An Edit mode exposes the recurring schedule editor (add / edit / long-press-delete classes, set belt and age eligibility). The founder has decided schedule editing leaves Teach home — Studio owns it. Viewing today's classes and running one stays.

3.10 Incident report

Feature-flagged form: dojo (if more than one) → student → category (6) → severity → title → location → narrative → submit. Staff-only; the student is never notified and never sees it. Also reachable from a warning glyph in Class Mode's header. Out of scope for this brief — keep it reachable (an overflow or header action, and inside Class Mode), do not redesign the form.

3.11 Who can do what

  • The tab shows for owners, head instructors and instructors (a staff role at the dojo), and app admins. Front desk never sees it.
  • Running a class, taking attendance, grading: needs to be on the dojo's instructor roster.
  • Editing test requirements, the curriculum calendar, sending an announcement, assigning a sub: head instructor or owner. Everyone else sees these read-only.
  • Everything scopes to the instructor's home dojo. There is no dojo switcher and the founder does not want one in this redesign.

3.12 What is deliberately NOT in Teach

Grading a belt test (pass / fail / absent, finalize promotions) lives under the Events tab. Coaching (students posting video for feedback) lives under Train. Members, families, billing, payroll, point of sale, message blasts and automations, kiosk device management, incident review and export, the dojo's public page — all Studio, on a desktop. Do not design any of these into Teach. If a screen seems to need one, name it as a reach into Studio and move on.

4. What is wrong with it (observed)

  1. Twelve rows at identical weight. Konjo's design law for a tab home is "one hero, then a little"; Teach is a hero, then a directory. Nothing below the hero tells the instructor what matters now.
  2. Two run-class flows for one job (§3.2), entered from different rows, with different controls for the same 0–5 grade.
  3. Two vocabularies. "Focus" / "What each class needs"; "Attendance history" / "Attendance insights"; "Coverage" / "cover" / "subs". Two hub screens that nothing links to still carry a third set of labels.
  4. The only badged, push-notified item — follow-ups — sits under a hero that is empty most of the day, and the hero's empty state points at the schedule editor.
  5. "Scan check-ins" is the one row never greyed, so a new instructor can open a scanner and nothing else.
  6. The new-staff state is a dead end: a gold card with no action and nine greyed rows.
  7. Header grammar differs by screen: the home has a left-aligned display title; children have centred titles with a back chevron; Subs has no back button at all.
  8. Design-law defects: the hero uses retired tokens; section labels use text.tertiary on the page (4.23:1, fails); Class Mode's Teach step shows two filled red buttons ("Add item" and "Wrap up") on one screen and a centred empty state floating in a void.
  9. Student detail is attendance only. An instructor cannot see belt, mastery, readiness or notes for one person in one place.
  10. Test readiness is invisible. The system knows nightly who is ready; the only way an instructor learns it is a follow-up card.

5. Fixed decisions — every take must honour these

  • One run-class flow: Class Mode. Three steps (Check in · Teach · Wrap up). The Organizer grid is the Teach step's tablet layout. QR scan and "Add a visitor" are actions inside Check in. There is no separate "Take attendance" tool; opening any class — live, past, or unscheduled — opens Class Mode.
  • One inbox for all work: "To do". Follow-ups, classes needing a sub, and students ready to test, in one sectioned screen, summarised as one compact strip under the hero on Teach home.
  • One student profile, with actions. Every tapped name anywhere in Teach lands on it.
  • Names (§9) are fixed. Use them verbatim.
  • Phone and tablet are equals.
  • Plans, curriculum calendar, test requirements, Gaps and Analytics stay in Teach and are at most two taps from home, via a Plan hub and an Insights hub. Home itself stays short.
  • Schedule editing is not on Teach home.

6. Target architecture — shared by all three takes

6.1 Teach home

Title "Teach"                              ⌕ (search students)   ⋯ (Report an incident)
HERO — the one class that matters now
  eyebrow: LIVE NOW · STARTS IN 12 MIN · NEXT CLASS · (none)
  class name · time · "Green Stripe Prep · 4 blocks" · "14 expected · 1 trial visitor"
  one CTA: Run class / Start class / Open class
TO DO strip — "3 follow-ups · 1 class needs a sub · 2 ready to test"  →  To do screen
Today's other classes — quiet rows (name · time · plan? · who's teaching)  → Class Mode
Plan     — quiet row → hub: Class plans · Curriculum calendar · Test requirements · Gaps
Insights — quiet row → hub: Attendance · Analytics · Subs

Rules: the trial-visitor banner and the plan strip are folded into the hero's meta, not stacked beneath it. The hero shows one class; if two are live, the second is the first "today" row with a LIVE marker. When nothing is scheduled today, the hero shows the next class this week quietly and the To do strip carries the weight. A new instructor with no roster row sees the same screen with everything readable; the hero explains what running a class requires (§8).

6.2 To do (the inbox)

Sections in this order: Needs a sub (open classes at the dojo, soonest first, one action: Claim — reversible until the class starts; assign/cancel for head instructors) · Ready to test (students with every requirement for their next rank graded 3 or better; one action opens the student profile) · Follow-ups (today's six buckets collapse into Overdue · Today · Upcoming · Someday) · Snoozed · Done. Keep today's follow-up card grammar (name leads; prove what you claim; bordered actions; Undo on everything). Empty is the good state and says so plainly.

6.3 Class Mode

  • Check in — tile grid; ink-filled tile = present, white = not yet; belt dot top-left; one status glyph top-right (safety flag, trial visitor, said "I'm here", booked). A "N need attention" row above the grid filters to flagged people. Actions in a bottom bar: Scan (camera), Add visitor, Next: Teach. Tablet: more columns, same tiles.
  • Teach — phone: today's MasteryDial with the By student / By technique toggle. Tablet: the grid — students down, techniques across, sticky first column, each cell a 0–5 with recency tint; tap a column header for the technique; "+ Add item" adds a column. The divergence glyph stays. Per-cell sync state (pending / error / conflict) must be visible but quiet.
  • Wrap up — participants with roles, blocks covered, "Notes, feedback and homework" as a link to the per-student composer, Finish. One filled primary on this step.

6.4 Student profile

‹                                                (back, no title in bar)
GREEN BELT · 6TH KYU                             eyebrow — use the dojo's own rank label
Maya Chen                                        display
Last attended Tue · 14 classes since promotion   meta
[ one primary action ]                           context-dependent (see below)
READINESS   4 of 18 requirements left for Green Stripe · gaps listed
MASTERY     by category, 0–5 as pips + recency
ATTENDANCE  last 30 days · since promotion · all-time · recent sessions
NOTES       staff-only notes (private) · homework sent · feedback sent
CONTACT     call · text · email (or guardian, for a minor)

Actions: Write a note (staff-only), Send feedback or homework (reuses the post-class composer; the student is notified), Flag ready to test. The primary action is whichever is most useful for this student's state; the rest are bordered. Assumption to state in your output: "Flag ready to test" creates a task for the head instructor — this is not a decided product fact; say you assumed it.

7. The three takes — what must differ

Same architecture, same content, same palette. Vary these three axes and name your take by them:

Take A — "Ink" Take B — "Card" Take C — "Timeline"
Hero Full-bleed surface.hero block: eyebrow · statement · meta · one red CTA. The literal reading of the tab-home law. A white card on the tinted page: class name, a row of avatars (expected / already here), the plan's blocks as a compact list, CTA hugging left. No inverted block. Today's classes as a vertical timeline; the live/next class is expanded inline and is the hero; earlier classes marked done with "attendance recorded" or not.
To do One quiet row with a count, directly under the hero. The one tonal tile: three counts side by side, tap anywhere. Count in a header badge plus a one-line strip pinned under the title.
Doors Two quiet rows: Plan, Insights. A 2×2 grid of four doors: Classes · Students · Plan · Insights. A single "More" row opening one hub that lists everything.
Class Mode on tablet Grid with the step bar as a left rail. Grid with the step bar on top, roster avatars in the sticky column. Grid with a right-hand "this class" panel (plan blocks, notes, timer).
Student profile Strict detail formula, sections as white cards. Header card with rank + readiness ring; sections as one card of hairline rows. Readiness first as a checklist; everything else behind two segments (Progress · Attendance).

A take that differs from another only in spacing has failed the brief.

8. Edge states every take must show

  • Nothing scheduled today — hero quiet, To do carries the screen, "Open a class" still reachable.
  • New instructor, not on a roster — nothing greyed; the hero says what running a class requires ("You're set up to teach at Blue Heron. A head instructor adds you to a class; then it appears here.") and offers one action you propose. Read-only screens say so in one line, not a banner.
  • Student who never attended — the profile says "No attendance recorded yet" and nothing that implies otherwise.
  • Offline cell in Class Mode Teach — pending and conflict visible, not alarming.
  • To do empty — "Nothing waiting on you." and nothing else loud.
  • Error — "Couldn't load your classes." plain words, one Try again that inherits the weight of what failed (a failed screen gets the filled button; a failed section gets a bordered one).

9. Vocabulary — use these words

Concept Use Not
The gap engine Gaps Focus, What each class needs, readiness dashboard
Substitutes Subs ("1 class needs a sub", "Request a sub", "Claim") Coverage, cover
The unified inbox To do Your work, Inbox, Follow-ups (Follow-ups is a section of To do)
The run-class flow Class Mode (CTA verbs: Run class / Start class / Open class) Take attendance, Organizer
Attendance read side Attendance Attendance history, Attendance insights
The two hubs Plan, Insights Plan & curriculum, Schedule & insights
Lesson plan Class plan Lesson, session plan
The place dojo gym, studio, box, school
A student's grade rank in anything shared; belt when speaking of this dojo level, tier; "kyu" / "dan" only inside this dojo's own labels
A promotion exam test grading, assessment
Staff titles owner, head instructor, instructor, front desk admin, manager, coach

Voice: plain, second person, no exclamation marks, no emoji in chrome, no first person from the app. "Nothing graded yet. Add what you're teaching to start grading." Not "Nothing here yet — let's fix that!" A streak is stated, a rank is celebrated; never a guilt nudge about attendance. No mascot anywhere an instructor sees.

10. Hard boundaries

Never design into Teach: money, payroll, memberships, CRM, message blasts or automations, kiosk device management, the recurring-schedule editor, belt-test grading, incident review. No dojo switcher. No photograph in the hero — a solid block carrying type, because most dojos never upload an image. No swipe-to-act (nothing in the app swipes today; use bordered buttons). Do not invent a feature to fill a space; leave the space.

11. Facts you may rely on

  • Blue Heron Martial Arts is the demo dojo. Classes: Adults All Levels Tue/Thu 6:00 PM, Kids Beginners Mon/Wed 4:30 PM, Weapons Fri 7:00 PM (Marcus's class; Elena covers it), Open Mat Sat 10:00 AM. Plans: Green Stripe Prep (4 blocks), Kata Night. Students: Maya Chen (green belt, two gaps in Kata 1 and Kata 2), Riley Okafor (green, regular), Quinn Sato (white, week two), Jordan Alvarez (fading, 23 days quiet), Sam Whitaker (ready to test), a trial visitor "Lee, 6:00 PM, adult". Instructors: Dana Whitfield, Marcus Bell, Elena Ruiz. Owner: Morgan Reyes.
  • Ranks — the belt ladder is the dojo's own; show a belt dot with a ring and the dojo's label. Never render a rank name a component would have to know in advance.
  • Subs — a head instructor or owner assigns; the assigned instructor is told, not asked; any instructor may claim an open class; an assignment or claim is reversible until the class starts; the requesting and the covering instructor are notified.
  • At risk — a student quiet longer than the dojo's threshold, default 21 days.
  • Ready to test — every requirement for the student's next rank graded 3 or better.
  • Incidents — staff-only; the student is never notified and never sees it.
  • Check-in removal — allowed by anyone who can take a check-in; not undoable but audited.
  • If something is not in this brief, it does not exist. Say what you assumed; do not invent scope.

12. Design law — Konjo's, in full enough form to build from

The source of truth is a token file the app imports; the values below are copied from it. Use token names in your annotations, not hex, so an engineer can map every choice.

The one idea. Loudness is a budget, and each screen gets one purchase. Konjo is bold, athletic, high-contrast, heavy condensed caps — and the failure of loud is that everything shouts. Spend the volume once per screen; everything else is quiet enough to disappear.

The four budgets — ceilings, not quotas; zero is legal and common.

Budget Allowance Counted as
Loud block (hero, inverted surface, display type) 1, or none instances
Red role 1 — the primary action or a live/urgent state meanings, not pixels
Filled primary button 1 — everything else is a text link or a bordered control instances
Uppercase label register 1 — labels only, ≤3 words, never a sentence type tokens

Chrome (tab bar, header icons, the screen title) is exempt. Control state is exempt (a checked-in tile filled with surface.hero is state, not a loud block). A status glyph repeated down a list is one red role; a red button plus a red glyph is two, and one gives.

Tab home, hero-led (Teach is hero-led by law):

Title  typography.display 34/800                 24pt glyphs, 44pt targets
▓▓ full-bleed surface.hero ▓▓                    pad 20 h / 24 v, radius 0
▓ typography.eyebrow 11/800 caps · accent.onHero
▓ typography.statement 46/900 caps · text.onHero (reflow to 3 lines, then step to display)
▓ meta typography.body 15/400 · text.onHeroMuted
▓ [ ONE RED CTA → ] 48pt pill, hugs left         the block itself is NOT pressable
Quiet row  typography.rowTitle 16/600 + typography.caption 13 secondary   →
Quiet row                                                                  →
░ one tonal tile ░                               at most one

If a sixth section wants on the screen, it goes one tap away. Take B's white-card hero and Take C's inline timeline are deliberate departures from the inverted block — they still get exactly one loud element, one red role, one filled primary.

List row. Primary line typography.rowTitle 16/600; secondary typography.caption 13/400 in text.secondary; row ≥ 64pt. Never invert (never metadata above the subject). Hairlines inset to the text edge; five rows or fewer get no hairlines, just 12pt between groups.

Tile grid (check-in). About 111×92pt tiles, 3 across at 390pt, 8pt gaps. Ink fill = done, white = outstanding — never red, or the budget is spent once per tile. Belt dot top-left with a 1px border.control ring; one status glyph top-right; a tappable "N need attention" row above the grid is the legend.

Detail (student profile). Back chevron with no title in the bar → eyebrow (rank) → title (typography.display) → meta (typography.caption) → one filled primary, hugs left → eyebrow section → white card of rows → next section. The identifier is an eyebrow above the title, never a chip beside it.

Buttons. Primary: surface.hero fill (or brand.red when it is the screen's red role), height 48 (controlHeight.primary), radius.input, label typography.rowTitle 16/600. Secondary: no fill, 1px border.control, height 44, label typography.label 13/700. A full-width primary is not a pill; pills hug their content. Never disable a submit; validate on tap.

Empty. Eyebrow → title → what goes here and why → one filled primary → one text link, left-aligned and in flow — never centred in a void. First ask whether the screen should be empty at all. Error. "Couldn't load your classes." plain words, no codes, one Try again inheriting the weight of what it replaced. Loading. Under 1s nothing; then a spinner; a skeleton only where the layout is known.

Separation. White cards on a tinted page — surface.card on surface.page — never the reverse (a #FAFAFA card on white is invisible). No shadow, blur, glow or gradient. Group with 12pt of space, not dividers. border.hairline divides rows inside a card; border.control is the edge of anything tappable. A floating surface gets a scrim and a hairline, never a drop shadow.

Spacing ramp. 0 2 4 6 8 12 16 20 24 32 40 48 64 80. 8 is the spine; 4, 6, 12, 20 are legal half-steps (6 only for gaps inside a component); 2 is optical correction only. Aliases: spacing.page 20, spacing.section 24, spacing.card 16, spacing.tight 8.

Type scale. typography.hero 64/900 (a numeral only) · typography.statement 46/900 caps (the hero's words) · typography.display 34/800 · typography.metric 28/800 · typography.title 22/700 · typography.rowTitle 16/600 · typography.bodyLarge 16/400 · typography.body 15/400 · typography.caption 13/400 · typography.label 13/700 sentence case · typography.micro 12/500 · typography.eyebrow 11/800 caps — the only uppercase label register. Two sizes should carry any screen. Nothing under 11pt. No fixed-height container holding text.

Colour (light | dark). Name the surface you paint on and let the token resolve.

Token Light Dark Use
brand.red #D62828 #D62828 the red fill (white text on it)
accent.red #C42020 #FF5252 red as text on the page or a card
accent.onHero #FF5252 #C42020 red on the hero surface (the two swap by theme)
brand.ink #111111 #111111 brand ink; links, active tab, arrows
surface.page #F2F2F3 #0E0E10 the tinted page
surface.card #FFFFFF #1C1C22 white cards; input fill
surface.hero #111111 #F2F2F2 the inverting hero surface; primary button fill
surface.muted #FAFAFA #16161A tonal tile
surface.tag #F4F4F4 #232327 card-only; invisible on the page
text.primary #1F1F1F #F2F2F2
text.secondary #6B6B6B #A8A8AE captions, section eyebrows on the page
text.tertiary #737373 #909094 card-only — fails on the page in light
text.onHero #FFFFFF #131313
text.onHeroMuted #A8A8AE #5A5A60
border.hairline #E8E8E8 #2C2C2F row dividers inside a card, inset
border.control #88888C #6A6A72 edge of anything tappable; belt-dot ring
border.input #D8D8D8 #3A3A40 input edge; skeleton placeholder on surface.card or surface.page alike
border.focus #1F1F1F #F2F2F2 2px focus ring
feedback.errorFill / feedback.errorText #FDECEE / #B73232 #3A1518 / #FF6B6B error pair, used as a set
feedback.warningFill / feedback.warningText #FFF6E0 / #8A6300 #332A0E / #E8C35A warning pair (fading student, safety flag)
feedback.infoFill / feedback.infoText #EAF2FB / #1F4F8A #13263A / #7FB3E8 info pair
feedback.successFill / feedback.successText #E6F4EC / #1A7A42 #11301E / #5BC487 success pair
gold.fill / gold.text #FFF4D6 / #8A6300 #2A2310 / #E0A800 achievement only — not for status
overlay.dim rgba(0,0,0,0.35) rgba(0,0,0,0.5) sheet scrim

Retired, never use: any band.* token, the diagonal band, text.quaternary as a text colour.

Radius. radius.input 8 · radius.card 12 · radius.large 16 · radius.sheet 24 · radius.pill 999. Nothing else. Icons 16 inline / 24 standalone / 19 status glyph. Avatars 32 in rows, 88 on a profile. Chips 32 tall, 12 pad-h, pill radius, surface.card fill + border.control; chips wrap, never scroll horizontally. Touch targets ≥ 44×44pt. Pressed opacity 0.85. Motion 100–350ms, exits faster than entrances, nothing over 400ms.

Sheets. Grabber, left-aligned title, rows ≥ 64pt with a check on the selected row, top corners radius.sheet, overlay.dim scrim and nothing else. Chips inline for 2–6 options; a sheet for 7–20; a sheet with pinned search for more; the native picker for dates and times.

Serious actions. State the consequence before the tap; never pre-select a field that carries judgement; clinical copy; destructive actions arm on first tap, fire on second.

What never ships. A screen with no empty state. A mutation with no error path. A list with no loading state. Two controls of equal weight competing to be primary. A centred button floating in a void. Truncation as layout. Text over a photo or gradient. A gradient nav bar. A decorative accent that means nothing. A row whose metadata is larger than its subject. Copy in developer voice. A hardcoded hex where a token exists.

The bar. The instructor with one free hand gets what they came for on the first screen, without reading a paragraph, and would do it again next week. If you cannot point at the one loud thing on a screen within a second, it is not finished.

13. How to respond

  1. Design only the three screens in §1, in the states in §8, for each of the three takes in §7, at 390pt and ~1024pt, light theme.
  2. Preserve every capability listed in §3 somewhere reachable. You may regroup, rename to the fixed vocabulary, nest into the two hubs, or fold into Class Mode — that is the job — but nothing an instructor can do today may disappear. For each take, include a table: today's twelve rows → where each now lives (and how many taps).
  3. Stay strictly on the palette, type scale, spacing ramp and budgets in §12. Annotate with token names. Compute contrast; do not eyeball it.
  4. Use the Blue Heron content in §11. Show real-looking names, belts, times and counts, and at least one unhappy state per screen.
  5. If you are unsure whether something exists in the product, it is in this brief or it does not exist. Write a short Assumptions list per take rather than inventing scope. Flag the "Flag ready to test" assumption explicitly.
  6. For each take, one paragraph of rationale: what it optimises for, what it gives up, and which parts are easiest to lift into another take.
  7. Do not merge the takes into one recommendation. The founder will mix them.