[Frontend][Feature] Global toggleable help/explainer mode covering every control, i18n-ready

[Chris0Jeky]

Source: maintainer dogfooding session 2026-08-22 (voice-captured walkthrough of a fresh/demo account). The build under test was not pinned — re-verify each symptom against current main before implementing; some items may already be partially addressed by the closed live-repro wave (#1764–#1769) and #1818.

Feature request

A global, toggleable help/explainer mode: when on, every button, section, and view carries helper text (tooltip, inline caption, or popover) explaining what it does and where it fits in the capture → review → board loop. When off, the UI is clean.

Requirements from the maintainer:

• Togglable at any point in the journey (persistent per-user preference), not a one-time onboarding.
• Coverage bar: every control is either self-explanatory (clear label/placeholder/nearby text) or has a helper entry — no dead-mystery buttons.
• Helper strings live in the i18n layer so they are translatable (relates Seed an i18n translation layer (vue-i18n) with Italian and Spanish locales #1770 vue-i18n seeding, i18n & accessibility decisions (ADR): English-only + browser-locale dates; Legacy reduced-motion #1141 i18n ADR, ADR-0054 rollout — mind the bundle-budget decision Decide how the i18n rollout is budgeted against the total-JS gate, before step 3 #1858).

Acceptance criteria

• Toggle discoverable in the header or settings; state persists.
• Helper content system (component + string catalog), seeded across Home, Today, Boards, Review, Inbox/capture.
• Strings routed through the i18n layer.
• A coverage checklist or lint (even manual) so new controls ship with helper text.

[Chris0Jeky]

Scoping evidence from the hands-on audit — 2026-08-22 (v0.7.2 at 127.0.0.1:5000)

Two findings that make this feature cheaper than it looked, plus a sharper case for it.

1. The i18n layer already ships

/workspace/settings/appearance has a working Language switcher: English / Italiano / Español, with the honest caption "Taskdeck is being translated one surface at a time. Anything not translated yet stays in English." So the "helper text must be translatable" requirement does not need new infrastructure — it needs the helper strings to enter the existing catalog. (Mind the bundle-budget decision, #1858.)

2. Much of the writing is already good — the gap is placement, not authorship

The app is not short of explanatory copy; it is short of copy at the point of confusion. Examples of genuinely good existing text found during the audit:

• Inbox: "Drop the thought. It will sit here, untouched, until you triage it. Nothing flows to the board without your approval."
• Inbox composer footer: "Captures land in Inbox. Linking to a board creates a proposal, not a card."
• Review, on approve: "Approved — not yet applied to the board."
• Apply dialog: "This is the second and final step… Nothing has been written to the board yet."
• Today: "No events are being invented."
• Empty board: "Columns are the lanes work moves through. Add the first one to make this board usable."

That is a strong voice. The failures found in this audit were nearly all unlabelled controls rather than missing prose: aria-label="Settings" on an icon the maintainer read as a theme toggle (#1932), a "Solo Workspace" button labelled "Switch workspace" that does nothing (#1934), "Day sealed" (#1939), "Seal the day"/"Write a note" with no stated destination, NEW/TYPED/READY FOR REVIEW/APPLIED TO BOARD tags with no explanation (#1944).

Implication for the design

A help mode whose content is per-control (what does this button do, what happens next, where does this go) will pay for itself; one that re-states page-level prose will not, because the page-level prose is already there and already good.

Acceptance criteria (revised)

• Persistent per-user toggle, discoverable in the header or Settings (Settings → Appearance is the natural home; it already hosts theme + language).
• Content is per-control: destination, effect, and next step. Prioritise the unlabelled controls listed above.
• Strings enter the existing i18n catalog (English first; the caption already sets the expectation that translation is incremental).
• A coverage checklist so new controls ship with helper text — the recurring defect class in this audit is shipping a control with no stated behaviour.
• Test: rather than asserting individual strings (brittle), assert coverage — every interactive element in a view has either an accessible name that is not generic, or a registered helper entry. That guard also catches the dead-affordance class ([Frontend][UX] Header controls are dead: theme toggle, notification bell, and account avatar do nothing on click #1932/[Frontend][UX] Sidebar: 'Solo workspace' item looks interactive but is not clickable; sidebar order doesn't match the actual workflow #1934/[Frontend][Bug] Review provenance card: the Tune heuristics link is dead #1941).

[Chris0Jeky]

Realignment 2026-08-23 — three scope updates against main a43df082c. No re-scope applied; these are inputs for the maintainer.

1. The bundle-budget caveat is discharged

The 2026-08-22 comment on this issue said "Mind the bundle-budget decision, #1858." That was ruled on 2026-08-23 (walkthrough q-1): it/es catalogs lazy-load, shipped in PR #2002 ("feat(i18n): lazy-load it/es catalogs, gate the eager graph (#1858), disclose machine translation", merged 15:08Z). The eager-graph gate holds at 1250 KB with the measured eager graph at 402 KB.

So AC3 — "strings enter the existing i18n catalog" — no longer carries a budget caveat. Adding helper strings to the English catalog does not trade against the budget.

2. Most of the prioritised control list has since been labelled

Of the five unlabelled controls the earlier comment named, four are done:

• the gear now reads Appearance settings — [Frontend][UX] Header controls are dead: theme toggle, notification bell, and account avatar do nothing on click #1932, PR fix(frontend): #1932 wire Paper topbar controls #1954
• Solo Workspace is non-interactive text — [Frontend][UX] Sidebar: 'Solo workspace' item looks interactive but is not clickable; sidebar order doesn't match the actual workflow #1934, PR fix(frontend): #1934 #1941 dead sidebar + provenance controls #1957
• the seal copy is rewritten — [Frontend][UX] Today view: unexplained empty state; daily seal and note affordances are opaque, sealing has no visible undo #1939, PR fix(frontend): #1939 Today seal + empty-state legibility #1976
• triage states now say why an action is off — [Frontend][UX] Capture triage: no pre-triage edit, and Accept/Reject give no legible state feedback #1944, PR fix(frontend): #1944 capture triage states why a blocked action is off and what a decision did #1952

The remaining case for this feature is therefore new controls, not the audited backlog — which strengthens AC4 (the coverage checklist) as the durable half of the issue and weakens the "go label these five things" framing.

3. AC5 and #1949 are the same test — build it once

The coverage assertion proposed here (every interactive element has a non-generic accessible name or a registered helper entry) is #1949's AC2 with a helper-registry lookup added. If both are built independently the repo ends up with two scanners over the same SFC set, drifting apart.

frontend/taskdeck-web/src/tests/guards/ is the established home — PR #1957 landed deadAnchors.spec.ts there and PR #1998 added nativeBrowserDialogs.spec.ts beside it.

Recommendation for the maintainer: #1949 owns the guard, this issue owns the content. Not applied here — it changes both issues' scope.

Milestone context

Priority II, so outside the q-3 v0.1.2 tranche.