fix(a11y): name directory navigation from a hidden heading

[seonghobae]

Current exact authority

• protected target: master@55b39b4ebad435670f26ec8065dfc980950e090e
• exact head: 4435d487079f501d87e4d5e500615e907665b10e
• lifecycle: open / Draft / mechanically mergeable

Bounded accessibility contract

The generated directory navigation changes from <nav aria-label="디렉토리 목록"> to <nav aria-labelledby="nav-heading"> with <h2 id="nav-heading" class="visually-hidden">디렉토리 목록</h2>. The focused structural regression requires both the reference and the referenced heading text.

W3C APG recommends naming navigation landmarks so assistive-technology users can understand their purpose and supports aria-labelledby when a label element is available; its navigation landmark example also shows a nav containing a heading. That supports the semantic structure. It does not establish that this pattern is universally superior to aria-label, nor does it prove Chrome Translate or every browser/AT combination will translate and announce it as intended.

Primary references:

• W3C WAI-ARIA APG, Providing Accessible Names and Descriptions: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/
• W3C WAI-ARIA APG, Navigation Landmark: https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/navigation.html

Repair performed

Exact-head descendant 4435d487079f501d87e4d5e500615e907665b10e restores .jules/palette.md to the protected-base blob. The branch no longer introduces a repository-wide rule that aria-labelledby is always preferable or that this pattern solves browser-translation compatibility. The product-specific markup and stronger structural regression remain unchanged. Protected-base comparison now contains only src/main/kotlin/html4tree/main.kt and src/test/kotlin/html4tree/MainTest.kt.

Older #587 implements the same generated markup against an older base, but its regression checks only the nav aria-labelledby attribute and does not separately require the referenced hidden <h2>. Its valid delta is therefore fully carried by this stronger current-base lane; its claim of “100%” translation/accessibility compatibility is explicitly not inherited.

Delivery Gate

• Intentionality: PASS — the hidden heading gives the navigation landmark a concrete text-node label and a heading-navigation target.
• Functional completeness: PASS at static markup-contract level — nav, list, links and label reference remain generated; browser/AT behavior is not yet claimed.
• Content fit: PASS — no decorative or template-only UI was added.
• Resilience: PARTIAL — existing generated-output regression covers structure, but current-head browser/accessibility-tree behavior and major AT combinations are not executed here.
• Evidence: FAIL/PENDING for browser translation and cross-AT claims; those claims are not promotion authority.
• Product identity: unchanged.

Promotion boundary

Keep Draft until exact-head CI/JaCoCo/security evidence is terminal, current review/thread admission is clean, and any browser-translation/AT claim has reproducible browser/accessibility-tree evidence. No predecessor evidence transfer, self-approval, no-op retrigger, force rewrite, or gate weakening.

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

🔍 Accessibility guidance is now stale

Repository guidance still mandates <nav aria-label>, conflicting with aria-labelledby. Future changes can restore the superseded markup or reject this pattern.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[seonghobae]

@jules Please repair this exact branch in place without changing the generated nav markup/test: remove the newly appended repository-wide .jules/palette.md rule that says aria-labelledby is always preferable and that it solves browser-translation compatibility. W3C supports naming navigation landmarks and the aria-labelledby mechanism, but this branch has no Chrome Translate or cross-AT execution proving universal superiority/compatibility. Restore the protected Palette blob for that appended delta (or keep only an evidence-bounded product-specific note if you can cite executed browser/AT evidence). Preserve <nav aria-labelledby="nav-heading">, the referenced hidden <h2>, and the structural regression. Normal descendant only; no force/rebase or gate changes.