Dark mode spike: token override approach for the playground

[twjeffery]

Summary

Initial spike exploring how dark mode could work with our V2 token architecture. Adds dark mode to the React PR playground so the team can see how components look and identify gaps.

This is the "CSS override" approach: a hand-authored dark theme file that overrides global and component tokens. It works well as a proof of concept, but the long-term version would involve integrating dark values into Style Dictionary (so they're generated alongside the light tokens), auditing component tokens for hardcoded hex values that break the cascade, and formalizing the surface token system as part of the published design-tokens package.

How to test

1. npm install (installs @abgov/design-tokens-v2)
2. npx nx serve react-prs
3. Click the moon/sun icon at the bottom of the side menu to toggle
4. Navigate to "Everything" to see all components in dark mode

How it works

• surface-tokens.css defines a two-layer elevation system (9 numbered scale tokens + 9 semantic tokens) with light defaults and dark overrides
• dark-theme.css overrides ~50 global color primitives + ~40 component tokens. The V2 outputReferences: true cascade handles most components automatically.
• dark-mode-overrides.css chains the imports in the right order (V2 tokens, surface tokens, dark theme)
• app.tsx adds a toggle in the side menu secondary content and respects system preference on first load

What this is

A spike to validate the approach, not a finished feature. Known gaps are documented. The main question for the team: does this approach feel right for how we'd ship dark mode?

Known gaps

• Some components have hardcoded values in shadow DOM that the CSS cascade can't reach (segmented tab indicator, form step hover, native dropdown chevron)
• Container interactive variant doesn't wire up its bg-color token (separate PR fix(#3847): Use missing container interactive bg-color token #3848)
• Menu action has no component tokens for hover bg
• textDark tokens serve double duty (text on colored surfaces vs text on page). Needs splitting long-term.

Refs #3849

[netlify]

✅ Deploy Preview for benji-docs-previews ready!

Name	Link
🔨 Latest commit	974da54
🔍 Latest deploy log	https://app.netlify.com/projects/benji-docs-previews/deploys/69e6c6bf86f0eb000836cc95
😎 Deploy Preview	https://deploy-preview-3850--benji-docs-previews.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[vanessatran-ddi]

It is very beautiful

Do you want to "host" dark theme css under design-tokens? Then ppl can use it as a beta testing if they want, and we can add to our docs site too.

Another question though: look like Alberta logo color is "invisible" during dark mode.

[twjeffery]

1. Do you want to "host" dark theme css under design-tokens? Then ppl can use it as a beta testing if they want, and we can add to our docs site too.

2. Another question though: look like Alberta logo color is "invisible" during dark mode.

@vanessatran-ddi

1. Yes, that's the plan. I added surface tokens that need team review first. The demo version also has dark-mode styles for its custom components that wouldn't apply to other teams, and some component tokens still need to land in design-tokens (feat(#3873): add work-side-menu-account-bg token design-tokens#154).

2. I opened feat(#3873): add dark mode theming with React context and Angular service #3874 to fix a few spots in the Svelte components so we can control all the styles with dark mode. The logo change is in there too.