---
title: Overview
description: Understand the Appearance package atoms, theme data, and preference boundary.
order: 1
toc:
  - id: package-role
    title: Package role
  - id: atomic-components
    title: Atomic components
  - id: preferences
    title: Preference integration
---

## Package role {#package-role}

`@workspace/appearance` owns theme mode, base color, accent color, color-vision assistance, text scale, motion, and interface brightness. It does not create its own provider or store, and it does not require changes to `@workspace/ui`. The application aggregates it with other preference packages through `@workspace/preferences`.

## Atomic components {#atomic-components}

The controlled components can be composed independently without preference context:

- `ThemeModeField` selects light, dark, or system mode.
- `ColorVisionModeField` selects the standard, protan, deutan, or tritan assistance palette.
- `TextScaleField` scales the interface to 100%, 125%, 150%, or 200%.
- `MotionModeField` follows the system, reduces motion, or enables full motion.
- `BrightnessField` selects dim, normal, or bright interface surfaces.
- `ThemeColorPicker` and `ThemeColorSwatchButton` select theme colors.
- `ThemePreview` previews a set of theme variables.
- `ThemeConfigCard` combines the preview, base color, and accent color controls.
- `ThemeToggle` switches between light and dark themes.

`AppearanceSettings`, `AppearanceDialog`, and `AppearanceController` are optional composition layers built from these atoms.

## Preference integration {#preferences}

```tsx
import {
  createDefaultPreferences,
  PreferencesProvider,
} from "@workspace/preferences"
import {
  AppearanceController,
  appearancePreferenceDefinitions,
  appearancePreferenceEffect,
} from "@workspace/appearance"

const preferenceDefinitions = {
  ...appearancePreferenceDefinitions,
}
const initialPreferences = createDefaultPreferences(preferenceDefinitions)
const preferenceEffects = [appearancePreferenceEffect] as const

export function App() {
  return (
    <PreferencesProvider
      effects={preferenceEffects}
      initialPreferences={initialPreferences}
    >
      <AppearanceController />
    </PreferencesProvider>
  )
}
```

Add definitions and effects from locale, keyboard, or other packages to the same objects. The application can persist every `{ key, value }` update through the shared `onPreferenceChange` and parse cookies on the server with the aggregated definitions.

Color-vision assistance does not filter the complete document or its images. It replaces semantic colors such as `destructive` and `chart-*`, and writes `data-ui-color-vision` to `<html>` so application components can add icons, labels, shapes, or patterns. Important information must never rely on color alone.

Text, motion, and brightness are also implemented entirely through root attributes and CSS variables. Once the Appearance stylesheet is imported, existing UI components, portals, and application content inherit these settings.