Lab Skills on the Academy Lesson Row — Design

Date: 2026-08-03 Status: Design approved except one open item (level wording, see §9) Mockup: mockups/lab-skill-row-mockups.html (self-contained, opens with no internet) Decided by: Mario, via chip interview + six mockup iterations on 2026-08-03

1. What this is

Mario's ask was "we need to add the lab skills the user will learn per lesson or unit per ase module." That split two ways and only one half turned out to be real work:

• (a) Author the missing labs. ALREADY DONE. The B2 backfill shipped in the commits pulled on 2026-08-03. The generated doc now reports 424 lessons carry a lab (B2 76, B3 82, B4 76, B5 95, B6 95), 2,119 procedure steps, 1,920 scored checks, 2,108 instructor sign-off lines. The only 4 lessons without a lab are SPRAYGUNS, DENTTYPES, VEHICLETYPES, BATTERYTYPES, all retired showcase decks that appear in no student menu. Nothing left to author.
• (b) Surface the skills to the student. This document. Chosen framing: a skills passport, meaning a per-student record of what they can actually do, not a marketing list.

Placement, in Mario's words: "it should be on the lesson box, to the right side, next to the practice, test, start buttons." So the passport is not a separate page. The Academy lesson list itself becomes the roadmap, one row per lesson, each carrying that lesson's lab state.

Scope: current module only (not a career-wide record across B2 to B6).

2. The lesson row, final

Rendered in simulator.html, inside academySelectUnit, around line 7698. Current action group (.atp-actions) holds: Practice icon (.atp-tp), Test icon (.atp-exam), then the open button (.atp-open). Final order after this change:

[Practice] [Test]  [ LESSON / Start ]  [ LAB / Not attempted ]

Both text buttons become two-line pills sharing one geometry block:

Both pills measure exactly 32px tall. They share one CSS rule for geometry rather than two, so they cannot drift apart when either is edited later.

Why explicit pixel sizes, not em

The surrounding row CSS is written in em, which compounds. The difficulty-modal sizing failed twice for exactly this reason (see CLAUDE.md: .diff-btn span matched both the wrapper and the inner span). The two pill text lines are therefore fixed px with line-height: 1. Do not convert them to em.

3. The six LAB states

Three earned levels are metals; everything below is a flat outline. A metal always means the student earned something.

The metal recipe

All three metals use one shared .metal class carrying a diagonal gloss sweep. The sweep fires ON HOVER ONLY, once per hover — it never loops (Mario, 2026-08-03).

.metal::after{content:"";position:absolute;top:0;left:-70%;width:45%;height:100%;
  background:linear-gradient(100deg,transparent,rgba(255,255,255,.85),transparent);
  transform:skewX(-18deg);pointer-events:none}
@media(hover:hover){.metal:hover::after{animation:shine .85s ease-out}}
@keyframes shine{from{left:-70%}to{left:130%}}
@media(prefers-reduced-motion:reduce){.metal::after{display:none}}

The pill needs position:relative; overflow:hidden for the sweep to clip correctly.

Three things this buys, all deliberate:

• A unit full of metal pills is not constantly animating. A looping sweep on a dozen rows was visual noise and a needless repaint cost on a page students leave open.
• @media(hover:hover) keeps touch devices out of it. Phones and tablets have no real hover and can otherwise get stuck in a hover state after a tap. The consequence to accept: students on a phone never see the sweep. That is fine, because the metal reads as metal from the gradient and bevel alone; the sweep is a flourish on top, not the thing carrying the meaning.
• prefers-reduced-motion removes the element entirely, so there is nothing to animate at all.

Verified in-browser: default state has animation-name: none with the sweep parked off-screen at -95px, the hover rule resolves to 0.85s ease-out ... 1 normal ... shine (iteration count 1), and the word infinite appears nowhere in the stylesheet. Exact gradients for copper, steel B and gold are in the mockup and should be copied verbatim.

All metals are pure CSS, no image, so they stay crisp at any zoom and add zero network requests.

Rejected along the way, with the reason

