docs(appearance): document display preferences

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.