From f5ab81c2c3c6bba0549a8b1ab1505ba4870b0891 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Thu, 15 Oct 2026 00:35:02 +0000
Subject: [PATCH 1/4] =?UTF-8?q?=EC=A0=91=EA=B7=BC=EC=84=B1=20=EA=B0=9C?=
 =?UTF-8?q?=EC=84=A0:=20=ED=8C=8C=EC=9D=BC=20=EC=97=85=EB=A1=9C=EB=93=9C?=
 =?UTF-8?q?=20=ED=95=84=EB=93=9C=EC=97=90=20=EB=AA=85=EC=8B=9C=EC=A0=81=20?=
 =?UTF-8?q?`(required)`=20=ED=85=8D=EC=8A=A4=ED=8A=B8=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

문서 업로드 폼의 필수 입력 필드 레이블에 시각적 애스터리스크(*)나 `aria-hidden` 대신 명시적인 `(required)` 텍스트를 추가하여 스크린 리더 접근성과 WCAG 2.5.3 (Label in Name) 호환성을 향상시켰습니다. 변경사항을 검증하기 위해 `ViewerUiRequiredFieldAccessibilityTest`를 추가했으며, Palette 저널에 관련 내용을 기록했습니다.
---
 .jules/palette.md                               |  4 ++++
 CHANGELOG.md                                    |  2 ++
 .../viewer/controller/ViewerUiController.java   |  2 +-
 .../controller/ViewerUiControllerTest.java      | 17 +++++++++++++++++
 4 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/.jules/palette.md b/.jules/palette.md
index a34ea59b2..117f5f3fb 100644
--- a/.jules/palette.md
+++ b/.jules/palette.md
@@ -13,3 +13,7 @@
 ## 2026-07-13 - Async Table Actions UX
 **Learning:** Adding explicit loading and disabled states to table action buttons that invoke asynchronous processes helps prevent redundant API calls and visually assures the user that their request is being handled.
 **Action:** Consistently apply `disabled` state and `Loading...` text changes to inline table action buttons linked to async workflows, and carefully preserve underlying DOM structures with `Array.from(btn.childNodes)` during the loading cycle to avoid rendering regressions.
+
+## 2024-10-24 - Explicit (required) Text Pattern
+**Learning:** Using an explicit `(required)` text directly inside the `<label>` instead of using styled asterisks (`*`) or `aria-hidden` elements provides better accessibility for screen readers and complies with WCAG guidelines. This is enforced by `ViewerUiRequiredFieldAccessibilityTest`.
+**Action:** Always use the explicit `(required)` text inside the `<label>` for required form fields across this app to maintain a consistent accessibility pattern.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1187deb2a..382bd974b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@
 
 ### Added
 
+- **접근성 개선**: 문서 업로드 폼의 필수 입력 필드 레이블에 시각적 애스터리스크(*)나 `aria-hidden` 대신 명시적인 `(required)` 텍스트를 포함하여 스크린 리더 접근성과 WCAG 2.5.3 호환성을 향상시켰습니다.
+
 - **UI UX 개선**: 'Details' 버튼 클릭 시, 작업 상세 정보 로드 중에 사용자가 명시적인 로딩 상태를 확인할 수 있도록 'Loading...' 텍스트와 비활성화 상태를 표시하도록 추가했습니다.
 - **관리자용 단건 작업 삭제 및 재시도 API 추가**
   - 특정 변환 작업을 삭제할 수 있는 `DELETE /api/v1/admin/convert/jobs/{jobId}` 엔드포인트를 추가했습니다.
diff --git a/src/main/java/com/clearfolio/viewer/controller/ViewerUiController.java b/src/main/java/com/clearfolio/viewer/controller/ViewerUiController.java
index 3e5ee0710..d344b8e7a 100644
--- a/src/main/java/com/clearfolio/viewer/controller/ViewerUiController.java
+++ b/src/main/java/com/clearfolio/viewer/controller/ViewerUiController.java
@@ -185,7 +185,7 @@ private static String demoShellHtml() {
                         </div>
 
                         <form id="upload-form" class="upload-form" enctype="multipart/form-data">
-                          <label class="field-label" for="file-input">Document</label>
+                          <label class="field-label" for="file-input">Document (required)</label>
                           <input id="file-input" name="file" class="file-input" type="file" required />
 
                           <div class="actions">
diff --git a/src/test/java/com/clearfolio/viewer/controller/ViewerUiControllerTest.java b/src/test/java/com/clearfolio/viewer/controller/ViewerUiControllerTest.java
index fa2dcfcac..a09c977ea 100644
--- a/src/test/java/com/clearfolio/viewer/controller/ViewerUiControllerTest.java
+++ b/src/test/java/com/clearfolio/viewer/controller/ViewerUiControllerTest.java
@@ -228,4 +228,21 @@ void viewerStillServesUuidDocId() {
                 .expectBody(String.class)
                 .value(body -> assertTrue(body.contains(docId.toString())));
     }
+
+    @Test
+    void viewerUiRequiredFieldAccessibilityTest() {
+        webTestClient.get()
+                .uri("/")
+                .exchange()
+                .expectStatus().isOk()
+                .expectHeader().contentTypeCompatibleWith(
+                        MediaType.TEXT_HTML)
+                .expectBody(String.class)
+                .value(body -> {
+                    assertTrue(body.contains(
+                            "<label class=\"field-label\" "
+                            + "for=\"file-input\">"
+                            + "Document (required)</label>"));
+                });
+    }
 }

