Maofeng
91 lines
4.0 KiB
Plaintext
91 lines
4.0 KiB
Plaintext
---
|
|
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
|
|
- id: hooks
|
|
title: Hooks
|
|
---
|
|
|
|
## 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.
|
|
- `ThemeConfigCard` combines the 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.
|
|
|
|
## Hooks {#hooks}
|
|
|
|
Applications do not need to know the string keys that Appearance uses in the shared store. The package provides a semantic hook for every preference: `useThemeMode`, `useAccentColor`, `useBaseColor`, `useColorVisionMode`, `useTextScale`, `useMotionMode`, and `useBrightness`.
|
|
|
|
Composition and resolution hooks support higher-level surfaces:
|
|
|
|
- `useThemeConfig` reads and updates base and accent colors as one configuration.
|
|
- `useSystemTheme` and `useSystemMotion` only read operating-system settings.
|
|
- `useResolvedTheme` and `useResolvedMotion` return the final value after resolving `system`.
|
|
- `useToggleTheme` returns a callback that switches between explicit light and dark modes.
|
|
- `useAppearancePreference` is the typed low-level entry point, while `useAppearancePreferences` returns the complete Appearance snapshot.
|
|
|
|
```tsx
|
|
const [themeMode, setThemeMode] = useThemeMode()
|
|
const [themeConfig, setThemeConfig] = useThemeConfig()
|
|
const resolvedTheme = useResolvedTheme()
|
|
const resolvedMotion = useResolvedMotion()
|
|
const toggleTheme = useToggleTheme()
|
|
```
|