DESIGN.md@benchmark/results/meditation-sound-claude-code-opus-5.5-medium-2026-11-14/with · git:20261114.909b911 · 2026-11-14 · sha256 4b2aacb2e191625e
DESIGN.md@benchmark/results/meditation-sound-claude-code-opus-5.5-medium-2026-11-14/with git:20261114.909b911A
Immutable. This exact content never changes and is served at /api/v1/blob/4b2aacb2e191625e.
# DESIGN.md — Ma · a quiet meditation timer Source of truth for this project. Read before changing anything; add a changelog line for every change. ## 1. Concept - **Concept sentence:** a single brushstroke on washi paper in a quiet temple room. - **Name:** Ma (間), the Japanese idea of the meaningful pause between things. - **Mood:** still, warm, handmade · **Anti-words:** clinical, sugary. - **Category cliché (meditation apps):** pastel teal/lavender gradients, lotus icon, glowing blob, rounded sans, sunset photo. **Divergence:** colour (warm paper + sumi ink + one vermilion), type (mincho serif numerals), imagery (a procedural dry-brush ensō, not a blob), sound (synthesised singing bowls in one key). - **Style:** Japandi base + Editorial accent (serif numerals and headings only). - **Signatures:** (1) the ensō is *drawn by your breath*: it inks in on the inhale and retreats on the exhale; (2) the vermilion 間 seal pulses at interval bells and stamps at completion. ## 2. Decision log | Decision | Choice | Why | Source | |---|---|---|---| | Effort | All-out | — | User | | Name | "Ma" (間) | Means the pause between things; short; original | User asked me to name it → Agent judgment | | Direction | Ensō (ink on washi) | Picked from 3 rendered style tiles (`directions.html`) | User | | Breathing | Calm 4·6, Even 5·5, Box 4·4·4·4, 4-7-8, Unguided + Custom sliders | Asked for presets + custom; described by timings only, no health claims | User + DENT `SKILL.md §3` (honesty) | | Ambience | Rain, Ocean, Wind, Low drone, generated live | No files, no licences, works from file:// | User | | Theme | Follows system + Auto/Light/Dark override, no flash | — | User + DENT `all-out.md §2.1` | | Extras | Remember settings, session log, vibration, keep awake | — | User | | Type | Shippori Mincho (numerals, headings) + Zen Kaku Gothic New (UI) | Japandi pairing; tabular serif numerals carry the screen | DENT `styles/japandi.md` | | Palette | Paper #F4EFE6, ink #1F1B16, ink-2 #5C544A, seal #A63F2A; dark: #14110E / #ECE4D6 / #A99F90 / #D86A48 | Natural materials; one muted accent | DENT `styles/japandi.md` + Agent judgment (all pairs checked) | | Ensō rendering | Canvas, seeded dry-brush stroke rendered once, revealed per frame with a sector clip + conic-gradient feather | Real brush texture at ~1 drawImage per frame | Override (DENT suggests SVG/CSS; canvas gives real kasure texture cheaply) | | Bells default | On, but nothing sounds until the user presses Begin or a preview | A timer's end bell is its core function; still never autoplays; global toggle always visible | Override of DENT "sound off by default" (`audio-implementation §1`), logged in plan audit | | Ambience when tab hidden | Keeps playing during an active sit; stops when idle | Meditators lock or switch apps mid-sit | Override of DENT "suspend ambience on hidden" | | Bell scheduling | On the AudioContext clock, 3-min lookahead, end bell always pre-scheduled | Background tabs throttle JS timers (up to 1/min) | Agent judgment | | End session | Only reachable from Pause | Prevents an accidental tap ending a sit | Agent judgment (Nielsen #5 error prevention) | | Live region | Session events only (start, interval, pause, complete) | Announcing every breath would be noise | DENT `accessibility.md` + Agent judgment | | Layout | Phone: stacked; ≥960 px: asymmetric stage + 400 px settings column; sitting: settings hidden, stage centred | Japandi asymmetry; focus while sitting | DENT `styles/japandi.md` + Agent judgment | | Libraries | None (vanilla JS, Web Audio, Canvas) | One file; every job covered natively | DENT `catalog/component-selection.md` (reuse/none first) | ## 3. Tokens ```css --paper #F4EFE6 | #14110E --surface #EBE4D7 | #1E1A16 --ink #1F1B16 | #ECE4D6 --ink-2 #5C544A | #A99F90 --line #D8CFBF | #332D27 (decorative) --line-strong #7F7566 | #7A7064 (controls) --seal #A63F2A | #D86A48 --on-seal #FBF6EE | #14110E space 4/8/12/16/24/32/48/64 · radius 4 (controls) / 6 (containers) motion 180 / 450 / 700 ms · ease (.25,.1,.25,1) · ease-out (.16,1,.3,1) type: body 16/1.55 · small 14 · h2 22 · time clamp(44px, 19% of stage, 116px) ``` `prefers-contrast: more` raises ink-2 and hairlines to full contrast; `forced-colors` keeps seal and buttons legible. **Contrast (contrast.py):** ink/paper 14.95 · ink-2/paper 6.50 · ink-2/surface 5.89 · seal/paper 5.45 · on-seal/seal 5.80 · dark ink 14.90 · dark ink-2 7.21 (6.63 on surface) · dark seal 5.44 · control borders 3.95 / 3.58 (light, paper/surface) and 3.88 / 3.56 (dark). All pass. ## 4. States idle · settling (10/30 s countdown, ghost circle) · sitting (breath phase + count, remaining time, progress hairline with interval ticks) · paused (Resume / End session) · complete (seal stamps, "You sat for N minutes.") · ended early (logged only if ≥ 1 min) · custom-duration error (Begin disabled, fix-it message) · ambience preparing / playing / error · log: empty / populated / storage blocked / clear-confirm · vibration and wake-lock unsupported notes · sound off (previews disabled with reason) · reduced motion (static circle, text phases, no stamp scale). ## 5. Motion spec | Element | Motion | Timing | Reduced motion | |---|---|---|---| | Ensō inhale | Brush inks along the circle; scale .955→1 | Breath length, sine ease | Static full circle; phase text only | | Ensō exhale | Ink retreats from the start; scale 1→.955 | Breath length, sine ease | Static | | Interval | Seal pulse + halo | 1.8 s once | Outline highlight, no scale | | Complete | Seal stamps (scale 1.9→1, rotate) | 700 ms ease-out | Fade only | | View change | View Transition crossfade (when supported) | Browser default | Instant | | Dialog | Rise 12 px + fade | 450 ms | Instant | Only transform/opacity and a canvas redraw are animated; the canvas skips frames when nothing changed (holds). ## 6. Sound spec **Role:** identity + function (start, interval, end), plus optional atmosphere. **Sonic concept:** a brass singing bowl in a wooden room. **Character:** warm, resonant, unhurried · **Anti:** digital beeps, chimes-on-every-click. **Silence policy:** no UI clicks, no breath cues, nothing before a gesture. | Cue | Design | Level (measured, 70 % bell volume, dry) | |---|---|---| | Start | Bowl strike on G3 (196 Hz) + softer fifth (D4) 0.62 s later: a rising fifth opens | peak −13.5 dBFS | | Interval | One higher bowl (G4), ±1.5 % pitch variation each time | peak −17.9 dBFS | | End | Three strikes: fifth, root, softer root, 2.8 s apart: a falling close | peak −14.3 dBFS | | Ambience | Rain, Ocean, Wind, Low drone (drone tuned to G, matching the bells) | RMS −30.8 dBFS at 60 %, ≈ −28 dBFS at the 70 % default | Bowl synthesis: four inharmonic partials (1, 2.71, 5.15, 8.43×), each a detuned sine pair for the slow "wah" beating, plus a 35 ms felt-mallet noise touch, through a generated 3.4 s room reverb (34 % wet) and a limiter. Ambience is rendered offline into 60 s loops with an equal-power 4 s crossfade at the seam, normalised to −22 dBFS RMS at full volume. Render times measured headless: rain 248 ms, ocean 264 ms, wind 270 ms, drone 467 ms. | Event | Sound | Visual equivalent | Repeat limit | |---|---|---|---| | Sit starts | Start cue | Ensō begins, "Breathe in", live-region "Session started" | Once per sit | | Interval | Interval cue | Seal pulse, progress tick turns vermilion, live-region "N minutes passed" | Once per interval | | Sit complete | End cue, ambience fades out | "Complete" view, seal stamp, live-region | Once | | Preview buttons | The cue | Button press | 350 ms debounce | Controls: header sound toggle (`aria-pressed`, M key) mutes everything instantly; bell volume, ambience volume; ambience Listen/Stop; all persisted. Works fully muted. ## 7. Licences | Asset | Source | Licence | |---|---|---| | Shippori Mincho | Google Fonts (FONTDASU) | SIL Open Font License 1.1 | | Zen Kaku Gothic New | Google Fonts (Yoshimichi Ohira) | SIL Open Font License 1.1 | | Icons (speaker, bars, close), favicon, ensō, seal | Drawn for this project | Project-owned | | All sounds | Synthesised in the browser by this code | Project-owned, no samples | | Libraries | None | — | Fonts load from Google's CDN; offline, the page falls back to installed serif/sans fonts and still works. ## 8. Verification (2026-11-14, Playwright Chromium headless on Windows) | Check | Result | Evidence | |---|---|---| | G2 overflow 320/375/390/768/1024/1440 | Passed | verify_page.py: scrollWidth = viewport at all widths | | G3 contrast | Passed | contrast.py on every token pair + sampled page: 0 failures | | G4 labels / names / keyboard | Passed | verify_page.py: 0 unlabeled, 0 unnamed; Tab order header → Begin → settings, visible focus on every stop; dialog focus in, Esc closes, focus returns to "Practice" | | G10 reduced motion | Passed | verify_page.py reduced-motion run: 0 running animations; screenshot shows static circle with text phases | | G11 no autoplay | Passed | No AudioContext before a gesture (also after reload); created on Begin, state "running" | | Session journey | Passed | Custom 2 min, 1-min interval, 10 s settle, rain (time accelerated 8×): settling → sitting; phases "Breathe in 1–4 / Breathe out 1–6" seen; interval tick + announcement; Space pauses; time frozen while paused; bells cancelled on pause, rescheduled on resume (only `end@120000` left); mute → master 0.000, unmute → 1.000; complete with correct text; log entry written | | Ended early | Passed | Pause → End session after ~70 s: "You sat for 1 minute.", logged as ended early | | Validation | Passed | Custom 0 or 500 min → error shown, Begin disabled, summary explains | | Persistence | Passed | Reload restores duration, custom value, interval, ambience, theme | | Log | Passed | Seeded 6 sits: totals 6 / 90 min / 4-day streak correct; 7-day bars labelled; clear-confirm focus to "Keep it" | | Console errors | Passed | 0 in every run | | Loudness | Passed (digital measure) | Offline renders: bells peak −13.5 to −17.9 dBFS, ambience RMS −28 to −31 dBFS, no clipping | | Listening by ear | Not run | The agent cannot hear; needs a human listen on speakers and headphones | | Real phones (iOS Safari, Android Chrome), vibration, wake lock | Not run | Only feature detection paths were checked; needs a device test | | Firefox / Safari desktop | Not run | Chromium only | **Known limitations:** iOS Safari suspends Web Audio when the screen locks, so keep-awake matters there (and iOS has no Wake Lock before 16.4). Vibration doesn't exist on iPhone browsers; the UI says so. ## 9. Changelog - 2026-11-14: v1 built. Improve round 1: rain render 68 s → 0.25 s (drops synthesised directly instead of ~2,000 audio nodes, which had also blocked page navigation); log dialog layout fixed (floated heading); brush beading removed (per-bristle layers) and edges feathered with a conic mask; sitting view centred; interval bell +3.4 dB; ambience default 60 → 70 %. - 2026-11-14: Shipped as is (user decision). Still unverified: listening by ear, and vibration and wake lock on real phones.