docs(appearance): document preference hooks

2026-09-29 22:12:56 +08:00
parent 642cb71b93
commit e34675a931
4 changed files with 68 additions and 2 deletions
@@ -57,7 +57,18 @@ For a more granular layout, compose `baseColorSwatches`, `accentColorSwatches`,

 ## 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.
+`AppearanceSettings` is the default binding layer between the atoms and the shared `PreferencesProvider`. A custom surface can use Appearance hooks such as `useThemeMode`, `useThemeConfig`, and `useResolvedTheme` without knowing shared-preference string keys or reusing the default layout.
+
+```tsx
+const [themeConfig, setThemeConfig] = useThemeConfig()
+const resolvedTheme = useResolvedTheme()
+
+<ThemeConfigCard
+  config={themeConfig}
+  onConfigChange={setThemeConfig}
+  scheme={resolvedTheme}
+/>
+```

 ## Live preview {#live-preview}

@@ -9,6 +9,8 @@ toc:
    title: Atomic components
  - id: preferences
    title: Preference integration
+  - id: hooks
+    title: Hooks
 ---

 ## Package role {#package-role}
@@ -66,3 +68,23 @@ Add definitions and effects from locale, keyboard, or other packages to the same
 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()
+```