fix(ui): stop the theme switch repainting the page half in each theme

[BigSimmo]

Summary

• Switching Light <-> Dark left the app painted in two themes at once for roughly half a second: a light header band and light sidebar chrome over dark panels, with row headings still carrying the light-theme ink colour on a dark surface.

• Cause: the theme-transitioning block declared, with !important, a 200 ms colour transition on html.theme-transitioning and html.theme-transitioning * and both pseudo-element tiers, so every node in the document started a transition on the same frame.

• Measured in Chromium 1194 on the settings dialog at 1440x900, Light -> Dark, sampling every requestAnimationFrame:

   313ms cls=1 anims=1226 body=rgb(255,255,255) header=rgb(255,255,255) heading=rgb(10,18,32)
   859ms cls=0 anims=27   body=rgb(11,14,17)    header=rgb(38,44,50)    heading=rgb(251,252,253)
  

  1226 concurrently running animations, then 546 ms with no frame presented. The frame that survives that stall is the mixed-theme paint. The crossfade it was paying for never rendered either — sampled colours had already snapped to their dark end on the first frame after the click.

• The !important was the other half of the cost: it replaced every element's own transition-property for the whole window, so any transform/opacity animation in flight during a theme switch was dropped mid-run.

• Fix: the class now suppresses transitions instead of adding them. That is what this block's own prefers-reduced-motion branch already did for the identical selector, and reduced motion is the one path this was never reported from. The branch is removed because it is now the unconditional behaviour, so reduced-motion users see exactly what they saw before.

• Rejected alternative, recorded in the code comment: fading only the root. The ground then interpolated for the full 200 ms while every panel above it snapped, leaving a near-white page background behind dark chrome (body measured rgb(234,235,235) at 190 ms with the header already dark). A partial fade reads worse than no fade.

• After, same probe, two consecutive runs:

    62ms cls=1 anims=0 body=rgb(11,14,17) header=rgb(38,44,50) heading=rgb(251,252,253)
   104ms cls=1 anims=0 body=rgb(11,14,17) header=rgb(38,44,50) heading=rgb(251,252,253)
  

  Zero animations, every surface dark on the first frame sampled, frames presented every 17-65 ms. No mixed-theme frame exists.

• use-theme.ts is unchanged: the class and its 200 ms timer keep their behaviour and tests/theme-transition-timer.dom.test.tsx still passes as written.

• The 2026-08-02 CWV audit (RB-3) flagged this selector and judged it acceptable because it is user-triggered. The new comment records that judgement as wrong — being user-triggered is exactly what made it visible.

Verification

• npm run verify:pr-local — Verification not run: heavy scope selects build plus the full unit suite for a src/app/globals.css change; the CSS-scoped gates below were run individually instead and CI runs the aggregate.
• npm run check:design-system-contract exit 0 — Design-system contract passed (1232 production files; raw colors 0; literal shadows 0; legacy tap classes 0; sub-floor interactive min-heights 5; edge conflicts 5; 1px shadow spreads 0).
• npm run check:design-drift-ratchet exit 0 — both ceilings held.
• npx vitest run tests/theme-transition-timer.dom.test.tsx tests/mobile-chrome-paint-contract.test.ts tests/ui-overlay-css-contract.test.ts tests/clinical-dashboard-merge-artifacts.test.ts tests/design-token-contract.test.ts — Test Files 5 passed (5) / Tests 74 passed (74).
• npm run test — Test Files 3 failed | 1157 passed | 1 skipped (1161) / Tests 3 failed | 16995 passed. The three failures are clinical-hazard-controls, privacy-readiness-contract and rag-plan-package-parity; all three reproduce identically on a stashed clean tree, so they are pre-existing and unrelated to this diff.
• npm run test:focused -- --files src/app/globals.css — no test files selected (CSS is not in the Vitest import graph), which is why the contract suites above were run by name.
• npm run verify:ui — UI verification not run: npm run plan:browser selects level: full because src/app/globals.css is a shared foundation, and this container's Chromium is rev 1194 against the repo's pinned 1234 (feat(ui): compact phone bottom search bar on search/result views #255 drift), so a local run would not be the gate. Browser proof delegated to CI; please keep this PR out of draft so the Production UI job runs. Direct instrumented Chromium measurement of the changed behaviour is quoted above.

Risk and rollout

• Risk: Low, and confined to how a theme switch is painted. One CSS block in src/app/globals.css; no TypeScript, no component, no token value changed. The behaviour the block now produces for everyone is the behaviour prefers-reduced-motion users already had.
• Rollback: revert this commit. The block is self-contained.
• Provider or production effects: None.
• RAG impact: none.

Notes

• The two probe scripts used for the measurements were scratchpad-only and are not part of this diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mp72U91fKSqD6S12R9ijZd

---

Generated by Claude Code

---

Note

Low Risk
Single CSS block in globals.css; no token or TS changes, and reduced-motion users already had this paint behavior.

Overview
Fixes Light ↔ Dark painting the app in two themes at once (light header/sidebar over dark panels with mismatched text colors).

The html.theme-transitioning block no longer forces a 200ms !important color transition on every node (html, *, and pseudo-elements). That pattern spawned ~1200 concurrent animations, stalled frames, and produced a visible half-themed frame while the intended crossfade never actually rendered.

Change: while the class is on <html> (unchanged in use-theme.ts), CSS now applies transition: none !important on the same selectors so all surfaces flip in one frame. The old prefers-reduced-motion branch is removed because that suppression is now the default for everyone.

A long inline comment documents measured failure modes and warns against re-adding transitions here.

^{Reviewed by Cursor Bugbot for commit 3b337d4. Configure here.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 429ca0c1-7033-4ecf-ae30-66212dc705f5

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b5b075f7-84a6-4b84-800c-f518a21aca76)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_ff5745a9-ebe0-47dc-b78f-6d5482368962)