[FEAT] Add optional light mode

[matt-cossins]

Before submitting a pull request for a new Learning Path, please review Create a Learning Path

• I have reviewed Create a Learning Path

Please do not include any confidential information in your contribution. This includes confidential microarchitecture details and unannounced product information.

• I have checked my contribution for confidential information

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the Creative Commons Attribution 4.0 International License.

---

@zachlasiuk @pareenaverma
Appreciate there may be more complexities / other factors to consider - so might not be so simple, but I've taken a stab over lunch at drafting an optional light-mode aligned with the new branding changes, and it came together pretty quickly. Please let me know if this could be workable.

Summary

Add an optional light mode to Arm Learning Paths using the new purple theme.

Dark mode remains the default. Readers can select light mode using an accessible theme toggle, and the browser remembers that preference across Learning Path pages and future visits.

Visual changes

Light mode adds appropriate styling for:

• Homepage headings and category cards
• Learning Path and install guide content
• List pages, filters, and sorting controls
• Content navigation and tabs
• Tables and inline code
• Notices and callouts
• Featured Learning Path labels
• ADS cards and buttons
• Mobile content navigation

The implementation uses the existing refreshed accent tokens:

• Primary violet: #6023DE
• Secondary lilac: #D1BAFC

Additional refinements include:

• A darker purple FEATURED label on light-mode (for visibility)
• Darker purple notice backgrounds and borders on light-mode (for visibility)
• Dark code blocks in both modes

Theme behavior

The selection order is:

1. An explicitly stored light preference
2. An explicitly stored dark preference
3. Dark mode when no preference exists

The operating-system color preference is not used.

The preference is stored in the browser and does not depend on an Arm account or authentication.

Implementation

Theme behavior is owned by a single theme-preference.js controller.

The controller:

• Applies the selected theme before page CSS renders
• Updates the accessible toggle state
• Stores an explicit reader preference
• Handles unavailable or restricted browser storage
• Reapplies the theme after global navigation hydration
• Synchronizes changes between browser tabs
• Emits a learn-theme-change event

Theme manipulation has been removed from the authentication and general preference scripts.

The toggle is hidden when JavaScript is unavailable, leaving the site in its default dark mode without presenting an inactive control.

Tests

Run:

node --test tools/tests/theme-preference.test.mjs

The seven tests cover:

• Dark default behavior
• Stored light preference
• Stored dark preference
• Toggle state and persistence
• Restricted browser storage
• Global navigation hydration
• Cross-tab synchronization

Light mode:

Dark mode:

Dark code blocks remain for both:

[matt-cossins]

Aligned with the Arm light-blue light-mode styling (CSS details pulled from support site) and removed custom toggle button in favour of aligning with developer and support lightbulb buttons.

• Defaults to dark mode when no preference exists.
• Stores an explicit light or dark preference in browser storage.
• Restores that preference across pages and future visits.
• Handles unavailable or restricted browser storage.
• Synchronizes theme changes between browser tabs.
• Updates the global navigation and footer themes.
• Does not use the operating-system color preference.
• Does not depend on authentication or an Arm account.
• Theme behavior is centralized in theme-preference.js rather than being split between authentication and general preference scripts.

Without JavaScript, the site remains in its existing default dark mode and does not present a non-functional local theme control.

The DevHub bundle already contains the native theme control and emits the arm-theme event expected by the Learning Paths theme controller. However, the control is currently hidden by this configuration:
"enableThemeMode": false
Can we change this to enable it?

- "enableThemeMode": false
+ "enableThemeMode": true

Until the control is enabled, light mode can be tested from the browser console:
document.dispatchEvent(new CustomEvent('arm-theme', { detail: true }));
Use detail: false to switch back to dark mode.

Lights-up on hover:

cc. @pareenaverma @zachlasiuk