---
title: Design document
summary: How the course is built and why. Four places and three moves, scenes where the risky choice fails, a test that fails dangerous answers, and the records a hotel with high turnover needs.
---

# Design document

**Project:** Human Trafficking Awareness for Hawaii hotel staff, "Notice it. Don't confront. Report it."

**Client:** none. A portfolio piece set in a fictional 64-room Waikiki hotel, the Seabright. The plan is to offer it to real hotels later.

**Built on:** the engine from the Property Crew Safety course (P3): a slide deck with Back and Next, a 4 by 3 skills grid, scenes, a diagnostic test and xAPI-style tracking. This course forks that engine.

## 1. Purpose and scope

The course gets every guest-contact worker to notice the signs of trafficking, keep the moment safe, and report it the same shift. It is built to the five content parts Hawaii's Act 191 lists (see the [compliance map](compliance-map.html)).

| In scope | Out of scope |
|---|---|
| Signs in four places | Investigation |
| The safe response | Interviewing victims |
| Reporting, and what the manager who hears the report does next (the manager guide) | Security procedures beyond "call security" |
| The numbers to call | How the police respond |
| The records and kit a hotel needs | The legal detail of other states |

## 2. Structure: four places, three moves

The P3 engine runs on a grid of rows and moves. Here the rows are **places in the hotel** and the moves are **notice it, don't confront, report it**.

| Place | Notice it | Don't confront | Report it |
|---|---|---|---|
| Check-in and lobby | | | |
| Guest rooms | | | |
| Young guests | | | |
| Our workforce | | | |

The grid gives the learner a map, fills in as lessons are done, and comes back on the results page, with one test question per cell.

"Young guests" is a row, not a place, because the law singles out the commercial exploitation of children, and the response is different: danger now means 911 first.

| Part | Content | Slides |
|---|---|---|
| Introduction | Who it is for; why (the law, guest and staff safety, "you are not asked to investigate"); four places; three moves; how it works, with a support line | 5 |
| Lesson 1. What it is | Force, fraud or coercion; minors; labor versus sex trafficking in a hotel; behavior, not looks; what happens when you report; good-faith protection | 4, a check, a scene |
| Lessons 2 to 5 | One place each: a tap-to-explore picture, a "what to do" slide (lessons 2 and 3 add a report slide), a check, a scene | 2 to 3 each |
| Test | 12 questions, one per cell, from a bank of 26 | |
| Results | Score ring, the grid, review links, a first move, and the completion record | |

## 3. Interactions, and what each is for

- **Tap to explore** (one picture per place). Every point carries its source. In lessons 2, 4 and 5 the learner decides first: is this point a sign to report, or not a sign on its own? Only then does the explanation show. Each of those scenes has at least one ordinary thing (paying cash, the late hour, a van ride, crowded housing), so the learner has to judge rather than tap "sign" every time. Only the first answer counts; tapping the point again shows the answer and the explanation. That is the Act's part (3)(A) and (B), made into the same judgment the test asks for. (Until October 15, 2026, lesson 2 asked who each sign was about. A simulated designer review pointed out that staff never make that call on the job, so it was replaced.)
- **Sign or not on its own** (cards, lesson 3 and the test). Half the cards are ordinary things: a family with a stroller, a late checkout, a language. This is where profiling gets unlearned.
- **Write the report** (lesson 3). Four boxes: where, what I saw, how long, what I did. A word check, then a model. The P3 version offered to open the phone's messages app. That was turned off here, because a report about a possible trafficking case goes to the manager on duty or security in person or by phone, never into a personal text thread.
- **Scenes with consequences** (one per lesson). The risky choice is the kind-hearted one:
  - asking her if she is okay in front of him;
  - slipping a note into the towels;
  - stepping in front of the elevator;
  - confronting the agency.

  The consequence shows what that does to the person you meant to help. The learner then chooses again. The partial choice is the common half-measure: waiting until tomorrow, or turning the guests away.

## 4. Safety and sensitivity

These are design rules, not decoration:

- **Signs are behavior, never looks.** No sign mentions race, nationality, accent, clothing or an age gap. Those appear only as "not a sign on its own." The pictures are flat figures with no faces or skin tones.
- **Nobody is asked to investigate, search, photograph, rescue, or pass a secret message.** Every one of those is a dangerous answer in the test.
- **No graphic content, no faces, no injuries.** The minor in lesson 4 is a small figure in a hoodie, with her head down.
- **A support line on the introduction.** Some staff may have lived through this. The hotline helps survivors too.
- **No shock statistics.** The Hawaii studies are small and not representative, so the course uses none.
- **Plain, calm wording.** "May be," "a sign," "worth a report." The course never says a guest *is* a trafficker.

