docs(design): fix 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: 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) <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-08-09 20:20:17 -07:00
co-authored by Claude Opus 5
parent 6594cc0d86
commit b2bf8b476e
2 changed files with 141 additions and 0 deletions
+31
View File
@@ -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
+110
View File
@@ -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) => `<span class="seg${i === 2 ? " on" : ""}">${esc(w)}</span>`).join("");
return `<figure class="specimen state">
<div class="rack">
<div class="flow">
<div class="node fam-filter" style="--h:${moduleHue("peaking")}">
<span class="n">02</span>
<div class="nmrow"><span class="nm">Shape One Range</span><span class="tag">Peaking EQ</span></div>
<div class="segrow">${seg}</div>
<div class="knob-row">
<span class="kl">How much</span>
<span class="track"><i style="width:34%"></i><b style="left:34%"></b></span>
<span class="live" style="color:oklch(72% .012 250)">&minus;3.0</span>
</div>
<div class="ends"><span>Take it out</span><span>Bring it forward</span></div>
</div>
</div>
</div>
<figcaption>
<p class="sl">A &mdash; Two controls</p>
<p class="sn">Where is a <em>word</em> from the shared vocabulary, not a frequency field. Honest, and the ruler is doing the teaching &mdash; but it is two decisions, and the first one is still jargon wearing a friendly coat.</p>
</figcaption>
</figure>`;
}
/** 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 `<div class="node fam-filter" style="--h:${moduleHue("peaking")}">
<span class="n">${String(no).padStart(2, "0")}</span>
<div class="nmrow"><span class="nm">${esc(j.name)}</span><span class="tag">Peaking EQ</span></div>
${open
? `<div class="knob-row"><span class="kl">How much</span>
<span class="track"><i style="width:${j.gain < 0 ? 38 : 62}%"></i><b style="left:${j.gain < 0 ? 38 : 62}%"></b></span></div>
<div class="ends"><span>${j.gain < 0 ? "Barely" : "A touch"}</span><span>${j.gain < 0 ? "Gone" : "Forward"}</span></div>`
: `<div class="says">${esc(j.says)}</div>`}
</div>`;
}
const jobsSpecimen = `<figure class="specimen state">
<div class="rack"><div class="flow">
${jobSpecimen(JOBS[0]!, true, 2)}
${jobSpecimen(JOBS[1]!, false, 3)}
${jobSpecimen(JOBS[2]!, false, 4)}
</div></div>
<figcaption>
<p class="sl">B &mdash; The range is the module</p>
<p class="sn">The add menu offers <em>jobs</em>, not a parametric. Picking "Reduce Mud" IS picking the range, so one knob genuinely works &mdash; and a preset chain never shows the same name twice.</p>
</figcaption>
</figure>`;
const rangeGrid = whereSpecimen() + jobsSpecimen;
/** The payoff: Clean Voice re-read with named jobs. */
const cleanVoiceFixed = `<figure class="specimen state">
<div class="rack"><div class="flow">
<div class="term"><span class="cap">IN</span><span class="lbl">this track</span></div>
<div class="group"><span class="gl">CLEAN VOICE</span>
<div class="node fam-filter" style="--h:${moduleHue("highpass")}"><span class="n">01</span>
<div class="nmrow"><span class="nm">Remove Rumble</span><span class="tag">80 Hz</span></div></div>
<div class="node fam-filter" style="--h:${moduleHue("peaking")}"><span class="n">02</span>
<div class="nmrow"><span class="nm">Reduce Mud</span><span class="tag">250 Hz</span></div></div>
<div class="node fam-dynamics" style="--h:${moduleHue("compressor")}"><span class="n">03</span>
<div class="nmrow"><span class="nm">Even Out Loudness</span><span class="tag">-20 dB</span></div></div>
<div class="node fam-filter" style="--h:${moduleHue("peaking")}"><span class="n">04</span>
<div class="nmrow"><span class="nm">Add Clarity</span><span class="tag">3 kHz</span></div></div>
<div class="node fam-dynamics" style="--h:${moduleHue("limiter")}"><span class="n">05</span>
<div class="nmrow"><span class="nm">Peak Ceiling</span><span class="tag">-1 dB</span></div></div>
</div>
<div class="term out"><span class="cap">OUT</span><span class="lbl">to mix</span></div>
</div></div>
<figcaption>
<p class="sl">The payoff</p>
<p class="sn">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.</p>
</figcaption>
</figure>`;
/* ---- presets ------------------------------------------------------------ */
function presetCard(p: (typeof HF_AUDIO_FX_PRESETS)[number]) {
const nodes = p.nodes
@@ -493,6 +578,12 @@ const html = `<title>FX rack — the casual author's view</title>
.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 = `<title>FX rack — the casual author's view</title>
${modulesByGroup}
</section>
<section>
<h2>How do you pick the range?</h2>
<p class="lede">
A hole in the single-knob rule, and a real one. <em>Shape One Range</em> has three controls
&mdash; where, how much, how wide &mdash; and I nominated <em>how much</em> as the one that
matters. That is incoherent: boosting an unspecified frequency means nothing. The range is
the first decision, not the second.
</p>
<div class="mods">${rangeGrid}</div>
<p class="lede" style="margin-top:var(--s5)">
<strong>B is the answer</strong>, 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 &mdash; where
option A's band picker is exactly the right control.
</p>
<div class="mods" style="margin-top:var(--s5)">${cleanVoiceFixed}</div>
</section>
<section>
<h2>The module that should exist</h2>
<p class="lede">