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

Priority	Category	Prefix
1	Accessibility	a11y-
2	Appropriateness	appropriate-
3	Implementation	impl-
4	Weight Matching	weight-

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