Design document

Download as .md Case study

Status. Draft for Dean's review. Drafted with AI (Claude); nothing here has been reviewed by a subject-matter expert. Facts about a real client are unknown (see the open items at the end).

1. Summary

A safety training for maintenance techs, groundskeepers and property managers, built as a deck of slides that fills a computer screen and stacks into one column on a phone. It teaches four hazards (shock, fire, falls and heat) and three moves for each (see it, stop it, report it), then tests all twelve.

Five lessons, each in the same order: learn (short slides with diagrams, pictures you tap through, steps and examples), practice (one or two short checks, a card drill, and writing a report, none scored), prove it on the job (a scene where you decide and see what happens), then a scored test after lesson 5 that returns a personal grid of what is solid and what to look at again. A one-page field card is the same grid.

It replaces v1, an eight-screen topic-first course with one recall question. v1 is kept, unedited apart from a banner, for a side-by-side comparison.

Why the design changed three times.

1. The first v2 jumped from a two-line welcome into scenes. The first reaction was right: there was no training in it. It tested what a learner already knew and taught nothing.
2. The second version taught first, then practiced, then tested. A separate model reviewed it cold and called it "well built and conventional." Its test was the weakest part: the longest answer was the key on 14 of 16 questions, the picture questions numbered the hazards 1 to 5 with markers on top of them, and a learner who knew nothing about safety could pass. The learner never wrote a report or pushed back on a senior coworker. Section 12 lists what it found and what changed.
3. The third version fixed the test, made the practice produce answers instead of recognizing them, corrected the safety framings that a safety professional would have raised, then cut the length to about an hour and added drawn diagrams (section 13).
4. This version changes how it feels. Dean opened it on a computer and said it was a phone design on a desktop, tall and narrow, with page scrolling where he wanted slides he could click back and forth through; the introduction was ungrounded and named a city it did not need to; the drawings looked like a child's crayon work; and nothing moved, so it felt static. Section 14 lists what changed.

2. Audience

Assumption (no client data was supplied):

• Who. Maintenance technicians, groundskeepers and property managers at a mid-size Honolulu property-management company. Some have been on the job for a decade; some for three weeks.
• What they know. The trade. Not the regulations, and not always the reasons: that tape is not a repair, what an anchor must hold, what the signs of heat stroke are.
• What they don't have. Time at a desk. The training has to work on the phone they already carry, in sittings of about fifteen minutes.
• Constraints. Sun glare, gloves, interruptions, patchy signal in stairwells and parking structures, and often a supervisor who is not in the building.
• Motivation. Mixed. Most want to be careful. What stops them is the crew waiting, a senior coworker's "it is fine," and not wanting to be the person who made a fuss. Lesson 5 and four of the scenes address that directly.

3. Delivery context

4. How the training teaches

Each lesson follows the same plan, so the learner always knows what comes next.

After lesson 5, the test asks twelve questions, one for each cell. It differs from the practice in five ways: no feedback until the end, one try on each question, situations that are new rather than repeated from the lessons, a score, and a rule that a dangerous answer cannot pass (section 6).

Interactions, and the job each does

