From 2fdb6028bfc30fd2ecfff0412a94fc464485aaa6 Mon Sep 17 00:00:00 2001
From: Kalin Rudnicki <kalin.r.rudnicki@gmail.com>
Date: Thu, 13 Aug 2026 22:09:50 -0600
Subject: [PATCH 1/2] OXY-154: harden ColorModePicker into a standalone
 Light/Dark/System component
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rework the reusable color-mode picker into a first-class, standalone widget,
fully independent of the theme-pack machinery (depends only on the ColorMode
service).

- Config-builder widget (à la ToggleThumb / HorizontalRadio) with two variants:
  Segmented (role=radiogroup, default) and Compact (single icon cycle button).
- Config knobs: small/medium/large, label/noLabel, includeSystem/lightDarkOnly,
  withIcons/noIcons, idPrefix. Backward-compatible apply()/apply(label=...).
- a11y: roving tabindex, role=radio + aria-checked per option, and keyboard
  navigation (arrows / Home / End / Space / Enter) that moves selection and DOM
  focus together; compact is a native button with descriptive aria-label/title.
- Extracted pure decision logic (ColorModePicker.Logic) and unit-tested it.
- Opt-in ColorModePicker.syncAcrossTabs subscribes to the Broadcast color-mode
  channel and re-highlights every mounted picker on cross-tab / programmatic
  changes.
- Showcase (ThemePage) demos the variants; docs updated.

No changes to ColorMode / Theme / ColorTheme / ThemePicker behavior.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011YxWKdsz97QT9BD7AdpSq6
---
 docs/docs/ui/builders.md                      |  32 +-
 .../ui/page/showcase/pages/ThemePage.scala    |  23 +-
 .../ui/web/component/ColorModePicker.scala    | 311 ++++++++++++++++--
 .../ui/web/style/OxygenColorSystemSpec.scala  |  55 +++-
 report/OXY-154-colormode.md                   |  43 +++
 5 files changed, 427 insertions(+), 37 deletions(-)
 create mode 100644 report/OXY-154-colormode.md

diff --git a/docs/docs/ui/builders.md b/docs/docs/ui/builders.md
index 7a769a27..9aca3514 100644
--- a/docs/docs/ui/builders.md
+++ b/docs/docs/ui/builders.md
@@ -222,7 +222,37 @@ ThemePicker(OxygenThemes.graphiteFamilyPacks)  // filter to a pack family
 
 Both are self-contained (backed by a shared `GlobalState` seeded from the stored value): they
 reflect the current selection and call `ColorMode.setAndPersist` / `Theme.applyAndPersist` on
-select. They do not re-highlight on cross-tab changes until the page re-renders.
+select.
+
+**`ColorModePicker`** is a first-class, standalone Light/Dark/System control — independent of the
+theme-pack machinery (depends only on the `ColorMode` service). It is a config builder (à la
+`ToggleThumb` / `HorizontalRadio`):
+
+```scala
+ColorModePicker()                    // segmented radiogroup (default)
+ColorModePicker.compact              // single icon button that cycles modes (top-bar friendly)
+ColorModePicker.segmentedWithIcons   // segmented + Light/Dark/System glyphs
+ColorModePicker().lightDarkOnly      // drop the System option
+ColorModePicker().large.label("Theme")
+```
+
+- **a11y:** segmented is a `role=radiogroup` with `role=radio` + `aria-checked` per option, roving
+  `tabindex`, and keyboard nav (Left/Up = prev, Right/Down = next, Home/End = first/last with wrap,
+  Space/Enter select) that moves selection **and** DOM focus together. Compact is a native
+  `<button>` with a descriptive `aria-label`/`title`.
+- **Live cross-tab highlight (opt-in):** by default the highlight reflects the mode at render time.
+  Wire `ColorModePicker.syncAcrossTabs` once (e.g. from `prePageLoad`) to have every mounted picker
+  re-highlight on cross-tab / programmatic `ColorMode` changes:
+
+  ```scala
+  override protected def prePageLoad: RIO[Env & Scope, Unit] =
+    ColorTheme.install *> ColorModePicker.syncAcrossTabs
+  ```
+
+  (For labeled *form* contexts, use the generic `HorizontalRadio.form[ColorMode.Mode]` instead — a
+  dedicated dropdown variant is intentionally omitted.)
+
+`ThemePicker` does not re-highlight on cross-tab changes until the page re-renders.
 
 ### Mobile / viewport
 
