MCPInstall

sounds-on-the-web

Audit UI code for audio feedback best practices. Use when reviewing sound implementation, checking audio UX decisions, or auditing accessibility. Outputs file:line findings.

Installs
152
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/raphaelsalaja/userinterface-wiki --skill sounds-on-the-web
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads sounds-on-the-web automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Sounds on the Web

Review UI code for audio feedback best practices and accessibility.

How It Works

  1. Read the specified files (or prompt user for files/pattern)
  2. Check against all rules below
  3. Output findings in file:line format

Rule Categories

PriorityCategoryPrefix
1Accessibilitya11y-
2Appropriatenessappropriate-
3Implementationimpl-
4Weight Matchingweight-

Rules

Accessibility Rules

a11y-visual-equivalent

Every audio cue must have a visual equivalent; sound never replaces visual feedback.

Fail:

function SubmitButton({ onClick }) {
  const handleClick = () => {
    playSound("success");
    onClick(); // No visual confirmation
  };
}

Pass:

function SubmitButton({ onClick }) {
  const [status, setStatus] = useState("idle");
  
  const handleClick = () => {
    playSound("success");
    setStatus("success"); // Visual feedback too
    onClick();
  };
  
  return <button data-status={status}>Submit</button>;
}

a11y-toggle-setting

Provide explicit toggle to disable sounds in settings.

Fail:

// No way to disable sounds
function App() {
  return <SoundProvider>{children}</SoundProvider>;
}

Pass:

function App() {
  const { soundEnabled } = usePreferences();
  return (
    <SoundProvider enabled={soundEnabled}>
      {children}
    </SoundProvider>
  );
}

a11y-reduced-motion-check

Respect prefers-reduced-motion as proxy for sound sensitivity.

Fail:

function playSound(name: string) {
  audio.play(); // Plays regardless of preferences
}

Pass:

function playSound(name: string) {
  const prefersReducedMotion = window.matchMedia(
    "(prefers-reduced-motion: reduce)"
  ).matches;
  
  if (prefersReducedMotion) return;
  audio.play();
}

a11y-volume-control

Allow volume adjustment independent of system volume.

Fail:

function playSound() {
  audio.volume = 1; // Always full volume
  audio.play();
}

Pass:

function playSound() {
  const { volume } = usePreferences();
  audio.volume = volume; // User-controlled
  audio.play();
}

Appropriateness Rules

appropriate-no-high-frequency

Do not add sound to high-frequency interactions (typing, keyboard navigation).

Fail:

function Input({ onChange }) {
  const handleChange = (e) => {
    playSound("keystroke"); // Annoying on every keystroke
    onChange(e);
  };
}

Pass:

function Input({ onChange }) {
  // No sound on typing - visual feedback only
  return <input onChange={onChange} />;
}

appropriate-confirmations-only

Sound is appropriate for confirmations: payments, uploads, form submissions.

Pass:

async function handlePayment() {
  await processPayment();
  playSound("success"); // Appropriate - significant action
  showConfirmation();
}

appropriate-errors-warnings

Sound is appropriate for errors and warnings that can't be overlooked.

Pass:

function handleError(error: Error) {
  playSound("error"); // Appropriate - needs attention
  showErrorToast(error.message);
}

appropriate-no-decorative

Do not add sound to decorative moments with no informational value.

Fail:

function Card({ onHover }) {
  return (
    <div onMouseEnter={() => playSound("hover")}> {/* Decorative, no value */}
      {children}
    </div>
  );
}

appropriate-no-punishing

Sound should inform, not punish; avoid harsh sounds for user mistakes.

Fail:

function ValidationError() {
  playSound("loud-buzzer"); // Punishing
  return <span>Invalid input</span>;
}

Pass:

function ValidationError() {
  playSound("gentle-alert"); // Informative but not harsh
  return <span>Invalid input</span>;
}

Implementation Rules

impl-preload-audio

Preload audio files to avoid playback delay.

Fail:

function playSound(name: string) {
  const audio = new Audio(`/sounds/${name}.mp3`); // Loads on demand
  audio.play();
}

Pass:

const sounds = {
  success: new Audio("/sounds/success.mp3"),
  error: new Audio("/sounds/error.mp3"),
};

