---
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
---

## Controlled atoms {#controlled-atoms}

`ThemeModeField`, `CompactLayoutField`, `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} />
<CompactLayoutField checked={compacted} onCheckedChange={setCompacted} />
```

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

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

```tsx
<ThemeConfigCard
  active={resolvedTheme === "light"}
  compacted={compacted}
  config={lightTheme}
  onConfigChange={setLightTheme}
  scheme="light"
/>
```

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

## 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.