# Designesy — /labs/acoustics Canonical page: https://www.designesy.org/labs/acoustics --- ## Acoustics Interaction sound as a token system. Acoustics studies the sound parallel to the visual token system. Nineteen cues, nineteen interaction roles, one documented engine. No sound appears on a Designesy surface without a token name and a rationale here. If the sound is louder than the action it confirms, it fails. ## Live artifact Enable sound, then hover or press each cue. Notice what does not happen: no ambient bed, no focus sounds, no randomization. Preference stored under `designesy:sound`. Defaults off under reduced motion. Cues · 19 ** Sound on Sound off ## Thesis Sound is a token. Each cue has a name, a role, and a character. The system is interaction-only: no ambient audio, no mood beds, no unmapped sounds. Preference is user-owned; reduced motion is an acoustic-reduction proxy. ## Principle - 01 Every sound has a name A sound without a token is a contract violation. Nineteen cues, nineteen roles, documented here. If a new interaction needs audio, add a token before adding the sound. - 02 Preference is part of craft Sound is opt-in. The toggle stores preference in localStorage; reduced motion defaults it off. The user can always enable or mute. Silent fallback means blocked Web Audio degrades invisibly. - 03 One cue family per role Nav stays tick. Brand stays sparkle. Dense lists stay whisper. Do not randomize per page without updating this document. Consistency is the product quality; surprise is the failure. ## Portable contract Mapping rules adopted into design system contract v0.3.0. Check a rule off as your surface adopts it. ** **0** / 9 adopted Source contract: [Design system contract v0.4.7](/contracts/design-system) · [Token reference page](/acoustic-tokens) · [Machine export](/acoustic-tokens.json) ## Token reference Nineteen cues, nineteen interaction roles, one documented engine. Every sound on a Designesy surface traces to a token here. ### `--cue:brand` · sparkle **Character.** Bright playful accent **Role.** Brand wordmark contact Where · Hero wordmark, topbar logo, footer mark, Open field card hover ### `--cue:nav` · tick **Character.** Crisp instant tick **Role.** Navigation and wayfinding Where · Topbar nav links, surface footer links, secondary CTAs ### `--cue:invite` · chime **Character.** Soft default chime **Role.** Primary invitation / machine surfaces Where · Primary hero CTA hover, kit field card, machine footer links ### `--cue:action` · press **Character.** Dull muted knock **Role.** Pointer-down on actionable surfaces Where · Buttons, field cards, surface cards ### `--cue:resolve` · release **Character.** Brighter springy tick **Role.** Pointer-up default resolve Where · Most buttons and cards ### `--cue:complete` · success **Character.** Warm three-note confirmation **Role.** High-value resolve Where · Primary Open CTA release, Open/Kit field card release ### `--cue:reveal` · bloom **Character.** Warm slow swell **Role.** Content / experiment reveal Where · Pillar cards, Lab field card hover, kit cards, open field cards, work cards, graph cards, docs cards, learn cards, review cards, continuity cards, score target landing ### `--cue:list` · whisper **Character.** Breathy quiet swell **Role.** Dense list / surface scan Where · Contracts pages, review overview, check grids, toggle rows, state-of-compliance, dense principle rails ### `--cue:switch` · toggle **Character.** Mechanical click-clack **Role.** State toggle Where · Sound preference button ### `--cue:contact` · droplet **Character.** Soft dismissive droplet **Role.** Contact / outbound mail Where · Footer mail, privacy mail ### `--cue:error` · error **Character.** Low descending two-note buzz (330→196Hz) **Role.** Error / corrective feedback Where · Score form network failure, copy failure, not-found page, error page ### `--cue:warning` · warning **Character.** Pitch-bent triangle tone (440→466Hz) **Role.** Heads up without blocking Where · Score form soft errors (invalid URL, unknown format) ### `--cue:info` · info **Character.** Two-note rising sine blip (660→880Hz) **Role.** Informational notice Where · Copy-to-clipboard success confirmation ### `--cue:blocked` · blocked **Character.** Two low square pulses, lowpass-filtered (165Hz) **Role.** Cannot proceed Where · Score form rate limit / access denied (HTTP 403/429 analogues) ### `--cue:retry` · retry **Character.** Rising sine pair with timing acceleration (330→440Hz) **Role.** Try again invitation Where · Score form fetch failures (502, timeout, could not reach target) ### `--cue:processing` · processing-start / processing-stop **Character.** Low triangle pulse loop, 500ms interval, gain 0.025 **Role.** Analysis in progress (state loop) Where · Score engine running checks, audit processing ### `--cue:check-pass` · check-pass **Character.** Brief 880Hz sine blip, 40ms **Role.** One verification check passed Where · Score engine count-up animation: fires per check as pass count increments ### `--cue:check-fail` · check-fail **Character.** Soft 220→110Hz triangle thud, 60ms **Role.** One verification check failed Where · Score engine count-up animation: fires per check as fail count increments ### `--cue:grade-reveal` · grade-reveal **Character.** Grade-mapped arpeggio: A+ ascending 4-note + harmonics with large-room reverb; A ascending 4-note with small-room reverb; B ascending pair; C two-note rising 440→554; D descending pair; F single low note **Role.** Score grade reveal: the hero acoustic moment Where · Score page grade animation completion, report page grade display ## Accessibility - **Reduced motion → sound off.** prefers-reduced-motion: reduce is treated as an acoustic-reduction proxy. The user can still enable sound manually via the toggle. - **No focus sounds.** Sounds fire on pointer and click events, never on focus. Screen reader users navigate by focus and hear no hover cues. - **Toggle is keyboard-accessible.** The sound toggle button uses aria-pressed and plays via the preference hook on click (includes keyboard activation). - **Silent fallback.** If Web Audio is blocked or unavailable, all sounds become no-ops. No errors, no degradation of visual experience. - **Volume is not adjustable.** Cuelume synthesizes at fixed gain levels tuned for subtlety. If a user finds sounds too loud, they can mute via the toggle. ## Implementation notes ``` Build interaction audio as a token system. Rules: 1. Every sound maps to a named token (--cue:role). No unmapped sounds anywhere. 2. One primary cue family per role. Nav stays tick. Brand stays sparkle. Do not randomize. 3. Sound is opt-in via a single toggle; store preference in localStorage; default off when prefers-reduced-motion. 4. Hover sounds fire on fine-pointer only. On touch, map the same hover cue to a single tap. 5. No focus sounds. Sounds fire on pointer and click, never on focus events. 6. No ambient audio: interaction-only. No background music, no loading sounds, no mood beds. 7. Silent fallback when Web Audio is blocked. No errors, no visual degradation. 8. Reduced motion is an acoustic-reduction proxy. The user can still enable sound manually. 9. Every cue must trace to a token document. A sound in the markup without a token here is a contract violation. ``` ## Review checklist ## Provenance ## Anti-patterns ## Remix notes Reuse the token model on any Designesy surface. Add a new cue by extending the acoustic-tokens module before wiring the sound into markup: the token document is the source of truth, and the attribute follows it. Do not remix interaction cues into ambient beds or loading sounds; Cuelume is interaction-only. If a new role needs audio, start from the closest existing cue family before inventing a new character. ## Lab anatomy coverage ## Verification ## Standards context ``` { "$value": "tick", "$type": "sound", "$description": "Navigation hover", "$extensions": { "designesy": { "engine": "cuelume", "role": "nav" } } } ``` Designesy declares $type: sound with $extensions.designesy namespacing per the DTCG extension convention. This format may be proposed to the W3C DTCG as a future token type contribution.