# UI Sound Design Skill

```
  ▁ ▃ ▅ ▇ ▅ ▃ ▁     ▁ ▃ ▅ ▇ ▅ ▃ ▁     ▁ ▃ ▅ ▇ ▅ ▃ ▁
██╗   ██╗██╗    ███████╗ ██████╗ ██╗   ██╗███╗   ██╗██████╗
██║   ██║██║    ██╔════╝██╔═══██╗██║   ██║████╗  ██║██╔══██╗
██║   ██║██║    ███████╗██║   ██║██║   ██║██╔██╗ ██║██║  ██║
██║   ██║██║    ╚════██║██║   ██║██║   ██║██║╚██╗██║██║  ██║
╚██████╔╝██║    ███████║╚██████╔╝╚██████╔╝██║ ╚████║██████╔╝
 ╚═════╝ ╚═╝    ╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚═════╝
      ░ ▒ ▓ █ ▓ ▒ ░     ░ ▒ ▓ █ ▓ ▒ ░     ░ ▒ ▓ █ ▓ ▒ ░
       ██████╗ ███████╗███████╗██╗ ██████╗ ███╗   ██╗
       ██╔══██╗██╔════╝██╔════╝██║██╔════╝ ████╗  ██║
       ██║  ██║█████╗  ███████╗██║██║  ███╗██╔██╗ ██║
       ██║  ██║██╔══╝  ╚════██║██║██║   ██║██║╚██╗██║
       ██████╔╝███████╗███████║██║╚██████╔╝██║ ╚████║
       ╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝
  ▇ ▅ ▃ ▁ ▃ ▅ ▇     ▇ ▅ ▃ ▁ ▃ ▅ ▇     ▇ ▅ ▃ ▁ ▃ ▅ ▇
```

An [Agent Skill](https://agentskills.io) that translates plain-English sound descriptions into working Web Audio API and Tone.js code. Works with Claude Code, Cursor, VS Code/Copilot, Windsurf, Codex, Goose, and [30+ other AI coding tools](https://agentskills.io/specification). No audio engineering background needed.

## What It Does

Describe what you want to hear, and your AI agent generates production-ready sound synthesis code.

The workflow is iterative: **Describe** the sound in plain language, **Generate** the code, **Listen** in-browser, **Refine** with feedback like "make it snappier" or "warmer". The skill handles the translation from subjective language to synthesis parameters.

## Sound Categories

| Category | Duration | Character |
|----------|----------|-----------|
| **Click** | 30-100ms | Noise burst, bandpass filtered |
| **Toggle** | 80-200ms | Rising/falling pitch sweep |
| **Hover** | 30-100ms | Gentle, nearly subliminal |
| **Success** | 200-500ms | Ascending major third |
| **Error** | 150-400ms | Descending, buzzy |
| **Warning** | 150-350ms | Double pulse, mid-range |
| **Notification** | 200-800ms | Bell-like FM synthesis |
| **Whoosh** | 100-400ms | Filtered noise sweep |
| **Pop** | 30-100ms | Sine with pitch drop |

## Try It

Open [`skills/ui-sound-design/assets/sound-preview.html`](skills/ui-sound-design/assets/sound-preview.html) in any browser. No install needed — click the buttons to hear all 10 default sounds.

## Install

```bash
npx skills add dannyjpwilliams/ui-sound-design-skill
```

The CLI auto-detects your installed AI coding tools and installs the skill to all of them.

## Compatibility

This skill follows the [Agent Skills](https://agentskills.io/specification) open standard and works with any compatible AI coding tool, including:

- **Claude Code** — `.claude/skills/`
- **Cursor** — `.cursor/skills/`
- **VS Code / GitHub Copilot** — `.github/skills/`
- **Windsurf** — `.windsurf/skills/`
- **Codex CLI** — `.codex/skills/`
- **Goose** — `.goose/skills/`
- **Gemini CLI**, **Roo Code**, **Trae**, and others

`npx skills add` handles the correct installation path for each tool automatically.

## Usage

Ask your AI agent to design sounds using natural language:

```
"Make a click sound for a settings toggle — subtle, professional"
```

```
"I need a notification chime that sounds like a soft bell, not too attention-grabbing"
```

```
"Create a success sound for when a file uploads. Cheerful but not over the top."
```

```
"Build me a complete UI sound library with click, hover, success, and error sounds. Output as an ES module."
```

Your agent will generate an HTML preview you can open in your browser, then refine based on your feedback ("make it warmer", "shorter", "more playful").

### Audio File References

Have a sound you want to match? Use it as a style reference:

```bash
node skills/ui-sound-design/tools/analyze-sound.mjs path/to/reference.wav
```

The analyzer extracts a detailed sound profile — duration, envelope, spectral content, harmonics, brightness — and maps it to synthesis parameters. Paste the output into your conversation, and your agent uses it as the starting point for synthesis. Then refine as usual.

Supports `.wav` natively. Other formats (`.mp3`, `.ogg`, `.flac`) require [ffmpeg](https://ffmpeg.org). Zero npm dependencies — just Node.js.

## How It Works

The skill acts as a **vocabulary bridge** between subjective language and audio synthesis parameters:

| You Say | What Changes |
|---------|-------------|
| "Brighter" | Raise frequency or filter cutoff |
| "Warmer" | Lower filter cutoff, switch to sine/triangle |
| "Snappier" | Shorter attack and decay |
| "Softer" | Lower volume, longer attack |
| "More metallic" | FM synthesis, inharmonic ratios |
| "More playful" | Higher pitch, add overshoot |
| "More professional" | Lower volume, sine wave, short duration |
| "Retro / 8-bit" | Square wave, quantized pitch |

The full vocabulary bridge and all recipes are embedded in the skill files, so any compatible agent has the synthesis knowledge to translate any description.

## Skill Structure

```
skills/ui-sound-design/
├── SKILL.md                        # Skill definition — workflow, vocabulary bridge, rules
├── references/
│   ├── sound-recipes.md            # 9 complete sound implementations + UISoundLibrary class
│   ├── web-audio-api.md            # Web Audio API building blocks and patterns
│   ├── audio-file-references.md    # Guide for interpreting audio file analysis profiles
│   └── tone-js.md                  # Tone.js patterns and vanilla conversion guide
├── assets/
│   └── sound-preview.html          # Self-contained HTML demo with all 10 sounds
└── tools/
    └── analyze-sound.mjs           # CLI audio analyzer (zero dependencies)
```

## License

[MIT](LICENSE)