change-primitive
Skill202 starsChanged 33 days agoMITView on GitHub
Change, fix or add a headless primitive or its logic in the published packages @audio-ui/react (packages/ui) or @audio-ui/core (packages/core): props, parts, keyboard or pointer behavior, ARIA, scales, timeline or waveform math. Use for any edit under packages/, since each one needs tests, a changeset and the matching docs API reference.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- skills/audio-ui/AGENTS.mdAGENTS.md
- skills/core/AGENTS.mdAGENTS.md
- skills/design/AGENTS.mdAGENTS.md
- skills/web-audio/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- add-registry-itemSkill
- film-componentSkill
- audio-uiSkill
- coreSkill
- designSkill
- web-audioSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Keep the domain words of CONTEXT.md: onValueChange streams every change, onValueCommitted fires once when the gesture ends.
- Very specific: line 28
Shipped skill: If a prop, part, data attribute or CSS variable that skills/audio-ui/ names changed, update it.
- Very specific: line 29
Registry element: If the styled element in apps/www/src/registry-audio/bases/base/audio/elements/<name>.tsx should use the new prop or …
- Very specific: line 48
Look at it: Run bun run dev, open the component's docs page on localhost:4000, and drive it with the pointer, the wheel and the keyboard.
- Very specific: line 50
If the change is visible, film it: film-component skill, bun run update <name>.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Change a primitive
Both packages are published to npm. Every change here is a change to someone's app.
Where the code goes
- Logic that doesn't need React (geometry, value mapping, clip operations, peaks):
packages/core/src/primitives/<name>/, with a*.test.tsnext to it. Shared helpers:packages/core/src/{shared,value,dom}/. - React parts:
packages/ui/src/primitives/<name>/elements/<part>.tsx, the context incontext.ts, tests intest/. The public surface ispackages/ui/src/entries/<name>.ts, re-exported byindex.ts. - A new export from core that adapters need but users don't goes in
packages/core/src/internal.ts, notindex.ts.
Rules
- Relative imports end in
.ts/.tsx(./controller.ts). A.jsspecifier breaks the www build. - Keep the domain words of CONTEXT.md:
onValueChangestreams every change,onValueCommittedfires once when the gesture ends. - Accessibility is part of the behavior: every interactive part keeps a role, an accessible name hook (
aria-labelor aLabelpart), keyboard support andaria-valuetextwhere a value is shown. - Public API: removing or renaming a prop, part or export is a breaking change. Prefer adding. If you must break, say so in the changeset and ask first.
Steps
- Test first. Reproduce the bug or describe the new behavior in a test (
bun testin the package). Pointer and keyboard tests for parts live inpackages/ui/src/primitives/<name>/test/. - Change the code in core first if the logic is framework-free, then the React part.
- Docs API reference. The JSDoc of each part in
elements/and the<TypeRow>lines under "API reference" inapps/www/src/content/docs/components/base/(<space>)/<name>.mdxare hand-kept copies of each other. Change both, word for word. - Shipped skill. If a prop, part, data attribute or CSS variable that
skills/audio-ui/names changed, update it;bun test test/skills.test.tsinapps/wwwchecks the names. - Registry element. If the styled element in
apps/www/src/registry-audio/bases/base/audio/elements/<name>.tsxshould use the new prop or part, update it and follow theadd-registry-itemskill's build step. - Changeset.
bun run changeset, or write.changeset/<short-name>.mdby hand:--- "@audio-ui/react": patch --- Timeline: <what changed for the user, and why, in one or two sentences>.patchfor fixes,minorfor new props or parts,majoronly for breaks. Start with the component name. No em dashes, and don't name the underlying headless library. - Check like CI (from the repo root):
bun run lint:fix bunx biome ci packages/core packages/ui bun run build:pkg (cd packages/core && bunx tsc --noEmit && bun test) (cd packages/ui && bunx tsc --noEmit && bun test && bun run size)bun run sizeenforces bundle budgets per entry. If it fails, look for an import that pulls in more than the primitive needs. - Look at it. Run
bun run dev, open the component's docs page onlocalhost:4000, and drive it with the pointer, the wheel and the keyboard.
If the change is visible, film it: film-component skill, bun run update <name>.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

