From b2bf8b476e2fb85594d3c95e42cbea005b57617a Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Sun, 9 Aug 2026 20:20:17 -0700 Subject: [PATCH] =?UTF-8?q?docs(design):=20fix=20the=20hole=20in=20the=20s?= =?UTF-8?q?ingle-knob=20rule=20=E2=80=94=20picking=20the=20range?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Shape One Range has three controls (where, how much, how wide) and the copy nominated "how much" as the one that matters. That is incoherent: boosting an unspecified frequency means nothing. The range is the FIRST decision, not the second, and the rule broke on this module without my noticing. Two ways out, both drawn. A keeps the module generic and makes "where" a word from the shared vocabulary instead of a frequency field — honest, but still two decisions with the first one jargon in a friendly coat. B makes the range the module: the add menu offers jobs — Reduce Mud, Add Clarity, Tame Harshness — each a peaking node with its frequency already chosen, so one knob is honest rather than a simplification hiding the real choice. B is the answer, and it is the same insight as the multi-band EQ: an author does not want a parametric equaliser, they want to fix a thing. It also dissolves the duplicate-name problem at the root instead of papering it with a role label — Clean Voice now reads Remove Rumble, Reduce Mud, Even Out Loudness, Add Clarity, Peak Ceiling, and nothing repeats. Option A is not wasted: its band picker is the right control for moving the frequency under Details. This changes the catalogue rather than only the copy — presets should reference named jobs, and EFFECT_COPY.peaking stops being a single entry. Co-Authored-By: Claude Opus 5 (1M context) --- plans/audio-fx-ux/README.md | 31 ++++++++ plans/audio-fx-ux/build-preview.mts | 110 ++++++++++++++++++++++++++++ 2 files changed, 141 insertions(+) diff --git a/plans/audio-fx-ux/README.md b/plans/audio-fx-ux/README.md index 50d5a45199..b0c3685d2f 100644 --- a/plans/audio-fx-ux/README.md +++ b/plans/audio-fx-ux/README.md @@ -97,6 +97,37 @@ property print as their escape sequence on the page. This cost three rounds of chasing what looked like three unrelated rendering bugs. The template is a plain literal; keep it that way, and use HTML entities for typographic characters. +## The hole in the single-knob rule: picking the range + +`Shape One Range` has three controls — where, how much, how wide — and the +copy nominated *how much* as the one that matters. That is incoherent, and it +took someone asking to see it: boosting an unspecified frequency means nothing. +**The range is the first decision, not the second.** + +Two ways out: + +**A — two controls.** Keep the module generic and make *where* a word from the +shared vocabulary rather than a frequency field. Honest, and the ruler does the +teaching, but it is still two decisions and the first is jargon in a friendly +coat. + +**B — the range IS the module.** The add menu offers *jobs* — Reduce Mud, Add +Clarity, Tame Harshness — each a peaking node with its frequency already +chosen. Picking the module is picking the range, so one knob is honest rather +than a simplification hiding the real choice. + +**B is the answer**, and it is the same insight as the EQ: an author does not +want a parametric equaliser, they want to fix a thing. It also dissolves the +duplicate-name problem at the root rather than papering it with a role label — +`Clean Voice` reads *Remove Rumble · Reduce Mud · Even Out Loudness · Add +Clarity · Peak Ceiling*, and nothing repeats. + +Option A is not wasted: its band picker is exactly the right control for moving +the frequency under **Details**, for the author who wants to. + +This changes the catalogue, not just the copy: the presets should reference +named jobs, and `EFFECT_COPY.peaking` stops being one entry. + ## Proposed: a multi-band EQ ("Tone") The clearest failure this exercise surfaced is a rack holding two *Shape One diff --git a/plans/audio-fx-ux/build-preview.mts b/plans/audio-fx-ux/build-preview.mts index 6073c75ac1..a6c79ff9b0 100644 --- a/plans/audio-fx-ux/build-preview.mts +++ b/plans/audio-fx-ux/build-preview.mts @@ -276,6 +276,91 @@ const eqGrid = [ eqSpecimen(EQ5, "Five bands", "The same module opened up. Band names are the shared vocabulary, so using the EQ teaches the words the rest of the rack uses.", false), ].join(""); + +/* ---- picking the range: the hole the single-knob rule left ------------- */ +const WHERE = ["Rumble", "Weight", "Mud", "Middle", "Presence", "Edge", "Air"]; + +/** Option A — admit it is two-dimensional, and make "where" a word, not a Hz field. */ +function whereSpecimen() { + const seg = WHERE.map((w, i) => `${esc(w)}`).join(""); + return `
+
+
+
+ 02 +
Shape One RangePeaking EQ
+
${seg}
+
+ How much + + −3.0 +
+
Take it outBring it forward
+
+
+
+
+

