Build: The Tokens File and the Test Suite

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

test suite

A set of automatic checks you run with one command.

baseline

The saved picture a snapshot test compares against. The first run writes it.

webServer

A Playwright setting that starts your dev server before the tests and stops it after.

pinned version

An exact version written in package.json (5.0.5, not ^5), so every machine installs the same code.

1. 1

   Slow the toast with a token

   Press --dur-base: 440ms and then Show a toast. The toast's WAAPI track is 440 ms long. Press Reset: the next toast is 220 ms again. The Playwright test "a token change reaches the toast" does the same with 900 ms.

2. 2

   Run one test

   In your project run npx vitest run -t "fourth toast" to run a single test by name, and npx playwright test -g "reduced motion" to run the two reduced-motion tests only.

Your lumen-motion project after this topic. Click a file to see it in full.

/* tokens.css: Lumen's motion tokens. One place for durations and easings, so every component speaks the same language.
   Phase 2 started this file and Phase 18 finishes it. Never rename a token: components depend on the names. */
:root {
  /* durations (the Nielsen Norman Group ladder, Topic 2.4) */
  --dur-fast: 120ms; /* feedback: a press, a hover colour */
  --dur-base: 220ms; /* most things: toasts, panels, dialogs entering */
  --dur-slow: 400ms; /* large movement: a drawer across the screen */

  /* easings (Topic 5.3 explains the choices) */
  --ease-out: cubic-bezier(0.22, 1, 0.36, 1); /* things arriving */
  --ease-in: cubic-bezier(0.55, 0, 1, 0.45); /* things leaving */
  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1); /* things moving between two places on screen */
  /* ── Phase 5: choreography ── */
  --stagger-step: 60ms; /* gap between neighbours in a reveal; main.js caps how many steps count */
  /* ── end Phase 5 ── */

  /* ── Phase 18: purpose names (components ask for the purpose, not for a number) ── */
  --motion-enter-duration: var(--dur-base); /* something appears */
  --motion-enter-ease: var(--ease-out);
  --motion-exit-duration: var(--dur-fast); /* something leaves: quicker than it came */
  --motion-exit-ease: var(--ease-in);
  --motion-emphasis-duration: var(--dur-slow); /* a big, rare move: the drawer, a page change */
  --motion-emphasis-ease: var(--ease-in-out);
  /* springs: "stiffness damping-ratio" (mass is always 1). CSS cannot run a spring: tokens.js reads these for spring.js.
     The shape follows Material 3's spring tokens (stiffness plus a damping ratio, spatial and effects); the numbers are Lumen's own. */
  --spring-spatial-fast: 700 0.9; /* small things that move: a switch, a chip */
  --spring-spatial: 380 0.87; /* the drawer (Phase 9): a calm, tiny overshoot */
  --spring-spatial-slow: 200 0.9; /* large things that move */
  --spring-effects: 1600 1; /* opacity and colour: never overshoot (a ratio of 1 does not) */
  /* ── end Phase 18 ── */
}

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   Why the site needs this now: this closes Kofi's chapter. The contractors will edit the toast and the drawer, Lena wants a failing check instead of a complaint, and Tomás wants to know before customers do. Nothing yet tells the team when motion changes by accident.

2. 2

   What it adds. tokens.css keeps every earlier token and gains the purpose and spring tokens; src/js/motion/tokens.js exports token(), ms() and springOf(). index.html already links tokens.css (Phase 2), so nothing else loads it. The two configs are new and package.json gains the scripts and pinned dev dependencies (it also lists the packages of Phases 14 to 16). One honest gap: the purpose tokens are in place but Lumen's components still ask for primitives, such as var(--dur-base, 220ms). Moving each rule over to --motion-enter-* is the first pull request after this phase; until then a change to --dur-base still reaches the toast, but a change to --motion-enter-duration does not.

3. 3

   The Vitest suite (tests/motion.test.js, 8 tests, happy-dom, fake timers) checks the tokens (the mirror reads the CSS, a wrong token throws, every var() names a token that exists), the toast (there at 2,599 ms, gone at 2,600 ms; a fourth pushes out the oldest), the drawer (starts closed, opens with the spring, ends at translateX(0px), Escape closes it) and reduced motion (the device setting is followed, the visitor's choice beats it). It checks our logic; it cannot see an animation (Topic 18.4).

4. 4

   The Playwright suite (tests/launch.spec.js, 6 tests, Chromium, with its own dev server) seeks the toast's real animation to 0, 110 and 220 ms; opens the drawer and polls until the spring settles (a spring is JavaScript, so there is nothing to seek); under reducedMotion: "reduce" checks the toast uses the fade and the drawer needs no spring; changes --dur-base to 900 ms and checks the toast's real duration; and takes a snapshot of the toast.

5. 5

   What we measured. npm test: 8 passed. npm run test:e2e: the first run passed 5 and failed the snapshot (A snapshot doesn't exist ... writing actual.); the second passed all 6. Then we broke things on purpose (see Break it) and the right check failed.

6. 6

   What the launch site can do now that it could not before: be edited by someone who was not in the room, with a safety net for the toast, the drawer and reduced motion; read its motion numbers from one place in CSS and JavaScript; and fail a check, not a customer. What is still missing: the interview rounds, the jank hunt and the launch audit (Phase 19). The suites skip the gallery, the page transition and the scroll story; we ran them in Chromium on Windows only (snapshot toast-win32.png), and on no real phone.

• tokens.css has every earlier token plus the purpose and spring tokens, and tokens.js reads them

• npm test passes 8 tests and npm run test:e2e passes 6, after the first snapshot is committed

• You broke a token, a media query and a timer on purpose and saw the right check fail

• You can say which problems the unit suite can catch and which only the browser suite can