Help where the question is asked: a field's in a tooltip, a card's behind a question mark that opens a drawer

tiagoagueda commented

2026-09-29 11:26:36 +00:00

Owner

From the interface review of 2026-09-29. The rule asked for, for every page:

A field's help text becomes a tooltip on the field.
A card whose help belongs to the card gets a question-mark icon (circle-question-mark) in its top corner, at the inline end. Hovering over it shows one sentence. Clicking it opens a drawer at the inline end holding the full help for that card, taken from the wiki.
The tooltip is placed wherever the current layout has room for it.

Your details is where this was asked for card by card, so it is the first page to do: Your picture (with the accepted files and the limits), Your name, Contact block, Telephone numbers, Social profiles, Code repositories, Websites, Postal addresses and Identifiers. For the last six, the sentence under the card's title may be what the tooltip replaces.

What is there today

#205 put help under every field that needed it, visible, as help_text drawn by <c-field-feedback> and named in the control's aria-describedby. Nothing is hidden, and a screen reader reads it with the field.
A card says what it is for in a sentence under its title: the subtitle of <c-section-title>, or a <p> under a <legend> on Your details.
The interface links the wiki in two places only, Settings → Accessibility and the API's error documents. Nothing is fetched from it.
Basecoat 1.0.2 has both pieces, and neither is imported yet: tooltip.css, and drawer.css with drawer.js.

What Basecoat's pieces do, and what they do not

The tooltip is CSS only. [data-tooltip="…"] draws the attribute's text in a ::before: one line, truncated, on hover only. It is hidden on :focus-visible, so a keyboard never shows it. Screen readers do not reliably read a pseudo-element's generated text. Nothing dismisses it with Escape, and a phone has no hover. WCAG 2.2 1.4.13 (content on hover or focus) asks for the opposite on every count. So the text has to be an element in the page, reachable by focus and by touch, named by aria-describedby, and dismissible. That could be Basecoat's look painted onto something else, or the Popover API anchored with CSS anchor positioning, using its fallback positions for "wherever there is room" and a fixed side where a browser has none.
The drawer is a <dialog> that its script opens. With scripts off, the question mark has to be a link to a page holding the same text, which the script opens in the drawer instead. A menu here works the same way: it is a <details> first.
Sides. A drawer "on the right" is at the inline end, which is on the left in Arabic and Hebrew. The tooltip's sides are logical too. tests/test_template_lint.py refuses a physical side.

Decisions to take

Which help moves into a tooltip. A sentence saying what a field is for can move. A format the field requires (a date, an IBAN, "the whole address is fine") is an instruction, which WCAG 3.3.2 wants available before the mistake; behind a hover it is out of sight for everybody who does not think to look for it. Proposal: the tooltip takes the explanation and the format stays visible. Either way, the text stays in the DOM as the field's description.
Where the drawer's text comes from. The wiki is a separate repository, written in English, and not part of an installed instance. Fetching it at run time would mean a self-hosted server calling this Forgejo, an outage whenever it is down, and help nobody can translate. The options are:
- help written as templates in the application and translated through the catalogues like every other string, with the wiki pointing to the same text;
- the wiki's pages bundled at build time and shown in English only.
The first keeps the promise that the interface speaks the reader's language; the second keeps a single copy of the text. The rest of this issue waits on this decision.
A card with nothing more to say gets no question mark. An icon that opens the same sentence the tooltip gave is a control that does nothing.

Done when

A tooltip and a help drawer exist as components, each with a scripts-off path, reachable by keyboard and by touch, axe-clean in both themes, and tested at 320 pixels in the browser suite.
Your details uses them card by card. The help for Your picture states the accepted formats and the size limits the code enforces, read from the code so the two cannot disagree.
CONTRIBUTING.md says when to use which, so the next page follows the rule without having to ask.

