docs(appearance): document display preferences

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

@@ -15,11 +15,14 @@ toc:
 
 ## 受控原子组件 {#controlled-atoms}
 
-`ThemeModeField`、`CompactLayoutField`、`ThemeColorPicker` 和 `ThemeToggle` 都由 `value` 与回调驱动。它们不要求使用偏好上下文，因此可以接入表单、预览工具或其他状态库。
+`ThemeModeField`、`ColorVisionModeField`、`TextScaleField`、`MotionModeField`、`BrightnessField`、`ThemeColorPicker` 和 `ThemeToggle` 都由 `value` 与回调驱动。它们不要求使用偏好上下文，因此可以接入表单、预览工具或其他状态库。
 
 ```tsx
 <ThemeModeField value={mode} onValueChange={setMode} />
-<CompactLayoutField checked={compacted} onCheckedChange={setCompacted} />
+<ColorVisionModeField value={colorVisionMode} onValueChange={setColorVisionMode} />
+<TextScaleField value={textScale} onValueChange={setTextScale} />
+<MotionModeField value={motionMode} onValueChange={setMotionMode} />
+<BrightnessField value={brightness} onValueChange={setBrightness} />
 ```
 
 ## 组合主题卡片 {#compose-card}
@@ -28,11 +31,9 @@ toc:
 
 ```tsx
 <ThemeConfigCard
-  active={resolvedTheme === "light"}
-  compacted={compacted}
-  config={lightTheme}
-  onConfigChange={setLightTheme}
-  scheme="light"
+  config={{ baseColor, accentColor }}
+  onConfigChange={setThemeColors}
+  scheme={resolvedTheme}
 />
 ```
 

packages/appearance/docs/zh-Hans/guide/setup.mdx

@@ -17,6 +17,13 @@ toc:
 
 在应用边界构建一份完整的偏好定义。把外观、语言、快捷键等功能 package 的 definitions 合并，再创建默认值或从服务端加载初始值。
 
+在应用样式中于 UI 之后导入 Appearance，无需修改任何 UI 组件：
+
+```css
+@import "@workspace/ui/globals.css";
+@import "@workspace/appearance/globals.css";
+```
+
 ```tsx
 import {
   createDefaultPreferences,
@@ -54,11 +61,11 @@ export function Root({ children }: { children: React.ReactNode }) {
 
 ## 注册副作用 {#effects}
 
-`appearancePreferenceEffect` 组合了两个公开回调：`applyAppearancePreferenceEffect` 在浏览器绘制前更新文档类名和主题变量，`subscribeSystemThemePreferenceEffect` 在绘制后监听操作系统主题。把组合后的 effect 放进传给 `PreferencesProvider` 的稳定 `effects` 数组中。
+`appearancePreferenceEffect` 在浏览器绘制前更新文档类名、根节点属性和主题变量，并在绘制后监听操作系统主题与动态效果偏好。把组合后的 effect 放进传给 `PreferencesProvider` 的稳定 `effects` 数组中。
 
 ## 注入主题变量 {#theme-style}
 
-使用 `buildThemeStyleSheet` 生成浅色、深色以及跟随系统时使用的 CSS 变量。保留固定的元素 ID 后，外观 effect 可以在颜色偏好变化时更新同一个节点。
+使用 `buildThemeStyleSheet` 根据一组基础色、强调色以及色彩辨识模式生成浅色和深色 CSS 变量。保留固定的元素 ID 后，外观 effect 可以在偏好变化时更新同一个节点。
 
 ```tsx
 import {
@@ -69,11 +76,19 @@ import {
 ;<style
   id={THEME_STYLE_ELEMENT_ID}
   dangerouslySetInnerHTML={{
-    __html: buildThemeStyleSheet(themeLight, themeDark),
+    __html: buildThemeStyleSheet(
+      { baseColor, accentColor },
+      colorVisionMode,
+      brightness
+    ),
   }}
 />
 ```
 
+辅助模式会调整需要区分的图表与破坏性语义色，并设置 `data-ui-color-vision`。它不是色觉模拟器，也不会改变照片、视频或品牌资产。
+
+文字缩放通过 `data-ui-text-scale` 改变根字号；减少动态效果通过 `data-ui-motion` 缩短全局动画，并为加载状态保留低运动反馈；亮度只调整主题表面变量，不使用 `filter: brightness()`。
+
 ## 持久化更新 {#persistence}
 
 共享的 `onPreferenceChange` 只在值实际变化时收到类型安全的 `{ key, value }`。应用可以把它交给服务端函数或 Cookie 写入器。

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

@@ -13,14 +13,17 @@ toc:
 
 ## 包的职责 {#package-role}
 
-`@workspace/appearance` 提供主题模式、基础色、强调色和紧凑布局所需的定义、副作用、主题数据与界面组件。它不创建自己的 Provider 或 store，而是由应用通过 `@workspace/preferences` 与其他偏好 package 统一聚合。
+`@workspace/appearance` 负责主题模式、基础色、强调色、色彩辨识、文字缩放、动态效果和界面亮度。它不创建自己的 Provider 或 store，也不要求修改 `@workspace/ui`；应用通过 `@workspace/preferences` 与其他偏好 package 统一聚合。
 
 ## 原子组件 {#atomic-components}
 
 受控组件可以独立组合，不依赖偏好上下文：
 
 - `ThemeModeField` 选择浅色、深色或跟随系统。
-- `CompactLayoutField` 切换主内容宽度。
+- `ColorVisionModeField` 选择标准、Protan、Deutan 或 Tritan 辅助色板。
+- `TextScaleField` 将界面缩放到 100%、125%、150% 或 200%。
+- `MotionModeField` 跟随系统、减少动态效果或启用完整动效。
+- `BrightnessField` 选择柔暗、标准或明亮的界面表面。
 - `ThemeColorPicker` 与 `ThemeColorSwatchButton` 选择主题颜色。
 - `ThemePreview` 预览一组主题变量。
 - `ThemeConfigCard` 组合预览、基础色与强调色设置。
@@ -60,3 +63,7 @@ export function App() {
 ```
 
 把语言、快捷键等 package 的 definitions 和 effects 添加到相同对象即可。应用可以通过共享的 `onPreferenceChange` 持久化所有 `{ key, value }` 更新，并在服务端使用聚合后的 definitions 解析 Cookie。
+
+色彩辨识辅助不会给整个页面或图片添加滤镜。它只替换 `destructive` 与 `chart-*` 等语义颜色，并在 `<html>` 上写入 `data-ui-color-vision`，供业务组件添加图标、文字、形状或纹理。关键信息不能只靠颜色表达。
+
+文字、动态效果和亮度同样只通过根节点属性与 CSS 变量实现。导入 Appearance 样式后，现有 UI 组件、Portal 和应用内容都会继承这些设置。