agentleFS
naomiaronaomiaro/waveform-playlist/.claude/skills/design-proposals/SKILL.md

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

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the naomiaro/waveform-playlist repository that our weekly crawl found: only 11 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about naomiaro/waveform-playlist

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

3 more on GitHub

On Stack Overflow · 2

On Hacker News · 1

The file

Files
SKILL.md

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 outer ThemeProvider (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 MediaElementPlaylistProvider only. 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 isPlaying to 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 (seekTo clamped to a duration state 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() because setSelection already restarts playback. play() also wrote playbackStartTimeRef and audioStartPositionRef, which useEngineRefs() hands to consumers; the restart inside setSelection did 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?: string on loadMidiTracks without 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: name renames 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 onTracksChange away; 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().tracks here) 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 by buildTrackFromConfig; both removed since, with #812) and a type that existed only for it (core's TrackEffectsFunction). Removing the field removed a working option of useAudioTracks, 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's kind and the clip's midiNotes).
  • Before moving an option down the tree, list who reads it ABOVE its new home. waveHeight moved to the view (#689); SpectrogramProvider sits 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 from PlayheadProps. A side agent pointed out that a playhead copied from the old PlayheadWithMarker destructures every removed prop (four as a fallback, controlsOffset with 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 is undefined, 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.editable was read once at mount; moving the MediaElement editable prop 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 is useFollowedOption in packages/browser/src/providerInternals/useAnnotationState.ts (value state plus "last prop seen" state, compared during render).
  • A refactor that moves a switch can widen a case. Moving the engine's change handler into a default: branch made the selection clearing run for setTracks too, 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's pointer-events: none rule: 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 annotationBoxBorder would 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 in WaveformPlaylistTheme (a required one breaks consumers' complete theme objects), with the fallback in the component.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.