Maofeng
69 lines
2.9 KiB
Plaintext
69 lines
2.9 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
|
|
---
|
|
|
|
## 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.
|