Skip to content

Use semantic landmarks for comments wrapper and compose form#686

Open
lrdj wants to merge 1 commit into
utterance:masterfrom
lrdj:semantic-html-aside-and-compose
Open

Use semantic landmarks for comments wrapper and compose form#686
lrdj wants to merge 1 commit into
utterance:masterfrom
lrdj:semantic-html-aside-and-compose

Conversation

@lrdj
Copy link
Copy Markdown

@lrdj lrdj commented May 28, 2026

What

Two small semantic-HTML changes to improve screen-reader navigation:

  • src/client.ts: the wrapper injected around the comments iframe is now
    <aside aria-label="Comments"> instead of <div class="utterances">. This
    exposes the comments widget as a named complementary landmark, so AT users can
    jump straight to it from the host page's landmark list.
  • src/new-comment-component.ts: the compose-form root is now <section aria-label="Write a comment"> instead of <article>. An unsent draft isn't a
    self-contained published composition, so <article> was semantically
    incorrect — <section> with a label is the right fit. Existing comments
    rendered in CommentComponent remain <article>, which is correct.

Why

Both elements kept the .utterances / .timeline-comment classes, so there
is no visual or styling impact and no change to the public embed API. The
benefit is purely for users of assistive technology and for the document
outline.

Refs

Testing

Verified:

  • grep confirms no selector in the project depends on the changed tag names
    (div.utterances, article.timeline-comment) — everything uses class
    selectors, which are unchanged.
  • TypeScript: the only type change is script.nextElementSibling as HTMLElement (was HTMLDivElement), a widening cast that remains valid.

Not verified:

  • I was unable to run the dev server locally to confirm rendered output. The
    current lmdb native dependency (pulled in via parcel@2.3.x) fails to build
    against modern Node (Node 24), with V8 API errors from an older nan.
    Working around this would have required setting up an older Node toolchain
    just for this two-line change, which felt disproportionate. Happy to do so on
    request, or to validate against CI output if available.

client.ts:
wrap injected iframe in <aside aria-label="Comments"> instead of <div>, so AT users get a named complementary landmark to jump to.
new-comment-component.ts:
change compose-form root from <article> to <section aria-label="Write a comment">. Not sure unsent comment is a self-contained composition, so <article> was the wrong element?
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