---
name: iconmuse
description: Add IconMuse by ChordMuse (199 hand-drawn music icons for notation, instruments, playback, volume, studio gear and library UI) to any project. Detects the tech stack (React, Next.js, React Native/Expo, Vue, Nuxt, Svelte/SvelteKit, Angular, Solid, Astro, vanilla HTML/Lit, Django/Flask/Rails/Laravel/PHP/Go, Flutter, Android/Compose, iOS/macOS SwiftUI/UIKit), including monorepos, and installs the official package or generates a native, typed icon pack. Use when the user asks for music icons, IconMuse or ChordMuse icons, or icons for play/pause, instruments, notes, clefs, volume, headphones, microphones and similar.
---

# IconMuse

IconMuse is a set of 199 music icons on a 24 × 24 grid with a 1.5px round stroke. Colour comes from `currentColor` on the web and from tint natively.

The gallery is at https://icons.chordmuse.app, and the agent index is at `https://icons.chordmuse.app/llms.txt`.

Everything you need is in `scripts/iconmuse.mjs`, a zero-dependency script for Node 18+. It ships with its own copy of the icon data in `assets/icons.json`, so it works offline.

## Workflow

### 1. Detect the stack

```bash
node <skill-dir>/scripts/iconmuse.mjs detect --cwd <project> --json
```

This returns `targets: [{ tech, root, language, outDir, needs? }]`. In a monorepo you'll see one target per app. If it's unclear which app the user means, ask them.

If nothing is detected, run `techs` and choose the tech the user describes.

### 2. Choose how to install

Prefer the official package when the user's environment can reach it, and generate a pack otherwise.

| Tech | Official package | Fallback |
| --- | --- | --- |
| React, Next | `npm i iconmuse`, then `import { IconMuse } from 'iconmuse/react'` | `generate` |
| Vue, Nuxt, Svelte, Angular, Solid, Astro, React Native | none native; the npm package only offers a Web Component | **`generate`** (preferred: typed, framework-native component) |
| Vanilla / static | `<script type="module" src="https://icons.chordmuse.app/dist/icon-muse.js">` | `generate` (self-hosted) |
| Flutter | `flutter pub add iconmuse`, or a git dependency with `path: packages/flutter` | `generate` |
| iOS / macOS | Swift Package `https://github.com/chordmuse/icon_library`, product `IconMuse` | `generate` |
| Android | `app.chordmuse:iconmuse` (Maven) | **`generate`** |

The registry packages may not be published yet, and the GitHub repo may be private. Before using a registry install, check it resolves, e.g. `npm view iconmuse version`. If it doesn't, use `generate`. Never invent a version number.

### 3. Generate the pack (fallback or preferred)

```bash
# single app
node <skill-dir>/scripts/iconmuse.mjs generate --cwd <project> --json

# monorepo: pick the app
node <skill-dir>/scripts/iconmuse.mjs generate --cwd <repo> --tech next --root apps/web --json

# only the icons the user needs (smaller bundles and apps)
node <skill-dir>/scripts/iconmuse.mjs generate --cwd <project> --icons play,pause,skip-forward,volume-high --json

# preview without writing
node <skill-dir>/scripts/iconmuse.mjs generate --cwd <project> --dry-run --json
```

Other options:
- `--out <dir>` overrides the folder.
- `--ts` or `--js` forces the language.
- `--source https://icons.chordmuse.app` pulls the latest icons instead of the bundled copy.
- `--all` generates for every target in a monorepo.

If the output contains `"ambiguous": true`, ask the user which target to use, or pass `--root`.

What gets written:

| Tech | Files | Usage |
| --- | --- | --- |
| react / next | `IconMuse.tsx`, `iconmuse-data.ts`, `index.ts` | `<IconMuse name="play" size={24} />` |
| react-native | `IconMuse.tsx` (react-native-svg), data | `<IconMuse name="play" color={c} />` |
| vue | `IconMuse.vue`, data | `<IconMuse name="play" :size="24" />` |
| nuxt | `components/IconMuse.vue` (auto-imported), `iconmuse/iconmuse-data.ts` | `<IconMuse name="play" />` |
| svelte | `IconMuse.svelte`, `index.ts` in `src/lib/iconmuse` | `import { IconMuse } from '$lib/iconmuse'` |
| angular | standalone `IconMuseComponent` (`<icon-muse>`); uses `@if/@for` on 17+ and `*ngFor` on older versions | add to `imports: []` |
| solid / astro | `IconMuse.tsx` / `IconMuse.astro`, data | `<IconMuse name="play" />` |
| web | `iconmuse.js` (`<icon-muse>` Web Component) and `sprite.svg` | `<icon-muse name="play">` |
| static | the above plus `svg/*.svg` in the framework's static folder | template snippet in the output |
| flutter | `lib/iconmuse/iconmuse.dart`: `IconMuseIcons` enum and `IconMuse` widget | `IconMuse(IconMuseIcons.play)` |
| android | `res/drawable/ic_iconmuse_*.xml` | `painterResource(R.drawable.ic_iconmuse_play)` |
| ios | `IconMuse.xcassets` and `IconMuse.swift` next to `Assets.xcassets` | `IconMuse.play.image` |

### 4. Finish the job

1. **Dependencies:** install anything listed in `needs`, e.g. `npx expo install react-native-svg` or `flutter pub add flutter_svg`.
2. **Use the icons:** replace the placeholder or the icons the user asked about with real `IconMuse` usages, adapting the `usage` snippet from the output to the project's import aliases.
3. **Verify:** run the project's own type-check or build (`tsc --noEmit`, `npm run build`, `flutter analyze`, `./gradlew :app:assembleDebug`, or an Xcode build), then report the result.
4. **Xcode:** if the project doesn't use synchronized folders, tell the user to add `IconMuse.xcassets` and `IconMuse.swift` to the target.
5. **Report:** tell the user which files were written and how to regenerate them. Re-running `generate` overwrites only IconMuse's own files.

## Finding icons

```bash
node <skill-dir>/scripts/iconmuse.mjs list --search guitar --json
```

Names are kebab-case (`guitar-electric`). In code they become camelCase in Swift, Dart and Kotlin (`guitarElectric`), and snake_case in Android resources (`ic_iconmuse_guitar_electric`). There are 10 categories:
- notation
- playback
- audio (volume and sound)
- strings
- keys
- winds
- percussion
- devices
- studio
- library

## Rules

- Don't hand-edit generated files. Re-run `generate` with different flags instead.
- Don't draw new icons or substitute another icon set. If an icon doesn't exist, say so, suggest the closest match from `list`, and point to `src/icons.mjs` in the IconMuse repo for contributions.
- Keep icons decorative (`aria-hidden`) unless they convey meaning on their own. In that case pass `title`, `label` or `semanticLabel`.