From b44ece624dfff9f9cea9891dbc8f60f4447e013f Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sat, 8 Aug 2026 19:17:15 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20[UX=20improvement]=20?=
 =?UTF-8?q?HTML=20=EB=A6=AC=ED=8F=AC=ED=8A=B8=EC=9D=98=20=EB=B9=88=20?=
 =?UTF-8?q?=EC=83=81=ED=83=9C=EC=97=90=20ARIA=20Live=20Region=20=EC=A0=81?=
 =?UTF-8?q?=EC=9A=A9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `fast_mlsirm/scoring/essay/validation_report_html.py`의 `_identifier_list`에서 빈 상태를 렌더링할 때 `<p>` 태그 대신 `<div class="empty-state" role="status">`를 사용하도록 변경했습니다.
- 이를 통해 스크린 리더 사용자가 페이지를 동적으로 탐색하거나 로딩될 때 데이터가 없음을 명확하게 인지할 수 있도록 접근성을 개선했습니다.
- 관련된 테스트와 `.jules/palette.md`의 학습 일지도 함께 업데이트했습니다.
---
 .jules/palette.md                             |  4 ++++
 .../scoring/essay/validation_report_html.py   | 15 +++++--------
 ...st_scoring_essay_validation_report_html.py | 22 ++++++++++++-------
 3 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/.jules/palette.md b/.jules/palette.md
index ee48ab0ea..1463b6968 100644
--- a/.jules/palette.md
+++ b/.jules/palette.md
@@ -47,3 +47,7 @@
 ## 2025-02-12 - Exposing Unrounded Numeric Representations for Formatted Floats
 **Learning:** In data-heavy HTML reports, formatting floats to a fixed number of significant digits can obscure the original Python float representation. A native `title` tooltip can help pointer users inspect that unrounded representation, but it is not a reliable keyboard, touch, or assistive-technology disclosure mechanism.
 **Action:** Add the unrounded Python float representation as a supplemental native `title` tooltip on formatted values. Preserve the report's accessible exact-value disclosure and JSON/CSV exports as the authoritative non-hover paths; never claim that `title` alone provides accessibility.
+
+## 2025-02-13 - Empty States ARIA Live Regions
+**Learning:** In HTML reports, simply using generic tags like `<p>` for empty states (such as an empty list of triggers) fails to proactively announce the absence of data to screen reader users navigating dynamically.
+**Action:** Always use `<div class="empty-state" role="status">` for empty states to ensure they act as ARIA live regions and are reliably announced by assistive technologies when content is evaluated or loaded.
diff --git a/python/fast_mlsirm/scoring/essay/validation_report_html.py b/python/fast_mlsirm/scoring/essay/validation_report_html.py
index 3c8eea6d3..ee3e1b148 100644
--- a/python/fast_mlsirm/scoring/essay/validation_report_html.py
+++ b/python/fast_mlsirm/scoring/essay/validation_report_html.py
@@ -74,8 +74,7 @@ def _validated_report(
         category_count=report.category_count,
         paired_observation_count=report.paired_observation_count,
         metrics=tuple(
-            _replay_metric(metric, index)
-            for index, metric in enumerate(report.metrics)
+            _replay_metric(metric, index) for index, metric in enumerate(report.metrics)
         ),
         review_trigger_ids=report.review_trigger_ids,
         metadata=report.metadata,
@@ -108,7 +107,7 @@ def _identifier_list(
 ) -> str:
     """Render identifier evidence as a semantic list or explicit empty state."""
     if not identifiers:
-        return f'<p class="empty-state">{escape(empty_message)}</p>'
+        return f'<div class="empty-state" role="status">{escape(empty_message)}</div>'
     items = "".join(
         f"<li><code>{escape(identifier)}</code></li>" for identifier in identifiers
     )
@@ -191,9 +190,9 @@ def _render_html(report: EssayValidationEvidenceReport, title: str) -> str:
             '<section class="review-required" aria-labelledby="review-heading">',
             '<h2 id="review-heading">Human interpretation required</h2>',
             f'<p class="notice">{escape(_VALIDITY_NOTICE)}</p>',
-            '<h3>Review triggers</h3>',
+            "<h3>Review triggers</h3>",
             triggers,
-            '<h3>Interpretation boundaries</h3>',
+            "<h3>Interpretation boundaries</h3>",
             boundaries,
             "</section>",
             '<section aria-labelledby="provenance-heading">',
@@ -206,7 +205,7 @@ def _render_html(report: EssayValidationEvidenceReport, title: str) -> str:
             "</section>",
             '<section aria-labelledby="json-heading">',
             '<h2 id="json-heading">Canonical JSON</h2>',
-            '<p>The complete deterministic evidence payload is available below for audit reconstruction.</p>',
+            "<p>The complete deterministic evidence payload is available below for audit reconstruction.</p>",
             '<pre tabindex="0" role="region" aria-label="Canonical essay validation evidence JSON">',
             _canonical_json(report),
             "</pre>",
@@ -236,9 +235,7 @@ def render_essay_validation_evidence_report_html(
     if output.suffix.lower() != ".html":
         raise ValueError("essay validation evidence output path must end with .html")
     if title is not None and (not isinstance(title, str) or not title.strip()):
-        raise ValueError(
-            "essay validation evidence title must be a non-empty string"
-        )
+        raise ValueError("essay validation evidence title must be a non-empty string")
     resolved_title = _DEFAULT_TITLE if title is None else title
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_text(_render_html(validated, resolved_title), encoding="utf-8")
diff --git a/tests/test_scoring_essay_validation_report_html.py b/tests/test_scoring_essay_validation_report_html.py
index 27a5739c2..97e12ac88 100644
--- a/tests/test_scoring_essay_validation_report_html.py
+++ b/tests/test_scoring_essay_validation_report_html.py
@@ -80,18 +80,24 @@ def test_custom_title_and_identifiers_are_escaped(tmp_path: Path) -> None:
 
     assert "&lt;img src=x onerror=&quot;alert(1)&quot;&gt;" in html
     assert "<img src=x" not in html
-    assert validation_report_html._identifier_list(
-        ("review_<unsafe>",),
-        empty_message="No review trigger.",
-    ) == '<ul class="trigger-list"><li><code>review_&lt;unsafe&gt;</code></li></ul>'
+    assert (
+        validation_report_html._identifier_list(
+            ("review_<unsafe>",),
+            empty_message="No review trigger.",
+        )
+        == '<ul class="trigger-list"><li><code>review_&lt;unsafe&gt;</code></li></ul>'
+    )
 
 
 def test_empty_identifier_list_renders_explicit_state() -> None:
     """An empty evidence list remains understandable without hidden state."""
-    assert validation_report_html._identifier_list(
-        (),
-        empty_message="No boundary is available.",
-    ) == '<p class="empty-state">No boundary is available.</p>'
+    assert (
+        validation_report_html._identifier_list(
+            (),
+            empty_message="No boundary is available.",
+        )
+        == '<div class="empty-state" role="status">No boundary is available.</div>'
+    )
 
 
 def test_renderer_rejects_wrong_type_and_wrong_suffix(tmp_path: Path) -> None: