From 352db2c4c0421285fbfcf301b588059a04ec1f1d Mon Sep 17 00:00:00 2001 From: Maofeng Date: Tue, 29 Sep 2026 21:29:49 +0800 Subject: [PATCH] docs(appearance): document control variants --- .../appearance/theme-toggle/AccentPicker.tsx | 4 ++++ .../sandboxes/appearance/theme-toggle/App.tsx | 7 ++++-- .../en-US/advanced/atomic-composition.mdx | 22 ++++++++++++++++--- packages/appearance/docs/en-US/overview.mdx | 3 +-- .../zh-Hans/advanced/atomic-composition.mdx | 22 ++++++++++++++++--- packages/appearance/docs/zh-Hans/overview.mdx | 3 +-- 6 files changed, 49 insertions(+), 12 deletions(-) diff --git a/docs/src/sandboxes/appearance/theme-toggle/AccentPicker.tsx b/docs/src/sandboxes/appearance/theme-toggle/AccentPicker.tsx index 417c11b..6d14402 100644 --- a/docs/src/sandboxes/appearance/theme-toggle/AccentPicker.tsx +++ b/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 ( onConfigChange({ ...config, accentColor }) } diff --git a/docs/src/sandboxes/appearance/theme-toggle/App.tsx b/docs/src/sandboxes/appearance/theme-toggle/App.tsx index c954050..94d427c 100644 --- a/docs/src/sandboxes/appearance/theme-toggle/App.tsx +++ b/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 (
- +
) } diff --git a/packages/appearance/docs/en-US/advanced/atomic-composition.mdx b/packages/appearance/docs/en-US/advanced/atomic-composition.mdx index 7c7a9f3..27d3204 100644 --- a/packages/appearance/docs/en-US/advanced/atomic-composition.mdx +++ b/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 + + ``` +`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 ``` -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 + +``` ## State bindings {#connected-layer} diff --git a/packages/appearance/docs/en-US/overview.mdx b/packages/appearance/docs/en-US/overview.mdx index 891a81f..9529aee 100644 --- a/packages/appearance/docs/en-US/overview.mdx +++ b/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 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. diff --git a/packages/appearance/docs/zh-Hans/advanced/atomic-composition.mdx b/packages/appearance/docs/zh-Hans/advanced/atomic-composition.mdx index 919dbf1..0069229 100644 --- a/packages/appearance/docs/zh-Hans/advanced/atomic-composition.mdx +++ b/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 + + ``` +`AppearanceOptionList` 提供 `TextScaleOptionList` 使用的通用单选列表。向 `items` 传入 `value`、`label`、可选 `icon` 与 `description`，即可用相同风格实现主题、动态效果、色彩辨识和亮度选择器。组件使用原生 radio，自动支持键盘导航与表单语义。 + ## 组合主题卡片 {#compose-card} -`ThemeConfigCard` 把预览、基础色和强调色选择组合在一起，但仍由调用方持有配置。 +`ThemeConfigCard` 把基础色和强调色选择组合在一起，但仍由调用方持有配置。 ```tsx ``` -需要更细粒度的布局时，可以分别使用 `ThemePreview`、`baseColorSwatches`、`accentColorSwatches` 和 `ThemeColorSwatchButton`。 +需要更细粒度的布局时，可以分别使用 `baseColorSwatches`、`accentColorSwatches` 和 `ThemeColorSwatchButton`。 + +`ThemeColorPicker` 默认使用带文字的 `pill` 样式；空间紧凑时可切换为仅显示颜色和选中标记的 `swatch` 样式： + +```tsx + +``` ## 状态连接层 {#connected-layer} diff --git a/packages/appearance/docs/zh-Hans/overview.mdx b/packages/appearance/docs/zh-Hans/overview.mdx index 6c92dca..35ae7f7 100644 --- a/packages/appearance/docs/zh-Hans/overview.mdx +++ b/packages/appearance/docs/zh-Hans/overview.mdx @@ -25,8 +25,7 @@ toc: - `MotionModeField` 跟随系统、减少动态效果或启用完整动效。 - `BrightnessField` 选择柔暗、标准或明亮的界面表面。 - `ThemeColorPicker` 与 `ThemeColorSwatchButton` 选择主题颜色。 -- `ThemePreview` 预览一组主题变量。 -- `ThemeConfigCard` 组合预览、基础色与强调色设置。 +- `ThemeConfigCard` 组合基础色与强调色设置。 - `ThemeToggle` 在浅色和深色主题之间切换。 `AppearanceSettings`、`AppearanceDialog` 与 `AppearanceController` 是建立在这些原子组件之上的可选组合层。