docs(appearance): add bilingual package guides

2026-09-21 16:05:19 +08:00
parent e2dbbcb884
commit 6711401f5f
9 changed files with 490 additions and 0 deletions
@@ -0,0 +1,41 @@
+---
+title: Atomic composition
+description: Build a custom appearance surface from controlled components without the preset dialog.
+order: 1
+toc:
+  - id: controlled-atoms
+    title: Controlled atoms
+  - id: compose-card
+    title: Compose a theme card
+  - id: connected-layer
+    title: State bindings
+---
+
+## Controlled atoms {#controlled-atoms}
+
+`ThemeModeField`, `CompactLayoutField`, `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} />
+<CompactLayoutField checked={compacted} onCheckedChange={setCompacted} />
+```
+
+## Compose a theme card {#compose-card}
+
+`ThemeConfigCard` combines a preview with base and accent color controls while keeping the configuration owned by the caller.
+
+```tsx
+<ThemeConfigCard
+  active={resolvedTheme === "light"}
+  compacted={compacted}
+  config={lightTheme}
+  onConfigChange={setLightTheme}
+  scheme="light"
+/>
+```
+
+For a more granular layout, compose `ThemePreview`, `baseColorSwatches`, `accentColorSwatches`, and `ThemeColorSwatchButton` directly.
+
+## 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.