From 69ea3f21df3b5366c929db982ad4611452bb288a Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Thu, 15 Oct 2026 00:37:09 +0000
Subject: [PATCH 2/4] =?UTF-8?q?=EC=A0=91=EA=B7=BC=EC=84=B1=20=EA=B0=9C?=
 =?UTF-8?q?=EC=84=A0:=20=ED=8C=8C=EC=9D=BC=20=EC=97=85=EB=A1=9C=EB=93=9C?=
 =?UTF-8?q?=20=ED=95=84=EB=93=9C=EC=97=90=20=EB=AA=85=EC=8B=9C=EC=A0=81=20?=
 =?UTF-8?q?`(required)`=20=ED=85=8D=EC=8A=A4=ED=8A=B8=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

문서 업로드 폼의 필수 입력 필드 레이블에 시각적 애스터리스크(*)나 `aria-hidden` 대신 명시적인 `(required)` 텍스트를 추가하여 스크린 리더 접근성과 WCAG 2.5.3 (Label in Name) 호환성을 향상시켰습니다. 변경사항을 검증하기 위해 `ViewerUiRequiredFieldAccessibilityTest`를 추가했으며, Palette 저널에 관련 내용을 기록했습니다.

From 50e00bae45c0a55859617c8aa78a376958e68fa4 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Thu, 15 Oct 2026 00:39:30 +0000
Subject: [PATCH 3/4] =?UTF-8?q?=EC=A0=91=EA=B7=BC=EC=84=B1=20=EA=B0=9C?=
 =?UTF-8?q?=EC=84=A0:=20=ED=8C=8C=EC=9D=BC=20=EC=97=85=EB=A1=9C=EB=93=9C?=
 =?UTF-8?q?=20=ED=95=84=EB=93=9C=EC=97=90=20=EB=AA=85=EC=8B=9C=EC=A0=81=20?=
 =?UTF-8?q?`(required)`=20=ED=85=8D=EC=8A=A4=ED=8A=B8=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

문서 업로드 폼의 필수 입력 필드 레이블에 시각적 애스터리스크(*)나 `aria-hidden` 대신 명시적인 `(required)` 텍스트를 추가하여 스크린 리더 접근성과 WCAG 2.5.3 (Label in Name) 호환성을 향상시켰습니다. 변경사항을 검증하기 위해 `ViewerUiRequiredFieldAccessibilityTest`를 추가했으며, Palette 저널에 관련 내용을 기록했습니다.

From fbd322c07e8a3506d2d3927f79d703be980ad5e8 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Thu, 15 Oct 2026 00:41:59 +0000
Subject: [PATCH 4/4] =?UTF-8?q?=EC=A0=91=EA=B7=BC=EC=84=B1=20=EA=B0=9C?=
 =?UTF-8?q?=EC=84=A0:=20=ED=8C=8C=EC=9D=BC=20=EC=97=85=EB=A1=9C=EB=93=9C?=
 =?UTF-8?q?=20=ED=95=84=EB=93=9C=EC=97=90=20=EB=AA=85=EC=8B=9C=EC=A0=81=20?=
 =?UTF-8?q?`(required)`=20=ED=85=8D=EC=8A=A4=ED=8A=B8=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

문서 업로드 폼의 필수 입력 필드 레이블에 시각적 애스터리스크(*)나 `aria-hidden` 대신 명시적인 `(required)` 텍스트를 추가하여 스크린 리더 접근성과 WCAG 2.5.3 (Label in Name) 호환성을 향상시켰습니다. 변경사항을 검증하기 위해 `ViewerUiRequiredFieldAccessibilityTest`를 추가했으며, Palette 저널에 관련 내용을 기록했습니다.