fix(web): remove the theme setting and force every install back to light (#6168)

Product removed theme selection: the workspace surfaces shipped for team
workspaces have no dark tokens, so dark mode renders a broken app.

Deleting the picker is not sufficient on its own. Every install that ever
opened it still has `theme: 'dark'` — or `'system'`, which resolves dark on a
dark OS — persisted in localStorage, and a stored value does not move when the
default does. So the theme is now coerced on READ, at all three points a
persisted value can reach the document:

- `loadConfig()` funnels `parsed.theme` through `resolveAppTheme()` and marks
  the config migrated so the coerced value is written back once.
- `applyAppearanceToDocument()` stamps `data-theme="light"` unconditionally.
  The attribute must be PRESENT, not merely non-dark: every dark CSS rule is
  gated on `html:not([data-theme])` / `html:not([data-theme="light"])`, and
  every JS theme reader (shiki, ConnectorLogo, SketchEditor, TerminalViewer,
  connectorBrandColor, MentionNode) falls back to `prefers-color-scheme` only
  when the attribute is absent.
- The pre-hydration inline script in `app/layout.tsx` stamps light before React
  mounts, outside its try/catch so a throwing storage read still leaves the
  attribute set.

Electron's `themeSource` defaults to `system`, which colours everything the web
layer does not own (macOS vibrancy glass, native menus/dialogs) on a dark-mode
Mac — including the splash, before the renderer's appearance IPC lands. It is
now pinned to light before the first window exists.

Removed surfaces:

- `AppearanceSection` in SettingsDialog, orphaned by #6156 (zero call sites),
  together with its `settings-general-block--appearance` styles. Its docblock
  claimed the control was "deliberately kept … NON-ALIGNMENT #9"; that decision
  is superseded, so the comment goes with the code.
- The onboarding welcome page's sun/moon toggle — the last reachable theme
  writer — and the `onThemeChange` prop chain behind it
  (App → EntryView/ProjectView → EntryShell → OnboardingView).
- The orphaned theme row in EntrySettingsMenu and its styles.
- i18n keys `settings.appearance`, `settings.appearanceHint`,
  `settings.themeSystem`, `settings.themeLight`, `settings.themeDark` across
  `types.ts` and all 19 locales.
- Analytics `trackSettingsAppearanceClick`, `SettingsAppearanceClickProps`, and
  the `settings_popover` `appearance` element.

`'appearance'` survives only as a legacy settings deep-link token that
`normalizeSettingsSection` folds into General, so an old link is not a type
error.

Red-first: tests/state/force-light-theme.test.ts and
tests/components/theme-settings-removed.test.tsx were written against the
unmodified branch and went red (11 failing) before any source change.

Author: lefarcen

apps/desktop/src/main/runtime.ts

@@ -1468,6 +1468,22 @@ export type SplashWindowHandle = {
   window: BrowserWindow;
 };
 
+/**
+ * Pin Electron's native appearance to light.
+ *
+ * The app has one theme now, so `themeSource` is not a preference to sync — it
+ * is a constant. Leaving it at Electron's `system` default lets a dark-mode OS
+ * colour everything the web layer does not own: the macOS vibrancy glass
+ * (`vibrancy: "under-window"`), native menus and dialogs, and the renderer's
+ * own `prefers-color-scheme` before `data-theme` is stamped.
+ *
+ * Idempotent, so both the splash path and the `od:appearance:set-theme` handler
+ * can call it.
+ */
+export function pinNativeAppearanceToLight(): void {
+  nativeTheme.themeSource = "light";
+}
+
 /**
  * Create and immediately show the light brand-splash window. The packaged entry
  * calls this BEFORE awaiting the daemon/web sidecars so the animation masks the
@@ -1477,6 +1493,12 @@ export type SplashWindowHandle = {
  * + matching size so the reveal swap reads as a single window, never a flash.
  */
 export function createSplashWindow(): SplashWindowHandle {
+  // Open Design ships light-only (the theme setting was removed), so pin the
+  // native appearance before the first window exists. Electron defaults
+  // `themeSource` to `system`, which paints the macOS vibrancy glass and the
+  // native chrome dark on a dark-mode Mac — visible on the splash and again in
+  // the gap before the renderer's `od:appearance:set-theme` lands.
+  pinNativeAppearanceToLight();
   // Stamp creation time at the instant the window appears (see SplashWindowHandle).
   const startedAt = Date.now();
   const splash = new BrowserWindow({
@@ -2520,10 +2542,11 @@ export async function createDesktopRuntime(options: DesktopRuntimeOptions): Prom
     if (theme !== "light" && theme !== "dark" && theme !== "system") return;
     // Pin the native appearance to the app theme. The macOS frosted window
     // (vibrancy: under-window) draws its glass in the SYSTEM appearance by
-    // default, so an explicitly light app over a dark OS sat on dark glass
-    // and read as a muddy gray (#94); forcing the native theme keeps the
-    // glass material in step with the app's tokens. `system` restores
-    // following the OS for the follow-system theme setting.
+    // default, so a light app over a dark OS sat on dark glass and read as a
+    // muddy gray (#94); forcing the native theme keeps the glass material in
+    // step with the app's tokens. The host protocol still carries all three
+    // values as generic infrastructure, but the app ships light-only, so this
+    // is the same value `pinNativeAppearanceToLight` already set at startup.
     nativeTheme.themeSource = theme;
   });
 

apps/web/app/layout.tsx

@@ -19,14 +19,18 @@ export const viewport: Viewport = {
 };
 
 /**
- * Inline script that runs before React hydrates to apply the saved theme
- * preference without a flash of unstyled content. It reads the same
- * localStorage key used by `state/config.ts` and sets `data-theme` on
- * `<html>` immediately — before any CSS or React paint.
+ * Inline script that runs before React hydrates so the first paint already
+ * carries the app's appearance — no flash of unstyled content.
+ *
+ * `data-theme` is pinned to `light` unconditionally, and deliberately OUTSIDE
+ * the try/catch: Open Design ships light-only (product removed the theme
+ * setting), and a stored `dark` / `system` from the old picker must never reach
+ * the document. Every dark CSS rule is gated on the attribute being absent, so
+ * a storage read that throws must still leave the attribute stamped.
  * Keep the accent variable mix ratios in sync with `accentVars()` in
  * `src/state/appearance.ts`; this script cannot import application modules.
  */
-const themeInitScript = `(function(){try{var c=JSON.parse(localStorage.getItem('open-design:config')||'{}');var t=c.theme;if(t==='light'||t==='dark')document.documentElement.setAttribute('data-theme',t);var a=typeof c.accentColor==='string'&&/^#[0-9a-fA-F]{6}$/.test(c.accentColor.trim())?c.accentColor.trim().toLowerCase():'#353535';if(c.configMigrationVersion!==3&&(a==='#87ea5c'||a==='#c96442'))a='#353535';var s=document.documentElement.style;s.setProperty('--accent',a);s.setProperty('--accent-strong','color-mix(in srgb, '+a+' 82%, var(--text-strong))');s.setProperty('--accent-soft','color-mix(in srgb, '+a+' 12%, var(--bg-subtle))');s.setProperty('--accent-tint','color-mix(in srgb, '+a+' 6%, var(--bg-panel))');s.setProperty('--accent-hover','color-mix(in srgb, '+a+' 86%, var(--text-strong))');}catch(e){}})();`;
+const themeInitScript = `(function(){document.documentElement.setAttribute('data-theme','light');try{var c=JSON.parse(localStorage.getItem('open-design:config')||'{}');var a=typeof c.accentColor==='string'&&/^#[0-9a-fA-F]{6}$/.test(c.accentColor.trim())?c.accentColor.trim().toLowerCase():'#353535';if(c.configMigrationVersion!==3&&(a==='#87ea5c'||a==='#c96442'))a='#353535';var s=document.documentElement.style;s.setProperty('--accent',a);s.setProperty('--accent-strong','color-mix(in srgb, '+a+' 82%, var(--text-strong))');s.setProperty('--accent-soft','color-mix(in srgb, '+a+' 12%, var(--bg-subtle))');s.setProperty('--accent-tint','color-mix(in srgb, '+a+' 6%, var(--bg-panel))');s.setProperty('--accent-hover','color-mix(in srgb, '+a+' 86%, var(--text-strong))');}catch(e){}})();`;
 
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (

apps/web/src/App.tsx

@@ -1171,16 +1171,14 @@ function AppInner() {
     agents,
   ]);
 
-  // Sync theme preference to the <html> element so CSS variables pick it up.
-  // useLayoutEffect (vs useEffect) fires before the browser paints, so a
-  // live theme switch in Settings applies atomically — no 1-frame flash of
-  // the old theme. Safe here because the component tree is ssr:false.
+  // Stamp the app appearance onto the <html> element so CSS variables pick it
+  // up. The theme itself is a constant (light-only), but the accent still comes
+  // from config, and the stamp must be re-applied whenever that changes.
+  // useLayoutEffect (vs useEffect) fires before the browser paints, so no
+  // 1-frame flash. Safe here because the component tree is ssr:false.
   useLayoutEffect(() => {
-    applyAppearanceToDocument({
-      theme: config.theme ?? 'system',
-      accentColor: config.accentColor,
-    });
-  }, [config.theme, config.accentColor]);
+    applyAppearanceToDocument({ accentColor: config.accentColor });
+  }, [config.accentColor]);
 
   // Tell the daemon what the user is currently looking at, so the MCP
   // server can surface it as `get_active_context` to a coding agent in
