Skip to content

fix(a11y): name directory navigation from translatable text #637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
seonghobae wants to merge 6 commits into
base: master
Choose a base branch
from
+7 −2
Draft

fix(a11y): name directory navigation from translatable text #637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8412948
🎨 Palette: [UX 개선] nav 요소에 aria-labelledby 적용
seonghobae Sep 6, 2026
b40efc8
🎨 Palette: [UX 개선] nav 요소에 aria-labelledby 적용
seonghobae Sep 6, 2026
b242c31
repair(a11y): keep local nav change out of Palette doctrine
seonghobae Sep 6, 2026
5d46390
🎨 Palette: [UX 개선] nav 요소에 aria-labelledby 적용
seonghobae Sep 6, 2026
0d04bb8
🎨 Palette: [UX 개선] nav 요소에 aria-labelledby 적용
seonghobae Sep 6, 2026
8988e0d
🎨 Palette: [UX 개선] nav 요소에 aria-labelledby 적용
seonghobae Sep 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .jules/palette.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,6 @@
## 2026-08-17 - 브라우저 번역과 화면 판독기의 호환성을 위한 텍스트 처리
**Learning:** `aria-label` 속성으로 지정된 화면 판독기용 대체 텍스트는 Chrome Translate 등 브라우저 번역 도구에 의해 번역되지 않는 경우가 많습니다. 이로 인해 문서 언어가 변환되어도 스크린 리더에서는 원본 언어(예: 영어)로 읽혀 다국어 접근성이 저하됩니다.
**Action:** 화면 판독기를 위한 숨겨진 설명 텍스트를 제공할 때 `aria-label` 대신 CSS `.visually-hidden` 클래스를 적용한 `<span>` 요소를 사용하여, 브라우저가 일반 텍스트로 인식하고 번역할 수 있도록 하여 다국어 접근성 호환성을 확보하십시오.
## 2026-09-06 - aria-label 대신 aria-labelledby를 사용하여 네비게이션 헤더 작성
**Learning:** 브라우저 번역 도구는 종종 `aria-label` 속성을 번역하지 못하는 반면, 시각적으로 숨겨진 요소 내의 표준 텍스트 노드는 올바르게 번역합니다. 또한, 실제 제목 요소를 사용하면 스크린 리더 사용자가 '제목 단위 이동' 단축키를 사용하여 네비게이션 블록을 더 쉽게 발견할 수 있습니다. (aria-labelledby 번역 호환성)
**Action:** 항상 시각적으로 숨겨진 제목 요소 (예: `<h2 id="nav-heading" class="visually-hidden">제목</h2>`)를 선호하고 번역된 텍스트를 직접 `aria-label`에 배치하는 대신 `aria-labelledby="nav-heading"`을 사용하여 네비게이션 컨테이너와 연결합니다.
3 changes: 2 additions & 1 deletion src/main/kotlin/html4tree/main.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -427,7 +427,8 @@ fun process_dir(curr_dir: File, excludeSet: Set<String>? = null, dirFiles: Array
<body>
<main>
<h1>${directoryName.escapeHtml()}</h1>
<nav aria-label="디렉토리 목록">
<nav aria-labelledby="nav-heading">
<h2 id="nav-heading" class="visually-hidden">디렉토리 목록</h2>
<ul role="list">
<li><a class="dir-link" href="./.." title="상위 디렉토리로 이동"><span class="icon" aria-hidden="true">&#x21B0;</span> <span aria-hidden="true">..</span> <span class="visually-hidden">상위 디렉토리로 이동</span></a></li>
"""
Expand Down
3 changes: 2 additions & 1 deletion src/test/kotlin/html4tree/MainTest.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -331,7 +331,8 @@ class MainTest {
assertTrue(htmlContent.contains("<meta name=\"theme-color\" content=\"#ffffff\" media=\"(prefers-color-scheme: light)\">"))
assertTrue(htmlContent.contains("<meta name=\"theme-color\" content=\"#0d1117\" media=\"(prefers-color-scheme: dark)\">"))
assertRobotsDirective(htmlContent)
assertTrue(htmlContent.contains("<nav aria-label=\"디렉토리 목록\">"))
assertTrue(htmlContent.contains("<nav aria-labelledby=\"nav-heading\">"))
assertTrue(htmlContent.contains("<h2 id=\"nav-heading\" class=\"visually-hidden\">디렉토리 목록</h2>"))
assertTrue(htmlContent.contains("role=\"list\""))
assertTrue(htmlContent.contains("<main>"))
assertTrue(htmlContent.contains("</main>"))
Expand Down
Loading