Repository navigation
fix(a11y): preserve report focus and data contrast #548
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.
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
Closed
Closed
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
595cfcc
🎨 Palette: 향상된 포커스 표시 및 접근성 대비 개선
seonghobae e326833
test(a11y): pin focus reveal and non-dimming report CSS
seonghobae 6ae2613
docs(a11y): calibrate focus and contrast claims
seonghobae 14a9865
docs(doctoring): ground report focus and contrast styling
seonghobae a1ad3be
docs(changelog): record report focus and contrast repair
seonghobae b79ce7e
ci: render PR 548 changelog once
seonghobae c9142c9
docs(changelog): render report focus and contrast repair
github-actions[bot] cc288bc
test(a11y): retain non-destructive row hover cue
seonghobae 0ea6d41
🎨 Palette: 향상된 포커스 표시 및 접근성 대비 개선
seonghobae File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| # Diagnostics-report focus and contrast preservation | ||
|
|
||
| ## Fixed | ||
|
|
||
| - Revealed the visually hidden diagnostics-report skip link for every actual `:focus` state while retaining the explicit `:focus-visible` treatment and strong outline. | ||
| - Removed opacity-based dimming of non-hovered chart and table rows so unrelated active data retains its normal rendered foreground and background colors. | ||
| - Added public-renderer regression coverage and APA 7th doctoring grounded in WCAG 2.2 and Selectors Level 4 without making a formal conformance claim. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # Doctoring record: diagnostics-report focus reveal and contrast preservation | ||
|
|
||
| ## Decision | ||
|
|
||
| The standalone diagnostics report reveals its visually hidden skip-navigation link whenever that link has actual input focus. The stylesheet keeps both `.skip-link:focus` and `.skip-link:focus-visible`, using the same visible placement and outline treatment. | ||
|
|
||
| Pointer hover may highlight the active bar or table row, but it no longer lowers the opacity of every unrelated row. Data that remains active and readable should retain its normal foreground and background colors while another row is hovered. | ||
|
|
||
| ## Standards rationale | ||
|
|
||
| Selectors Level 4 distinguishes `:focus`, which applies while an element has input focus, from `:focus-visible`, which additionally depends on user-agent heuristics about whether a focus indicator should be drawn. A skip link that is visually hidden until focused therefore uses `:focus` as the reveal boundary rather than relying only on the heuristic pseudo-class. | ||
|
|
||
| WCAG 2.2 Success Criterion 1.4.3 requires minimum text contrast for ordinary visible text, subject to its stated exceptions. Applying opacity to an entire otherwise active row composites both text and background and can reduce the final rendered contrast. Because the actual ratio depends on all computed colors and the rendering environment, this change does not claim that the removed selector was universally nonconforming or that the resulting report is formally WCAG-conformant. It removes an avoidable contrast risk and retains exact visible content for all rows. | ||
|
|
||
| ## Verification contract | ||
|
|
||
| `tests/test_report_focus_contrast.py` renders a realistic diagnostics report through the public `render_diagnostics_report` entry point and proves that: | ||
|
|
||
| - the generated stylesheet includes a `.skip-link:focus` reveal rule alongside `.skip-link:focus-visible`; | ||
| - the focused link retains the strong repository-owned outline; | ||
| - the generated stylesheet contains no chart-peer opacity selector; and | ||
| - the generated stylesheet contains no table-peer opacity selector. | ||
|
|
||
| The test validates deterministic generated markup. It is not a substitute for browser, assistive-technology, zoom, forced-colors, dark-mode, print, or user testing. | ||
|
|
||
| ## Compatibility and rollback | ||
|
|
||
| The change affects presentation only. It does not alter report data, JSON parsing, numerical values, table semantics, export formats, model fitting, database objects, network behavior, or public Python signatures. Rollback consists of restoring the prior CSS selectors, but doing so would reintroduce the documented focus-reveal and contrast risks. | ||
|
|
||
| ## References | ||
|
|
||
| World Wide Web Consortium. (2023, October 5). *Web Content Accessibility Guidelines (WCAG) 2.2* (W3C Recommendation). https://www.w3.org/TR/WCAG22/ | ||
|
|
||
| World Wide Web Consortium CSS Working Group. (2026, January 22). *Selectors Level 4* (W3C Working Draft). https://www.w3.org/TR/selectors-4/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| """Accessibility contracts for diagnostics-report focus and contrast styling.""" | ||
|
|
||
| from __future__ import annotations | ||
|
|
||
| import json | ||
| from pathlib import Path | ||
|
|
||
| from fast_mlsirm.report import render_diagnostics_report | ||
|
|
||
|
|
||
| def _render_report(tmp_path: Path) -> str: | ||
| """Render one realistic diagnostics report and return its complete HTML.""" | ||
| source = tmp_path / "fit_diagnostics.json" | ||
| output = tmp_path / "diagnostics_report.html" | ||
| source.write_text( | ||
| json.dumps( | ||
| { | ||
| "model_fit": {"loglik": -3.2}, | ||
| "itemfit": { | ||
| "item_id": ["item_alpha", "item_beta"], | ||
| "outfit_mnsq": [1.0, 1.2], | ||
| "observed_count": [120, 117], | ||
| }, | ||
| } | ||
| ), | ||
| encoding="utf-8", | ||
| ) | ||
| render_diagnostics_report(source, output, title="Accessible Fit Review") | ||
| return output.read_text(encoding="utf-8") | ||
|
|
||
|
|
||
| def test_skip_link_is_revealed_for_every_actual_focus_state(tmp_path: Path) -> None: | ||
| """A focused skip link must not depend only on user-agent focus heuristics.""" | ||
| html = _render_report(tmp_path) | ||
|
|
||
| assert ".skip-link:focus,\n.skip-link:focus-visible {" in html | ||
| assert "outline: 3px solid var(--teal);" in html | ||
|
|
||
|
|
||
| def test_hover_does_not_dim_unrelated_chart_or_table_content(tmp_path: Path) -> None: | ||
| """Pointer hover must preserve the normal contrast of unrelated data rows.""" | ||
| html = _render_report(tmp_path) | ||
|
|
||
| assert ".bar-chart:hover .bar-row:not(:hover)" not in html | ||
| assert "tbody:hover tr:not(:hover)" not in html | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.