Keyboard hints: a switch for the key badges, apart from the switch for the keys themselves #658

New issue

Closed

opened 2026-10-03 01:58:39 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

2026-10-03 01:58:39 +00:00

Owner

From the maintainer's list, under User settings: “Enable/disable Basecoat's Kbd.” Read as: a person can turn the small key badges (Basecoat's kbd, drawn as keycaps) on or off. Postulo already has a switch for the keys' behaviour; it has no switch for what tells somebody the keys exist, and hardly any badges to switch.

What exists today

The component is adopted and almost unused. kbd.css is imported (assets/css/app.css:33) and painted as a keycap (assets/css/basecoat.css:556-570, with dark variants). <kbd> is rendered in four lines: templates/jobs/capture_review.html:207-208 and :212 (a sentence of help under the review) and templates/server/design.html:107 (the gallery).
The keys that exist. Ctrl or ⌘ with Enter saves and moves on, d discards and moves on, j skips (src/postulo/static/js/app.js:1098-1123, on the buttons marked data-key-save-next, data-key-discard-next and data-key-next); / jumps to the search box (:1344-1366). The masthead's search over everything says it as text in its placeholder, “Search /”, only when shortcuts are on (src/postulo/templates/cotton/site_search.html:103) and sets no aria-keyshortcuts; the variant that narrows a page's table sets aria-keyshortcuts="/" when shortcuts are on (:78) and has no “/” in its placeholder.
One switch, for behaviour. Profile.keyboard_shortcuts (accounts/models.py:336, default on) turns the single-key shortcuts off, which WCAG 2.1.4 requires at level A (#227); it is on Settings → Accessibility (src/postulo/accounts/forms.py:664-701, templates/settings/accessibility.html:31). Shortcuts with Ctrl are outside it and always work. The help sentence on the review tells the truth about it: it names d and j only while they work (capture_review.html:200-214).
Nothing shows a hint beside a control. Save and next, Discard and next and Skip to the next (capture_review.html:173-197) carry no badge.
Preferences travel unevenly. #464 (open) says keyboard_shortcuts and others are not in the archive.

Checked against main at f09b6010b.

Proposal

A preference, Profile.show_key_hints, default on, under Settings → Accessibility beside the behaviour switch, in whatever list of exported preferences #464 settles.
A badge beside each control that has a key, from the same component and one include: Save and next (Ctrl+Enter), Discard and next (d), Skip to the next (j), and the search box (/, replacing the text in its placeholder; the box over everything gains the aria-keyshortcuts the table variant already has). Each badge is aria-hidden; the control carries aria-keyshortcuts whether or not the badge is shown, so assistive technology is told either way, and a visible badge never becomes part of the control's accessible name.
The two switches combine honestly. Hints off: no badge anywhere. Shortcuts off: no badge for d, j or /, because a hint for a dead key is a lie (the sentence's own rule); the Ctrl+Enter badge follows the hint switch alone.
The help sentence stays. It is help and not decoration, and removing it would leave the person who wants the keys with no place to read them.

Decisions

Hints everywhere, or only in the help. Options: badges beside controls; the sentence only; a global overlay of keys. Recommended: badges beside the four controls above and nothing more; no new shortcuts are added by this issue.
Separate from the behaviour switch. Recommended: separate. Somebody who knows the keys may want a quiet page; somebody who dictates may want the keys off and the hints with them.
Default. Recommended: on. The default is what the conformance claim rests on and it helps discovery; the control is the way out.
Ctrl or ⌘. The server cannot tell the platform. Recommended: draw Ctrl, and let the script that already handles metaKey replace it with ⌘ on Apple platforms, since a hint only matters where the script runs.
Key names are translated. Ctrl and Enter are printed on keyboards in the local language in some places (Strg, Entrée). Recommended: wrap each key name for translation with a context so msgid "Enter" does not collide with another use.

Builds on

Issues #291 (kbd adopted), #281 (the Accessibility page), #227 (the switch), #464 (preferences in the archive).

Done when

tests/e2e/test_keyboard_and_focus.py and tests/test_keyboard_and_focus.py (existing) gain: with hints on, the capture review's three buttons and the search box show their badge, aria-hidden, with aria-keyshortcuts set; with hints off there is no badge and the attribute is still there; with shortcuts off no d, j or / badge shows.
tests/test_contrast.py holds .kbd at 4.5:1 in both themes; axe is clean in both schemes on the review page.
A preference, not a record: the archive format (29 today) moves to one more than whatever it is when the commit lands, because PROFILE_FIELDS gains a name; candidate format (4), API, search and the processing record are untouched. Strings (key names, the switch's label and help) in en-GB, fr-FR and pt-PT (drafts) and Weblate (#349); the wiki's Accessibility page, which names the switches.

From the list of improvements of 2026-10-02.

From the maintainer's list, under *User settings*: “Enable/disable Basecoat's Kbd.” Read as: a person can turn the small key badges (Basecoat's `kbd`, drawn as keycaps) on or off. Postulo already has a switch for the keys' *behaviour*; it has no switch for what tells somebody the keys exist, and hardly any badges to switch. ## What exists today - **The component is adopted and almost unused.** `kbd.css` is imported (`assets/css/app.css:33`) and painted as a keycap (`assets/css/basecoat.css:556-570`, with dark variants). `<kbd>` is rendered in four lines: `templates/jobs/capture_review.html:207-208` and `:212` (a sentence of help under the review) and `templates/server/design.html:107` (the gallery). - **The keys that exist.** `Ctrl` or `⌘` with `Enter` saves and moves on, `d` discards and moves on, `j` skips (`src/postulo/static/js/app.js:1098-1123`, on the buttons marked `data-key-save-next`, `data-key-discard-next` and `data-key-next`); `/` jumps to the search box (`:1344-1366`). The masthead's search over everything says it as text in its placeholder, “Search /”, only when shortcuts are on (`src/postulo/templates/cotton/site_search.html:103`) and sets no `aria-keyshortcuts`; the variant that narrows a page's table sets `aria-keyshortcuts="/"` when shortcuts are on (`:78`) and has no “/” in its placeholder. - **One switch, for behaviour.** `Profile.keyboard_shortcuts` (`accounts/models.py:336`, default on) turns the single-key shortcuts off, which WCAG 2.1.4 requires at level A (#227); it is on *Settings → Accessibility* (`src/postulo/accounts/forms.py:664-701`, `templates/settings/accessibility.html:31`). Shortcuts with Ctrl are outside it and always work. The help sentence on the review tells the truth about it: it names `d` and `j` only while they work (`capture_review.html:200-214`). - **Nothing shows a hint beside a control.** *Save and next*, *Discard and next* and *Skip to the next* (`capture_review.html:173-197`) carry no badge. - **Preferences travel unevenly.** #464 (open) says `keyboard_shortcuts` and others are not in the archive. Checked against `main` at `f09b6010b`. ## Proposal 1. **A preference, `Profile.show_key_hints`,** default on, under *Settings → Accessibility* beside the behaviour switch, in whatever list of exported preferences #464 settles. 2. **A badge beside each control that has a key,** from the same component and one include: *Save and next* (`Ctrl+Enter`), *Discard and next* (`d`), *Skip to the next* (`j`), and the search box (`/`, replacing the text in its placeholder; the box over everything gains the `aria-keyshortcuts` the table variant already has). Each badge is `aria-hidden`; the control carries `aria-keyshortcuts` whether or not the badge is shown, so assistive technology is told either way, and a visible badge never becomes part of the control's accessible name. 3. **The two switches combine honestly.** Hints off: no badge anywhere. Shortcuts off: no badge for `d`, `j` or `/`, because a hint for a dead key is a lie (the sentence's own rule); the `Ctrl+Enter` badge follows the hint switch alone. 4. **The help sentence stays.** It is help and not decoration, and removing it would leave the person who wants the keys with no place to read them. ## Decisions - **Hints everywhere, or only in the help.** Options: badges beside controls; the sentence only; a global overlay of keys. **Recommended:** badges beside the four controls above and nothing more; no new shortcuts are added by this issue. - **Separate from the behaviour switch.** **Recommended:** separate. Somebody who knows the keys may want a quiet page; somebody who dictates may want the keys off and the hints with them. - **Default.** **Recommended:** on. The default is what the conformance claim rests on and it helps discovery; the control is the way out. - **`Ctrl` or `⌘`.** The server cannot tell the platform. **Recommended:** draw `Ctrl`, and let the script that already handles `metaKey` replace it with `⌘` on Apple platforms, since a hint only matters where the script runs. - **Key names are translated.** *Ctrl* and *Enter* are printed on keyboards in the local language in some places (*Strg*, *Entrée*). **Recommended:** wrap each key name for translation with a context so `msgid "Enter"` does not collide with another use. ## Builds on Issues #291 (kbd adopted), #281 (the Accessibility page), #227 (the switch), #464 (preferences in the archive). ## Done when - `tests/e2e/test_keyboard_and_focus.py` and `tests/test_keyboard_and_focus.py` (existing) gain: with hints on, the capture review's three buttons and the search box show their badge, `aria-hidden`, with `aria-keyshortcuts` set; with hints off there is no badge and the attribute is still there; with shortcuts off no `d`, `j` or `/` badge shows. - `tests/test_contrast.py` holds `.kbd` at 4.5:1 in both themes; axe is clean in both schemes on the review page. - A preference, not a record: the archive format (29 today) moves to one more than whatever it is when the commit lands, because `PROFILE_FIELDS` gains a name; candidate format (4), API, search and the processing record are untouched. Strings (key names, the switch's label and help) in en-GB, fr-FR and pt-PT (drafts) and Weblate (#349); the wiki's *Accessibility* page, which names the switches. From the list of improvements of 2026-10-02.

tiagoagueda added this to the 0.6.0 milestone

2026-10-03 01:58:39 +00:00

tiagoagueda added the

interface

enhancement

labels

2026-10-03 01:58:39 +00:00

tiagoagueda commented

2026-10-05 20:48:48 +00:00

Author

Owner

Done in 98b2c1a65 and 89e73dafc (on main; CI green at 15e6d7ee4). Settings → Accessibility has a separate switch for the key badges; the controls still announce their keys. Wiki: Accessibility page.

Done in 98b2c1a65 and 89e73dafc (on main; CI green at 15e6d7ee4). Settings → Accessibility has a separate switch for the key badges; the controls still announce their keys. Wiki: Accessibility page.

tiagoagueda closed this issue

2026-10-05 20:48:48 +00:00