From 4710a5624228003373ef5c609825b06f1bec8c21 Mon Sep 17 00:00:00 2001
From: Maofeng <hornjs@qq.com>
Date: Tue, 29 Sep 2026 20:58:46 +0800
Subject: [PATCH] docs(appearance): document display preferences

---
 .../en-US/advanced/atomic-composition.mdx     | 15 ++++++-------
 .../appearance/docs/en-US/guide/setup.mdx     | 21 ++++++++++++++++---
 packages/appearance/docs/en-US/overview.mdx   | 11 ++++++++--
 .../zh-Hans/advanced/atomic-composition.mdx   | 15 ++++++-------
 .../appearance/docs/zh-Hans/guide/setup.mdx   | 21 ++++++++++++++++---
 packages/appearance/docs/zh-Hans/overview.mdx | 11 ++++++++--
 6 files changed, 70 insertions(+), 24 deletions(-)

diff --git a/packages/appearance/docs/en-US/advanced/atomic-composition.mdx b/packages/appearance/docs/en-US/advanced/atomic-composition.mdx
index 2cbcde0..7c7a9f3 100644
--- a/packages/appearance/docs/en-US/advanced/atomic-composition.mdx
+++ b/packages/appearance/docs/en-US/advanced/atomic-composition.mdx
@@ -15,11 +15,14 @@ toc:
 
 ## Controlled atoms {#controlled-atoms}
 
-`ThemeModeField`, `CompactLayoutField`, `ThemeColorPicker`, and `ThemeToggle` are driven by values and callbacks. They do not require preference context, so they can work with forms, preview tools, or another state library.
+`ThemeModeField`, `ColorVisionModeField`, `TextScaleField`, `MotionModeField`, `BrightnessField`, `ThemeColorPicker`, and `ThemeToggle` are driven by values and callbacks. They do not require preference context, so they can work with forms, preview tools, or another state library.
 
 ```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 a theme card {#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}
 />
 ```
 
diff --git a/packages/appearance/docs/en-US/guide/setup.mdx b/packages/appearance/docs/en-US/guide/setup.mdx
index 38088c5..9a65f73 100644
--- a/packages/appearance/docs/en-US/guide/setup.mdx
+++ b/packages/appearance/docs/en-US/guide/setup.mdx
@@ -17,6 +17,13 @@ toc:
 
 Build one complete preference definition map at the application boundary. Spread definitions from appearance, locale, keyboard, and other feature packages into this map, then create or load the initial values.
 
+Import Appearance after UI in the application stylesheet. No UI component changes are required:
+
+```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 }) {
 
 ## Register effects {#effects}
 
-`appearancePreferenceEffect` combines two exported callbacks: `applyAppearancePreferenceEffect` updates document classes and theme variables before paint, while `subscribeSystemThemePreferenceEffect` watches the operating-system theme after paint. Register the composed effect in the stable `effects` array passed to `PreferencesProvider`.
+`appearancePreferenceEffect` updates document classes, root attributes, and theme variables before paint, then watches operating-system theme and motion preferences after paint. Register it in the stable `effects` array passed to `PreferencesProvider`.
 
 ## Inject theme variables {#theme-style}
 
-Use `buildThemeStyleSheet` to generate the CSS variables for light, dark, and system modes. Keep the stable element ID so the appearance effect can update the same node when color preferences change.
+Use `buildThemeStyleSheet` to generate light and dark CSS variables from one base color, one accent color, and a color-vision mode. Keep the stable element ID so the appearance effect can update the same node when preferences change.
 
 ```tsx
 import {
@@ -69,11 +76,19 @@ import {
 ;<style
   id={THEME_STYLE_ELEMENT_ID}
   dangerouslySetInnerHTML={{
-    __html: buildThemeStyleSheet(themeLight, themeDark),
+    __html: buildThemeStyleSheet(
+      { baseColor, accentColor },
+      colorVisionMode,
+      brightness
+    ),
   }}
 />
 ```
 
+Assistance modes adjust chart and destructive semantic colors and set `data-ui-color-vision`. They are not color-vision simulators and do not transform photos, video, or brand assets.
+
+Text scaling changes the root font size through `data-ui-text-scale`; reduced motion shortens global animation through `data-ui-motion` while preserving low-motion loading feedback; brightness adjusts theme surface variables without using `filter: brightness()`.
+
 ## Persist updates {#persistence}
 
 The shared `onPreferenceChange` receives a typed `{ key, value }` only when a value actually changes. Forward it to a server function or cookie writer owned by the application.
diff --git a/packages/appearance/docs/en-US/overview.mdx b/packages/appearance/docs/en-US/overview.mdx
index 72d9d49..891a81f 100644
--- a/packages/appearance/docs/en-US/overview.mdx
+++ b/packages/appearance/docs/en-US/overview.mdx
@@ -13,14 +13,17 @@ toc:
 
 ## Package role {#package-role}
 
-`@workspace/appearance` provides the definitions, effects, theme data, and UI components for theme modes, base colors, accent colors, and compact layouts. It does not create its own provider or store. The application aggregates it with other preference packages through `@workspace/preferences`.
+`@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.
-- `CompactLayoutField` toggles the main content width.
+- `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.
 - `ThemePreview` previews a set of theme variables.
 - `ThemeConfigCard` combines the preview, base color, and accent color controls.
@@ -60,3 +63,7 @@ export function App() {
 ```
 
 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.
diff --git a/packages/appearance/docs/zh-Hans/advanced/atomic-composition.mdx b/packages/appearance/docs/zh-Hans/advanced/atomic-composition.mdx
index e053648..919dbf1 100644
--- a/packages/appearance/docs/zh-Hans/advanced/atomic-composition.mdx
+++ b/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}
 />
 ```
 
diff --git a/packages/appearance/docs/zh-Hans/guide/setup.mdx b/packages/appearance/docs/zh-Hans/guide/setup.mdx
index bc74756..17b2eaa 100644
--- a/packages/appearance/docs/zh-Hans/guide/setup.mdx
+++ b/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 写入器。
diff --git a/packages/appearance/docs/zh-Hans/overview.mdx b/packages/appearance/docs/zh-Hans/overview.mdx
index 7b41048..6c92dca 100644
--- a/packages/appearance/docs/zh-Hans/overview.mdx
+++ b/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 和应用内容都会继承这些设置。