• Tiny level dot on an icon button. Mario wanted the level readable at full size, not decoded.
• Filled pills for every level. A solid pill next to the solid orange Start competes with it; outlines read as status so Start stays the thing a student taps. Only earned metals are filled.
• "Awaiting sign-off" as the ungraded wording. Measured 176px against 138px for the level states. At 375px it does not fit beside the LESSON pill and wraps the row onto a second line. Replaced with "Ungraded" (138px), which Mario chose. Proven cut-off is 154px, since "Not attempted" at 154px stays on one line. For the record: "Pending sign-off" 169px fails, "Needs sign-off" 154px and "Not signed off" 153px would have passed.
• Inline LAB tag instead of stacked. Saved 1px of height. Not worth losing the stacked look.

4. The repetition count

Shown as xN at the right end of the LAB top line, using space that was already empty. It costs zero width and zero height: every pill is still 138px wide (154px for "Not attempted") and 32px tall with the count present, including the two-digit x10.

Rule: the count shows from the very first rating. A rated lab always carries at least x1. The two states with no rating yet, Ungraded and Not attempted, carry no count, because there is nothing to count and x0 would read as an error.

Practice targets, shown in the legend only

These are a guide, not a promotion rule. This matters and was raised with Mario explicitly:

• LABLEVEL_V1 deliberately does not derive the level from a score or a count, because "a student can tick every box on a lab they were walked through and still not be Proficient." Publishing "repeat it 3 times to become Practiced" risks students reading the count as the thing that earns the level.
• There is also a notation collision: the pill's x3 means runs completed, while the legend's x3 means runs typically needed. A student at LAB x3 / PRACTICED could conclude they are owed Proficient.
• Resolution: the legend words it as "Usually takes about N runs of the lab", and the legend's xN entry states outright that hitting the number does not promote you, the instructor sets the level after watching you work. Mario accepted this framing.
• Not built: reps auto-assigning the level. If that is ever wanted it is a separate decision, and it would let a student reach Mastered by repetition alone.

Practical note flagged to Mario: at 10 ratings for Mastered across 424 labs, Mastered becomes rare. That may be intended, since a gold pill should mean something, but 10 is the number to revisit if Mastered should be reachable within a semester.

5. The skill card (what the LAB pill opens)

Opens that lesson's own skill, not a separate passport page. Content, per Mario's choice "show the standard, hide the scored questions":

Always visible

• SKILL: what the student will be able to do
• THE STUDENT: the numbered shop procedure
• JUDGED BY: the quality standard
• SIGNED OFF: the instructor rubric lines, so the student knows the target
• SAFETY: the PPE and hazard note

Hidden until the lab has been done

• CHECKED ON: the scored in-lab questions. Revealing these in advance would stop them measuring anything.

After rating, everything unlocks, including which rubric lines they missed, their level, the date, and the rep count.

6. The unit legend (Legend B)

Sits at the bottom of every unit's lesson list, after the rows, inside a bento card per CLAUDE.md rule 15 (accent top border, title, short description above the content).

Layout: a vertical list, real pill on the left, meaning on the right. 9 rows total.

1. Six rows, one per state, each showing the real pill at its typical rep count (Exposed x1, Practiced x3, Proficient x5, Mastered x10; Not attempted and Ungraded carry none) with the meaning and the "usually takes about N runs" line beneath.
2. A divider, then three rows explaining the rest of the row: the Practice icon, the Test icon, and what xN on the LAB button means.

Using the real pills in the legend rather than swatches is deliberate. A student matches what is on the row to what is in the key without translating anything.

Rejected: a grid layout (three across, more compact but harder to scan), and a collapsed "What do these mean?" bar (saves room but a first-timer has to notice and tap it).

7. Data

Read at runtime

lab_grades/{studentUid} — one document per student holding every lab they have ever done, so the whole passport costs a single Firestore read. This matches the caching discipline in CLAUDE.md; do not add a per-lesson read.