## 5. Assessment

- **One question per cell.** The result reads as a grid of 12 skills, each with a link back to the right page.
- **Dangerous answers fail the attempt** at any score:
  - confronting;
  - alerting a possible victim;
  - entering or searching a room;
  - taking a young person away yourself;
  - reporting to the agency that may be in control.
- **Retakes draw unseen versions.** Two or three per cell, 26 in all.
- **Answer length is balanced** so the longest option is not a giveaway. `tools/metrics.js` reports how often the keyed answer is the longest, counting ties (see the review log for the current figure).
- **Stems are positive** ("what do you do?", "what helps most?"), not "which should you never do?", which is hard for readers in a second language.
- **Victims and controllers vary:** a woman offering a boy, a male coworker threatened through his family, a guest family's nanny, as well as the young women in the main scenes.
- **Objective O1** (picking the situation that shows force, fraud or coercion) is practiced in lesson 1 and tested by the pick-one versions of the "Notice it" questions, since the test grid is places by moves. The learner uses force, fraud and coercion to choose; no question asks them to name which one.
- **The pass mark is 80 percent with no dangerous answers.** That is this demo's choice; the law sets none.

## 6. Records and the roster (built for turnover)

The law asks hotels to train each new guest-contact worker within 180 days and to keep records. With high turnover, that is a scheduling problem as much as a teaching one.

**The completion record** is made only from a real pass, with every lesson done before the test started. A test unlocked "for review" makes none. The learner adds a name, a role and a worker type (hotel employee or contract worker). The record stores:

- the completion date;
- the score;
- the course version;
- the refresher due date (two years later).

It prints as a certificate and downloads as CSV. The name never goes into the tracking statements.

**The manager's roster** shows sample staff and any records on the device. It computes:

- the first due date: 180 days after hire, but never before December 1, 2027;
- the refresher date: two years after each completion;
- each person's status: current, due within 30 days, overdue, or not due yet.

It can show the roster as of any date. The demo opens on March 1, 2028, a few months after the rule takes effect, so the overdue cases are visible.

Dates are plain calendar dates built from local parts, so Hawaii time never shifts them by a day. `tools/records-check.js` tests this with the browser set to Pacific/Honolulu.

## 7. The kit

| Piece | What it is | Status |
|---|---|---|
| Pocket card | The 4 by 3 grid, what to tell, "never," the numbers, and editable manager and security numbers | Prints on one page |
| Policy template | Who it covers, the three moves, reporting steps, protection, training, records, signs, review | Not legal advice |
| Draft staff sign | Hotline, text line, 911, "not police or immigration," the 10-percent language rule | Draft until the Department of Law Enforcement sets the form |
| Manager guide | What the manager on duty does after a staff report: danger now, take the report, pass it on the same shift, what to do when the usual route breaks (manager unreachable, a manager or agency involved, a contract worker, the worker is the one being exploited, someone said drop it), what not to do, afterward, and blanks the hotel fills in | Prints on one page. Added October 15, 2026, after a simulated designer review found the course taught staff to report but gave the manager nothing for what comes next. Not legal advice |
| Roster and certificate | See section 6 | |

## 8. Look, motion and access

**Its own look, the Seabright theme, version 2: hotel wayfinding signs (2026-10-08).** The first theme came from a reference Dean chose: sand pages, ochre highlights, a pastel per place, rounded blocks with a small solid offset. Dean then said it looked too much like AI-made design: rounded corners everywhere, colors too close to each other, icons floating around the cover, and no contrast between the backdrop and the slide. Version 2 keeps the reference's hues and fixes those four things:

| Color | Hex | Used for |
|---|---|---|
| Night navy | #1E2B40 | the backdrop, the header and the bottom bar; type on light |
| Paper | #FBF8F2 | the slide |
| Ochre | #E3A23B | highlights, the current step, the check-in and lobby lessons |
| Harbor blue | #2B5C8A | lesson 1 and the introduction |
| Terracotta | #B44D33 | guest rooms |
| Violet | #5A4E9C | young guests |
| Green | #2E7558 | our workforce |
| Warning red | #A33A25 | dangerous answers |