A — Two controls

+

Where is a word from the shared vocabulary, not a frequency field. Honest, and the ruler is doing the teaching — but it is two decisions, and the first one is still jargon wearing a friendly coat.

+
+
`; +} + +/** Option B — the range is picked when you ADD it. One knob survives. */ +const JOBS = [ + { name: "Reduce Mud", hz: 250, gain: -3, says: "Cutting 250 Hz by 3 dB" }, + { name: "Add Clarity", hz: 3000, gain: 2.5, says: "Lifting 3 kHz by 2.5 dB" }, + { name: "Tame Harshness", hz: 3200, gain: -3, says: "Cutting 3.2 kHz by 3 dB" }, +]; +function jobSpecimen(j: (typeof JOBS)[number], open: boolean, no: number) { + return `
+ ${String(no).padStart(2, "0")} +
${esc(j.name)}Peaking EQ
+ ${open + ? `
How much +
+
${j.gain < 0 ? "Barely" : "A touch"}${j.gain < 0 ? "Gone" : "Forward"}
` + : `
${esc(j.says)}
`} +
`; +} +const jobsSpecimen = `
+
+ ${jobSpecimen(JOBS[0]!, true, 2)} + ${jobSpecimen(JOBS[1]!, false, 3)} + ${jobSpecimen(JOBS[2]!, false, 4)} +
+
+

B — The range is the module

+

The add menu offers jobs, not a parametric. Picking "Reduce Mud" IS picking the range, so one knob genuinely works — and a preset chain never shows the same name twice.

+
+
`; + +const rangeGrid = whereSpecimen() + jobsSpecimen; + +/** The payoff: Clean Voice re-read with named jobs. */ +const cleanVoiceFixed = `
+
+
INthis track
+
CLEAN VOICE +
01 +
Remove Rumble80 Hz
+
02 +
Reduce Mud250 Hz
+
03 +
Even Out Loudness-20 dB
+
04 +
Add Clarity3 kHz
+
05 +
Peak Ceiling-1 dB
+
+
OUTto mix
+
+
+

The payoff

+

The same preset, read top to bottom, with every stage naming its own job. Nothing repeats, and an author can follow what was done for them.

+
+
`; + /* ---- presets ------------------------------------------------------------ */ function presetCard(p: (typeof HF_AUDIO_FX_PRESETS)[number]) { const nodes = p.nodes @@ -493,6 +578,12 @@ const html = `FX rack — the casual author's view .rack.locked::after { content:""; position:absolute; inset:0; border-radius:3px; background:repeating-linear-gradient(135deg, transparent 0 6px, oklch(60% .012 250 / .05) 6px 12px); pointer-events:none; } + .segrow { display:flex; flex-wrap:wrap; gap:3px; margin-top:10px; } + .seg { font-family:"DIN Alternate",sans-serif; font-size:9px; letter-spacing:.06em; + text-transform:uppercase; color:oklch(58% .012 250); border:1px solid oklch(28% .012 250); + border-radius:2px; padding:2px 5px; } + .seg.on { color:oklch(14% .004 265); background:var(--h); border-color:var(--h); } + /* ---- multi-band EQ ---- */ .fam-eq .nm { font-family:"DIN Alternate","Oswald",sans-serif; text-transform:uppercase; letter-spacing:.1em; font-size:14px; font-weight:600; } @@ -575,6 +666,25 @@ const html = `FX rack — the casual author's view ${modulesByGroup} +
+

How do you pick the range?

+

+ A hole in the single-knob rule, and a real one. Shape One Range has three controls + — where, how much, how wide — and I nominated how much as the one that + matters. That is incoherent: boosting an unspecified frequency means nothing. The range is + the first decision, not the second. +

+
${rangeGrid}
+

+ B is the answer, and it is the same insight as the EQ: an author does not + want a parametric equaliser, they want to fix a thing. Picking the module IS picking the + range, so a single knob is honest rather than a simplification that hides the real choice. + Moving the frequency stays available under Details for anyone who wants it — where + option A's band picker is exactly the right control. +

+
${cleanVoiceFixed}
+
+

The module that should exist