---
title: Atomic composition
description: Build a custom appearance surface from controlled components without the preset dialog.
order: 1
toc:
  - id: controlled-atoms
    title: Controlled atoms
  - id: compose-card
    title: Compose a theme card
  - id: connected-layer
    title: State bindings
  - id: live-preview
    title: Live preview
---

## Controlled atoms {#controlled-atoms}

`ThemeModeField`, `ThemeModeOptionList`, `ColorVisionModeField`, `TextScaleField`, `TextScaleOptionList`, `MotionModeField`, `BrightnessField`, `ThemeColorPicker`, and `ThemeToggle` are driven by values and callbacks. They do not require preference context, so they can work with forms, preview tools, or another state library.

```tsx
<ThemeModeField value={mode} onValueChange={setMode} />
<ThemeModeOptionList value={mode} onValueChange={setMode} />
<ColorVisionModeField value={colorVisionMode} onValueChange={setColorVisionMode} />
<TextScaleField value={textScale} onValueChange={setTextScale} />
<MotionModeField value={motionMode} onValueChange={setMotionMode} />
<BrightnessField value={brightness} onValueChange={setBrightness} />
<TextScaleOptionList value={textScale} onValueChange={setTextScale} />
```

`AppearanceOptionList` is the reusable radio list behind `TextScaleOptionList`. Give its `items` a `value`, `label`, and optional `icon` and `description` to build theme, motion, color-vision, or brightness selectors with the same presentation. It uses native radio inputs for keyboard navigation and form semantics.

## Compose a theme card {#compose-card}

`ThemeConfigCard` combines base and accent color controls while keeping the configuration owned by the caller.

```tsx
<ThemeConfigCard
  config={{ baseColor, accentColor }}
  onConfigChange={setThemeColors}
  scheme={resolvedTheme}
/>
```

For a more granular layout, compose `baseColorSwatches`, `accentColorSwatches`, and `ThemeColorSwatchButton` directly.

`ThemeColorPicker` uses the labeled `pill` style by default. For tighter layouts, switch to the color-only `swatch` style with its selected indicator:

```tsx
<ThemeColorPicker
  title="Accent color"
  swatches={accentColorSwatches}
  value={accentColor}
  variant="swatch"
  onValueChange={setAccentColor}
/>
```

## State bindings {#connected-layer}

`AppearanceSettings` is the default binding layer between the atoms and the shared `PreferencesProvider`. A custom surface can call `usePreference` from `@workspace/preferences` for individual values without reusing the default layout.

## Live preview {#live-preview}

The documentation Sandbox can load a typed, multi-file example without embedding implementation details in MDX:

<Sandbox example="appearance/theme-colors" title="Theme color controls" />

For a single file, import the component and its raw source directly instead of creating a manifest:

```mdx
import Demo from "./Demo"
import source from "./Demo.tsx?raw"

<SingleFileSandbox component={Demo} filename="Demo.tsx" source={source} />
```