Rules for a clean interface, and the modules brought to them #9

2026-09-17T14:22:48-04:00

michael commented

2026-09-17 14:22:48 -04:00

Seven rules join the four already in the module guide, as rules 5–11 under a new Keeping the interface clean:

No help in a tile's gear; labels three words at most, one or two preferred. (One exception, below.)
Server-side settings in configSchema only — instanceSchema is display choices.
A tile setting changes that tile and nothing else.
Hide-toggles: 1–4 ungrouped, 5+ in one folded Show group at two columns.
Title-bar controls are icons with tooltips, never names. A state indicator may ride alongside; a name may not.
If a control needs words to explain it, it belongs in the gear.
One control per action — title bar or gear, never both.

CLAUDE.md carries the summary.

Two passages said the opposite

The guide already told module authors to "keep labels short and put the explanation there" and to use "icon buttons, short labels". Both now agree with the rules: the first is scoped to configSchema, the second becomes icons with no labels at all. Left alone they would have contradicted rules 5 and 9 on the same page.

The modules

Nothing changes a setting key or a default. Saved layouts, named layouts and every tile already on a wall keep working — group names, labels, help and fold state are presentation, and none of them is stored in a layout.

Module	Change	Version
pco-plan	16 labels cut to ≤3 words; `Show / hide` renamed Show and folded; group help dropped	1.4.0 → 1.5.0
propresenter-timers	`Timers ▾` menu → stopwatch icon + count badge; Show folded; Colours help dropped	1.3.0 → 1.4.0
propresenter-now-next	Show folded, in the manifest and the `Now` entry's own copy	1.1.0 → 1.1.1
prodcom-transcript	"Show channel icons" → "Channel icons"	1.3.1 → 1.3.2
slack, clock	already compliant — untouched	—

Sample relabels: "Tint items by type (song / media / other)" → Tint by type; "Keep the current item in view" → Auto-scroll; "Running clock (ahead / behind)" → Running clock; "Item runtime (elapsed vs planned)" → Item runtime.

Two things worth knowing

The template help stays, by request, and rule 5 now says so. pco-plan's top-bar field keeps Use • between items and | to start a second line. The field already renders chips for every available variable, but the chips cannot convey the separator syntax — so the rule carves out template fields rather than leaving the module quietly breaking its own guide.

The timers count needed more than deleting a label. setLabel() sets button.textContent, which wipes the icon — so switching that menu to an icon meant moving its Timers (3/7) ▾ count onto a badge span, the pattern ProdCom's channel button already uses. The icon now survives every repaint.

Verified

A scripted audit over /api/modules — every module and every picker entry, including the ones built at runtime by the timers server — reports no rule failures: no help, no label over three words, no unfolded Show group.

In the browser with all eight tile kinds on one board:

the only help line left in any gear is the template one;
every title-bar control across every tile is icon-only with a tooltip — Timers, Refresh, Smaller text, Larger text, Channels, Timestamps, Latest, Clear, Lock;
the timers badge is hidden at rest, shows 3/4 while filtering, returns to hidden when everything is switched back on, and the icon survives throughout;
the gears open with Show folded — 7 toggles for All timers, 24 for PCO Plan.

🤖 Generated with Claude Code