- **Contrast.** The slide is a light panel on a dark navy surround, so the foreground never melts into the backdrop.
- **One strong color per place,** used the way a hotel color-codes its floors: a band across the top of the slide, a door-sign plate for the lesson label, and a stripe on the lesson's card on the map. Everything else is navy, paper and white, so the place colors stand apart.
- **Square plates, not rounded cards.** Corners are square or nearly so; surfaces are flat white with a thin rule. No offset shadows.
- **Nothing floating.** The cover picture is one framed print. The circled icons that floated around it are gone.
- **Type.** Headings are Barlow, a face drawn from road and building signs; labels use Barlow Semi Condensed in capitals, like room-number plates. Both load from Google Fonts with system fallbacks, so the course still works offline.
- **The pictures, version 3 (Dean's choice, 2026-10-08): a clean hand-drawn style.** One smooth, even ink line with rounded ends, never sketchy; flat colors printed slightly off the line, like a screen print; people with real proportions (necks, shoulders, bent arms, hands, hair, uniforms) and no facial features. Skin tones (Dean, 2026-10-08, after the fourth review): five tones, assigned on purpose so that staff, guests, people at risk and people in control each include several, and no tone goes with a role; no answer depends on how anyone looks. Small hotel details give a sense of place: a Diamond Head print, pendant lamps, an orchid on the desk, a wood-slat counter, key cubbies, a housekeeping cart. All 11 pictures are drawn in code from one figure kit in `art.js`, so they stay sharp, tiny and consistent. The cover shows the hotel with three floors of rooms and lanai rails, Diamond Head on the horizon, and two palms that sway a little when motion is on. The numbered pins are square plates, like room numbers, and sit beside people, with a short dotted line where a pin is set off from its thing. `tools/pins-check.js` fails any pin that covers a person's head, body or legs, at phone and computer widths.
- **How it is built.** The theme is one layer at the end of `style.css` and `kit.css`, so P3's look is untouched and the engine stays shared.
- **Contrast checks.** Text meets 4.5 to 1 everywhere, checked by axe-core on every screen. Focus rings are navy on light surfaces and light on the navy bars.

Reused from P3:

- a slide deck that works with a mouse, a keyboard and arrow keys;
- motion that eases each slide in and can be turned off in the header (it is off for anyone whose device asks for reduced motion). The palms' sway follows the same switch. The slide title arrives word by word; body text slides in from the right as one block, so it can be read at once (Dean, 2026-10-08).

Every picture has a text description for screen readers. Every interaction works by keyboard.

## 9. Length: the tradeoff

The target was 30 minutes. The time model (`tools/metrics.js`) adds reading at a given speed to a fixed time per interaction:

| Reading speed | Total |
|---|---|
| 240 words a minute | 35 minutes |
| 180 words a minute | 42 minutes |
| 150 words a minute | 47 minutes |
| 120 words a minute, closer to a second-language reader on a phone | 55 minutes |

The course states "40 to 55 minutes," to cover slower readers in a second language (about 55 at 120 words a minute). To reach 30, these are the cuts, in order, if a client asks:

1. Drop the written report in lesson 3 (about 2 minutes).
2. Cut the test to 8 questions, two per place (about 3 minutes).
3. Merge lesson 1's last two slides (about 1 minute).

The cost: less practice of the hardest behavior, which is reporting well, and a test that no longer covers every cell.

## 10. Engine changes from P3

- **New wording.** Storage keys and wording moved into `content.js` (`words`). The engine no longer says "hazard," "cord" or "field card."
- **The picture question** and the sorting cards take their labels from the course: "A sign to notice" and "Not a sign on its own." The 10-second timer is off; speed is not the point here.
- **The completion record** (results page and data panel), plus `records-lib.js`, shared with the certificate and the roster.
- **The report block's labels** are set by the content. The messages-app button is off by default.
- **Icons per lesson:** lesson 1 has its own icon, instead of P3's "speak" fallback.
- **Reviewer mode:** "Unlock the test" and "My session data" show only when the address carries `?review=1` (remembered on that device; `?review=0` clears it). The portfolio's links use it; a hotel's staff never see those controls.

## 11. Open items

See `QUESTIONS.md` in the project folder. The main ones are:

- expert and survivor-informed review;
- a native-speaker translation of the sign;
- the final rules;
- the full read of the DHS toolkit;
- whether to cut to 30 minutes.