docs(appearance): document preference hooks

packages/appearance/docs/en-US/advanced/atomic-composition.mdx

@@ -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}
 

packages/appearance/docs/en-US/overview.mdx

@@ -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()
+```

packages/appearance/docs/zh-Hans/advanced/atomic-composition.mdx

@@ -57,7 +57,18 @@ toc:
 
 ## 状态连接层 {#connected-layer}
 
-`AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以直接使用 `@workspace/preferences` 的 `usePreference` 读取单个字段，而不必复用默认布局。
+`AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以使用 Appearance 提供的 `useThemeMode`、`useThemeConfig`、`useResolvedTheme` 等 hooks，而不必知道共享偏好的字符串键，也不必复用默认布局。
+
+```tsx
+const [themeConfig, setThemeConfig] = useThemeConfig()
+const resolvedTheme = useResolvedTheme()
+
+<ThemeConfigCard
+  config={themeConfig}
+  onConfigChange={setThemeConfig}
+  scheme={resolvedTheme}
+/>
+```
 
 ## 在线预览 {#live-preview}
 

packages/appearance/docs/zh-Hans/overview.mdx

@@ -9,6 +9,8 @@ toc:
     title: 原子组件
   - id: preferences
     title: 偏好集成
+  - id: hooks
+    title: Hooks
 ---
 
 ## 包的职责 {#package-role}
@@ -66,3 +68,23 @@ export function App() {
 色彩辨识辅助不会给整个页面或图片添加滤镜。它只替换 `destructive` 与 `chart-*` 等语义颜色，并在 `<html>` 上写入 `data-ui-color-vision`，供业务组件添加图标、文字、形状或纹理。关键信息不能只靠颜色表达。
 
 文字、动态效果和亮度同样只通过根节点属性与 CSS 变量实现。导入 Appearance 样式后，现有 UI 组件、Portal 和应用内容都会继承这些设置。
+
+## Hooks {#hooks}
+
+应用不需要知道 Appearance 在共享 store 中使用的字符串键。Package 为每个偏好提供了语义化 hook：`useThemeMode`、`useAccentColor`、`useBaseColor`、`useColorVisionMode`、`useTextScale`、`useMotionMode` 和 `useBrightness`。
+
+组合和解析类 hook 用于更高层的界面：
+
+- `useThemeConfig` 将基础色和强调色作为一个配置读写。
+- `useSystemTheme` 与 `useSystemMotion` 只读取操作系统设置。
+- `useResolvedTheme` 与 `useResolvedMotion` 解析 `system` 后返回最终值。
+- `useToggleTheme` 返回在显式浅色与深色之间切换的回调。
+- `useAppearancePreference` 提供类型安全的底层入口，`useAppearancePreferences` 返回 Appearance 所有偏好的快照。
+
+```tsx
+const [themeMode, setThemeMode] = useThemeMode()
+const [themeConfig, setThemeConfig] = useThemeConfig()
+const resolvedTheme = useResolvedTheme()
+const resolvedMotion = useResolvedMotion()
+const toggleTheme = useToggleTheme()
+```