Seven rules join the four already in the module guide, as **rules 5–11** under a new *Keeping the interface clean*: 5. No `help` in a tile's gear; labels three words at most, one or two preferred. *(One exception, below.)* 6. Server-side settings in `configSchema` only — `instanceSchema` is display choices. 7. A tile setting changes that tile and nothing else. 8. Hide-toggles: **1–4** ungrouped, **5+** in one folded **Show** group at two columns. 9. Title-bar controls are icons with tooltips, never names. A state indicator may ride alongside; a name may not. 10. If a control needs words to explain it, it belongs in the gear. 11. One control per action — title bar or gear, never both. `CLAUDE.md` carries the summary. ### Two passages said the opposite The guide already told module authors to *"keep labels short and put the explanation there"* and to use *"icon buttons, short labels"*. Both now agree with the rules: the first is scoped to `configSchema`, the second becomes icons with no labels at all. Left alone they would have contradicted rules 5 and 9 on the same page. ### The modules **Nothing changes a setting key or a default.** Saved layouts, named layouts and every tile already on a wall keep working — group names, labels, help and fold state are presentation, and none of them is stored in a layout. | Module | Change | Version | |---|---|---| | **pco-plan** | 16 labels cut to ≤3 words; `Show / hide` renamed **Show** and folded; group help dropped | 1.4.0 → **1.5.0** | | **propresenter-timers** | `Timers ▾` menu → stopwatch icon + count badge; **Show** folded; Colours help dropped | 1.3.0 → **1.4.0** | | **propresenter-now-next** | **Show** folded, in the manifest and the `Now` entry's own copy | 1.1.0 → **1.1.1** | | **prodcom-transcript** | "Show channel icons" → "Channel icons" | 1.3.1 → **1.3.2** | | **slack**, **clock** | already compliant — untouched | — | Sample relabels: *"Tint items by type (song / media / other)"* → **Tint by type**; *"Keep the current item in view"* → **Auto-scroll**; *"Running clock (ahead / behind)"* → **Running clock**; *"Item runtime (elapsed vs planned)"* → **Item runtime**. ### Two things worth knowing **The template help stays, by request, and rule 5 now says so.** pco-plan's top-bar field keeps `Use • between items and | to start a second line.` The field already renders chips for every available variable, but the chips cannot convey the separator syntax — so the rule carves out `template` fields rather than leaving the module quietly breaking its own guide. **The timers count needed more than deleting a label.** `setLabel()` sets `button.textContent`, which wipes the icon — so switching that menu to an icon meant moving its `Timers (3/7) ▾` count onto a badge span, the pattern ProdCom's channel button already uses. The icon now survives every repaint. ### Verified A scripted audit over `/api/modules` — every module **and** every picker entry, including the ones built at runtime by the timers server — reports **no rule failures**: no help, no label over three words, no unfolded `Show` group. In the browser with all eight tile kinds on one board: - the only help line left in any gear is the template one; - every title-bar control across every tile is icon-only with a tooltip — `Timers`, `Refresh`, `Smaller text`, `Larger text`, `Channels`, `Timestamps`, `Latest`, `Clear`, `Lock`; - the timers badge is hidden at rest, shows `3/4` while filtering, returns to hidden when everything is switched back on, and the icon survives throughout; - the gears open with **Show** folded — 7 toggles for All timers, 24 for PCO Plan. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

michael added 1 commit 2026-09-17 14:22:48 -04:00

Rules for a clean interface, and the modules brought to them 12f0b20e5f

Seven rules join the four in the module guide, as rules 5 to 11: no
explanatory text in a tile's gear and no label over three words; server-side
settings in configSchema only; a tile setting changes that tile alone;
hide-toggles ungrouped when there are four or fewer and in a folded "Show"
group when there are five or more; title-bar controls are icons with
tooltips, never names; anything needing words belongs in the gear; and one
control per action, either place but not both.

Two passages said the opposite and now say the same thing — "keep labels
short and put the explanation there" is scoped to configSchema, and "icon
buttons, short labels" becomes icons with no labels at all. CLAUDE.md
carries the summary.

Then the modules. Nothing here changes a setting key or a default, so saved
layouts, named layouts and every tile already on a wall keep working; group
names, labels, help and fold state are presentation and are not stored.

- pco-plan: sixteen labels cut to three words or fewer ("Tint items by type
  (song / media / other)" is now "Tint by type"), "Show / hide" renamed
  "Show" and folded. Its one remaining help line stays by request: the top
  bar's template needs its separator syntax spelled out, which the variable
  chips beside it cannot convey, so rule 5 carves out template fields.
- propresenter-timers: the "Timers ▾" menu was the only named control left
  in any title bar. It is a stopwatch icon now, with the count riding
  alongside it while some timers are hidden — setLabel() writes over the
  button's contents, so the count needed ProdCom's badge treatment rather
  than a label. "Show" folds; the Colours help goes.
- propresenter-now-next: "Show" folds, in the manifest and in the Now
  entry's own copy.
- prodcom-transcript: "Show channel icons" loses the redundant verb.

slack and clock were already compliant and are untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

michael merged commit 5025e12b71 into main

2026-09-17 15:53:03 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: michael/ProdDash#9