lab_grades/{studentUid} = {
  "<deckId>": {                       // e.g. "b5-l04"
    score: 4, total: 5, pct: 80,
    lines: [true,true,false,true,true],   // index-aligned to the deck's rubric lines
    level: "proficient", levelNum: 3, levelLabel: "Proficient",
    reps: 3,                              // true count, may exceed attempts[].length
    first: <ms epoch>,
    attempts: [ ... ],                    // capped at 12: first + latest 11
    lessonTitle: "...", lesson: "Lesson L04", module: "B5",
    by: "<admin email>", at: <ms epoch>
  }, ...
}

Field names are an external contract (the STC Collision Portal Phase 2 consumes them). Keep lines[] index-aligned or old grades silently mislabel.

State derivation for the pill:

Read for the skill text

The skill content lives in each lesson's labassignment block, inside the deck files and Firestore. The menu cannot load 95 decks to paint a unit. It needs a small generated lookup, following the existing _deck-versions.js pattern, keyed by deckId and carrying at minimum the SKILL line (and ideally the procedure, standard, rubric and safety for the card).

functions/scripts/academy-build/build-lab-skills-doc.js already harvests exactly this content for the human-readable doc, so the generator should be extended rather than rewritten. Re-run it after any lesson change, same rule as build-deck-versions.js.

Precedent for the menu-side lookup: window.ACADEMY_LESSON_META (time, slides, ASE tasks).

8. Measured constraints (verified in-browser, not estimated)

Why the row height does not grow: the time chip and ASE task chip under the lesson title already make the row taller than any pill, so the pill growing from 28px to 32px is absorbed.

9. OPEN — needs Mario before build

The four level definitions. These are my draft of his ladder, and students will read them as the definition of their own skill level. They are his grading language, not mine:

• Exposed: "You performed the skill with help and guidance."
• Practiced: "You performed the skill on your own."
• Proficient: "You performed it to standard, without help."
• Mastered: "You can do it to standard every time, and show someone else how."

Two smaller ones, both with a defensible default if he does not care:

• Should Ungraded and Not attempted show x0 instead of no count? (Default: no count.)
• Is copper too close to the amber Exposed outline? Shown side by side in the mockup. In practice the fill does the separating, since Exposed is a white pill with a thin amber edge. A cooled-off grey-blue Exposed is mocked up if he wants maximum separation.

10. Implementation notes for the build session

• simulator.html is ~1.3 MB. Give the build a fresh session with room.
• The row CSS lives inside _atpInjectCss, a JS string-concatenation block. Injected CSS must be a single line with no newlines, or the whole main script fails to parse. This has already cost one syntax error historically.
• Never let an opening brace sit directly against a hash anywhere in simulator.html — that pair opens a Nunjucks comment and kills the build with "expected end of comment, got end of file". Write ){ #someId{...}, with a space. Pre-deploy check: searching simulator.html for that pair must return 0. ⚠ This document may not contain the pair either. It is a .md under docs/, which Eleventy renders through Nunjucks as a page, so the first version of this spec — which quoted the two characters literally, three times — broke the build for the entire repo ("Wrote 0 files") until it was reworded on 2026-08-03. Describe the pair; never type it.
• Syntax check before deploy: the inline-script checker in CLAUDE.md should report 24 scripts, 0 errors.
• Mobile rules already in the file: @media(max-width:760px) sets .atp-ltext to full width and .atp-actions to width:100%. The pills must take flex:1 1 auto; min-width:0 there, matching how .atp-open already behaves, or they will not share the line.
• Deploy target is --project ase-portal-5d37c, verified twice (CLAUDE.md rule 5a; a hook blocks any deploy without the explicit flag).
• Google Drive clobbering is no longer a risk as of the 2026-07-31 move to /Users/Shared/asecollisiontestprep.com, but git is now the only sync between the two Macs.

11. Explicitly out of scope

• A separate printable or exportable student passport page. The lesson list is the passport.
• A career-wide record spanning B2 to B6. Current module only.
• A skills section on the b2 to b6 sales pages. Possible later; it would reuse the same generated data.
• Reps auto-assigning the level (see §4).
• Anything touching the instructor grading flow, the gradebook, or the STC portal feed. Those are built and unchanged.