Prevent learner dashboard metric help text from overflowing mobile viewport

[alexeygrigorev]

Problem

The integrated accessibility registry reaches 29/30 states, then fails the real signed-in learner dashboard at the 390px viewport. span#enrolled-definition.metric-help-text is centered on its trigger with a max-content width; its right edge reaches approximately x=413 and increases document width by 23 CSS pixels.

This is a real responsive defect on /courses/<family>/<cohort>/dashboard, not a registry exception. The help content must remain available and the overflow assertion must remain strict.

Authority

• _docs/design/design-system.md — the dashboard is an ordinary content page using the shared narrow shell, design tokens, theme behavior, and visible focus treatment.
• _docs/specs/04-courses-and-cohorts.md — learner dashboard/cohort route ownership.
• _docs/specs/10-verification-strategy.md — accessibility, keyboard, zoom/reflow, responsive browser, and maintained-gate requirements.
• _docs/PROCESS.md — template work requires desktop/mobile screenshots and the full applicable browser tier.

Scope

• Repair the metric-help-text geometry in courses/templates/courses/dashboard.html so the enrolled-definition tooltip cannot enlarge or leave the viewport at narrow widths.
• Cover both dashboard branches that render the metric row: before the first homework is scored (two tiles) and after scoring begins (four tiles).
• Preserve the tooltip's text, aria-describedby relationship, tooltip semantics, keyboard focus behavior, and dark/light token usage.
• Add focused browser regression coverage for document and tooltip bounds at 390px and 320px, including the tooltip-hidden and keyboard-visible states.
• Retain the established desktop metric presentation and ordinary narrow dashboard shell.

Non-goals

• Redesigning the learner dashboard, changing metrics/count calculations or copy, or changing dashboard routes/authentication.
• Changing /courses catalogue/card target sizes addressed by Recompose the lower /courses journey around project-based learning #417.
• Hiding or truncating the definition, removing the help control, disabling focus, or using global overflow-x: hidden/clipping to conceal the defect.
• Weakening, skipping, quarantining, or adding an exception for learner.dashboard in the accessibility registry.
• Broad changes to shared cards, stat tiles, or other public pages unless a narrowly demonstrated shared primitive defect requires them and regression coverage is added.

Dependencies and blocked work

• No open implementation dependency. Repair accessibility registry after Event identity migration #426 exposed this defect by repairing the integrated accessibility harness; it is historical/test-baseline context, not an interface prerequisite for the CSS repair.
• This issue blocks completion evidence for Repair accessibility registry after Event identity migration #426 and full browser evidence for template candidates such as Canonicalize and improve docs navigation and brand-asset previews #420/Make current-course lessons and homework a coherent reading flow #425. After this fix lands, those candidates must rebase/freeze and rerun their graph-selected gates; prior selective evidence does not waive the failing registry state.

Acceptance criteria

• At 390×844 and 320×800, document.documentElement.scrollWidth and document.body.scrollWidth are no more than one CSS pixel wider than the viewport before, during, and after keyboard exposure of the enrolled definition.
• When visible, #enrolled-definition stays fully inside the viewport/content gutter (left >= 0, right <= viewport width, allowing the same one-pixel rounding tolerance), wraps into readable lines, and is neither clipped, truncated, nor horizontally scrollable.
• The pre-score two-tile state and scored four-tile state both satisfy the narrow-width contract with representative short and large metric values.
• The ? control remains a native keyboard-focusable button with a visible focus indicator; Tab focus reveals the definition, and moving focus away hides it without trapping focus.
• The definition remains associated through aria-describedby="enrolled-definition", has one unique ID in the rendered branch, retains role="tooltip", and keeps the existing truthful copy.
• With JavaScript disabled, the server-rendered dashboard and CSS-only focus/hover disclosure remain usable and within bounds; no script is required to read the definition.
• Light and dark themes pass at 390px and 320px with legible definition text/border/focus treatment and no horizontal overflow.
• At 768px and 1440×900, the metric row remains aligned, the tooltip is readable and visually anchored to its control, and the dashboard remains on the ordinary narrow content shell.
• No global overflow suppression, registry exception, test skip/quarantine, content hiding, or unrelated dashboard redesign is introduced.
• Focused Django dashboard tests, the focused browser regression, and the complete integrated accessibility registry pass; the graph-selected full Playwright tier also passes.

Browser scenarios

1. Sign in as the deterministic learner and open a cohort dashboard before the first homework is scored. At 390×844 and 320×800 in light and dark themes, record page width, Tab to “What enrolled means,” assert the tooltip is visible and in bounds, Tab away, and assert the page never overflows.
2. Repeat for the scored dashboard containing all four headline metric tiles, including representative large values that exercise wrapping/alignment.
3. Repeat the mobile focus scenario in a JavaScript-disabled context; the definition remains accessible through CSS focus behavior and the server page remains complete.
4. At 768px and 1440×900, inspect the metric row and focused tooltip in both themes for alignment, anchoring, focus visibility, and absence of regression.
5. Run the complete accessibility registry and verify learner.dashboard passes with its original strict structure/overflow checks and no exception.

