docs(appearance): add bilingual package guides

2026-09-21 16:05:19 +08:00
parent e2dbbcb884
commit 6711401f5f
9 changed files with 490 additions and 0 deletions
@@ -0,0 +1,62 @@
+---
+title: 概览
+description: 了解 Appearance 包的原子组件、主题数据和偏好边界。
+order: 1
+toc:
+  - id: package-role
+    title: 包的职责
+  - id: atomic-components
+    title: 原子组件
+  - id: preferences
+    title: 偏好集成
+---
+
+## 包的职责 {#package-role}
+
+`@workspace/appearance` 提供主题模式、基础色、强调色和紧凑布局所需的定义、副作用、主题数据与界面组件。它不创建自己的 Provider 或 store，而是由应用通过 `@workspace/preferences` 与其他偏好 package 统一聚合。
+
+## 原子组件 {#atomic-components}
+
+受控组件可以独立组合，不依赖偏好上下文：
+
+- `ThemeModeField` 选择浅色、深色或跟随系统。
+- `CompactLayoutField` 切换主内容宽度。
+- `ThemeColorPicker` 与 `ThemeColorSwatchButton` 选择主题颜色。
+- `ThemePreview` 预览一组主题变量。
+- `ThemeConfigCard` 组合预览、基础色与强调色设置。
+- `ThemeToggle` 在浅色和深色主题之间切换。
+
+`AppearanceSettings`、`AppearanceDialog` 与 `AppearanceController` 是建立在这些原子组件之上的可选组合层。
+
+## 偏好集成 {#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>
+  )
+}
+```
+
+把语言、快捷键等 package 的 definitions 和 effects 添加到相同对象即可。应用可以通过共享的 `onPreferenceChange` 持久化所有 `{ key, value }` 更新，并在服务端使用聚合后的 definitions 解析 Cookie。