Found during an accessibility review of a story map rendered by @windyroad/itil in an adopter repo.
The finding
scripts/render-story-map.mjs builds every reference link with the identifier as its own link text:
link(hrefs, id, esc(id)) // traces footer
link(hrefs, p, esc(p)) // row problems
So the links on a rendered map read P033, JTBD-400, RFC-009. A screen reader's link list presents links out of context, where those announce as six or eight characters sitting between full sentences.
SC 2.4.4 (Link Purpose, In Context) is a marginal pass for the row-problem links, which sit inside a th scope="row" that supplies some context. The traces-footer links sit in a p and have less. SC 2.4.9 (Link Purpose, Link Only) fails for both.
Why it belongs here rather than in an adopter repo
The link text is not authored by the adopter. The renderer emits it for every story map this toolchain produces, so a fix applied to a rendered HTML file is overwritten on the next render:story-maps run.
Suggested fix
Both call sites already hold the resolved path, so a readable label can be derived from the filename slug without a second lookup. 033-source-inspection-tests-anti-pattern.md yields "Source inspection tests are an anti-pattern", which gives:
P033: Source inspection tests are an anti-pattern
That keeps the identifier for people who navigate by it and gives the link list something to distinguish entries by. Reading the title out of the target file's H1 would be more faithful, at the cost of a read per link.
Scope
Eight anchors on the map I looked at, all of the same shape. The same link() helper serves both call sites, so one change covers both.
Reported from https://github.com/mountain-pass/addressr. I can open a PR if you would rather review a diff than a description.
Found during an accessibility review of a story map rendered by
@windyroad/itilin an adopter repo.The finding
scripts/render-story-map.mjsbuilds every reference link with the identifier as its own link text:So the links on a rendered map read
P033,JTBD-400,RFC-009. A screen reader's link list presents links out of context, where those announce as six or eight characters sitting between full sentences.SC 2.4.4 (Link Purpose, In Context) is a marginal pass for the row-problem links, which sit inside a
th scope="row"that supplies some context. The traces-footer links sit in apand have less. SC 2.4.9 (Link Purpose, Link Only) fails for both.Why it belongs here rather than in an adopter repo
The link text is not authored by the adopter. The renderer emits it for every story map this toolchain produces, so a fix applied to a rendered HTML file is overwritten on the next
render:story-mapsrun.Suggested fix
Both call sites already hold the resolved path, so a readable label can be derived from the filename slug without a second lookup.
033-source-inspection-tests-anti-pattern.mdyields "Source inspection tests are an anti-pattern", which gives:That keeps the identifier for people who navigate by it and gives the link list something to distinguish entries by. Reading the title out of the target file's H1 would be more faithful, at the cost of a read per link.
Scope
Eight anchors on the map I looked at, all of the same shape. The same
link()helper serves both call sites, so one change covers both.Reported from https://github.com/mountain-pass/addressr. I can open a PR if you would rather review a diff than a description.