Refinement work order for a strong model

Result — Produced a genuinely sharp critique that found six real defects, then fixed them. Cost: one clean run.

# Work order — RAIL STORE: assessment + premiere-quality refinement pass

Adopt the perspective of a senior design engineer and creative director while working
through this. The brief is deliberately blunt about what is wrong; please be equally
blunt back in your assessment.

## Context

A working asset is built and deployed at `/home/ubuntu/rail-store/`
(live: https://rail-store.pages.dev). It implements a 1,359-line spec, `PRD-v1.md`,
held at `/home/ubuntu/menashi-webstore/`. The spec was itself written from a
576 px, twice-encoded phone screen-recording of a reference storefront — the real
site's URL is unknown, so every dimension was measured off video frames.

The design: **the rail is the catalogue.** No tile grid, no card chrome. A
photorealistic clothing rail on a pegboard wall, garments hanging side-on at rest,
hovering one turns it front-on / scales it / spreads its neighbours, clicking opens a
full-height product overlay. A slate-indigo marquee runs along the bottom.

## What is already verified — do not regress these

These were measured from the reference's own pixels and are correct. Changing them
makes the build *less* faithful, not better:

| Quantity | Value | Where |
|---|---|---|
| rail centreline | 15.0u | `--rail-centre-y` |
| rail span | 74.5u, pitch 6.77u | `--rail-span`, app.js item x |
| marquee top / height | 53.7u / 2.65u | `--marquee-height` |
| garment fabric band | 16.2 → 39.2u (24.2 tall) | `--garment-img-h` |
| nav baseline / wordmark block | 2.9u / 5.9u | `--header-top-y`, `--type-wordmark-*` |
| pill centre / width | 48.0u / 11.5u | `--pill-width`, `.rail__cta` top |
| hook alignment | hook top exactly on the tube centre (delta 0.000u) | `--hook-top-ratio` |
| surface | `#DFDFDD` | `--surface` |

`--u: min(1vw, 1.7778vh)` is the layout unit; **every** geometry and type value is a
multiple of it. Do not introduce bare `vw` — it is viewport-relative, not
composition-relative, and reads ~14% large on a short/wide window.

Four ink tokens are **deliberately not** the reference's values: the reference's
palette fails WCAG AA. Each was darkened to the lightest passing value with hue
preserved, and the ratios are documented in `BRAND-SWAP.md`. Do not revert them.

## What the owner said after reviewing it

His words: *"there's just some kind of tearing and it looks like some shapes behind
each one of the actual items as we render as you go through the rail… also all of the
items aren't actually on the hanger… some inadequacies here and there, but overall it
was a good attempt. I think some fine-tuning will make this more premiere, make the
transitions better… a cleaner implementation that is closer to pure Triple A Awards
production quality asset that I can showcase."*

Two of those are already fixed since he looked:
- **The "shapes behind each item"** were faint alpha (≈10% of every canvas at
  alpha 0.02–0.75) leaking beyond the garment — a soft plate behind each item that
  stacked into visible seams where images overlap. Fixed: now 0.55%, and
  `edgeStrips` measures 0.00 on every image. See `scripts/diagnose.py`.
- **The hangers** were floating 0.42u below the tube. Fixed via `--hook-top-ratio`.

## Your task

1. **Assess it honestly.** Look at the built site, the reference frames
   (`/home/ubuntu/menashi-webstore/crops/`), and the spec. Write
   `/home/ubuntu/rail-store/OPUS-ASSESSMENT.md`: what is genuinely good, what is
   mediocre, and ranked by how much each item costs the asset in a portfolio. Do not
   be generous. If it is not yet showcase-grade, say which specific things stop it.

2. **Then implement the refinements that close the gap.** Priorities, highest first:

   - **The garment turn is currently an opacity crossfade.** It is the defining
     interaction of the entire asset and it is the weakest thing in the build. The
     reference's turn reads as a *rotation*. Make it feel like the garment physically
     turns on its hanger. Any mechanism is fair game — 3D transform, sprite, layered
     parallax, scale + skew — but it must be smooth, must not jitter, and must
     degrade instantly under `prefers-reduced-motion`.
   - **Motion craft generally.** Read `references/motion-notes.md` in this folder.
     The asset should feel expensive. Right now the hover, spread and overlay
     transitions are correct but not *designed*. Add taste, not decoration, and keep
     total JS under 30 KB gzipped.
   - **The cast shadows read as heavy grey blobs.** `SHADOW_GAIN`/`SHADOW_MAX` in
     `scripts/cutout.py` are 3.2/0.60. They should read as light falling on a wall,
     with falloff, not as a shape. Tune the extraction, not the DOM.
   - **The pegboard** should be perceptible as a designed surface at close range and
     dissolve at normal viewing distance. It is currently a flat repeating gradient.
   - **Typography and vertical rhythm** in the header, caption, counter and overlay
     stack — check the optical spacing, not just the measured positions.
   - **Empty / loading state.** First paint currently shows a blank wall; the rail
     fades in. Consider whether that is the best entry, or whether the surface should
     carry a hint of the rail before images decode.
   - **Mobile and tablet** are Menashi original design (unreferenceable) and are the
     least finished part of the build. Make them feel deliberate.

3. **Verify your own work.** Then run:
   - `npm run validate` — must pass (the build fails on a contract breach)
   - `node build.mjs` — must emit cleanly
   - `node scripts/diagnose.py` — `edgeStrips` must stay 0.00 and `faint>0.02%` low
   - `node scripts/measure_ref.py` / `measure_bands.py` — confirm you did not move
     the measured anchors listed above
   - `node scripts/serve.mjs 8100 --dist` and check the site in a browser

## Hard constraints

- **Do not change the measured geometry values.** They are the fidelity contract.
- **Do not remove or weaken accessibility**: focus rings, reduced-motion handling,
  dialog semantics, `inert` backdrop, alt text, the `aria-hidden` decorative capsule,
  and the rule that no `role="progressbar"` exists anywhere.
- **`tokens.css` and `products.json` stay the single sources of truth.** No brand
  value hard-coded in `styles.css` or `app.js`.
- Keep the contract rules intact: `images.side` + `images.front` per product, every
  CTA resolving, non-null `forms.endpoint`, `soldOutLabel` present.
- **Never edit anything under `/home/ubuntu/Menashi`.** All work stays in
  `/home/ubuntu/rail-store/`.
- No new runtime dependencies. This ships as a static export to Cloudflare Pages.
- Preserve the file layout: `tokens.css`, `styles.css`, `app.js`, `products.json`,
  `index.html` / `about.html` / `contact.html` / `404.html`, `p/`, `fonts/`,
  `scripts/`.

## Evidence you can use

- `/home/ubuntu/menashi-webstore/crops/` — reference frames. `store_c.png` (catalogue,
  clearest rail), `store_b.png` (the hover turn), `store_d.png` (the overlay),
  `full_20.0.png` (catalogue at native scale), `card_foot.png` (the marquee).
- `scripts/compare_catalogue.py` and `compare_pair.py` render the reference beside
  your build at matched width — `python3 scripts/compare_pair.py <ref> <build> <out>`
  then open the result. Judge that image; relative size errors are invisible in two
  separate screenshots and obvious in a pair.
- `QA-CHECKLIST.md` §Executed has every measurement and every gate result.
- `_raw/src/` holds the flat-wall renders the cut-outs come from; `p/` holds the
  shipped tiers.

## Two rendering traps that will waste your time

- **`loading="lazy"` looks broken in a headless capture.** Lazy loading uses
  intersection machinery that does not fire reliably headless, so screenshots show
  empty slots while the images are fine. Verify by counting `naturalWidth > 0`,
  never by eyeballing a screenshot. Force `loading='eager'` to photograph the full rail.
- **`filter` on an ancestor creates a stacking context.** Anything inside
  `.catalog-layer` can never rise above the overlay, whatever its `z-index`. That is
  why the decorative capsule lives outside that layer.

## Deliverables

1. `/home/ubuntu/rail-store/OPUS-ASSESSMENT.md` — the honest assessment.
2. The refined implementation, in place.
3. `/home/ubuntu/rail-store/OPUS-CHANGES.md` — what you changed and why, one entry
   per change, with the verification output for each claim. If you could not verify
   something, say so rather than asserting it.

kind

code

type

skill

model

claude-opus-5-5

effort

high

tool

claude-code

author

designer

status

proven

project

rail-store

created

2026-10-03

first used at /home/ubuntu/rail-store/WORKORDER-opus.md