From the interface review of 2026-09-29. The rule asked for, for every page: - A field's help text becomes a tooltip on the field. - A card whose help belongs to the card gets a question-mark icon (`circle-question-mark`) in its top corner, at the inline end. Hovering over it shows one sentence. Clicking it opens a drawer at the inline end holding the full help for that card, taken from the wiki. - The tooltip is placed wherever the current layout has room for it. *Your details* is where this was asked for card by card, so it is the first page to do: *Your picture* (with the accepted files and the limits), *Your name*, *Contact block*, *Telephone numbers*, *Social profiles*, *Code repositories*, *Websites*, *Postal addresses* and *Identifiers*. For the last six, the sentence under the card's title may be what the tooltip replaces. ## What is there today - #205 put help under every field that needed it, visible, as `help_text` drawn by `<c-field-feedback>` and named in the control's `aria-describedby`. Nothing is hidden, and a screen reader reads it with the field. - A card says what it is for in a sentence under its title: the subtitle of `<c-section-title>`, or a `<p>` under a `<legend>` on *Your details*. - The interface links the wiki in two places only, *Settings → Accessibility* and the API's error documents. Nothing is fetched from it. - Basecoat 1.0.2 has both pieces, and neither is imported yet: `tooltip.css`, and `drawer.css` with `drawer.js`. ## What Basecoat's pieces do, and what they do not - **The tooltip is CSS only.** `[data-tooltip="…"]` draws the attribute's text in a `::before`: one line, truncated, on hover only. It is hidden on `:focus-visible`, so a keyboard never shows it. Screen readers do not reliably read a pseudo-element's generated text. Nothing dismisses it with Escape, and a phone has no hover. WCAG 2.2 1.4.13 (content on hover or focus) asks for the opposite on every count. So the text has to be an element in the page, reachable by focus and by touch, named by `aria-describedby`, and dismissible. That could be Basecoat's look painted onto something else, or the Popover API anchored with CSS anchor positioning, using its fallback positions for "wherever there is room" and a fixed side where a browser has none. - **The drawer is a `<dialog>` that its script opens.** With scripts off, the question mark has to be a link to a page holding the same text, which the script opens in the drawer instead. A menu here works the same way: it is a `<details>` first. - **Sides.** A drawer "on the right" is at the inline end, which is on the left in Arabic and Hebrew. The tooltip's sides are logical too. `tests/test_template_lint.py` refuses a physical side. ## Decisions to take 1. **Which help moves into a tooltip.** A sentence saying what a field is for can move. A format the field requires (a date, an IBAN, "the whole address is fine") is an instruction, which WCAG 3.3.2 wants available before the mistake; behind a hover it is out of sight for everybody who does not think to look for it. Proposal: the tooltip takes the explanation and the format stays visible. Either way, the text stays in the DOM as the field's description. 2. **Where the drawer's text comes from.** The wiki is a separate repository, written in English, and not part of an installed instance. Fetching it at run time would mean a self-hosted server calling this Forgejo, an outage whenever it is down, and help nobody can translate. The options are: - help written as templates in the application and translated through the catalogues like every other string, with the wiki pointing to the same text; - the wiki's pages bundled at build time and shown in English only. The first keeps the promise that the interface speaks the reader's language; the second keeps a single copy of the text. The rest of this issue waits on this decision. 3. **A card with nothing more to say gets no question mark.** An icon that opens the same sentence the tooltip gave is a control that does nothing. ## Done when - A tooltip and a help drawer exist as components, each with a scripts-off path, reachable by keyboard and by touch, axe-clean in both themes, and tested at 320 pixels in the browser suite. - *Your details* uses them card by card. The help for *Your picture* states the accepted formats and the size limits the code enforces, read from the code so the two cannot disagree. - `CONTRIBUTING.md` says when to use which, so the next page follows the rule without having to ask.

tiagoagueda added this to the 0.5.0 milestone

2026-09-29 11:26:36 +00:00

tiagoagueda added the

labels

2026-09-29 11:26:36 +00:00

tiagoagueda commented

2026-09-29 19:37:57 +00:00

Author

Owner

Decided (2026-09-29): the help is written as templates in the application, translated through the catalogues like every other string, and the wiki points at the same text. Nothing is fetched from the wiki at run time, and nothing is bundled from it.

**Decided (2026-09-29): the help is written as templates in the application**, translated through the catalogues like every other string, and the wiki points at the same text. Nothing is fetched from the wiki at run time, and nothing is bundled from it.

tiagoagueda referenced this issue

2026-10-01 09:46:28 +00:00

Documentation: a fuller wiki for the people who use, run and extend Postulo, readable in more than English #345

tiagoagueda referenced this issue

2026-10-01 10:24:56 +00:00

Search on a phone: tapping the icon should open a search field in place, not load a separate page #350

tiagoagueda referenced this issue

2026-10-01 10:34:02 +00:00

Wiki in several languages: find out whether it can be done, and how, before any page is translated #352

tiagoagueda referenced this issue from a commit

2026-10-03 04:40:24 +00:00

Put help where the question is asked: a field's in a tooltip, a card's behind a question mark