---
title: Appearance
description: Finish the application with persistent theme, color, and compact-layout preferences.
order: 22
toc:
  - id: provide-ui-state
    title: Provide UI state
  - id: apply-preferences
    title: Apply preferences
  - id: add-locales
    title: Add locales
---

## Provide UI state {#provide-ui-state}

Mount `UiStateProvider` near the application root. A controlled provider can persist every state update through its change handler.

```tsx
<UiStateProvider>
  <AppearanceController />
  <App />
  <ThemeToggleButton />
</UiStateProvider>
```

## Apply preferences {#apply-preferences}

Render `AppearanceController` once so the current state becomes document classes and theme variables. `useUiState` reads or updates individual preferences, while `useResolvedTheme` returns the effective light or dark scheme after resolving system mode.

## Add locales {#add-locales}

Add the appearance catalog only when the application uses these controls:

```json
{
  "catalogSources": ["@workspace/blocks/appearance/locales/{locale}"]
}
```

The application shell is now complete. Add only the other block-specific catalogs used by the product.