The independent tester stores and inspects light/dark screenshots for the focused tooltip at 1440, 768, 390, and 320 under .tmp/screenshots/, and confirms they show the intended authenticated dashboard rather than an error/debug/login page. Screenshots and logs must contain only synthetic user data.

[alexeygrigorev]

Grooming Complete

The 23px learner-dashboard overflow is specified as a real viewport-geometry defect. Acceptance covers both dashboard metric branches, hidden/focused tooltip bounds at 390px and 320px, light/dark, keyboard and no-JS behavior, desktop/tablet regression, strict full accessibility-registry evidence, and inspected screenshots. Global clipping, content removal, and registry exceptions are explicit non-goals.

No open dependency. #426 is historical harness context; affected candidates rerun after this P0 baseline repair.

[alexeygrigorev]

Engineer handoff — implementation complete, isolated candidate frozen

Worktree: /home/alexey/git/dtc-website/.tmp/worktrees/issue-428-dashboard
Base/head commit: 28f6395a6357290d23bf5bfab16b0b3de2a3f0f1
Uncommitted owned files only:

• courses/templates/courses/dashboard.html
• playwright_tests/test_dashboard_metric_help.py

Implementation

• Keeps the existing centered desktop tooltip anchor.
• At widths below 40rem, inline-end-aligns the tooltip to the help control and gives it a viewport-bounded 16rem width.
• Adds border-box sizing and emergency wrapping; does not clip, truncate, suppress overflow globally, hide content, change copy, or require JavaScript.
• Preserves the native button, visible 3px focus indicator, aria-describedby, unique tooltip ID, role and CSS-only focus/hover disclosure.
• Adds real-browser coverage for both two-tile and four-tile branches, 390×844 and 320×800, hidden/focused/blurred states, light/dark, no-JS, representative large metric values, and 768/1440 desktop anchoring.

Focused evidence

• env -u DTC_SQLITE_PATH DJANGO_SETTINGS_MODULE=website.settings.test uv run --frozen pytest -q courses/tests/test_dashboard.py courses/tests/test_dashboard_access.py courses/tests/test_content_page_shell.py
  • 12 passed, 22 subtests passed.
• env -u DTC_SQLITE_PATH DJANGO_SETTINGS_MODULE=website.settings.test DJANGO_ALLOW_ASYNC_UNSAFE=true uv run --frozen pytest -q playwright_tests/test_dashboard_metric_help.py
  • 16 passed.
• uv run --frozen ruff check playwright_tests/test_dashboard_metric_help.py
  • green.
• git diff --check
  • green.

Screenshots are under .tmp/screenshots/issue-428/: all sixteen state/theme/viewport captures plus inspected mobile-montage.png and desktop-montage.png. Inspection confirms the authenticated dashboard, fully visible wrapped tooltip, visible focus ring, both metric branches, both themes, and no error/login/debug page.

Exact #426 integration evidence

Disposable combined candidate: /home/alexey/git/dtc-website/.tmp/worktrees/issue-428-combined.

The #426 patch was copied exactly from its frozen owner worktree without changing that worktree or taking ownership:

• tracked dependency diff SHA-256: c506751ed3f5974df58efc70bd868d2864aa71120c0d6834aca507f32f59f600
• untracked dependency test SHA-256: 3d49a72894969648cf22b2bdde6e48a1165d1ce98d7b33ac63fb8ab6af0ca99b
• Prevent learner dashboard metric help text from overflowing mobile viewport #428 dashboard diff SHA-256 matched isolated and combined: 2b45680061cccea93bfc3b02b3a72d0bc5d54781206c2d33dd67bf301b26454a
• Prevent learner dashboard metric help text from overflowing mobile viewport #428 browser test SHA-256 matched isolated and combined: 43fe2c06fb8146b01a63a78ca5cbb71adb497939b923a13021fdc79190f33aef

env -u DTC_SQLITE_PATH uv run --frozen python scripts/ci.py test-accessibility ran the complete 30-test accessibility target. Result: 28 passed, 2 failed in 1323.32s. Both complete-registry desktop and the mobile registry path through learner.dashboard passed; the two failures are the same unrelated public.courses-hub 390px target-size failure on three course title anchors from #417, whose repair is not present on base 28f6395a. No learner-dashboard failure remains. This is a baseline/integration blocker, not an exception or skip.

Selective plan

Plan: .tmp/verification/verification-plan.json
Plan SHA-256: 114da6852f449e9631856d263effb3cf70d59c4ff6525eb6c7864ec72b6fb89e
Graph SHA-256: 8e961161a3862302b27538c12adb5bb8370716487038024cf1738e08b30db91e, policy 5.
Source tree OID: a9462cbe49c5918d42e91bd71a5c5952d512cd8c.
Profile/reason: full / render_impact; browser profile full.

All components are rerun: container, Django, evidence validation, Playwright, quality, screenshots and selector. No component is claimed reused, skipped or not applicable. Focused engineering evidence above is complete; graph-selected full Playwright, full Django, quality/container/control-plane evidence and the independent screenshot gate remain pending for the independent tester after integration with the accepted #417 and exact #426 baselines.

No commit or push was made.