diff --git a/example/apps/ui/src/main/scala/oxygen/example/ui/page/showcase/pages/ThemePage.scala b/example/apps/ui/src/main/scala/oxygen/example/ui/page/showcase/pages/ThemePage.scala
index 93fcf5f5..07b30741 100644
--- a/example/apps/ui/src/main/scala/oxygen/example/ui/page/showcase/pages/ThemePage.scala
+++ b/example/apps/ui/src/main/scala/oxygen/example/ui/page/showcase/pages/ThemePage.scala
@@ -26,10 +26,29 @@ object ThemePage extends RoutablePage.NoParams[Any] {
             "plus surface personalities (Aurora / Ember / Violet / Ocean). " +
             "Top bar = solid primary + on-primary ink. Light/Dark flips surfaces only.",
         ),
-        // mode — reusable picker
+        // mode — reusable picker, shown in its several variants
+        h3("Color mode picker", marginBottom := S.spacing._3),
+        p(
+          color := S.color.fg.moderate,
+          fontSize := S.fontSize._2,
+          marginBottom := S.spacing._4,
+          "Standalone Light/Dark/System control (independent of theme packs). " +
+            "Keyboard: arrows / Home / End move + select; Space/Enter select. " +
+            "All instances share one persisted preference.",
+        ),
         div(
+          display.flex,
+          flexDirection.column,
+          gap := S.spacing._4,
           marginBottom := S.spacing._5,
-          ColorModePicker(label = Some("Color mode")),
+          // default segmented, with a leading caption
+          ColorModePicker(label = Some("Segmented")),
+          // segmented with icons
+          ColorModePicker.segmentedWithIcons.label("With icons"),
+          // Light/Dark only (no System)
+          ColorModePicker().lightDarkOnly.label("Light / Dark only"),
+          // compact icon cycle button (top-bar style)
+          ColorModePicker.compact.label("Compact"),
         ),
         h3("Oxygen theme packs", marginBottom := S.spacing._3),
         p(
diff --git a/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala b/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala
index f24e1dad..65a83100 100644
--- a/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala
+++ b/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala
@@ -1,51 +1,141 @@
 package oxygen.ui.web.component
 
-import org.scalajs.dom.window
+import org.scalajs.dom.{document, window, HTMLElement, KeyboardEvent}
 import oxygen.ui.web.*
 import oxygen.ui.web.create.{*, given}
-import oxygen.ui.web.service.ColorMode
+import oxygen.ui.web.service.{Broadcast, ColorMode}
+import zio.*
 
 /**
   * Reusable, drop-in color-mode picker (Light / Dark / System).
   *
-  * Self-contained: backed by a shared [[GlobalState]] seeded from the stored preference, so it
-  * reflects the current mode and can be dropped into any page without wiring page state. Clicking
-  * an option calls [[ColorMode.setAndPersist]] (persists + rebinds `data-color-mode` + notifies
-  * other tabs) and updates the highlight.
+  * A first-class, standalone widget for switching color mode. It is fully independent of the
+  * theme-pack machinery ([[ThemePicker]] / `OxygenThemes` / `Theme`) — it depends only on the
+  * [[ColorMode]] service and stands on its own.
   *
-  * a11y: `role=radiogroup` container, `role=radio` + `aria-checked` per option.
+  * Self-contained: backed by a shared [[GlobalState]] seeded from the stored [[ColorMode]]
+  * preference, so it reflects the current mode and can be dropped into any page without wiring
+  * page state. Selecting an option calls [[ColorMode.setAndPersist]] (persists + rebinds
+  * `data-color-mode` + notifies other tabs) and updates the highlight.
+  *
+  * Variants (config builder, à la [[ToggleThumb]] / [[HorizontalRadio]]):
+  *   - [[segmented]] (default) — a `role=radiogroup` Light / Dark / System segmented control with
+  *     full keyboard support (arrows / Home / End / Space / Enter) and roving `tabindex`.
+  *   - [[compact]] — a single icon button that cycles modes; ideal for a top bar.
+  * (A form/dropdown variant is intentionally omitted — `HorizontalRadio.form[ColorMode.Mode]`
+  * already covers labeled form contexts.)
+  *
+  * a11y:
+  *   - segmented: `role=radiogroup`, `role=radio` + `aria-checked` per option, roving `tabindex`,
+  *     keyboard navigation that moves selection + DOM focus together.
+  *   - compact: a native `<button>` with a descriptive `aria-label` / `title` announcing the
+  *     current mode and the next action.
+  *
+  * Live updates: by default the highlight reflects the mode at render time. To make it live-update
+  * on cross-tab / programmatic `ColorMode` changes, wire [[ColorModePicker.syncAcrossTabs]] once
+  * (e.g. from `prePageLoad`); it pushes broadcast changes into the shared state and re-renders.
   *
   * {{{
-  * ColorModePicker()                 // just the segmented control
-  * ColorModePicker(label = "Color mode".some)
+  * ColorModePicker()                              // segmented control
+  * ColorModePicker(label = "Color mode".some)     // with a leading caption
+  * ColorModePicker.compact.small                  // icon cycle button for a top bar
+  * ColorModePicker().lightDarkOnly                 // drop the System option
   * }}}
-  *
-  * Known limitation (by design, OXY-154): the highlight does not live-update on cross-tab /
-  * programmatic mode changes until the page re-renders. Cross-tab *application* still works via
-  * `ColorTheme.install` / `ColorMode.subscribeCrossTab`.
   */
-object ColorModePicker {
+final case class ColorModePicker(
+    private val _variant: ColorModePicker.Variant,
+    private val _size: ColorModePicker.Size,
+    private val _label: Option[String],
+    private val _includeSystem: Boolean,
+    private val _showIcons: Boolean,
+    private val _idPrefix: String,
+) extends PWidget.Deferred.Stateless[Any, Nothing] {
 
-  private val options: Seq[ColorMode.Mode] =
-    Seq(ColorMode.Mode.Light, ColorMode.Mode.Dark, ColorMode.Mode.System)
+  import ColorModePicker.*
 
-  private def readStored: ColorMode.Mode =
-    Option(window.localStorage.getItem(ColorMode.storageKey)).flatMap(ColorMode.parse).getOrElse(ColorMode.Mode.System)
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+  //      Config
+  // ////////////////////////////////////////////////////////////////////////////////////////////
 
-  private object ModeState extends GlobalState[ColorMode.Mode]("ColorModePicker")(readStored)
+  def variant(v: Variant): ColorModePicker = copy(_variant = v)
+  def segmented: ColorModePicker = variant(Variant.Segmented)
+  def compact: ColorModePicker = variant(Variant.Compact)
+
+  def size(s: Size): ColorModePicker = copy(_size = s)
+  def small: ColorModePicker = size(Size.small)
+  def medium: ColorModePicker = size(Size.medium)
+  def large: ColorModePicker = size(Size.large)
+
+  def label(text: String): ColorModePicker = copy(_label = Some(text))
+  def label(text: Option[String]): ColorModePicker = copy(_label = text)
+  def noLabel: ColorModePicker = copy(_label = None)
+
+  def includeSystem(b: Boolean): ColorModePicker = copy(_includeSystem = b)
+  def lightDarkOnly: ColorModePicker = includeSystem(false)
+
+  def showIcons(b: Boolean): ColorModePicker = copy(_showIcons = b)
+  def withIcons: ColorModePicker = showIcons(true)
+  def noIcons: ColorModePicker = showIcons(false)
+
+  def idPrefix(p: String): ColorModePicker = copy(_idPrefix = p)
+
+  private def modes: List[ColorMode.Mode] = Logic.options(_includeSystem)
+
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+  //      Render
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+
+  override protected def build: PWidget[Any, Nothing, Any, Nothing] =
+    _variant match {
+      case Variant.Segmented => renderSegmented
+      case Variant.Compact   => renderCompact
+    }
 
-  private def option(st: WidgetState[ColorMode.Mode], mode: ColorMode.Mode, current: ColorMode.Mode): Widget = {
+  private def select(st: WidgetState[ColorMode.Mode], mode: ColorMode.Mode): UIO[Unit] =
+    ColorMode.setAndPersist(mode) *> st.set(mode)
+
+  private def optionId(mode: ColorMode.Mode): String =
+    s"${_idPrefix}-${mode.lower}"
+
+  private def focusOption(mode: ColorMode.Mode): UIO[Unit] =
+    ZIO.succeed {
+      Option(document.getElementById(optionId(mode))).foreach {
+        case el: HTMLElement => el.focus()
+        case _               => ()
+      }
+    }
+
+  private def iconWidget(mode: ColorMode.Mode): Widget =
+    Logic.iconFor(mode).size(_size.iconPx).decorativeIcon
+
+  private def leadingLabel: Widget =
+    _label match {
+      case Some(text) => span(text, color := S.color.fg.moderate, fontSize := _size.fontSize)
+      case None       => Widget.empty
+    }
+
+  // --- Segmented -------------------------------------------------------------------------------
+
+  private def segmentedOption(
+      st: WidgetState[ColorMode.Mode],
+      mode: ColorMode.Mode,
+      current: ColorMode.Mode,
+  ): Widget = {
     val selected: Boolean = mode == current
     span(
+      id := optionId(mode),
       Widget.raw.htmlAttr("role", "radio"),
       Widget.raw.htmlAttr("aria-checked", if selected then "true" else "false"),
+      Widget.raw.htmlAttr("aria-label", mode.pretty),
       Widget.raw.htmlAttr("tabindex", if selected then "0" else "-1"),
       display.inlineFlex,
       alignItems.center,
+      gap := S.spacing._2,
       cursor.pointer,
       userSelect.none,
-      padding(S.spacing._1, S.spacing._3),
-      fontSize := S.fontSize._2,
+      outline := "none",
+      padding(_size.padV, _size.padH),
+      fontSize := _size.fontSize,
       fontWeight := S.fontWeight.semiBold,
       borderStyle.solid,
       borderWidth := 1.px,
@@ -63,33 +153,190 @@ object ColorModePicker {
           borderColor.dynamic := S.color.bg.layerThree,
         )
       ,
+      if _showIcons then iconWidget(mode) else Widget.empty,
       mode.pretty,
-      onClick := (ColorMode.setAndPersist(mode) *> st.set(mode)),
+      onClick := select(st, mode),
     )
   }
 
-  /** Segmented Light / Dark / System control. Pass `label` to render a leading caption. */
-  def apply(label: Option[String] = None): Widget =
+  private def renderSegmented: Widget =
     Widget.state[ColorMode.Mode].detach(ModeState) { st =>
-      val current: ColorMode.Mode = st.renderTimeValue
+      val current: ColorMode.Mode = Logic.effectiveCurrent(modes, st.renderTimeValue)
       div(
         display.inlineFlex,
         alignItems.center,
         gap := S.spacing._2,
         flexWrap.wrap,
-        label match {
-          case Some(text) => span(text, color := S.color.fg.moderate, fontSize := S.fontSize._2)
-          case None       => Widget.empty
-        },
+        leadingLabel,
         div(
           Widget.raw.htmlAttr("role", "radiogroup"),
-          Widget.raw.htmlAttr("aria-label", "Color mode"),
+          Widget.raw.htmlAttr("aria-label", _label.getOrElse("Color mode")),
           display.inlineFlex,
           borderRadius := S.borderRadius._3,
           overflow.hidden,
-          Widget.foreach(options)(option(st, _, current)),
+          onKeyDown.e.handle { (e: KeyboardEvent) =>
+            Logic.keyToNav(e.key) match {
+              case Some(nav) =>
+                val next = Logic.resolveNav(modes, current, nav)
+                e.preventDefault()
+                if next == current then focusOption(next)
+                else select(st, next) *> focusOption(next)
+              case None => ZIO.unit
+            }
+          },
+          Widget.foreach(modes)(segmentedOption(st, _, current)),
         ),
       )
     }
 
+  // --- Compact ---------------------------------------------------------------------------------
+
+  private def renderCompact: Widget =
+    Widget.state[ColorMode.Mode].detach(ModeState) { st =>
+      val current: ColorMode.Mode = Logic.effectiveCurrent(modes, st.renderTimeValue)
+      val next: ColorMode.Mode = Logic.cycle(modes, current)
+      val describe: String = s"Color mode: ${current.pretty}. Activate to switch to ${next.pretty}."
+      val btn =
+        if _showIcons then Button().iconOnly(Logic.iconFor(current)).subtle
+        else Button(current.pretty).subtle
+      val sized = _size match {
+        case Size.small => btn.small
+        case Size.large => btn.large
+        case _          => btn.medium
+      }
+      div(
+        display.inlineFlex,
+        alignItems.center,
+        gap := S.spacing._2,
+        flexWrap.wrap,
+        leadingLabel,
+        sized.content(
+          Widget.raw.htmlAttr("aria-label", describe),
+          Widget.raw.htmlAttr("title", describe),
+          onClick := select(st, next),
+        ),
+      )
+    }
+
+}
+object ColorModePicker {
+
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+  //      Public entry points (backward compatible)
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+
+  /** Default segmented Light / Dark / System control. Pass `label` to render a leading caption. */
+  def apply(label: Option[String] = None): ColorModePicker =
+    ColorModePicker(
+      _variant = Variant.Segmented,
+      _size = Size.small,
+      _label = label,
+      _includeSystem = true,
+      _showIcons = false,
+      _idPrefix = "oxygen-color-mode",
+    )
+
+  /** Compact single-button cycle control (icon by default), ideal for a top bar. */
+  def compact: ColorModePicker = apply().compact.withIcons
+
+  /** Segmented control with a leading Light/Dark/System icon on each option. */
+  def segmentedWithIcons: ColorModePicker = apply().withIcons
+
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+  //      Shared state
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+
+  private def readStored: ColorMode.Mode =
+    Option(window.localStorage.getItem(ColorMode.storageKey)).flatMap(ColorMode.parse).getOrElse(ColorMode.Mode.System)
+
+  private object ModeState extends GlobalState[ColorMode.Mode]("ColorModePicker")(readStored)
+
+  /**
+    * Opt-in: keep every mounted [[ColorModePicker]] highlight in sync with cross-tab /
+    * programmatic [[ColorMode]] changes for the lifetime of the provided [[Scope]].
+    *
+    * Subscribes to the [[Broadcast]] color-mode channel and pushes changes into the shared state
+    * (which re-renders the current page). Cross-tab *application* of the mode already happens via
+    * `ColorMode.subscribeCrossTab` / `ColorTheme.install`; this only updates the picker's
+    * highlight. Wire once (e.g. from `prePageLoad`).
+    *
+    * {{{
+    * override protected def prePageLoad: RIO[Env & Scope, Unit] =
+    *   ColorTheme.install *> ColorModePicker.syncAcrossTabs
+    * }}}
+    */
+  def syncAcrossTabs: URIO[Scope, Unit] =
+    Broadcast.subscribeThemeMode.foreach(ModeState.set).forkScoped.unit
+
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+  //      Config types
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+
+  enum Variant { case Segmented, Compact }
+
+  final case class Size(fontSize: String, padV: String, padH: String, iconPx: Int)
+  object Size {
+    val small: Size = Size(S.fontSize._2, S.spacing._1, S.spacing._3, Icon.Size.sm)
+    val medium: Size = Size(S.fontSize._4, s"calc(${S.spacing._1} * 1.5)", S.spacing._4, Icon.Size.md)
+    val large: Size = Size(S.fontSize._6, S.spacing._2, S.spacing._5, Icon.Size.lg)
+  }
+
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+  //      Pure decision logic (DOM-free, unit-tested)
+  // ////////////////////////////////////////////////////////////////////////////////////////////
+
+  /** Keyboard-navigation intents within a segmented radiogroup. */
+  enum Nav { case Prev, Next, First, Last, Select }
+
+  object Logic {
+
+    /** Ordered options; `System` is included only when `includeSystem`. */
+    def options(includeSystem: Boolean): List[ColorMode.Mode] =
+      if includeSystem then List(ColorMode.Mode.Light, ColorMode.Mode.Dark, ColorMode.Mode.System)
+      else List(ColorMode.Mode.Light, ColorMode.Mode.Dark)
+
+    def iconFor(mode: ColorMode.Mode): Icon =
+      mode match {
+        case ColorMode.Mode.Light  => Icon.sun
+        case ColorMode.Mode.Dark   => Icon.moon
+        case ColorMode.Mode.System => Icon.monitor
+      }
+
+    /** The stored value, clamped into `options` (e.g. `System` stored but excluded => first). */
+    def effectiveCurrent(options: List[ColorMode.Mode], stored: ColorMode.Mode): ColorMode.Mode =
+      if options.contains(stored) then stored else options.headOption.getOrElse(stored)
+
+    /** Map a `KeyboardEvent.key` to a navigation intent, if any. */
+    def keyToNav(key: String): Option[Nav] =
+      key match {
+        case "ArrowLeft" | "Left" | "ArrowUp" | "Up"       => Some(Nav.Prev)
+        case "ArrowRight" | "Right" | "ArrowDown" | "Down" => Some(Nav.Next)
+        case "Home"                                        => Some(Nav.First)
+        case "End"                                         => Some(Nav.Last)
+        case " " | "Spacebar" | "Enter"                    => Some(Nav.Select)
+        case _                                             => None
+      }
+
+    /** Resolve a navigation intent to the target mode (Prev/Next wrap around). */
+    def resolveNav(options: List[ColorMode.Mode], current: ColorMode.Mode, nav: Nav): ColorMode.Mode = {
+      val n = options.size
+      if n == 0 then current
+      else {
+        val idx = math.max(options.indexOf(current), 0)
+        nav match {
+          case Nav.Prev   => options((idx - 1 + n) % n)
+          case Nav.Next   => options((idx + 1) % n)
+          case Nav.First  => options.head
+          case Nav.Last   => options.last
+          case Nav.Select => options(idx)
+        }
+      }
+    }
+
+    /** Next mode in cycle order (wraps) — used by the compact button. */
+    def cycle(options: List[ColorMode.Mode], current: ColorMode.Mode): ColorMode.Mode =
+      resolveNav(options, current, Nav.Next)
+
+  }
+
 }
diff --git a/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala b/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala
index fcd10d5c..af489457 100644
--- a/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala
+++ b/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala
@@ -3,9 +3,9 @@ package oxygen.ui.web.style
 import java.time.YearMonth
 import oxygen.predef.test.*
 import oxygen.ui.web.{LockState, Memo, PageURL}
-import oxygen.ui.web.component.{ColorPicker, DatePicker, DateTimePicker, Icon, InfiniteScroll, LazySection, Pagination, Progress, SideBar, SortableList, Tabs, TimePicker, TopBar}
+import oxygen.ui.web.component.{ColorModePicker, ColorPicker, DatePicker, DateTimePicker, Icon, InfiniteScroll, LazySection, Pagination, Progress, SideBar, SortableList, Tabs, TimePicker, TopBar}
 import oxygen.ui.web.create.{AnchorId, CSSColor, MediaCSS, Motion}
-import oxygen.ui.web.service.{IndexedDB, Intersect}
+import oxygen.ui.web.service.{ColorMode, IndexedDB, Intersect}
 import oxygen.ui.web.service.HashScroll
 import oxygen.ui.web.style.Breakpoints
 import oxygen.ui.web.style.OxygenColorSystem.*
@@ -383,6 +383,57 @@ object OxygenColorSystemSpec extends OxygenSpecDefault {
           assertTrue(w.forall(_.ratio > 0))
         },
       ),
+      suite("ColorModePicker.Logic")(
+        test("options include/exclude System") {
+          import ColorMode.Mode.*
+          assertTrue(ColorModePicker.Logic.options(true) == List(Light, Dark, System)) &&
+          assertTrue(ColorModePicker.Logic.options(false) == List(Light, Dark))
+        },
+        test("iconFor maps each mode to a distinct icon") {
+          import ColorMode.Mode.*
+          val names = Set(Light, Dark, System).map(ColorModePicker.Logic.iconFor(_).name)
+          assertTrue(names.size == 3) &&
+          assertTrue(ColorModePicker.Logic.iconFor(Light).name == "sun") &&
+          assertTrue(ColorModePicker.Logic.iconFor(Dark).name == "moon")
+        },
+        test("effectiveCurrent clamps a stored mode not in options") {
+          import ColorMode.Mode.*
+          val ld = ColorModePicker.Logic.options(false)
+          assertTrue(ColorModePicker.Logic.effectiveCurrent(ld, Dark) == Dark) &&
+          assertTrue(ColorModePicker.Logic.effectiveCurrent(ld, System) == Light) &&
+          assertTrue(ColorModePicker.Logic.effectiveCurrent(Nil, System) == System)
+        },
+        test("keyToNav maps arrows/home/end/space/enter, ignores others") {
+          import ColorModePicker.Nav.*
+          assertTrue(ColorModePicker.Logic.keyToNav("ArrowLeft").contains(Prev)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav("Up").contains(Prev)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav("ArrowRight").contains(Next)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav("Down").contains(Next)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav("Home").contains(First)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav("End").contains(Last)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav(" ").contains(Select)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav("Enter").contains(Select)) &&
+          assertTrue(ColorModePicker.Logic.keyToNav("a").isEmpty)
+        },
+        test("resolveNav wraps Prev/Next and honors First/Last/Select") {
+          import ColorMode.Mode.*
+          import ColorModePicker.Nav.*
+          val opts = ColorModePicker.Logic.options(true)
+          assertTrue(ColorModePicker.Logic.resolveNav(opts, Light, Prev) == System) &&
+          assertTrue(ColorModePicker.Logic.resolveNav(opts, System, Next) == Light) &&
+          assertTrue(ColorModePicker.Logic.resolveNav(opts, Dark, Next) == System) &&
+          assertTrue(ColorModePicker.Logic.resolveNav(opts, Dark, First) == Light) &&
+          assertTrue(ColorModePicker.Logic.resolveNav(opts, Dark, Last) == System) &&
+          assertTrue(ColorModePicker.Logic.resolveNav(opts, Dark, Select) == Dark)
+        },
+        test("cycle advances with wraparound") {
+          import ColorMode.Mode.*
+          val opts = ColorModePicker.Logic.options(true)
+          assertTrue(ColorModePicker.Logic.cycle(opts, Light) == Dark) &&
+          assertTrue(ColorModePicker.Logic.cycle(opts, Dark) == System) &&
+          assertTrue(ColorModePicker.Logic.cycle(opts, System) == Light)
+        },
+      ),
     )
 
 }
