Interface Sound

Interface Sound

Use sound as interaction feedback, not decoration. Sound should clarify state, confirm rare actions, or make a product moment more legible.

Sources:

• https://audio.raphaelsalaja.com/
• https://github.com/raphaelsalaja/audio

When Sound Belongs

Use sound for:

• success or completion moments
• error, warning, or destructive feedback
• notification or mention events
• tactile controls in creative tools, games, and playful apps
• onboarding or first-run moments where feedback is part of the product feel

Avoid sound for:

• high-frequency hover states
• normal navigation
• dense productivity workflows unless the user opted in
• anything that could fire repeatedly in a loop

Accessibility & UX Rules

• Default to muted or low volume unless the product category implies sound.
• Provide a visible sound setting when sounds can repeat or persist.
• Never autoplay sound on page load.
• Initialize audio from a user gesture.
• Respect reduced-motion style preferences as a signal to keep sensory feedback restrained.
• Pair every sound with visual feedback; sound must never be the only state indicator.

Install

bun add @web-kits/audio
pnpm add @web-kits/audio
npm install @web-kits/audio

Basic Pattern

import { defineSound, ensureReady } from "@web-kits/audio";

const successTone = defineSound({
  source: { type: "sine", frequency: { start: 660, end: 880 } },
  envelope: { attack: 0.005, decay: 0.12, release: 0.04 },
  gain: 0.18,
});

export async function playSuccessTone() {
  await ensureReady();
  successTone();
}

Call from an intentional user action, such as a completed submit or confirmed command.

Sound Vocabulary

| Event | Direction | | --- | --- | | click / tap | very short, low gain, fast decay | | toggle on | two small ascending tones | | toggle off | two small descending tones | | success | soft ascending interval or small chord | | error | short descending tone, restrained distortion | | notification | clear but quiet bell-like tone | | modal open | subtle ascending whoosh | | modal close | shorter descending whoosh |

Implementation Notes

• Keep per-sound gain conservative; start around 0.12 to 0.25.
• Keep most UI sounds under 200ms.
• Use patches when a project has more than a couple sounds.
• Store reusable patches under .web-kits/ or a project-specific src/sounds/ directory.
• Add a single sound preference in app settings before adding many sounds.

Verification

Before shipping:

1. Confirm sound only plays after user interaction.
2. Confirm mute/off works.
3. Test repeated actions for annoyance.
4. Test with system volume high.
5. Confirm the same state is visible without sound.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tommylower
• Source: tommylower/cortex
• License: MIT

Install and usage instructions live in the source repository linked above.