feat(webapp): swap the Black and White icons with the active theme

Replaces the placeholder circles with the supplied artwork, and picks between
them per active theme: the option matching the current end of the scale draws as
a ring so the background reads through it, the opposing one as a solid disc in
the foreground colour. Dark and Black show Black as a ring, Light and White show
White as a ring.

The appearance resolution joins the other theme resolution in
useSystemThemeSync, and defaults to dark before the effect runs so the first
client render agrees with the server's.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: samejr

apps/webapp/app/assets/icons/CircleFilledIcon.tsx

@@ -1,4 +1,5 @@
-/** Solid circle — the Black theme, whose surfaces are filled flat. */
+/** Solid circle. Paired with {@link CircleOutlineIcon} by the Black and White
+ *  theme options — the filled disc reads as the opposite of the active theme. */
 export function CircleFilledIcon({ className }: { className?: string }) {
   return (
     <svg

apps/webapp/app/assets/icons/CircleOutlineIcon.tsx

@@ -1,4 +1,5 @@
-/** Hollow circle — the White theme, the counterpart to {@link CircleFilledIcon}. */
+/** Hollow circle. Paired with {@link CircleFilledIcon} by the Black and White
+ *  theme options, which show the active theme's background through the ring. */
 export function CircleOutlineIcon({ className }: { className?: string }) {
   return (
     <svg
@@ -9,7 +10,7 @@ export function CircleOutlineIcon({ className }: { className?: string }) {
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
-      <circle cx="12" cy="12" r="9" stroke="currentColor" strokeWidth="2" />
+      <circle cx="12" cy="12" r="8" stroke="currentColor" strokeWidth="2" />
     </svg>
   );
 }

apps/webapp/app/components/themeOptions.ts

@@ -4,6 +4,7 @@ import { CircleFilledIcon } from "~/assets/icons/CircleFilledIcon";
 import { CircleOutlineIcon } from "~/assets/icons/CircleOutlineIcon";
 import { MoonIcon } from "~/assets/icons/MoonIcon";
 import { SunIcon } from "~/assets/icons/SunIcon";
+import { type ThemeAppearance } from "~/hooks/useSystemThemeSync";
 import { type ThemePreference } from "~/utils/themePreference";
 
 export type ThemeOption = {
@@ -22,10 +23,11 @@ export const THEME_OPTIONS: ThemeOption[] = [
 ];
 
 /** Dark and Light with their surfaces pinned flat, so grid lines carry the
- *  layout. Account page only, alongside Classic. */
+ *  layout. Account page only, alongside Classic. The icons here are the
+ *  dark-theme pair; `themeOptionIcon` swaps them per active theme. */
 const FLAT_OPTIONS: ThemeOption[] = [
-  { value: "black", label: "Black", icon: CircleFilledIcon },
-  { value: "white", label: "White", icon: CircleOutlineIcon },
+  { value: "black", label: "Black", icon: CircleOutlineIcon },
+  { value: "white", label: "White", icon: CircleFilledIcon },
 ];
 
 /** Legacy theme, offered on the account page only. */
@@ -41,3 +43,22 @@ export const ALL_THEME_OPTIONS: ThemeOption[] = [...THEME_OPTIONS, ...FLAT_OPTIO
 export const THEME_OPTIONS_BY_VALUE = Object.fromEntries(
   ALL_THEME_OPTIONS.map((option) => [option.value, option])
 ) as Record<ThemePreference, ThemeOption>;
+
+/**
+ * The icon to draw for an option under the active theme.
+ *
+ * Black and White show the active theme's background *through* the circle: the
+ * option matching the current end of the scale is a ring, so the background
+ * reads through it, and the opposing one is a solid disc in the foreground
+ * colour. On a dark theme that makes Black a ring and White a filled disc; on a
+ * light theme it flips. Every other option has one fixed icon.
+ */
+export function themeOptionIcon(option: ThemeOption, appearance: ThemeAppearance) {
+  if (option.value === "black") {
+    return appearance === "dark" ? CircleOutlineIcon : CircleFilledIcon;
+  }
+  if (option.value === "white") {
+    return appearance === "light" ? CircleOutlineIcon : CircleFilledIcon;
+  }
+  return option.icon;
+}

apps/webapp/app/hooks/useSystemThemeSync.ts

@@ -1,6 +1,39 @@
-import { useEffect } from "react";
+import { useEffect, useState } from "react";
 import { type ThemePreference } from "~/utils/themePreference";
 
+/** Which end of the scale a theme sits on. Classic and Black are dark; White is
+ *  light; `system` follows the OS. */
+export type ThemeAppearance = "dark" | "light";
+
+export function themeAppearance(
+  preference: ThemePreference,
+  prefersDark: boolean
+): ThemeAppearance {
+  if (preference === "system") return prefersDark ? "dark" : "light";
+  return preference === "light" || preference === "white" ? "light" : "dark";
+}
+
+/**
+ * The resolved appearance, tracking OS changes while the preference is `system`.
+ *
+ * Defaults to dark before the effect runs, matching the SSR fallback in root.tsx,
+ * so the first client render agrees with the server's.
+ */
+export function useThemeAppearance(preference: ThemePreference): ThemeAppearance {
+  const [prefersDark, setPrefersDark] = useState(true);
+
+  useEffect(() => {
+    if (preference !== "system") return;
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const apply = () => setPrefersDark(media.matches);
+    apply();
+    media.addEventListener("change", apply);
+    return () => media.removeEventListener("change", apply);
+  }, [preference]);
+
+  return themeAppearance(preference, prefersDark);
+}
+
 /**
  * Puts a preference on <html> now, resolving `system` against the OS once. Use
  * this to apply a theme the moment it's picked: the preference round-trips

apps/webapp/app/routes/account._index/route.tsx

@@ -35,11 +35,19 @@ import {
   useFavorites,
 } from "~/components/navigation/favoritePages";
 import { buildSideMenuSections } from "~/components/navigation/sideMenuSections";
-import { ALL_THEME_OPTIONS, THEME_OPTIONS_BY_VALUE } from "~/components/themeOptions";
+import {
+  ALL_THEME_OPTIONS,
+  THEME_OPTIONS_BY_VALUE,
+  themeOptionIcon,
+} from "~/components/themeOptions";
 import { prisma } from "~/db.server";
 import { SelectBestEnvironmentPresenter } from "~/presenters/SelectBestEnvironmentPresenter.server";
 import { useFeatureFlags } from "~/hooks/useFeatureFlags";
-import { applyThemePreference } from "~/hooks/useSystemThemeSync";
+import {
+  applyThemePreference,
+  type ThemeAppearance,
+  useThemeAppearance,
+} from "~/hooks/useSystemThemeSync";
 import { useFeatures } from "~/hooks/useFeatures";
 import { useHasAdminAccess, useUser } from "~/hooks/useUser";
 import { redirectWithSuccessMessage } from "~/models/message.server";
@@ -74,8 +82,8 @@ const MIN_CONTRAST = 15;
  *  same as `DEFAULT_THEME_CONTRAST`, the value applied when none is saved. */
 const DEFAULT_CONTRAST_MARK = 30;
 
-function themeIcon(value: ThemePreference) {
-  const Icon = THEME_OPTIONS_BY_VALUE[value].icon;
+function themeIcon(value: ThemePreference, appearance: ThemeAppearance) {
+  const Icon = themeOptionIcon(THEME_OPTIONS_BY_VALUE[value], appearance);
   // shrink-0: without it the icon is the flex item that gives way to a long
   // label, and "System"/"Classic" squash it to a sliver.
   return <Icon className="size-4 shrink-0 text-text-bright" />;
@@ -392,6 +400,9 @@ export default function Page() {
     typeof pendingTheme === "string"
       ? normalizeThemePreference(pendingTheme)
       : normalizeThemePreference(user.dashboardPreferences.theme);
+  // Black and White draw themselves against the active theme, so the icons
+  // follow the optimistic pick rather than waiting for the write to land.
+  const appearance = useThemeAppearance(theme);
 
   // Dragging previews the contrast via the CSS var before it persists; once the
   // save settles, resnap the page and the thumb to the stored value so a failed
@@ -545,7 +556,7 @@ export default function Page() {
                       items={ALL_THEME_OPTIONS.map((option) => option.value)}
                       text={(value) => (
                         <span className="flex items-center gap-1.5">
-                          {themeIcon(value)}
+                          {themeIcon(value, appearance)}
                           {THEME_OPTIONS_BY_VALUE[value].label}
                         </span>
                       )}
@@ -561,7 +572,7 @@ export default function Page() {
                           <SelectItem
                             key={item}
                             value={item}
-                            icon={themeIcon(item)}
+                            icon={themeIcon(item, appearance)}
                             className="text-text-bright"
                           >
                             {THEME_OPTIONS_BY_VALUE[item].label}