feat(theme): add system color mode to the theme toggle

[thetaPC]

Issue URL: internal

What is the current behavior?

The theme toggle only offers light and dark. Docusaurus 3.10 already ships a third system option, but two things hid it:

• respectPrefersColorScheme was never enabled, so the toggle stayed two-state
• _theme-toggle.scss painted an opaque ::before over the button and drew our own icons with ::after, so upstream's icons (including the system one) could never show

That stylesheet also keyed the icons on data-theme, the effective color, rather than data-theme-choice, the chosen mode. Light mode rendered a moon.

What is the new behavior?

• The toggle cycles system, light, dark, and new visitors default to their OS preference
• The brand sun and moon now come from swizzled Icon/LightMode and Icon/DarkMode rather than CSS pseudo-elements
• Icon/SystemColorMode is left untouched, so the system state uses upstream's half-filled circle
• All 52 lines of _theme-toggle.scss are gone

Most of that stylesheet was already dead: [class^='toggleTrack'] and input[type='checkbox'] target a toggle Docusaurus no longer renders. Upstream's own stylesheet supplies the sizing, centering, and state switching, so nothing needed replacing.

Does this introduce a breaking change?

• Yes
• No

Other information

Two intentional visual changes worth a look in the preview:

• The icons are swapped relative to before. Light now shows the sun and dark the moon, following Docusaurus's convention and matching what the system icon already did.
• Removing the ::before mask exposes upstream's hover background on the toggle.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ionic-docs	Ready	Preview	Aug 27, 2026 9:54pm