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,49 @@
+---
+title: Appearance settings dialog
+description: Compose a trigger, controller, and hotkeys into a complete appearance settings flow.
+order: 1
+toc:
+  - id: controller
+    title: Mount the controller
+  - id: trigger
+    title: Add a trigger
+  - id: custom-handle
+    title: Independent dialog instance
+---
+
+## Mount the controller {#controller}
+
+Mount one `AppearanceController` inside the application's shared `PreferencesProvider`. It composes the default settings content and registers `Mod+,` to open the dialog and `Mod+D` to toggle the theme.
+
+```tsx
+<PreferencesProvider
+  effects={[appearancePreferenceEffect]}
+  initialPreferences={preferences}
+>
+  <AppearanceController />
+  <App />
+</PreferencesProvider>
+```
+
+## Add a trigger {#trigger}
+
+Place `AppearanceDialogTrigger` in a user menu, settings button, or command palette. By default it connects to the handle used by the default controller.
+
+```tsx
+<AppearanceDialogTrigger render={<button type="button" />}>
+  Appearance
+</AppearanceDialogTrigger>
+```
+
+## Independent dialog instance {#custom-handle}
+
+When a page needs an isolated appearance dialog, pass the same new handle to its trigger and controller.
+
+```tsx
+const handle = createAppearanceDialogHandle()
+
+<AppearanceDialogTrigger handle={handle} render={<button type="button" />}>
+  Open theme settings
+</AppearanceDialogTrigger>
+<AppearanceController handle={handle} />
+```