• Tap-to-explore pictures (four): a cord laid out end to end, a utility closet, a balcony, and a made-up product label. The learner taps numbered points and reads what each means. The closet picture asks first: the learner sorts each point as fuel, flame or heat source, something that lets vapor build up, or a warning sign, sees whether that was right, and only then reads why. A Zoom button doubles the picture for a small screen.
• Use it or tag it (lesson 1 practice): five cords, one at a time, with feedback on each and a time per cord at the end. The lesson's goal is to spot a damaged cord in about ten seconds, so the practice is timed against that goal. Half the cords are fine: age and mud are not defects. This is the one place the training drills discrimination, not recognition.
• Steps with icons: the "stop it" teaching. Short, numbered, one line of reason each, with a small icon (a plug, a tag, a door, a message; a flame and a switch crossed out; shade, a wet towel, a phone, two people) that says the step before the words do.
• Diagrams (eight, drawn for this training): how a GFCI works, fuel plus a flame, what to do when you smell fuel or gas, the edge triggers and the guardrail, anchor-connector-harness, the signs that mean call 911, the Rule of 20 Percent as a bar chart, and the ladder to climb when a report goes nowhere. Each one carries only facts that are already in the sources log, and each has the same content in words for screen readers.
• Four-part report: shown as a weak example next to a strong one, then written by the learner. In lessons 1 and 5 the learner reads what happened, writes where, what, how bad and what they did in four boxes, and compares with a model. A word check lists which key facts the message mentions and says plainly that it checks words, not sense. An sms: link opens the text in the learner's own messages app. The training sends nothing. This is the generation practice that the first review said was missing: "Report it" is a third of the grid.
• Hold up (lesson 3): the learner builds an opening and a next step. The options change order each run and the beat labels do not give the answer away. Then Ray pushes back: "Relax, two minutes," then "You are three weeks in. You do not know this job." The learner picks a second and a third line. If he keeps going, the rule is to step back and call. This is the hard part of the skill, practiced.
• Who-to-call tool (lesson 5): pick the situation, see the answer and a tap-to-call number.
• Find the hazards (five test pictures): see the picture, tap the objects you think are a problem. No markers are drawn, so there is nothing to count and nothing covering the objects. A fire extinguisher, a sound stretch of railing and a neat coiled cord are real decoys.

The calculator for the Rule of 20 Percent and the do-and-don't columns from the second version were cut. The calculator answered a question a new worker does not control (the crew lead sets the hours), and the do-and-don't block was each "do" turned upside down. Both are now one sentence.

The grid

Four hazards by three moves make twelve skills. The same grid is the map, the test blueprint, the results screen and the field card. A learner who sees "Fall, Stop: review" has a Review button on that cell that opens the lesson page that teaches it, and the results screen is saved, so it is still there after a reload.

5. Tone

• Second person, present tense, plain words. Grade 4 to 6 reading level (approximate: Flesch-Kincaid grade 4.1 on a sample of the lesson prose, by a syllable-count heuristic that undercounts long words).
• Respectful of the learner's expertise. The training never lectures a tech about their trade.
• Plain English only. The original used Hawaiian words in its title and text. At Dean's direction v2 says the same things in ordinary English: care, responsibility, balcony. The module's name is now "Property Crew Safety," with the line "See it. Stop it. Report it." The place is still Honolulu, and the law is Hawaii's.
• The consequences are honest but not gory. Nobody dies in the training. A near miss is enough to make the point, and some partial choices end in "you got away with it," which is how risk feels.
• Characters are ordinary. Marcus is the supervisor. Ray is a twelve-year veteran who has taught the learner a lot. None is a villain. The pressure is social, not personal.
• Text for the learner is for the learner. Hedges meant for a reviewer ("a safety professional should confirm this") live in these documents, not on the screen. Where the training gives practice guidance rather than a quoted rule, a short "this is practice guidance" label says so.

6. Assessment strategy

• Practice is practice. One or two checks per lesson, plus the drills, the sorting and the writing, with feedback, not scored. Seven checks in all; the pool of twelve other practice questions is used in the welcome-back quiz.
• Scenes are practice at the level of the behavior. The first choice is recorded, and so is the retry, so the number of tries is visible.
• The test is the assessment. Twelve questions, one per cell of the grid, drawn from a bank of 32:
  • the See cells have two versions each (a find-the-hazards picture, a second picture, a use-it-or-tag-it drill, or a select-all);
  • the Stop and Report cells have three versions each.
• Every situation is new. None repeats a lesson scene, and none is a lesson check with a word changed. The earlier build claimed this and did not deliver it. The Report cells also carry what lesson 5 teaches (what a supervisor must do, what protects you, how long you have to file), so lesson 5 is tested.
• A retake is a different test. Each retake draws a version the learner has not seen for each cell, until all have been seen.
• Answers stay hidden until the learner passes. A failed attempt shows the grid and which lesson pages to review, not the answer key. Otherwise a retake becomes a memory test of the answer sheet.
• Scoring.
  • Single choice: 1, 0.5 or 0. Half credit goes only to a sensible but incomplete answer. A dangerous half-measure scores 0.
  • Select-all: right picks less wrong picks, over the number that are right.
  • Find the hazards: each missed hazard costs one share of the hazards; each false alarm costs half a share of the fine objects. Tapping everything scores 0.5 at most. Tapping nothing scores 0.
  • Use it or tag it: the share of cards sorted right.
