diff --git a/.jules/palette.md b/.jules/palette.md index 0bbf5248..fc541e30 100644 --- a/.jules/palette.md +++ b/.jules/palette.md @@ -115,3 +115,6 @@ ## $(date +%Y-%m-%d) - Prevent accidental data loss in inline editors **Learning:** Forms that take a long time to fill out (like a WBS editor) are prone to accidental closure by users pressing `Escape` or clicking cancel. This causes immediate data loss without any warning, resulting in frustration. **Action:** When working on editors that can be dismissed, track whether the user has modified any fields compared to their initial state. If there are changes, intercept the close action and present a confirmation dialog (`window.confirm`) to ensure they really want to discard their edits. Bypass this for intentional saves or explicit data overrides. +## 2026-08-15 - Prefer persistent visible help for static metric explanations +**Learning:** A `title` fallback on static content is not reliably discoverable by sighted keyboard or touch users, and making an otherwise non-interactive card a synthetic tab stop solely to expose that tooltip adds navigation cost without adding an action. +**Action:** For short explanatory copy on static metric cards, prefer persistent visible text. Do not add `tabindex` or an ARIA role only to make help discoverable. If a genuinely supplemental popup is needed, implement and test an explicit tooltip or disclosure interaction with the appropriate accessible relationship instead of relying on `title` alone. diff --git a/docs/doctoring/metric-card-explanations-accessibility.md b/docs/doctoring/metric-card-explanations-accessibility.md new file mode 100644 index 00000000..4e2b0c9c --- /dev/null +++ b/docs/doctoring/metric-card-explanations-accessibility.md @@ -0,0 +1,43 @@ +# Metric-card explanatory text accessibility + +## Status + +Active PR evidence only. This record documents the bounded accessibility change on the contributor branch; it does not claim protected `develop` ships this behavior until the PR is integrated. + +## Buyer-visible problem + +The planner's three summary metric cards exposed calculation explanations only through HTML `title` attributes. That makes the explanation dependent on user-agent tooltip behavior and is not reliably discoverable by sighted keyboard or touch users. Making otherwise static summary cards synthetic tab stops solely to expose those tooltips adds navigation cost without adding an action. + +The new visible copy is normal-size text, so it also needs sufficient foreground/background contrast. The original light ends of the plan and actual gradients did not provide the WCAG 2.2 SC 1.4.3 minimum 4.5:1 contrast for the 12 px explanatory text. + +## Decision + +Keep the metric cards non-interactive and make each explanation persistent visible text inside its card. Do not add `tabindex="0"`, `role="note"`, or any `title` fallback to these static cards merely to surface help text. + +This follows the W3C Authoring Practices guidance to prefer visible text and avoid relying on browser fallback naming/description mechanisms. The APG specifically notes that `title` tooltips are not particularly discoverable and are not accessible to visual users who do not use a pointing device. WCAG 2.2 SC 1.4.13 governs author-controlled content that appears on hover or focus; persistent visible explanatory copy avoids introducing an additional hover/focus popup interaction entirely. + +For the two accent cards, keep the existing 92% white explanatory foreground but constrain the plan gradient to `#1e40af` → `#2563eb` and the actual gradient to `#065f46` → `#047857`. Browser acceptance coverage samples each rendered gradient and requires at least 4.5:1 contrast for the composited explanatory text, matching WCAG 2.2 SC 1.4.3 for normal text. + +If ScopeWeave later needs genuinely supplemental, non-persistent help, it should use an explicit interaction with a reviewed tooltip/disclosure contract rather than making unrelated static content focusable. WAI-ARIA 1.2 describes a tooltip as a contextual popup associated with an owning element, typically shown on hover or owner focus, and recommends linking it with `aria-describedby`. + +## TDD traceability + +The discoverability regression was committed before the production correction. `tests/e2e/metric-card-explanations.spec.js` requires all three explanations to be visibly rendered, rejects the synthetic `tabindex="0"` and `role="note"`, and rejects the presence of any `title` attribute on these cards rather than checking only one expected title value. The legacy metric-card assertions in `tests/e2e/scopeweave.spec.js` are aligned to the same visible `.meta-description` contract instead of retaining contradictory title-based expectations. The subsequent production correction in `index.html` replaces the tooltip-only contract with persistent `.meta-description` text. + +A separate RED contrast regression was added before the gradient correction. It reads the browser-computed description color and gradient stops, composites the alpha foreground over 21 samples across each gradient, and requires the minimum contrast to be at least 4.5:1. `styles.css` then darkens only the two gradient endpoints needed to satisfy that acceptance contract. + +Hosted exact-head browser/CI evidence is authoritative. A queued, pending, skipped, stale, predecessor-head, model-only, or otherwise non-terminal result is not promoted to passing evidence. + +## Rollback + +Rollback reverts the visible descriptions, accessible gradient endpoints, and their regressions together. There is no persisted-data, API, authentication, or schema migration impact. + +## References + +World Wide Web Consortium. (2023). *Web Content Accessibility Guidelines (WCAG) 2.2*. https://www.w3.org/TR/WCAG22/ + +World Wide Web Consortium, Web Accessibility Initiative. (2026). *Understanding Success Criterion 1.4.13: Content on hover or focus*. https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus.html + +World Wide Web Consortium, Web Accessibility Initiative. (n.d.). *Providing accessible names and descriptions*. WAI-ARIA Authoring Practices Guide. Retrieved August 15, 2026, from https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/ + +World Wide Web Consortium. (2023). *Accessible Rich Internet Applications (WAI-ARIA) 1.2*. https://www.w3.org/TR/wai-aria-1.2/ diff --git a/index.html b/index.html index d24b2a88..a4aeca9b 100644 --- a/index.html +++ b/index.html @@ -29,20 +29,23 @@