// Preload on app init
Object.values(sounds).forEach(audio => audio.load());

function playSound(name: keyof typeof sounds) {
  sounds[name].currentTime = 0;
  sounds[name].play();
}

impl-default-subtle

Default volume should be subtle, not loud.

Fail:

const DEFAULT_VOLUME = 1.0; // Too loud

Pass:

const DEFAULT_VOLUME = 0.3; // Subtle default

impl-reset-current-time

Reset audio currentTime before replay to allow rapid triggering.

Fail:

function playSound() {
  audio.play(); // Won't replay if already playing
}

Pass:

function playSound() {
  audio.currentTime = 0;
  audio.play();
}

Weight Matching Rules

weight-match-action

Sound weight should match action importance.

Fail:

// Loud fanfare for minor action
function handleToggle() {
  playSound("triumphant-fanfare");
  setEnabled(!enabled);
}

Pass:

// Subtle click for minor action
function handleToggle() {
  playSound("soft-click");
  setEnabled(!enabled);
}

// Richer sound for significant action
function handlePurchase() {
  playSound("success-chime");
  completePurchase();
}

weight-duration-matches-action

Sound duration should match action duration.

Fail:

// 2-second sound for instant action
function handleClick() {
  playSound("long-whoosh"); // 2000ms
  // Action completes immediately
}

Pass:

// Short sound for instant action
function handleClick() {
  playSound("click"); // 50ms
}

// Longer sound for process
function handleUpload() {
  playSound("upload-progress"); // Matches upload duration
}

Output Format

When reviewing files, output findings as:

file:line - [rule-id] description of issue

Example:
components/input/index.tsx:23 - [appropriate-no-high-frequency] Playing sound on every keystroke
lib/sounds.ts:45 - [a11y-reduced-motion-check] Not checking prefers-reduced-motion

Summary Table

After findings, output a summary:

RuleCountSeverity
a11y-visual-equivalent2HIGH
appropriate-no-high-frequency1HIGH
impl-preload-audio3MEDIUM

Sound Appropriateness Matrix

InteractionSound?Reason
Payment successYesSignificant confirmation
Form submissionYesUser needs assurance
Error stateYesCan't be overlooked
NotificationYesMay not be looking at screen
Button clickMaybeOnly for significant buttons
TypingNoToo frequent
HoverNoDecorative only
ScrollNoToo frequent
NavigationNoKeyboard nav would be noisy

References

FAQ

What does the sounds-on-the-web skill do?

Audit UI code for audio feedback best practices. Use when reviewing sound implementation, checking audio UX decisions, or auditing accessibility. Outputs file:line findings.

How do I install sounds-on-the-web?

Run npx skills add https://github.com/raphaelsalaja/userinterface-wiki --skill sounds-on-the-web in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sounds-on-the-web/ (personal) or .claude/skills/sounds-on-the-web/ (project).

Which AI agents can use sounds-on-the-web?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is sounds-on-the-web safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains sounds-on-the-web?

It is published by raphaelsalaja in raphaelsalaja/userinterface-wiki. It has 152 recorded installs.

More from raphaelsalaja/userinterface-wiki

View all →

userinterface-wiki

raphaelsalaja/userinterface-wiki

UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.

Frontend & Design4.6K installs

12-principles-of-animation

raphaelsalaja/userinterface-wiki

Open the skill to read its SKILL.md instructions.

Frontend & Design275 installs

generating-sounds-with-ai

raphaelsalaja/userinterface-wiki

Open the skill to read its SKILL.md instructions.

177 installs

to-spring-or-not-to-spring

raphaelsalaja/userinterface-wiki

Open the skill to read its SKILL.md instructions.

Backend & APIs152 installs

mastering-animate-presence

raphaelsalaja/userinterface-wiki

Open the skill to read its SKILL.md instructions.

147 installs

pseudo-elements

raphaelsalaja/userinterface-wiki

Audit CSS for pseudo-element best practices and View Transitions API usage. Use when reviewing hover effects, decorative layers, or page transitions. Outputs file:line findings.

Frontend & Design139 installs

Popular frontend & design skills

View category →

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1M installs

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design999.2K installs

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design930.5K installs

vercel-react-best-practices

vercel-labs/agent-skills

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

OfficialFrontend & Design843.1K installs