• A dangerous answer cannot pass. Pass is 80 percent or more and no dangerous answers. A dangerous answer is a flagged option (for example "use the cord, no copper is showing"), a critical hazard missed in a picture (the open edge), a critical sign left out (confusion, slurred speech, hot dry skin, seizure, passing out), or a damaged cord with bare wire passed as fine. This is how certification exams treat critical errors. The earlier build let a learner choose four dangerous half-measures and still pass at 83 percent.
• No giveaways. Options within a question are close in length, shuffled on every run, and the best answer is not always the longest. tools/metrics.js counts, over every single-choice set (58 of them), how often the best option is the longest, the shortest, or in the middle, by words and by characters, and flags any set where it is more than 40 percent longer than the others. The test items are balanced on purpose in both directions, because always-longest and always-middle are both cues: by characters the keyed answer is the longest on 8 of 24, the shortest on 8 and in the middle on 8 (by words, 5, 9 and 10). The earlier build was the longest on 14 of 16. A first count by words understated the problem, which a reviewer caught by counting characters.
• The 80 percent mark is a design choice for this demo, not a legal requirement. A real client sets its own, and would set it after item analysis on real learners, which has not been done.
• Diagnostic, not only a score. The grid marks each skill Solid, Partly, Review or Dangerous. For each, a button opens the page that teaches it. After a pass, the results also show each missed question, the learner's answer and the best one.
• LTEM tiers. The practice sits at Tier 4 (knowledge, kept to what a worker needs in order to act). The scenes, the sentence and report writing, and the test sit at Tier 5 (decision-making in realistic situations). Tiers 6 to 8 cannot be observed inside the training and are planned in the evaluation plan.

7. Accessibility plan

Target: WCAG 2.2 level AA for the training, the field card and the case study.

Not yet done. The build has been checked with automated tools (axe-core on every kind of slide, 93 states, no violations) and by keyboard. It has not been tested with a screen reader on a real phone, with switch access, or with voice control. The find-the-hazards questions in particular should be tried with a screen-reader user before they are relied on.

8. Visual design

The first look was a field notebook: warm paper, hi-vis tape, black outlines two pixels thick, hard offset shadows and a typewriter face for labels. Dean's review of it: it looked like a child's crayon drawing, and it felt more like a phone app than a course. The look was replaced.

• Slide. A white card on a cool grey stage, 22 px corners and a soft shadow, with a faint tint in the top corner. Each lesson has its own color: amber for shock, red for fire, blue for fall, orange for heat and green for speaking up. The color tints the small label above each title, the corner glow, the numbers on steps and the icons, so the learner knows where they are without reading.
• Type. System fonts only, so nothing loads from the network. Titles are heavy and tight, body text is 17 to 19 px on a computer, and the labels are small capitals in the same face (the typewriter face is gone).
• Controls. One navy button, one white outlined button, one amber button for the big step (Start lesson, On to the test). Answer cards have one-pixel borders and lift a little under the pointer. Feedback appears in a panel beside the question, not under it.
• Palette. Ink #0F1B2D, navy #12284A, stage #EDF0F5, hi-vis amber #F5B301 (a fill with dark text on it, never text on its own), safe green #0C7A5C, danger red #C2362B, sea blue #1F5FA8. Text and tint pairs were checked for contrast.
• Illustrations. The same drawings, redrawn in one flat style: slate outlines about one and a half pixels thick instead of black outlines of three and a half, softer fills, no hand-drawn dashes except where a dash means something (vapor, a missing part, the path of a leak). The four tallest diagrams have a wide version for a computer (the GFCI, the smell flow chart, the heat signs and the ladder) and keep the tall version for a phone; the page picks the one that fits the space it has.
• Pieces. "What happens" and "Why" are white and tinted cards in the feedback panel. Messages look like text-message bubbles. The grid is a four-by-three table of colored cells that fill in one after another.