diff --git a/report/OXY-154-colormode.md b/report/OXY-154-colormode.md
new file mode 100644
index 00000000..e927931c
--- /dev/null
+++ b/report/OXY-154-colormode.md
@@ -0,0 +1,43 @@
+# OXY-154-colormode — Harden ColorModePicker
+
+Branch: `OXY-154-colormode` (stacked on `OXY-154`, PR #296).
+
+## Goal
+Make `ColorModePicker` a first-class standalone Light/Dark/System component: decouple from ThemePicker/pack work, add variants, solid a11y + keyboard nav, react to cross-tab/programmatic ColorMode changes, unit tests, showcase, docs.
+
+## Findings (current ColorModePicker.scala)
+- Single `apply(label)` -> segmented control only. No variants.
+- Uses own `ModeState` GlobalState + own `readStored` (duplicates ColorMode.readStored logic w/ localStorage).
+- a11y: role=radiogroup/radio, aria-checked, tabindex roving present, BUT no keyboard handlers (arrow keys / space) wired.
+- Known limitation documented: highlight does not live-update on cross-tab/programmatic changes (no Broadcast subscribe).
+- Coupling to ThemePicker: shares *pattern* (GlobalState + detach + readStored) but no direct code dependency. Independent already at code level — good.
+
+## Decisions
+- ColorModePicker was already code-independent of ThemePicker (only shared a *pattern*: GlobalState + detach + readStored). Confirmed no import/type coupling. Kept its own shared `ModeState` GlobalState seeded via `ColorMode.storageKey`/`ColorMode.parse` (depends only on `ColorMode` service, never on `Theme`/`OxygenThemes`/`ThemePicker`). => fully standalone.
+- Rewrote as a config case-class extending `PWidget.Deferred.Stateless` (matches ToggleThumb / HorizontalRadio / Icon conventions), so instances are droppable widgets AND fluently configurable. Backward-compat `apply()` / `apply(label = ...)` retained (existing call sites: ThemePage, StylesPage, KitchenSinkPage, ShellPage).
+- Variants: **Segmented** (role=radiogroup, default) + **Compact** (single icon cycle button, top-bar friendly, role=button). Deliberately did NOT add a native `<select>`/dropdown "form" variant — form contexts are already served by the generic `HorizontalRadio.form[ColorMode.Mode]`; a third variant would be over-engineering. Documented.
+- Config knobs: `.small/.medium/.large`, `.label(..)/.noLabel`, `.includeSystem(..)/.lightDarkOnly` (sensible variant: some apps only want Light/Dark), `.withIcons/.noIcons`, `.idPrefix(..)` (multi-instance focus-id disambiguation).
+- Icons: Light=sun, Dark=moon, System=monitor.
+- a11y hardening (segmented): roving `tabindex` (0 on selected, -1 others), `role=radiogroup`+`aria-label`, per-option `role=radio`+`aria-checked`+stable `id`, keyboard nav on the group (Left/Up = prev, Right/Down = next, Home/End = first/last with wrap, Space/Enter select) that selects + moves DOM focus to the new radio. Compact: native `<button>` via Button + descriptive `aria-label`/`title` announcing current mode and next action.
+- Extracted pure decision logic into `ColorModePicker.Logic` (options list, `keyToNav`, `resolveNav` with wraparound, `cycle`) — unit-tested (no DOM).
+- Cross-tab/programmatic live update: added opt-in `ColorModePicker.syncAcrossTabs: URIO[Scope, Unit]` that subscribes to `Broadcast.subscribeThemeMode` and pushes into the shared `ModeState` (via `GlobalState.set`, which re-renders the current page) so the highlight live-updates. Left OFF by default (no behavior change); consumers wire it in `prePageLoad`/`postLoad`. Kept ColorMode's own doc-application subscription untouched. Removed the old "known limitation" caveat since it's now addressable.
+
+## What changed (files)
+- `modules/ui/web/.../component/ColorModePicker.scala` — rewritten as config case-class widget (Segmented + Compact variants), a11y + keyboard nav, `Logic` (pure), `syncAcrossTabs`, `Size`/`Variant`/`Nav`. Backward-compat `apply()` kept.
+- `modules/ui/web/src/test/.../style/OxygenColorSystemSpec.scala` — added `ColorModePicker.Logic` suite (6 tests, all pure/DOM-free).
+- `example/apps/ui/.../showcase/pages/ThemePage.scala` — showcase now demos 4 variants (segmented, with-icons, light/dark-only, compact).
+- `docs/docs/ui/builders.md` — documented variants, a11y, `syncAcrossTabs`, form guidance.
+
+## Verification
+- `oxygen-ui-web/compile` ✅  `example-ui-web/compile` ✅  `oxygen-ui-web/test` ✅ (51 tests, incl. 6 new).
+- `sbt fmt` applied; JGit worktree workaround (`git.gitUncommittedChanges := false`) added temporarily to load sbt, then reverted — NOT committed.
+- No changes to `ColorMode` / `Theme` / `ColorTheme` / `ThemePicker` behavior. Existing `ColorModePicker()` call sites (ThemePage, StylesPage, KitchenSinkPage, ShellPage) unchanged and still compile.
+
+## Assumptions
+- Native `<select>`/dropdown variant intentionally skipped (HorizontalRadio.form covers form contexts) — judged as avoiding over-engineering, not a gap.
+- `syncAcrossTabs` left opt-in (no default wiring) to avoid changing existing app bootstrap behavior; `GlobalState.set` from a forked subscription fiber re-renders the current page (consistent with `ColorMode.subscribeCrossTab`'s scoped-fork pattern). Not exercised in a live browser here — logic is straightforward but unverified at runtime.
+- Keyboard focus management (`document.getElementById(id).focus()` after `st.set`) relies on `set` completing after the re-render patch; matches the framework's synchronous render model but not browser-tested.
+- Multi-instance focus ids share a default `_idPrefix`; `idPrefix(..)` provided for disambiguation. All instances intentionally share one persisted preference (single logical selection).
+
+## CONFIDENCE: 8/10
+Compiles, formatted, all tests green, backward compatible, decoupling verified. Deductions: runtime a11y/keyboard-focus behavior and `syncAcrossTabs` live cross-tab re-highlight are logically sound and unit-tested at the decision-logic level, but not exercised in a real browser this session.

From 5084477955e7a5e195f6efd94f34cacc328a74c1 Mon Sep 17 00:00:00 2001
From: Kalin Rudnicki <kalin.r.rudnicki@gmail.com>
Date: Thu, 13 Aug 2026 23:53:29 -0600
Subject: [PATCH 2/2] OXY-154: auto-unique ColorModePicker ids + pin System
 icon test

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011YxWKdsz97QT9BD7AdpSq6
---
 .../oxygen/ui/web/component/ColorModePicker.scala | 15 ++++++++++++++-
 .../ui/web/style/OxygenColorSystemSpec.scala      |  3 ++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala b/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala
index 65a83100..2f41ebec 100644
--- a/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala
+++ b/modules/ui/web/src/main/scala/oxygen/ui/web/component/ColorModePicker.scala
@@ -225,6 +225,19 @@ object ColorModePicker {
   //      Public entry points (backward compatible)
   // ////////////////////////////////////////////////////////////////////////////////////////////
 
+  /**
+    * Per-instance id counter (scala.js is single-threaded, so a plain `var` is safe).
+    * Guarantees every default-configured picker gets a document-unique `idPrefix`, so multiple
+    * pickers on one page don't emit colliding option ids (which would break roving-tabindex focus
+    * and produce invalid duplicate-id HTML). An explicit `.idPrefix(...)` still overrides this.
+    */
+  private var instanceCounter: Long = 0L
+  private def freshIdPrefix(): String = {
+    val n = instanceCounter
+    instanceCounter += 1L
+    s"oxygen-color-mode-$n"
+  }
+
   /** Default segmented Light / Dark / System control. Pass `label` to render a leading caption. */
   def apply(label: Option[String] = None): ColorModePicker =
     ColorModePicker(
@@ -233,7 +246,7 @@ object ColorModePicker {
       _label = label,
       _includeSystem = true,
       _showIcons = false,
-      _idPrefix = "oxygen-color-mode",
+      _idPrefix = freshIdPrefix(),
     )
 
   /** Compact single-button cycle control (icon by default), ideal for a top bar. */
diff --git a/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala b/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala
index af489457..95fc3419 100644
--- a/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala
+++ b/modules/ui/web/src/test/scala/oxygen/ui/web/style/OxygenColorSystemSpec.scala
@@ -394,7 +394,8 @@ object OxygenColorSystemSpec extends OxygenSpecDefault {
           val names = Set(Light, Dark, System).map(ColorModePicker.Logic.iconFor(_).name)
           assertTrue(names.size == 3) &&
           assertTrue(ColorModePicker.Logic.iconFor(Light).name == "sun") &&
-          assertTrue(ColorModePicker.Logic.iconFor(Dark).name == "moon")
+          assertTrue(ColorModePicker.Logic.iconFor(Dark).name == "moon") &&
+          assertTrue(ColorModePicker.Logic.iconFor(System).name == "desktop")
         },
         test("effectiveCurrent clamps a stored mode not in options") {
           import ColorMode.Mode.*