StellarUI

<stellar-button-color-mode>

Single-button control with a tri-state `mode` prop and a boolean `value` binding for whether the current result is dark on docs shell and preview surfaces.

Properties

Preview

Resolved output

value = false

mode=system resolves from prefers-color-scheme.

mode system

value false

This docs card mirrors the emitted boolean value. The docs header uses the same output to toggle the page-level .dark class.

Markup

Copy

<div
  data-signals:preview-color-mode="'system'"
  data-signals:preview-is-dark="false"
>
  <stellar-button-color-mode scope="preview" data-bind:preview-is-dark data-bind:preview-color-mode__prop.mode__event.input.change data-attr:tone="$tone" data-attr:appearance="$appearance" data-attr:size="$size" data-attr:shape="$shape"></stellar-button-color-mode>
  <div class="color-mode-preview-surface" data-class:dark="$previewIsDark">
    <div class="color-mode-preview-stack">
      <div class="color-mode-preview-copy">
        <p class="eyebrow">Resolved output</p>
        <h3 data-text="$previewIsDark ? 'value = true' : 'value = false'">value = false</h3>
        <p data-text="$previewColorMode === 'system' ? ('mode=system is currently resolving to ' + ($previewIsDark ? 'dark.' : 'light.')) : ('mode=' + $previewColorMode + ' forces that resolved value.')">mode=system resolves from prefers-color-scheme.</p>
      </div>
      <div class="color-mode-preview-readout">
        <div class="color-mode-preview-chip"><span>mode</span><strong data-text="$previewColorMode">system</strong></div>
        <div class="color-mode-preview-chip"><span>value</span><strong data-text="$previewIsDark ? 'true' : 'false'">false</strong></div>
      </div>
    </div>
  </div>
</div>

API

Complete props, events, slots, and implementation notes for the shipped color-mode control.

Props

Prop	Type	Default
`mode`	`light \| dark \| system`	`system`
`value`	`boolean`	`false`
`scope`	`none \| shell \| preview`	`none`
`tone`	`neutral \| primary \| secondary \| tertiary \| error`	`neutral`
`appearance`	`solid \| outline \| dash \| soft \| ghost \| link`	`outline`
`size`	`xs \| sm \| md \| lg \| xl`	`md`
`shape`	`'' \| square \| circle`	`square`
`width`	`'' \| wide \| full`	`''`

Events

Event	Source	Notes
`input`	host	Fires when `mode` or the resolved `value` changes, so both bindings stay live.
`change`	host	Fires after a committed selection change.

Slots

Slot	Notes
None	`stellar-button-color-mode` renders one fixed cycle button internally.

Notes

The public tag is `stellar-button-color-mode`, not the old `theme-controller` class hook.
The control is intentionally narrow: one button, three fixed modes, button-style `tone` / `appearance` / `size` / `shape` props, and normal `input` / `change` events.
Bind `mode` for the tri-state preference and bind `value` for the resolved boolean `isDark` result when the page itself needs to own dark state.
`system` resolves against `prefers-color-scheme` and keeps the resolved boolean `value` following OS changes while that mode stays active.
The button tooltip and accessible label show the current mode text: `Light`, `Dark`, or `System`.
The shared docs header consumes the resolved boolean output to toggle the page theme, while this preview card just mirrors that same output contract locally.
The visible control now delegates to `stellar-button`, so those four visual props match the rest of the action components instead of carrying a one-off utility style.