Skip to content
7 changes: 7 additions & 0 deletions .Jules/palette.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,10 @@
## 2026-08-04 - Status Semantics and Numeric Alignment for Reports
**Learning:** Explicit status semantics can make conditionally rendered empty states easier to discover with assistive technology, while tabular numerals improve visual comparison of metric columns. Focus-reveal behavior must not depend only on `:focus-visible`, and hover styling must not reduce the contrast of unrelated rows.
**Action:** Use `role="status"` for genuine conditionally rendered status messages, apply `font-variant-numeric: tabular-nums` to numeric report tables, reveal skip links on `:focus`, retain a visible `:focus-visible` indicator, and avoid opacity-based dimming of non-hovered content.
## 2026-08-05 - Avoid Dimming Non-Hovered Content
**Learning:** Applying `opacity: 0.5` to otherwise active chart and table rows can reduce the rendered text and control contrast below the intended accessible design target. The exact ratio depends on foreground, background, and compositing, so no formal WCAG conformance claim follows from the selector alone.
**Action:** Preserve the normal foreground and background colors of unrelated data rows during pointer hover; use a non-destructive highlight on the active row instead of dimming every peer.

## 2026-08-05 - Ensure Hidden Elements Reveal on Any Focus
**Learning:** `:focus` matches the element that actually has input focus, while `:focus-visible` depends on user-agent heuristics for when a focus indicator should be presented. A visually hidden skip link should therefore use `:focus` for reveal and may retain `:focus-visible` for an explicit focus treatment.
**Action:** Reveal hidden skip-navigation links on `:focus`, keep a strong visible outline, and cover the generated CSS with a regression test.
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,14 @@
- Criterion-level many-facet handoffs now use exact task revisions as the Rust estimator item axis while retaining aligned logical task and task-family labels for audit. Duplicate cells, support, resource bounds, respondent–item connectedness, item–rater connectedness, and response provenance are all revision-indexed; one revision cannot be rebound to a different logical task or family.
- Added an explicit, fail-closed schema-`1.0` request migration that verifies canonical content, fingerprint, public handle, and the authoritative engine-policy projection; requires a caller-supplied task revision; preserves normalized caller metadata; and intentionally does not migrate legacy observations or results. Content identity prevents accidental pooling but does not establish cross-revision comparability, which still requires anchors, invariance/DIF, drift, and recovery evidence.

### Fixed

#### Diagnostics-report focus and contrast preservation

- 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.

### Security

#### Descriptor-safe bounded JSON input for automation scripts
Expand Down
7 changes: 7 additions & 0 deletions docs/changelog.d/diagnostics-report-focus-contrast.md
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.
34 changes: 34 additions & 0 deletions docs/doctoring/diagnostics-report-focus-contrast.md
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/
9 changes: 1 addition & 8 deletions python/fast_mlsirm/report.py
Original file line number Diff line number Diff line change
Expand Up @@ -573,6 +573,7 @@ def _css() -> str:
font-weight: bold;
}

.skip-link:focus,
.skip-link:focus-visible {
top: 0;
outline: 3px solid var(--teal);
Expand Down Expand Up @@ -694,10 +695,6 @@ def _css() -> str:
margin-bottom: 16px;
}

.bar-chart:hover .bar-row:not(:hover) {
opacity: 0.5;
}

.bar-row {
display: grid;
grid-template-columns: minmax(104px, 180px) 1fr minmax(64px, auto);
Expand Down Expand Up @@ -830,10 +827,6 @@ def _css() -> str:
background: var(--hover-bg);
}

tbody:hover tr:not(:hover) {
opacity: 0.5;
}

.empty-state {
margin: 0;
padding: 14px;
Expand Down
45 changes: 45 additions & 0 deletions tests/test_report_focus_contrast.py
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

Comment thread
github-actions[bot] marked this conversation as resolved.
Resolved

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