@@ -1836,32 +1834,6 @@ function AppInner() {
     [],
   );
 
-  // Quick theme switch from the settings dropdown in the entry view.
-  // Skips the full SettingsDialog round-trip so the appearance flip
-  // feels instantaneous; the live preview comes for free because the
-  // `useLayoutEffect` above re-runs `applyAppearanceToDocument` the
-  // moment `config.theme` changes. We still persist to localStorage
-  // and the daemon so the choice survives reloads.
-  const handleThemeChange = useCallback(
-    (theme: AppConfig['theme']) => {
-      const current = latestPersistedConfigRef.current;
-      const next = { ...current, theme };
-      latestPersistedConfigRef.current = next;
-      // Apply to the DOM synchronously inside the click handler so the theme
-      // flips instantly. Otherwise the visible switch waits on the (heavier)
-      // React re-render of the whole tree before the layout effect re-applies
-      // it — which reads as a perceptible lag after the click.
-      applyAppearanceToDocument({
-        theme: theme ?? 'system',
-        accentColor: current.accentColor,
-      });
-      saveConfig(next);
-      void syncConfigToDaemon(next);
-      setConfig(next);
-    },
-    [],
-  );
-
   const handleAgentChange = useCallback(
     (agentId: string) => {
       const next = { ...latestPersistedConfigRef.current, agentId };
@@ -3384,7 +3356,6 @@ function AppInner() {
         onAgentModelChange={handleAgentModelChange}
         onApiModelChange={handleApiModelChange}
         onRefreshAgents={refreshAgents}
-        onThemeChange={handleThemeChange}
         onOpenSettings={openSettings}
         onOpenAmrSettings={openAmrSettings}
         onOpenMcpSettings={openMcpSettings}
@@ -3434,7 +3405,6 @@ function AppInner() {
         onSkillsRefresh={refreshSkills}
         onSkillsChanged={handleSkillsChanged}
         onRefreshAgents={refreshAgents}
-        onThemeChange={handleThemeChange}
         skillsLoading={skillsLoading}
         designSystemsLoading={dsLoading}
         projectsLoading={projectsLoading}

apps/web/src/analytics/events.ts

@@ -110,7 +110,6 @@ import type {
   SettingsMediaProvidersClickProps,
   SettingsConnectorsClickProps,
   SettingsLanguageClickProps,
-  SettingsAppearanceClickProps,
   SettingsNotificationsClickProps,
   SettingsPetsClickProps,
   SettingsPrivacyClickProps,
@@ -904,13 +903,6 @@ export function trackSettingsLanguageClick(
   send(track, 'ui_click', props);
 }
 
-export function trackSettingsAppearanceClick(
-  track: Track,
-  props: SettingsAppearanceClickProps,
-): void {
-  send(track, 'ui_click', props);
-}
-
 export function trackSettingsNotificationsClick(
   track: Track,
   props: SettingsNotificationsClickProps,

apps/web/src/components/EntrySettingsMenu.tsx

@@ -23,7 +23,7 @@ import {
   trackSettingsPopoverSurfaceView,
 } from '../analytics/events';
 import { createSocialSharePayload } from '../providers/registry';
-import type { AppConfig, AppTheme } from '../types';
+import type { AppConfig } from '../types';
 import { formatDiscordPresenceCount, useDiscordPresence } from './useDiscordPresence';
 import { Icon } from './Icon';
 import { SocialShareGrid } from './SocialShareGrid';
@@ -46,6 +46,9 @@ export type EntrySettingsSection =
   | 'integrations'
   | 'mcpClient'
   | 'language'
+  // Legacy deep-link token: the theme setting is gone (the app ships
+  // light-only) and SettingsDialog folds this into General, but the token stays
+  // accepted so an old link does not become a type error at the call site.
   | 'appearance'
   | 'notifications'
   | 'pet'
@@ -55,19 +58,8 @@ export type EntrySettingsSection =
   | 'memory'
   | 'designSystems';
 
-const ENTRY_THEME_OPTIONS: Array<{
-  value: AppTheme;
-  icon: 'sun-moon' | 'sun' | 'moon';
-  labelKey: 'settings.themeSystem' | 'settings.themeLight' | 'settings.themeDark';
-}> = [
-  { value: 'system', icon: 'sun-moon', labelKey: 'settings.themeSystem' },
-  { value: 'light', icon: 'sun', labelKey: 'settings.themeLight' },
-  { value: 'dark', icon: 'moon', labelKey: 'settings.themeDark' },
-];
-
 interface Props {
   config: AppConfig;
-  onThemeChange: (theme: AppTheme) => void;
   onOpenSettings: (section?: EntrySettingsSection) => void;
   // Fired when the gear trigger is clicked. Used by the in-project header to
   // emit the `artifact_header` / `settings` ui_click; the home/entry shell
@@ -80,7 +72,6 @@ interface Props {
 
 export function EntrySettingsMenu({
   config,
-  onThemeChange,
   onOpenSettings,
   onTrackTriggerClick,
   trackingPageName,
@@ -96,7 +87,6 @@ export function EntrySettingsMenu({
   const wrapRef = useRef<HTMLDivElement | null>(null);
   const triggerRef = useRef<HTMLButtonElement | null>(null);
   const langListRef = useRef<HTMLDivElement | null>(null);
-  const activeTheme = config.theme ?? 'system';
   const discordOnlineLabel = discordPresence
     ? t('entry.discordOnlineLabel', {
         count: formatDiscordPresenceCount(discordPresence.onlineCount),
@@ -155,7 +145,7 @@ export function EntrySettingsMenu({
   }, [open]);
 
   // surface_view — fire once each time the settings popover opens so the
-  // share / language / appearance funnels have a denominator.
+  // share / language funnels have a denominator.
   useEffect(() => {
     if (!open) return;
     trackSettingsPopoverSurfaceView(analytics.track, {
@@ -285,42 +275,6 @@ export function EntrySettingsMenu({
             </div>
           </section>
 
-          <section className="entry-settings-menu__section">
-            <div className="entry-settings-menu__section-title">
-              <Icon name="palette" size={14} />
-              <span>{t('settings.appearance')}</span>
-            </div>
-            <div className="entry-settings-menu__theme-row">
-              {ENTRY_THEME_OPTIONS.map((option) => {
-                const active = activeTheme === option.value;
-                return (
-                  <button
-                    key={option.value}
-                    type="button"
-                    role="menuitemradio"
-                    aria-checked={active}
-                    className={`entry-settings-menu__theme${
-                      active ? ' is-active' : ''
-                    }`}
-                    onClick={() => {
-                      trackSettingsPopoverClick(analytics.track, {
-                        page_name: pageName,
-                        area: 'settings_popover',
-                        element: 'appearance',
-                        value: option.value,
-                      });
-                      onThemeChange(option.value);
-                      setOpen(false);
-                    }}
-                  >
-                    <Icon name={option.icon} size={14} />
-                    <span>{t(option.labelKey)}</span>
-                  </button>
-                );
-              })}
-            </div>
-          </section>
-
           <section className="entry-settings-menu__section">
             <div className="entry-settings-menu__section-title">
               <Icon name="external-link" size={14} />

apps/web/src/components/EntryShell.tsx

@@ -78,7 +78,6 @@ import type {
   ApiProtocol,
   ApiProtocolConfig,
   AppConfig,
-  AppTheme,
   ConnectionTestResponse,
   DesignSystemSummary,
   ExecMode,
@@ -433,10 +432,6 @@ interface Props {
   onSkillsRefresh?: () => Promise<void> | void;
   onSkillsChanged?: (affectedSkillId?: string) => void;
   onRefreshAgents: () => Promise<AgentInfo[]> | AgentInfo[];
-  // Quick theme switch from the avatar-popover dropdown. Lets the user
-  // flip between system / light / dark without opening the full Settings
-  // dialog. App owns persistence; this component just calls the callback.
-  onThemeChange: (theme: AppTheme) => void;
   onCreateProject: (input: EntryCreateProjectInput) => Promise<boolean> | boolean | void;
   onCreatePluginShareProject: (
     pluginId: string,
@@ -573,7 +568,6 @@ export function EntryShell({
   onSkillsRefresh,
   onSkillsChanged,
   onRefreshAgents,
-  onThemeChange,
   onCreateProject,
   onCreatePluginShareProject,
   onImportClaudeDesign,
@@ -861,15 +855,6 @@ export function EntryShell({
     await open();
     return true;
   }
-  // Resolve the effective light/dark theme so the rail's account-menu theme toggle
-  // flips to the opposite of what's actually shown (system → resolved).
-  const activeTheme: AppTheme = config.theme ?? 'system';
-  const resolvedDark =
-    activeTheme === 'dark' ||
-    (activeTheme === 'system' &&
-      typeof window !== 'undefined' &&
-      typeof window.matchMedia === 'function' &&
-      window.matchMedia('(prefers-color-scheme: dark)').matches);
   // Workspace-only destinations. Personal and team workspaces both use these;
   // signed-out/local state falls back to home once the context has resolved.
   // `community` is allowed in both states, so it is not guarded.
@@ -1387,7 +1372,7 @@ export function EntryShell({
 
   // #5517 removes the entry top-bar settings cog: the nav-rail account menu owns
   // the settings entry (EntryNavRail onOpenSettings), so the top strip no longer
-  // carries a redundant one. Theme switching lives in 设置·通用 alone.
+  // carries a redundant one.
 
 
   if (view === 'onboarding') {
@@ -1409,7 +1394,6 @@ export function EntryShell({
             onConfigPersist={onConfigPersist}
             onRefreshAgents={onRefreshAgents}
             onFinish={finishOnboarding}
-            onThemeChange={onThemeChange}
             onGoBuild={() => {
               onCompleteOnboarding();
               refreshWorkspaceSurfacesAfterOnboarding();
@@ -1834,7 +1818,6 @@ function OnboardingView({
   onConfigPersist,
   onRefreshAgents,
   onFinish,
-  onThemeChange,
   onGoBuild,
 }: {
   config: AppConfig;
@@ -1856,7 +1839,6 @@ function OnboardingView({
   // `survey` is passed on the About-you completion paths (not on skip) so the
   // shell can build a personalized Home recommendation.
   onFinish: (survey?: { role: string; useCases: string[] }) => void;
-  onThemeChange: (theme: AppTheme) => void;
   onGoBuild: () => void;
 }) {
   const t = useT();
@@ -3108,16 +3090,8 @@ function OnboardingView({
 
   // Connect step, default face: a minimal, centered Open Design Cloud sign-in
   // landing. No stepper, no runtime cards — just the cloud CTA, a secondary
-  // link into the full runtime chooser, and a top-left language/theme bar.
+  // link into the full runtime chooser, and a top-left language bar.
   if (step === 0 && connectExpanded === null) {
-    const activeTheme: AppTheme = config.theme ?? 'system';
-    const resolvedDark =
-      activeTheme === 'dark' ||
-      (activeTheme === 'system' &&
-        typeof window !== 'undefined' &&
-        typeof window.matchMedia === 'function' &&
-        window.matchMedia('(prefers-color-scheme: dark)').matches);
-    const themeIcon: 'sun' | 'moon' = resolvedDark ? 'moon' : 'sun';
     const cloudBusy = amrLoginPending;
     const amrStatusResolving = !amrStatusResolved;
     return (
@@ -3127,15 +3101,6 @@ function OnboardingView({
       >
         <div className="onboarding-cloud__topbar">
           <LanguageMenu compact placement="down" align="end" />
-          <button
-            type="button"
-            className="onboarding-cloud__theme"
-            aria-label={resolvedDark ? t('settings.themeLight') : t('settings.themeDark')}
-            title={resolvedDark ? t('settings.themeLight') : t('settings.themeDark')}
-            onClick={() => onThemeChange(resolvedDark ? 'light' : 'dark')}
-          >
-            <Icon name={themeIcon} size={25} />
-          </button>
         </div>
         <div className="onboarding-cloud__center">
           <span