# Designesy — /acoustic-tokens Canonical page: https://www.designesy.org/acoustic-tokens --- ## Acoustic tokens The sound parallel to the visual token system. No sound appears on a Designesy surface without a token name and a rationale here. The W3C Design Tokens Format Module 2025.10 does not define acoustic token types — this system is net-new relative to the canonical standard. ## Standards context The W3C Design Tokens Format Module 2025.10 does not define acoustic/audio token types. Designesy acoustic tokens are net-new relative to the canonical standard. 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. `{"$value":"tick","$type":"sound","$description":"Navigation hover","$extensions":{"designesy":{"engine":"cuelume","role":"nav"}}}` ## Token reference Nineteen cues, nineteen interaction roles. 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, not 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 ## Mapping rules - Brand marks earn sparkle. Hero wordmark, topbar logo, and footer mark are brand contact — not generic nav ticks. - One primary cue family per role. Nav stays tick. Brand stays sparkle. Dense lists stay whisper. Do not randomize per page without updating this document. - Hover sounds are fine-pointer only upstream. On coarse/touch pointers, Designesy binder maps the same hover cue to a single tap. - Press/release on touch. Designesy binder plays the same cues on touch/pen pointerdown/pointerup. - Toggle sounds fire via preference hook. The sound button does not use data-cuelume-toggle. - No ambient audio. Cuelume is interaction-only. No background music, no mood beds, no loading sounds. - Preference is user-owned. Designesy stores the sound preference in localStorage under designesy:sound. - Audio unlock on first real cue. Mobile Safari keeps AudioContext suspended until a user gesture. - Every cue must trace to this document. If a sound appears in the markup without a token here, it is a contract violation. ## 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, not on focus. Screen reader users navigate by focus and are not bombarded with 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. ## Provenance - [Cuelume v0.2.2 (MIT) — cuelume@0.2.2 (MIT, Daniel Belyi)](https://www.npmjs.com/package/cuelume) - [GitHub repository — https://github.com/Danilaa1/cuelume](https://github.com/Danilaa1/cuelume) - [Design system contract v0.4.0 — Visual token system](https://www.designesy.org/contracts/design-system) - [Machine export — acoustic-tokens.json](https://www.designesy.org/acoustic-tokens.json)