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:
- Teach home — in two states: a class live or starting soon; nothing scheduled today.
- 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.
- 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)
- 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.
- Two run-class flows for one job (§3.2), entered from different rows, with different controls for the same 0–5 grade.
- 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.
- 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.
- "Scan check-ins" is the one row never greyed, so a new instructor can open a scanner and nothing else.
- The new-staff state is a dead end: a gold card with no action and nine greyed rows.
- 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.
- Design-law defects: the hero uses retired tokens; section labels use
text.tertiaryon 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. - Student detail is attendance only. An instructor cannot see belt, mastery, readiness or notes for one person in one place.
- 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
- 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.
- 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).
- Stay strictly on the palette, type scale, spacing ramp and budgets in §12. Annotate with token names. Compute contrast; do not eyeball it.
- Use the Blue Heron content in §11. Show real-looking names, belts, times and counts, and at least one unhappy state per screen.
- 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.
- 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.
- Do not merge the takes into one recommendation. The founder will mix them.