design-proposals
Skill1.7k starsChanged yesterdayMITView on GitHub
Use when proposing a design, a fix or an option to the maintainer for a change in packages/ - before saying a change is small, non-breaking or cheap, before removing, renaming or moving a public field, prop, option or hook, when merging two components or sharing one between providers, and when designing a pointer interaction, a limit or a theme key.
1 other project uses a version of this.
Trending
Quiet this year.thin dataabout the whole repository
Most recently taken up by
- satoshi-grm/design-proposals-skilltheir own version, first seen Sep 28, 2026
Who's talking about naomiaro/waveform-playlist
- WebAudio/web-audio-api“Ability to change the playback rate of an AudioBufferSourceNode without affecting the pitch”GitHub · Apr 27, 2022 · 26 reactions
- A Hacker News story“Web Audio API Playlist”Hacker News · Jun 24, 2013 · 2 points
- gilpanal/waveform-playlist“Fetchtest”GitHub · Mar 20, 2024
- lifeart/sm-annotate“Add audio spectrogramm?”GitHub · Aug 2, 2023
- Micrufun/daw“Stream”GitHub · Jan 29, 2023
The biggest 5 of 11 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 11
Talked about on GitHub, Stack Overflow and Hacker News (11 times).
On GitHub · 8
- Apr 27, 2022Ability to change the playback rate of an AudioBufferSourceNode without affecting the pitch — WebAudio/web-audio-api26 reactions · 8 comments
- Mar 20, 2024Fetchtest — gilpanal/waveform-playlist0 reactions
- Aug 2, 2023Add audio spectrogramm? — lifeart/sm-annotate0 reactions · 1 comment
- Jan 29, 2023Stream — Micrufun/daw0 reactions
- May 13, 2022[Feature Request] — doublesymmetry/react-native-track-player0 reactions · 15 comments
3 more on GitHub
- Feb 6, 2022using waveform-playlist with opus-recorder — chris-rudmin/opus-recorder0 reactions · 1 comment
- Dec 27, 2021Waveform playlist: mixing audio tracks — Tonejs/Tone.js0 reactions · 2 comments
- Jul 24, 2020add https://github.com/naomiaro/waveform-playlist — amilajack/awesome-web-audio0 reactions
On Stack Overflow · 2
- Jan 30, 2021Play multiple wave at the same time0 votes
- Apr 4, 2018Customising waveform-playlist plugin0 votes · 1 answer
On Hacker News · 1
- Jun 24, 2013Web Audio API Playlist2 points
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- satoshi-grm/design-proposals-skill★ 8same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- website/CLAUDE.mdCLAUDE.md
- browser-probesSkill
- dependency-updatesSkill
- dnd-kitSkill
- e2e-playwrightSkill
- mutation-testingSkill
- react-patternsSkill
- releaseSkill
- review-roundsSkill
- state-ownershipSkill
- translatable-stringsSkill
- unit-testingSkill
The file
Files
Design proposals: what to check before recommending
How a question is put to the maintainer (one lettered question, its own message) is in root CLAUDE.md. State with two places is the skill state-ownership.
Claims about behaviour
- "Nothing breaks" is a claim about behaviour, not about the API, and it needs the trees walked before it is said. #773 kept two
<Waveform>props beside a new context and was recommended as non-breaking. Review then found that an app with the flag on the provider only got 24px trim handles, and that<PlaylistVisualization>under the provider became interactive; the chat update called the round "a stale doc sentence and some test gaps", the PR merged on green CI, and the maintainer had it reverted (#774) and redone with one source (#775). Before recommending an option: write down each tree a consumer can build (with and without each provider, the lower-level export used directly, one provider nested in another, a leftover prop in plain JS) and what it does before and after. Brief the reviewer to return that table for the final diff, with a column for "stated in the upgrade guide". Every row goes to the maintainer in chat before the merge, whatever the standing merge authorisation says; each later round that adds a row means another message. - "It hangs" and "it is replaced" are claims to run before sending. On #689 I reported that zero-width bars freeze the page (they drew a blank waveform: the first bar position was
NaN) and that our theme replaces an outerThemeProvider(styled-components merges an object theme over the outer one). Both went to the maintainer as read from the code and both were wrong. - "Use another provider" is true for
MediaElementPlaylistProvideronly. Multitrack providers with the default Tone engine share one transport (one instance per page, per our docs; #805). Say which provider before recommending a second one. - A prediction is not a measurement: say which one a number is. On #686 the maintainer was told the built-in drag would cost one component per move (measured in a prototype) and that a toggle would fall to about 22 (a guess). Both were wrong on the real build (47 unchanged; 221). Write "predicted" or "measured in the prototype" next to a number, and replace it the moment the build is measured; a doc reviewer found the stale "+1" row in the upgrade guide.
- A fix asked for during review is a new design: trace what reads the state it touches before proposing it. On #769 the maintainer asked for
isPlayingto become false when the MediaElement provider replaces its player. That one line led to four more commits, each found by the next review round or a side agent: what happens to the cursor (asked only after building), a child's own restore being overwritten (the reset ran after child effects), the restore being cut off (seekToclamped to adurationstate that still held the old file's length), and the new player not being moved to the stored position. Before offering "a small fix", list who reads and who writes each value it changes, in the order React runs them (render, layout effects, passive cleanups, passive effects, async init,onReady), and put the behaviour choice to the maintainer with that list. Two orderings worth remembering: React runs every passive-effect cleanup of a commit before any passive effect, so a provider reset that a child's effect must be able to override belongs in the provider's cleanup; and a ref that a cleanup compares against must hold a COMMITTED value, so write it in a layout effect, not during render. - When a handler stops calling a function, list everything that function wrote. On #793 the release stopped calling
play()becausesetSelectionalready restarts playback.play()also wroteplaybackStartTimeRefandaudioStartPositionRef, whichuseEngineRefs()hands to consumers; the restart insidesetSelectiondid not, so a readout computed from them kept counting from the replaced play (found in review). "It already restarts" is about one effect of the call, not all of them. - Every option in a planned signature gets its meaning in the plan, and "port X from branch Y" is written after reading X. The plan for #853 listed
name?: stringonloadMidiTrackswithout saying what it does for a file with several tracks, and said "the placeholder look of the backup branch", which was one data attribute and no CSS. Both became an implementer's guess and then a question to the maintainer mid-build (answers:namerenames a single-track result only; a dim through a theme key). - When per-move writes to an owner are replaced by a preview, list everything that redrew BECAUSE of those writes. The trim preview of #812 took the per-move
onTracksChangeaway; the clip's drawing and the timeline width were given the preview, and the spectrogram (which redraws from the committed tracks when a canvas registers) was not on the list. It showed the pre-trim range during the drag and after release, found by the final reviewer from the source and confirmed by a pixel comparison. Grep the readers of the owner's value in every package (usePlaylistTimeline().trackshere) before the design says what follows the preview. The repair kept the preview internal: each canvas registers with the range it is drawn for (SpectrogramCanvasRegistration.offsetSamples/durationSamples), and the provider draws that.
Removing, moving and renaming
- Removing a public field: trace its writers as well as its readers, and report every public surface it reaches before removing it.
ClipTrack.effects(#752) had two readers in the Tone adapter, but also a writer (AudioTrackConfig.effects, copied onto the track bybuildTrackFromConfig; both removed since, with #812) and a type that existed only for it (core'sTrackEffectsFunction). Removing the field removed a working option ofuseAudioTracks, which the maintainer had not been asked about and which needed a replacement (AudioTrackConfig.id). When a removal turns out to reach a second public surface, stop and say so, with what replaces it. - "Remove it if it is unused": unused as an input is not unused. After #756 nothing needed
'piano-roll'to be SET (ClipTrack.renderMode,<daw-track render-mode>), but it was still the value the renderers switched on in four packages (SmartChannel,ChannelWithProgress,TrackRows, the<daw-editor>template). Grep the value's readers before answering, say which it is, and ask when removing it changes a public type or prop (#763: the maintainer chose "remove it entirely", and the discriminator became the track'skindand the clip'smidiNotes). - Before moving an option down the tree, list who reads it ABOVE its new home.
waveHeightmoved to the view (#689);SpectrogramProvidersits above the view and read it from the provider. It now takes the height each canvas registers with. - When hooks move onto shared contexts, list what stops throwing. After #688 part 2 made both providers render the same context objects,
usePlaybackShortcuts()(it reads only shared hooks) silently started working under the MediaElement provider, against a decision that there are no shortcuts there; a docs agent noticed, not the tests. After such a move, grep every exported hook and component for the contexts it reads and write down each one that no longer throws under the other provider, before the first review. - Removed names do not throw (maintainer's decision, 2026-11-12, #688 part 3). Part 2 gave the
usePlaybackRefs()value throwing getters for its eight moved fields, and part 3 first did the same for the five props removed fromPlayheadProps. A side agent pointed out that a playhead copied from the oldPlayheadWithMarkerdestructures every removed prop (four as a fallback,controlsOffsetwith a default of 0), so the guard would crash code that otherwise kept working; the maintainer then had both guards removed: "people need to check the upgrade guide". A value handed to consumers is a plain object, a leftover read isundefined, and the upgrade guide carries the removed-to-replacement table and says what a leftover read does. Do not add such a guard again. Before proposing any "fail loudly" device, list the consumer code that reads the name without depending on it. - A prop that seeds state is a trap when an option moves into a provider.
annotationList.editablewas read once at mount; moving the MediaElementeditableprop there would have silently stopped an app that drove it from its own state. Before moving an option to provider state, check whether the prop is followed or only seeds, and state it in the design's behaviour table. The pattern that follows a prop without an effect isuseFollowedOptioninpackages/browser/src/providerInternals/useAnnotationState.ts(value state plus "last prop seen" state, compared during render). - A refactor that moves a
switchcan widen a case. Moving the engine's change handler into adefault:branch made the selection clearing run forsetTrackstoo, and no test failed, because nothing pinned that it does not (#847; a docs agent found it reading source). When a decision is "X does NOT happen for case Y", write the negative test when the decision is made.
Shared components and markup
- Merging twin components: compare how each PARENT uses its copy, not only the two bodies. For #688 part 3 the playhead twins differed in a frame-callback id; the visible difference was one level up, where the multitrack view wraps its playhead in
PlayheadOverlay(hidden at rest while a range is highlighted) and the MediaElement view did not. That became a behaviour choice for the maintainer. A shared wrapper also costs one component per render of the parent that did not have it (40 to 41 per play on the MediaElement pages): say "within one or two" in the design, not "identical". - "One part for both providers" does not mean one playback call. On #686 the shared box part called
play(start, length)under both providers; under MediaElement, which ends an annotation through its animation loop, that changed four behaviours a reviewer had to trace. When two providers reach one result by different mechanisms, the part asks the provider (usePlaybackControls().playAnnotation), and the first design lists each provider's mechanism before choosing a shared call. - Before putting an attribute our guides style on a new element, grep the guides for CSS that targets it.
data-playlist-state="loading"on the MediaElement view met the Loading Audio guide'spointer-events: nonerule: clicks were dead until the metadata arrived (#685 part 2, first review). - Reusing one view's markup under another provider makes existing selectors match it. List the selector collisions (
[data-track-row],[data-selected], counts of[data-playlist-state]) as rows of the behaviour-change table. - A panel that fills its box hides a sibling in the flow. The #687 design said "the default panel plus your own control beside it"; only a control that positions itself is visible there. Render a composition claim in a browser before it goes into a design.
Interactions, limits and themes
- A design row about an interaction is written from the handlers, not from the API. For #782 the row "a drag during playback becomes selection playback" came from reading
setSelection; the multitrack view's mouse handlers at the time ignored moves while playing and treated the press as a seek, so the row was wrong and had to be corrected in chat after the design was approved. Read the view's pointer handlers for each row that starts with a press, a drag or a key. - A design for a pointer interaction says what moves under a still pointer, and how a click is told from a drag, as choices. On #793 (a drag during playback draws a range) I had not asked what happens with automatic scroll on, where the view scrolls and the audio under a held pointer changes, and I was about to tell a click from a drag by pointer travel, a rule nobody had seen. A side agent raised both before I did; the maintainer's answer (no live selection with automatic scroll on) made the second rule unnecessary. List these two for any press-hold-release design before building.
- A limit copied from an example is a behaviour choice. The first #686 build clamped the annotation edge drag to the audio's length because the examples' own wiring did; on an empty timeline that is 0 and a dragged edge collapsed (seen in a Storybook story with no audio). For any clamp, write down its value on an empty timeline, during a recording and in a view that fills its container, and put the choice to the maintainer. When the maintainer changes one limit, grep for its siblings (the boundary shortcuts kept the old clamp) and say so in the same message.
- A theme key that was never read can have a default nobody has seen. Wiring
annotationBoxBorderwould have turned dark-mode box borders from orange to the dark theme's unread#c49a6c. Before reading an existing key, compare its value in BOTH default themes with what is on screen. A new theme key is optional inWaveformPlaylistTheme(a required one breaks consumers' complete theme objects), with the fallback in the component.
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.

