docs(appearance): document control variants

2026-09-29 21:29:49 +08:00
parent 983ebead02
commit 352db2c4c0
6 changed files with 49 additions and 12 deletions
@@ -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 })
      }
@@ -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>
  )
 }
@@ -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}

@@ -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 preview, base color, and accent color controls.
+- `ThemeConfigCard` combines the 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.
@@ -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}

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

 `AppearanceSettings`、`AppearanceDialog` 与 `AppearanceController` 是建立在这些原子组件之上的可选组合层。