9. Technical design

Plain HTML, CSS and JavaScript. No build step, no framework, no CDN.

demo/
  index.html      the shell: header, stage, the Back and Next bar, session-data dialog
  style.css       tokens, the slide layout and components
  content.js      all lesson content: pages (a "break" block starts the next slide), blocks, checks, welcome-back pool, scenes, sources, the five introduction slides
  test-bank.js    the test items (32), their versions and scoring flags
  art.js          the teaching pictures and the header drawings
  diagrams.js     the diagrams (four with a wide version) and the line icons
  ui.js           shared helpers: scenes with tap areas and zoom, ordering, links
  motion.js       the entrance timeline, pops for feedback, drawing a diagram piece by piece, count-up for numbers
  intro.js        the five introduction slides
  blocks.js       the learn blocks: explore (with sort), figure (diagram), steps with icons, cards, report, sentence builder,
                  push-back turns, write-your-own report, who to call
  items.js        the question types: choice, select-all, order, find the hazards, use it or tag it
  decide.js       the "prove it on the job" scenes
  app.js          the controller: routes, the slide builder, the Back and Next bar, the arrow keys, map, lessons, return warm-up, test, results, session data
  tracking.js     xAPI-style statements in localStorage
  job-aid.html    the one-page field card with print CSS and a write-and-send report panel

