Acoustics

Live artifact

Enable sound, then hover or press each cue. Notice what does not happen: no ambient bed, no focus sounds, no randomization.

Thesis

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

Source contract: Design system contract v0.4.6 · Token reference page · Machine export

Token reference

Nineteen cues, nineteen interaction roles, one documented engine. Every sound on a Designesy surface traces to a token here.

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

Builder prompt

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"
    }
  }
}