sixfold-space/madtea

SHA256

Fork 0

docs(a11y): provide an abbreviation-expansion mechanism (WCAG 3.1.4) #452

New issue

Open

opened 2026-08-25 19:48:17 +00:00 by hexajon · 2 comments

hexajon commented

2026-08-25 19:48:17 +00:00

Owner

The constraint that puts this here rather than on the site: the docs render on madtea.lol through syncdocs, and those generated pages are machine-owned. They cannot be hand-patched on the site side, so the mechanism has to live in the docs source, or in a shared transform, so it survives a re-sync.

Options to weigh (not settled):

<abbr title="..."> on first use, from the docs source or a render hook.
A short glossary/terms page, linked site-wide (techniques G62/G55).
A build-time transform that wraps a known list of terms.

Whatever the mechanism, the visible prose stays exactly as written. Expansion is a tooltip, a link, or a first-use gloss, never a rewrite of the copy.

Acceptance:

A reader can find the expansion of each abbreviation used in the docs.
The visible copy and its voice are unchanged.
It applies across the generated docs, so it lives in the source or the transform, not in hand-edited pages.
Meets WCAG 3.1.4.

The docs lean on a lot of shorthand - CLI, MCP, GPG, TLS, TOFU, ADR, SSH, amd64/arm64 - with no way for a reader to get the expanded form. WCAG 3.1.4 (Abbreviations, level AAA) asks for a mechanism to do that. This is a future accessibility enhancement, not a launch blocker; the site targets AA today. The constraint that puts this here rather than on the site: the docs render on madtea.lol through syncdocs, and those generated pages are machine-owned. They cannot be hand-patched on the site side, so the mechanism has to live in the docs source, or in a shared transform, so it survives a re-sync. Options to weigh (not settled): - `<abbr title="...">` on first use, from the docs source or a render hook. - A short glossary/terms page, linked site-wide (techniques G62/G55). - A build-time transform that wraps a known list of terms. Whatever the mechanism, the visible prose stays exactly as written. Expansion is a tooltip, a link, or a first-use gloss, never a rewrite of the copy. Acceptance: - A reader can find the expansion of each abbreviation used in the docs. - The visible copy and its voice are unchanged. - It applies across the generated docs, so it lives in the source or the transform, not in hand-edited pages. - Meets WCAG 3.1.4.

hexajon added the

status/needs-decision

label

2026-08-27 03:57:10 +00:00

hexajon commented

2026-08-27 03:57:10 +00:00

Author

Owner

The docs render on madtea.lol through syncdocs, so the mechanism has to live in the source or a shared transform to survive a re-sync. Three shapes are open: inline <abbr title="..."> on first use, a linked glossary/terms page (techniques G62/G55), or a build-time transform over a known term list. I lean to the glossary page: it is one source-owned file, it survives a re-sync cleanly, it needs no per-page markup churn, and the visible prose stays exactly as written. The <abbr> route touches every first-use across the whole doc set; the transform is the most machinery for a AAA-level item that is not launch-blocking. Which mechanism do you want - say "glossary" and I will build the terms page plus the site-wide link, or name another.

The docs render on madtea.lol through syncdocs, so the mechanism has to live in the source or a shared transform to survive a re-sync. Three shapes are open: inline `<abbr title="...">` on first use, a linked glossary/terms page (techniques G62/G55), or a build-time transform over a known term list. I lean to the glossary page: it is one source-owned file, it survives a re-sync cleanly, it needs no per-page markup churn, and the visible prose stays exactly as written. The `<abbr>` route touches every first-use across the whole doc set; the transform is the most machinery for a AAA-level item that is not launch-blocking. Which mechanism do you want - say "glossary" and I will build the terms page plus the site-wide link, or name another.

hexajon commented

2026-09-08 18:13:44 +00:00

Author

Owner

Decided: a source-owned glossary / terms page, linked site-wide (WCAG techniques G62/G55).

One glossary file lives in the docs source and every generated page links to it. This survives the machine re-sync of the published pages, needs no per-page churn, and leaves the prose unchanged. It satisfies WCAG 3.1.4 without an inline <abbr> sweep across the whole doc set or a new build-time transform.

This stays AAA-level and is not a launch blocker; the site targets AA today.

No governing ADR touches docs accessibility, so this comment is the record.

Decided: a source-owned glossary / terms page, linked site-wide (WCAG techniques G62/G55). One glossary file lives in the docs source and every generated page links to it. This survives the machine re-sync of the published pages, needs no per-page churn, and leaves the prose unchanged. It satisfies WCAG 3.1.4 without an inline `<abbr>` sweep across the whole doc set or a new build-time transform. This stays AAA-level and is not a launch blocker; the site targets AA today. No governing ADR touches docs accessibility, so this comment is the record.

hexajon removed the

status/needs-decision

label

2026-09-08 18:13:45 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#452

No description provided.

Rows
Columns