feat(docs): add appearance sandbox example

bun.lock

@@ -55,6 +55,7 @@
       "version": "0.0.0",
       "dependencies": {
         "@icones/react": "^0.0.1",
+        "@workspace/appearance": "workspace:*",
         "@workspace/i18n": "workspace:*",
         "@workspace/media": "workspace:*",
         "@workspace/preferences": "workspace:*",

docs/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@icones/react": "^0.0.1",
+    "@workspace/appearance": "workspace:*",
     "@workspace/i18n": "workspace:*",
     "@workspace/media": "workspace:*",
     "@workspace/preferences": "workspace:*",

docs/src/index.css

@@ -1,4 +1,5 @@
 @import "@workspace/ui/globals.css";
+@import "@workspace/appearance/globals.css";
 @import "@workspace/media/globals.css";
 @import "@workspace/search/globals.css";
 

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

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

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

@@ -0,0 +1,19 @@
+import React from "react"
+import { ThemePreview } from "@workspace/appearance/components/theme-preview"
+import type { ThemeColorConfig } from "@workspace/appearance/theme"
+
+import { AccentPicker } from "./AccentPicker"
+
+export default function ThemeColorsExample() {
+  const [config, setConfig] = React.useState<ThemeColorConfig>({
+    accentColor: "indigo",
+    baseColor: "neutral",
+  })
+
+  return (
+    <div className="mx-auto flex max-w-xl flex-col gap-6">
+      <ThemePreview config={config} scheme="light" />
+      <AccentPicker config={config} onConfigChange={setConfig} />
+    </div>
+  )
+}

docs/src/sandboxes/appearance/theme-toggle/sandbox.ts

@@ -0,0 +1,12 @@
+import { defineSandbox } from "../../../components/sandbox"
+
+export default defineSandbox({
+  id: "appearance/theme-colors",
+  title: "Controlled theme colors",
+  entry: () => import("./App"),
+  files: {
+    "App.tsx": () => import("./App.tsx?raw"),
+    "AccentPicker.tsx": () => import("./AccentPicker.tsx?raw"),
+  },
+  defaultFile: "App.tsx",
+})

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

@@ -9,6 +9,8 @@ toc:
     title: Compose a theme card
   - id: connected-layer
     title: State bindings
+  - id: live-preview
+    title: Live preview
 ---
 
 ## Controlled atoms {#controlled-atoms}
@@ -39,3 +41,18 @@ For a more granular layout, compose `ThemePreview`, `baseColorSwatches`, `accent
 ## State bindings {#connected-layer}
 
 `AppearanceSettings` is the default binding layer between the atoms and the shared `PreferencesProvider`. A custom surface can call `usePreference` from `@workspace/preferences` for individual values without reusing the default layout.
+
+## Live preview {#live-preview}
+
+The documentation Sandbox can load a typed, multi-file example without embedding implementation details in MDX:
+
+<Sandbox example="appearance/theme-colors" title="Theme color controls" />
+
+For a single file, import the component and its raw source directly instead of creating a manifest:
+
+```mdx
+import Demo from "./Demo"
+import source from "./Demo.tsx?raw"
+
+<SingleFileSandbox component={Demo} filename="Demo.tsx" source={source} />
+```

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

@@ -9,6 +9,8 @@ toc:
     title: 组合主题卡片
   - id: connected-layer
     title: 状态连接层
+  - id: live-preview
+    title: 在线预览
 ---
 
 ## 受控原子组件 {#controlled-atoms}
@@ -39,3 +41,18 @@ toc:
 ## 状态连接层 {#connected-layer}
 
 `AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以直接使用 `@workspace/preferences` 的 `usePreference` 读取单个字段，而不必复用默认布局。
+
+## 在线预览 {#live-preview}
+
+文档 Sandbox 可以加载通过类型检查的多文件示例，而不需要把实现细节内联到 MDX：
+
+<Sandbox example="appearance/theme-colors" title="主题颜色控件" />
+
+单文件示例不需要创建 Manifest，直接导入组件和原始源码即可：
+
+```mdx
+import Demo from "./Demo"
+import source from "./Demo.tsx?raw"
+
+<SingleFileSandbox component={Demo} filename="Demo.tsx" source={source} />
+```