Listings: a question mark beside the heading, the summary on hover and the full help in a drawer #839

New issue

Closed

opened 2026-10-10 15:50:11 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

2026-10-10 15:50:11 +00:00

Owner

Put a circle-question-mark icon next to the Listings h1. Hovering it shows the helper text, which stays available to assistive technology but is no longer printed under the heading; clicking it opens the full help in a drawer on the right.

What exists today

templates/jobs/listing_list.html:82-89: <c-page-title>Listings</c-page-title>, then a paragraph “Every posting you have noticed, until you decide: shortlist it, discard it, or apply.” and the count.
The pattern already exists for cards (#302): cotton/help_mark.html (the circle-question-mark icon, a <p data-tooltip data-help-summary> tied by aria-describedby, data-opens-dialog="help-<slug>", and without scripts a link to /help/<slug>/ in a new tab), cotton/help_drawer.html on cotton/drawer.html (<dialog class="drawer" data-side="inline-end">, right in left-to-right). Topics are core/help.py:33-75 (Topic(slug, title, summary, template, home, back)), texts in templates/help/, route core:help_topic. Every topic today is a Your details card.
The mark's CSS is built for section titles and legends (assets/css/app.css:845-880).

What would change

A listings topic with its text in templates/help/listings.html, home="jobs:listing_list".
c-page-title takes a help topic and draws the mark beside the h1; the helper paragraph moves into the topic's summary.
The mark's layout beside an h1.

Decisions

Only Listings, or every list page. Recommended: the c-page-title change is general, the topic is Listings' now, and Applications, Companies and Documents follow as their help is written.
People without hover lose the sentence from the page; on touch the tooltip shows on focus, and the drawer has the full text. Recommended, as asked.

tests/test_help_topics.py checks every topic (summary, back link, text).

Checked against main at 8c3d03570. From the maintainer's improvements list of 2026-10-07.

Put a `circle-question-mark` icon next to the Listings `h1`. Hovering it shows the helper text, which stays available to assistive technology but is no longer printed under the heading; clicking it opens the full help in a drawer on the right. ## What exists today - `templates/jobs/listing_list.html:82-89`: `<c-page-title>Listings</c-page-title>`, then a paragraph “Every posting you have noticed, until you decide: shortlist it, discard it, or apply.” and the count. - **The pattern already exists for cards (#302)**: `cotton/help_mark.html` (the `circle-question-mark` icon, a `<p data-tooltip data-help-summary>` tied by `aria-describedby`, `data-opens-dialog="help-<slug>"`, and without scripts a link to `/help/<slug>/` in a new tab), `cotton/help_drawer.html` on `cotton/drawer.html` (`<dialog class="drawer" data-side="inline-end">`, right in left-to-right). Topics are `core/help.py:33-75` (`Topic(slug, title, summary, template, home, back)`), texts in `templates/help/`, route `core:help_topic`. Every topic today is a *Your details* card. - The mark's CSS is built for section titles and legends (`assets/css/app.css:845-880`). ## What would change - A `listings` topic with its text in `templates/help/listings.html`, `home="jobs:listing_list"`. - `c-page-title` takes a help topic and draws the mark beside the `h1`; the helper paragraph moves into the topic's summary. - The mark's layout beside an `h1`. ## Decisions - **Only Listings, or every list page.** Recommended: the `c-page-title` change is general, the topic is Listings' now, and Applications, Companies and Documents follow as their help is written. - **People without hover** lose the sentence from the page; on touch the tooltip shows on focus, and the drawer has the full text. Recommended, as asked. `tests/test_help_topics.py` checks every topic (summary, back link, text). Checked against `main` at `8c3d03570`. From the maintainer's improvements list of 2026-10-07.

tiagoagueda added this to the 0.6.0 milestone

2026-10-10 15:50:11 +00:00

tiagoagueda added the

accessibility

interface

enhancement

labels

2026-10-10 15:50:11 +00:00

tiagoagueda referenced this issue

2026-10-10 16:01:21 +00:00

Help beside the heading on Documents, Calendar and Your career #847

tiagoagueda self-assigned this