• Content is data. A new lesson is a new object in content.js. The storyboard is generated from the same files the training runs on.
• Slides. A slide has a head (label, title) and three regions: a for the text, b for the picture or the thing to do, w for a full-width row. Each block type has a default region; once a full-width block has appeared everything after it stays in that row, so the order on the slide is the order in the lesson. Above 62 rem the regions sit in a grid; below it they stack in the same order. A picture container asks how wide it is (a container query) and shows the wide or the tall version of a diagram.
• Routes. Each slide has a hash address (#/intro/2, #/map, #/lesson/shock/3, #/review/shock/0/1, #/test/4, #/results). The test uses replace, not push, so back leaves the test instead of stepping through answered questions, and an answered question cannot be shown again.
• Saved state. localStorage holds progress, the lesson position, the test in progress (item ids and results), the last result, the versions already seen, and the time of the last visit. Everything degrades to memory if storage is blocked.
• Return warm-up. After 20 hours or more away, the map offers three warm-up questions from lessons already finished, weakest test skills first. It can be skipped.
• Tracking. Verbs: initialized, experienced, interacted, answered, preferred, completed, scored, passed, failed. Every statement carries the stage (check, apply, test, practice or return), the grid cell, and the score or quality. Stored in localStorage. Nothing is sent anywhere. The shape is xAPI-style and has not been validated against a learning record store. The training labels it as a demo.
• Why local only. A real deployment needs a server and consent language. The decision log says no backend until someone pays for it. Local statements give a dashboard project (P6) real-shaped data to build against.
• Offline. No requests are made after the page loads. Reopening the page offline needs a service worker, which is not included.
• Browsers. Current Chrome, Safari, Firefox and Edge. dialog and :has() are used; both are supported in current versions.

10. What was cut from v1, and why

11. Known limits

• Ladders, lockout, and chemical labeling beyond the flame symbol are not covered. A ladder standard is in HIOSH's FY2025 top 10, and the review asked for it. Fall is built around a removed railing panel because that is the scene the action map calls for; ladders are a second module. The welcome screen says so.
• Practice steps have not had a subject-matter review. They are grounded in OSHA and CPSC pages (see the legal sources), but the order of steps, the breaker-off step, the strong-smell rule and the wording of "Hold up" are standard practice that a safety professional should confirm.
• No learner has used this. Timing, difficulty and tone are unproven. The test items have not been through item analysis. The word check on written reports looks for words, and the training says so.
• The environment gaps are not fixed by the training. See the action map: spare cords and tags, harnesses and anchors, an easy report channel, a reply to each report.
• Fictional setting. Names and events are invented.
• Length. About 60 minutes is still a lot for a phone, though it is built in short sittings with saved progress. A pilot should time real learners and say what else to cut. What the cut to 60 removed is in section 13.
• Supervisors' side. The training speaks to the supervisor once (lesson 5: reply the same day, act before the shift ends). A property-manager path would be a separate piece.

12. What two independent reviews changed

A model other than the one that built this reviewed it twice, cold, with no brief beyond the files and the running page. The log is in the AI review log.

• First review, of the second version. Originality 5, instructional soundness 6, learner value 5, accuracy 7, phone 6, test 3. It would interview the designer "narrowly." The findings that changed the build: longest-answer key on 14 of 16 test items; hazards always numbered 1 to 5 in the picture questions; a learner with no knowledge could pass; test items that were lesson scenes renamed; dangerous half-measures earning credit; lesson 5 never tested; no GFCI or breaker content; heavy sweating filed under "stop and cool"; driving a confused worker to urgent care rated "partial"; a strong fuel smell escalated only to the supervisor; stop-work shown as law; no history routing; a reload lost the learner's place; a sideways-scrolling field card; and a 40-minute claim for about 90 minutes.
• Second review, of this version. See the log for the scores and what was and was not acted on.

13. The cut to about 60 minutes, and the visuals

The second review and the first both said the build was too long, and Dean asked for about 60 minutes and for visuals that support the content. Three principles decided what to cut: keep what a worker does (the drills, the writing, the scenes, the pushback), cut what repeats (a second explanation of the same fact), and let a picture replace a paragraph.

Visuals. Eight diagrams and 18 line icons, all drawn for this training as inline SVG. Each replaces a paragraph or a list: a diagram of how a GFCI works instead of a sentence about leaking current; a flow chart for the smell of fuel or gas; the guardrail and the edge triggers drawn to scale; anchor, connector and body harness as a chain; a signs board for heat; the Rule of 20 Percent as a bar chart; the ladder to climb when a report gets no reply. Steps carry icons. The four report parts are colored the same way in every worked example and in the learner's own message. Each lesson opens with its header drawing, and the welcome screen and the training map carry a hazard icon for each lesson.

Why drawn, not photographs. The brief allowed diagrams, vector images or open-source photographs. Photographs would have meant choosing and downloading files and keeping their licenses and credits, and the training promises that nothing loads from another site. Drawn diagrams also say exactly one thing each, and they scale to a phone. A photograph of a real worker at a real edge, or a real GFCI outlet, would add a different kind of value, and the public-domain OSHA and NIOSH image libraries are the place to look. It is listed in QUESTIONS.

What the cut cost. Lesson 1 no longer has a scene about replying to Marcus, so the "Shock, Report" cell is practiced by writing the report instead; the fire and fall report cells are taught by the lesson 1 page and the scenes, and tested; and the practice checks are fewer, so the test carries more of the weight. The 12 test questions are unchanged.

14. From a phone page to a slide deck, and why it moves

Dean opened the 60-minute build on a computer and said five things. This is what each one led to.

What this cost. Time: the introduction and a few bridging sentences on slides that would otherwise have held a diagram alone added about two minutes. The model now says 64 minutes (54 at 240 words a minute, 72 at 150), still labeled Projected. The lesson texts, the checks, the scenes and the 12-question test are unchanged.

What this did not do. No learner has used it, so whether the motion helps or distracts is a pilot question. A screen reader on a real phone is still untested, and the diagrams' wide versions are drawn by hand, so a fifth diagram added later needs both versions.

15. Open items

These are not settled, and the design does not depend on them, but each would change what the case study can say.

• Whether the original was built for a real client, and what may be said about it. Until that is known, no client is named.
• When the original was built, with which tools, and what the review role was.
• Whether a real group of learners ever used it, and any feedback or quote. None is claimed.
• A subject-matter review of the practice steps.
• Whether the HAR sections still read as they did in the version HIOSH links today.
• The items marked "pending review" in the legal sources.