docs(appearance): document control variants

docs/src/sandboxes/appearance/theme-toggle/AccentPicker.tsx

@@ -1,21 +1,25 @@
 import {
   ThemeColorPicker,
   accentColorSwatches,
+  type ThemeColorPickerVariant,
 } from "@workspace/appearance/components/theme-color-picker"
 import type { ThemeColorConfig } from "@workspace/appearance/theme"
 
 export function AccentPicker({
   config,
   onConfigChange,
+  variant,
 }: {
   config: ThemeColorConfig
   onConfigChange: (config: ThemeColorConfig) => void
+  variant?: ThemeColorPickerVariant
 }) {
   return (
     <ThemeColorPicker
       title="Accent color"
       swatches={accentColorSwatches}
       value={config.accentColor}
+      variant={variant}
       onValueChange={(accentColor) =>
         onConfigChange({ ...config, accentColor })
       }

docs/src/sandboxes/appearance/theme-toggle/App.tsx

@@ -1,5 +1,4 @@
 import React from "react"
-import { ThemePreview } from "@workspace/appearance/components/theme-preview"
 import type { ThemeColorConfig } from "@workspace/appearance/theme"
 
 import { AccentPicker } from "./AccentPicker"
@@ -12,8 +11,12 @@ export default function ThemeColorsExample() {
 
   return (
     <div className="mx-auto flex max-w-xl flex-col gap-6">
-      <ThemePreview config={config} scheme="light" />
       <AccentPicker config={config} onConfigChange={setConfig} />
+      <AccentPicker
+        config={config}
+        variant="swatch"
+        onConfigChange={setConfig}
+      />
     </div>
   )
 }

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

@@ -15,19 +15,23 @@ toc:
 
 ## Controlled atoms {#controlled-atoms}
 
-`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.
+`ThemeModeField`, `ThemeModeOptionList`, `ColorVisionModeField`, `TextScaleField`, `TextScaleOptionList`, `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} />
+<ThemeModeOptionList value={mode} onValueChange={setMode} />
 <ColorVisionModeField value={colorVisionMode} onValueChange={setColorVisionMode} />
 <TextScaleField value={textScale} onValueChange={setTextScale} />
 <MotionModeField value={motionMode} onValueChange={setMotionMode} />
 <BrightnessField value={brightness} onValueChange={setBrightness} />
+<TextScaleOptionList value={textScale} onValueChange={setTextScale} />
 ```
 
+`AppearanceOptionList` is the reusable radio list behind `TextScaleOptionList`. Give its `items` a `value`, `label`, and optional `icon` and `description` to build theme, motion, color-vision, or brightness selectors with the same presentation. It uses native radio inputs for keyboard navigation and form semantics.
+
 ## Compose a theme card {#compose-card}
 
-`ThemeConfigCard` combines a preview with base and accent color controls while keeping the configuration owned by the caller.
+`ThemeConfigCard` combines base and accent color controls while keeping the configuration owned by the caller.
 
 ```tsx
 <ThemeConfigCard
@@ -37,7 +41,19 @@ toc:
 />
 ```
 
-For a more granular layout, compose `ThemePreview`, `baseColorSwatches`, `accentColorSwatches`, and `ThemeColorSwatchButton` directly.
+For a more granular layout, compose `baseColorSwatches`, `accentColorSwatches`, and `ThemeColorSwatchButton` directly.
+
+`ThemeColorPicker` uses the labeled `pill` style by default. For tighter layouts, switch to the color-only `swatch` style with its selected indicator:
+
+```tsx
+<ThemeColorPicker
+  title="Accent color"
+  swatches={accentColorSwatches}
+  value={accentColor}
+  variant="swatch"
+  onValueChange={setAccentColor}
+/>
+```
 
 ## State bindings {#connected-layer}
 

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

@@ -25,8 +25,7 @@ The controlled components can be composed independently without preference conte
 - `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 base color and accent color controls.
-- `ThemeConfigCard` combines the preview, base color, and accent color controls.
 - `ThemeToggle` switches between light and dark themes.
 
 `AppearanceSettings`, `AppearanceDialog`, and `AppearanceController` are optional composition layers built from these atoms.

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

@@ -15,19 +15,23 @@ toc:
 
 ## 受控原子组件 {#controlled-atoms}
 
-`ThemeModeField`、`ColorVisionModeField`、`TextScaleField`、`MotionModeField`、`BrightnessField`、`ThemeColorPicker` 和 `ThemeToggle` 都由 `value` 与回调驱动。它们不要求使用偏好上下文，因此可以接入表单、预览工具或其他状态库。
+`ThemeModeField`、`ThemeModeOptionList`、`ColorVisionModeField`、`TextScaleField`、`TextScaleOptionList`、`MotionModeField`、`BrightnessField`、`ThemeColorPicker` 和 `ThemeToggle` 都由 `value` 与回调驱动。它们不要求使用偏好上下文，因此可以接入表单、预览工具或其他状态库。
 
 ```tsx
 <ThemeModeField value={mode} onValueChange={setMode} />
+<ThemeModeOptionList value={mode} onValueChange={setMode} />
 <ColorVisionModeField value={colorVisionMode} onValueChange={setColorVisionMode} />
 <TextScaleField value={textScale} onValueChange={setTextScale} />
 <MotionModeField value={motionMode} onValueChange={setMotionMode} />
 <BrightnessField value={brightness} onValueChange={setBrightness} />
+<TextScaleOptionList value={textScale} onValueChange={setTextScale} />
 ```
 
+`AppearanceOptionList` 提供 `TextScaleOptionList` 使用的通用单选列表。向 `items` 传入 `value`、`label`、可选 `icon` 与 `description`，即可用相同风格实现主题、动态效果、色彩辨识和亮度选择器。组件使用原生 radio，自动支持键盘导航与表单语义。
+
 ## 组合主题卡片 {#compose-card}
 
-`ThemeConfigCard` 把预览、基础色和强调色选择组合在一起，但仍由调用方持有配置。
+`ThemeConfigCard` 把基础色和强调色选择组合在一起，但仍由调用方持有配置。
 
 ```tsx
 <ThemeConfigCard
@@ -37,7 +41,19 @@ toc:
 />
 ```
 
-需要更细粒度的布局时，可以分别使用 `ThemePreview`、`baseColorSwatches`、`accentColorSwatches` 和 `ThemeColorSwatchButton`。
+需要更细粒度的布局时，可以分别使用 `baseColorSwatches`、`accentColorSwatches` 和 `ThemeColorSwatchButton`。
+
+`ThemeColorPicker` 默认使用带文字的 `pill` 样式；空间紧凑时可切换为仅显示颜色和选中标记的 `swatch` 样式：
+
+```tsx
+<ThemeColorPicker
+  title="强调色"
+  swatches={accentColorSwatches}
+  value={accentColor}
+  variant="swatch"
+  onValueChange={setAccentColor}
+/>
+```
 
 ## 状态连接层 {#connected-layer}
 

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

@@ -25,8 +25,7 @@ toc:
 - `MotionModeField` 跟随系统、减少动态效果或启用完整动效。
 - `BrightnessField` 选择柔暗、标准或明亮的界面表面。
 - `ThemeColorPicker` 与 `ThemeColorSwatchButton` 选择主题颜色。
-- `ThemePreview` 预览一组主题变量。
+- `ThemeConfigCard` 组合基础色与强调色设置。
-- `ThemeConfigCard` 组合预览、基础色与强调色设置。
 - `ThemeToggle` 在浅色和深色主题之间切换。
 
 `AppearanceSettings`、`AppearanceDialog` 与 `AppearanceController` 是建立在这些原子组件之上的可选组合层。