Skip to content

Give pages their headings, landmarks, table semantics, names and status regions - #336

Open
r0ny123 wants to merge 22 commits into
ref/integrate-all-20261025from
fix/web-semantics
Open

r0ny123 wants to merge 22 commits into
ref/integrate-all-20261025from
fix/web-semantics

Conversation

@r0ny123

@r0ny123 r0ny123 commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

Based on ref/integrate-all-20261025, the build of all open PRs (#316's comment has the order), so the diff here is this change alone. One of a set of PRs from a review of the front end against the modern-web-guidance accessibility guides; the others are #328 and #330-#335, plus the layout PR. Checked in Chromium. Lighthouse Accessibility, Best Practices and SEO are 100 on every page, mobile and desktop.

Defects

  • 2038c8a. Live search looked for section.content; the page has main.content. A failed search therefore said "No results". It now shows its error and says the search failed, on all four live-search pages.
  • 402fb41. Markup that did not close:
    • a stray </p> and an unclosed <li> on the jobs page;
    • an unclosed <div> in the navbar;
    • a </tr> with no opening tag in the family header.

Names

  • e2f2d64. A new status_icon macro makes the yes/no icons read "Yes" and "No". The link hunt's unique matches read "(unique)" instead of being bold only.
  • a66e18a. Row controls are named after their row ("Filter by function 84", "Delete job 12", "Copy SHA256 634df40e", "Edit sample 3"), not one name for every row. clipboard_btn takes a label.
  • Font Awesome icons, in three commits:
    • d26846b makes four tests match job-description icons by title, not exact markup.
    • bf736fc is the purely mechanical commit: aria-hidden="true" on 111 decorative icons. Its message holds the script and the command (python -I hide_icons.py mcritweb/templates, run from the repo root). Re-running it on the parent reproduces the commit exactly, and a second run changes nothing. On a merge conflict, drop this commit and re-run the script after merging.
    • d261b15 is written by hand. It names the controls an icon's title alone used to name (Analyze, Rename, Regenerate token) and fixes the users page's <i aria-label>. It also adds words for icons that carry meaning: family or sample in job descriptions, and PicHash match counts.
  • 2d7bba5. Every table on a result page has a pager, and each was a <nav aria-label="Pagination"> with links named "Next page", "Previous page" and so on, so a list of landmarks or links read the same names several times over, each going to a different table.
    1. The icon-only links and buttons carried their name twice, in an aria-label and in a title with the same words. Now that each name says which row it acts on, the two copies differ from row to row and compress badly: about 400 bytes of a gzipped result page, for a title that only a mouse reads.
    • The markup says the name once. Code at the end of page_loading.js, queued after the first paint (it was icon_titles.js until 5a75c2c), sets the title from the aria-label of every link or button that shows no text and has no title of its own, and does the same for a control a script adds later when the pointer first reaches it.
    • Bootstrap's tooltips, which take their title over, and the pager links whose title is deliberately shorter than their name are left as they were.

Structure

  • 692ce1b. Headings and titles:
    • Every page has one <h1>. It is visually hidden on settings, users, submit, import, export, register and an empty search.
    • Dialog titles are h2.h5.
    • The pages titled "Compare" are now "Compare 1vsN", "Compare 1vs1" and "Cross Compare", and the link hunt is "LinkHunt for Job".
    • The <span> wrapped around some headings is gone.
  • 8a834a5. Landmarks:
  • 543966d. Tables:
    • Every data table has a visually hidden caption.
    • The label cells of the key/value tables are row headers, so they are now bold and the value column moves right a little.
    • scope is gone from <td>.
    • The jobs totals layout table is role="presentation".
  • 36a860f. Graphs:
    • The function page's CFG <svg> was read as one unnamed image named by all its block code run together. It is now hidden, because its code panel holds the same text as a focusable, named region.
    • The comparison graphs are named images, with their blocks hidden.

Status

    1. The loading, upload and import messages are written into status regions that exist before anything is written to them, and a running job's progress is also a native progress bar.
  • bcce8a4. page_loading.js added its empty status region to <body> when it ran, after the page had loaded. Bootstrap's legend + * makes the browser restyle the whole page for any element added there, which was a second full restyle of about 300 ms on a 100×100 cross compare matrix, and most of the load's extra style time. base.html now carries the empty region beside the status message box, and the script only writes to it, making its own only where it is missing. A browser test checks that nothing is added to <body> once a page has loaded.
  • dc3ec55. The diagram's "rendering diagram…" text and the breadcrumb's "/" were read aloud. They get alternative text (content: "…" / "") after the plain declaration, so older browsers show them as before.

Find in page (0c31f16). The new static/collapsed_find.js marks closed accordion panels hidden="until-found", only where the browser supports it, and opens the panel through Bootstrap when a search lands in it. Tab panes are left alone: a search landing in one would switch the selected tab, and the cross-compare panes are empty until first shown.

Since review was requested.

  • 0c6df75. The page structure browser tests passed string predicates to wait_for_function, which a policy without unsafe-eval refuses. They are arrow functions now. The caption test compared the exact caption text; it now compares the two panes' captions with each other, since its point is that a pane built in the browser keeps the rendered table's caption.
  • 22e68ab. The same secret-key race fix as Follow-ups from the batch E review: read-only database, backup command, key file without hard links, upper-case job ids #322: without hard links the key is staged and renamed into place under a lock on the instance folder, so workers cannot end up with different keys.
  • 4a4430a. A few // comments in the inline scripts of job_overview.html and result_cross.html went to the browser with every copy of the page. They are Jinja comments now, which are dropped on rendering. testInlineScriptComments.py keeps the count: no template may send more comment lines in its inline scripts than it did before.
  • With the comment and script changes of the other PRs, the sample result page on the build of all PRs is back at 14.1 KB gzipped, from 17.1 KB; the base is 14.1 KB.
  • 5a75c2c. The icon tooltips were icon_titles.js, a file of its own queued on every page. Every file the queue holds costs blocking time in Lighthouse's mobile run however little it does: on the build of all PRs the index page took 35 to 45 ms against the base's 8 to 15, and 10 ms against 15 once the every-page scripts were folded into files the base already queues (numbers in Make tooltips reachable and keep them in the window, report copies in a status message, and keep a stray drop off the page #334). The code now ends page_loading.js, in a function of its own so that file's "use strict" does not reach it, and icon_titles.js is gone with its later() line.

Tests. Each fix has a test that fails on the base:

  • new modules: testStatusIcons.py, testAccessibleNames.py, testTableSemantics.py, testGraphAccessibility.py, testBusyStates.py, testGeneratedContent.py, testHeadingsAndTitles.py, testLandmarks.py, testFindInPage.py, testMarkupValidity.py, testIconsHidden.py, testPageStructureBrowser.py and testInlineScriptComments.py;
  • testAccessibleNames.py also holds that icon_titles.js has no file of its own: the page does not queue it, the file is gone, and page_loading.js holds the code and is queued (5a75c2c);
  • testSecretKeyRace.py replaces the test that pinned the old create-then-lock order with two that pin the new one (22e68ab);
  • existing tests that matched the old markup now read the new one.

The 80 related test files pass at the last commit (2668 tests, browser tests included), and ruff is clean.

Lighthouse. Mobile Performance was measured on a loaded machine, where the base and this branch swung alike (88-100 each). It gets a run on a quiet machine, recorded in the merge-order comment on #316.

Merge notes.

  • Expect line conflicts:
    • keyboard: base.html menu toggles, jobs.html, pagination_widget.html, the row templates and result_cross.html;
    • forms: the settings and register headings, and the modal titles;
    • tooltips: clipboard_btn;
    • every PR of the set: the end of style.css and CHANGELOG.
  • Left to the PRs that own them: disabled on <a> (keyboard) and the duplicate form ids (forms).

live_search.js moved the flashed messages of the page it fetched into the
current one by looking up section.content, but base.html renders the
container as <main class="content">. The lookup failed, the backend's error
was dropped, and the status region said "No results" for a search that had
not run. It now looks up main.content, so the error is shown and the status
says the search failed, on all four pages with a live search.
A tick or a cross was the whole value of the library, MinHash, PicHash and
unique cells, and an icon font's glyph is a private-use character that
assistive technology reads as nothing or as "unknown character". The new
status_icon macro in table/links.html hides the glyph and writes "Yes" or
"No" as visually hidden text; every such cell uses it. The ticks beside
text that already says the same are hidden. The link hunt marked
family-unique matches with bold alone, so they carry "(unique)" too.
Every row of a match table had a "Filter by this function" link, every job
row "Delete job" and "Show result", every copy button "Copy to Clipboard",
every row of the cross compare matrix "Edit sample", and the same held for
the compare, Malpedia, remove-sample and 1 vs N controls: a list of links
or a walk with Tab read out the same name for controls that each did
something else. Their labels now name the family, sample, function or job,
clipboard_btn takes a label saying what it copies, and the jobs page's
second navbar toggle says it toggles the job categories.
testAccessibility.py found the filter links by their old wording; it now
matches the new one.
No table but the statistics page's had a caption, so a screen reader listed
a result page's tables as six unnamed ones, and the 1 vs 1 picker's two as
identical. The table macros take a caption, with a default per kind, and
every table written out in a template has a visually hidden one; the cross
compare panes filled on first click copy it from the rendered pane.

The job, sample, function, matching statistics, settings, server and unique
blocks report tables held their labels in <td>, so a value was announced
without its label; those cells are row headers now. scope="row" on a <td>
did nothing and is removed, and the jobs page's row of totals, a table for
its layout only, is role="presentation". The tests that matched the label
cells as <td> match them as row headers.
An <svg> without a role or name is exposed as an image named by all its
text, so each graph was read as every block's code run together, and on the
function's page the code panel then repeated it. That graph is now hidden
from assistive technology, and the code panel, which scrolls, is a named
region that takes focus in browsers that do not focus a scroller on their
own. The comparison page's graphs, which have no such panel, are each an
image named after its function and described by the hint above them; the
blocks drawn into them are hidden, since Chromium keeps an image's children
in its accessibility tree.
A live region is read when its text changes, and only one the screen
reader already knew of. page_loading.js created its overlay already holding
"Loading, please wait." in a status role, and the import page showed its
status box together with its first message; both are often not read. The
loading text now goes into a status region page_loading.js makes, empty,
when it runs, and the overlay is only the picture; the import box sits in a
region rendered from the start. The upload button's spinner was a status
hidden by its own aria-hidden: it is a picture now, and a status beside the
button says the upload is under way.

A running job's progress was a number in a cell; it is also a native
progress bar, which the overview's polling moves along with the number.
The match diagram's ::before placeholder ("rendering diagram...") stayed in
the accessibility tree after the image covered it, and Bootstrap's
breadcrumb divider was read as "slash" between the items. Both get an
empty alternative text, content: "..." / "", in a declaration after the
plain one, so a browser without the newer form drops it and keeps today's
behaviour. The divider is written without Bootstrap's variable, since a
declaration holding var() is only checked once the variable is substituted
and would then drop the divider instead.
The settings, users, submit, import, export and register pages had no <h1>,
nor had the search page before a search, so a screen reader's outline had
no start there; settings and register began at <h3>. They get a visually
hidden <h1>, and their <h3>s become <h2 class="h3">, which looks the same.
The headings on the settings and function comparison pages sat inside a
<span>, which a heading may not; the wrappers are gone. Dialog titles were
<h5> under the page's <h2>s and are <h2 class="modal-title h5"> now, as the
jobs page's already was, and the shingle table's <h6> under its accordion's
<h2> is an <h3 class="h6">.

The 1vsN, 1vs1 and cross compare pickers were all titled "Compare", and a
link hunt had its result page's title; each now has its own.
Every page made the keyboard cross two logos, four menus and the help link
before its content. A skip link is now the first focusable element, to a
<main id="content" tabindex="-1">; it is clipped out of sight until it has
focus and sits fixed at the top left in both states, so its appearing moves
nothing, not even its own text.

The navbar and the jobs page's category bar were two unnamed navigation
landmarks, and the breadcrumb's name repeated "navigation". They are named
"Main", "Job categories" and "Breadcrumb", and both pager widgets sit in a
<nav aria-label="Pagination">. The search boxes are wrapped in <search>
(the list pages' together with their syntax link, so no flex item changes),
the two on the 1 vs 1 picker named apart.

The current page of a pager, the current compare picker tab and the current
job category were marked by colour alone; they carry aria-current="page".
A closed Bootstrap accordion panel is display: none, which the browser's
find in page skips: a PicBlockHash or MinHash looked for with Ctrl+F on a
function's page was not found until its panel was opened. The new
static/collapsed_find.js, queued on the two pages with such panels, marks
the closed ones hidden="until-found" and opens a panel through Bootstrap
when the browser fires beforematch on it. Bootstrap's classes stay the
state: the attribute is taken off on show.bs.collapse, before Bootstrap
measures the panel, and put back on hidden.bs.collapse. A style.css rule
undoes Bootstrap's display: none for marked panels, whose content the
browser hides itself.

hidden="until-found" is not Baseline yet (Safari lacks it), and there it
would be plain hidden, so the script returns where onbeforematch is
missing and the panels stay exactly as they were. The tab panes are left
alone: a find landing in one would switch the selected tab under the
reader, and the cross compare's panes are empty until first shown.
The jobs page closed a paragraph it never opened, which the parser turns
into an empty one, and its menu items were closed only by the next one
opening. The navbar's collapsing <div> was left for </nav> to close on
every page, and the family table's header macro closed a row it never
opened. Each is closed where it ends now; the DOM a browser builds is the
one it built before.
Four tests found a family or sample line, or the Modify configuration
link, by the exact markup of the icon in it, so any attribute added to the
icon broke them. They match the icon by its class and title now, and allow
a visually hidden word after it, which the next two commits add for
assistive technology.
An icon is a glyph of the icon font, a private-use character that a screen
reader reads as nothing or as "unknown character"; one result page carried
459 of them. What an icon means is said by the text beside it or by the
name of the control it sits in. This adds aria-hidden="true" to every
<i class="fa..."> tag in the templates that lacks it, 111 of them, leaving
alone those with an onclick (a control, not decoration) or an aria-label.

The change is the output of the script below and nothing else, so that a
merge with branches editing the same lines can drop this commit, merge the
rest and run the script again. From the repository root, with the script
saved outside the repository as hide_icons.py:

    python -I hide_icons.py mcritweb/templates

It is idempotent: a second run changes nothing. The names of the controls
whose only content is an icon, and the words for icons that carry meaning,
are the next commit's.

--- hide_icons.py ---
"""Hide Font Awesome icons from assistive technology: add aria-hidden="true" to every
<i class="fa..."> tag in the templates that does not carry it yet.

    python hide_icons.py <templates directory> [--check]

An icon is a glyph from the icon font, a private-use character a screen reader reads as
nothing or as "unknown character"; what it means is the business of the text or the label
of the control around it. Left alone: a tag that already has aria-hidden, and one with an
aria-label or an onclick, which is a label or a control of its own and is not decoration.
Running it again changes nothing. With --check it only reports what it would change.
"""

import pathlib
import re
import sys

#: an <i> start tag on one line; a Jinja expression inside it holds no ">"
TAG = re.compile(r"<i(\s[^>]*)?>")
CLASS = re.compile(r'\sclass="([^"]*)"')
ICON_CLASS = re.compile(r"(?:^|\s)(?:fa|fas|far|fab|fa-solid|fa-regular|fa-brands)(?:\s|$)")


def hide(tag):
    attributes = tag.group(1) or ""
    classes = CLASS.search(attributes)
    if not classes or not ICON_CLASS.search(classes.group(1)):
        return tag.group(0)
    if re.search(r"\s(aria-hidden|aria-label|onclick)=", attributes):
        return tag.group(0)
    separator = "" if attributes.endswith(" ") else " "
    return f'<i{attributes}{separator}aria-hidden="true">'


def main():
    root = pathlib.Path(sys.argv[1])
    check = "--check" in sys.argv[2:]
    changed = 0
    for path in sorted(root.rglob("*.html")):
        text = path.read_text(encoding="utf-8")
        new, count = text, 0
        for match in list(TAG.finditer(text)):
            replacement = hide(match)
            if replacement != match.group(0):
                count += 1
        if count:
            new = TAG.sub(hide, text)
            changed += count
            print(f"{path.relative_to(root)}: {count}")
            if not check:
                path.write_text(new, encoding="utf-8")
    print(f"{changed} icons {'to hide' if check else 'hidden'}")


if __name__ == "__main__":
    main()
With the icons hidden, a control whose only content is an icon is named by
its label alone. Three had none but a title, which assistive technology
need not read: the function page's Analyze menu and its rename button (and
the disabled one) and the settings page's Regenerate token button; they
get an aria-label naming what they act on. The users page put an
aria-label on an <i>, which has no role to carry a name; the icon is hidden
and the words are visually hidden text beside it.

Some icons say what the value after them is: the family and the sample in
a job's description, in the unique blocks report's requested samples, and
the families, samples and functions a PicHash matched. Hidden, they would
leave "win.citadel | 3" or "3, 5, 7"; each now has its word beside it as
visually hidden text, as the table headers already did.

The registration URL's copy icon on the server page is an <i onclick>, a
control rather than decoration; turning it into a button is its own fix,
so it is left alone here and in the test.
Every table on a result page has a pager, and each pager's nav was
"Pagination" with links named "Next page", "Previous page" and so on, so a
list of landmarks or links read the same names several times over, each
going to a different table.

pagination_widget takes a _label of its own, which is not part of the
keyword arguments that become URL parameters. The nav is named "<Label>
pages" and each link "Next page of <label>", "Page 2 of <label>" and so on.
Every caller passes the name of its table. The visible text is unchanged.
The tests passed string predicates to wait_for_function, which a policy
without unsafe-eval refuses. They are arrow functions now.

The caption test also expected the exact caption text. Its point is that a
pane built in the browser keeps the rendered table's caption, so it now
compares the two panes' captions with each other.
r0ny123 added a commit that referenced this pull request Oct 25, 2026
#336 names each pager after its table: "Last page of functions, ...",
"Rows per page of samples". #335's tests looked for the cursor pager's
"Last page," and for select[aria-label='Rows per page'] exactly, so the
disabled-pager check and five page-size tests failed. The pager check
allows an " of <table>" before the comma, and the browser tests find the
select by the start of its name.
Without hard links the key was written into a file created with O_EXCL,
empty until filled. A worker that opened that file in the gap could
replace it and find the creator's key still written into the file it
had displaced; a third worker that had opened the displaced file before
the replacement then read the loser's key and used it, while everyone
else used the winner's. One round in about 1600 ended that way.

The staged key, complete and private from mkstemp, is now renamed into
place under a lock on the instance folder, looking at the key file again
once the lock is held. No key file is opened for writing any more, and
none is ever visible unfinished.

The test that pinned the old create-then-lock order is replaced by two
that pin the new one.
page_loading.js added its empty status region to <body> when it ran, after the
page had loaded. Bootstrap's `legend + *` makes the browser restyle the whole
page for any element added there, which was a second full restyle of about 300 ms
on a 100 by 100 cross compare matrix, and most of the load's extra style time.
base.html now carries the empty region beside the status message box, and the
script only writes to it, making its own only where it is missing. A browser test
checks that nothing is added to <body> once a page has loaded.
The icon-only links and buttons carried their name twice, in an aria-label and in
a title with the same words. Now that each name says which row it acts on, the
two copies differ from row to row and compress badly: about 400 bytes of a
gzipped result page, for a title that only a mouse reads.

The markup now says the name once. icon_titles.js, queued after the first paint,
sets the title from the aria-label of every link or button that shows no text
and has no title of its own, and does the same for a control a script adds later
when the pointer first reaches it. Bootstrap's tooltips, which take their title
over, and the pager links whose title is deliberately shorter than their name
are left as they were.
A few // comments inside inline scripts of templates went to the browser with
every copy of the page, where a Jinja comment says the same to whoever reads the
template and is dropped on rendering. They are Jinja comments now.

A ratchet test keeps the count: no template may send more comment lines in its
inline scripts than it did before.
The tooltips of the icon-only controls were icon_titles.js, queued on every page.
Each file the queue adds is one more ordered request before the page's scripts have
run, and in Lighthouse's mobile run it costs blocking time however little it does.
On the build of all the pull requests the index page took 35 to 45 ms against the
base's 8 to 15, and /data/export 50 to 57 ms against 5 to 12. With icon_titles.js,
keyboard.js and hints.js folded into files the base already queues, the index page
is at 10 ms against 15 and /data/export at 14 ms against 5, all 100.

The code goes at the end of page_loading.js, which every page queues already and
which loaded right before icon_titles.js with nothing queued between them. It is its
own function, so page_loading.js's "use strict" does not reach it. icon_titles.js is
gone, with its later() line.
r0ny123 added a commit that referenced this pull request Oct 26, 2026
…ading and #333's slider wording

The tag that queues upload_form.js from base.html carries the page's
nonce, the overlay's title is the h2 #336 made it, and the slider's
handler upload_form.js defines for the overlay sets its aria-valuetext
as the template's does. #333's tests of the overlay's button and of its
family, version and base address fields read the overlay as the first
drag fetches it.
The labels that became bold table headings carry tooltips written on one line
(white-space: pre), up to 960px wide. hint.css hides a tooltip it does not
show with opacity and visibility alone, and a hidden box still takes its room,
so the sample, function and cross compare result pages scrolled sideways by
that much in a phone or a tablet. A tooltip is now laid out only on hover or
keyboard focus. A browser test checks the three pages at 390 and 820px.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant