@gjsify/adwaita-storybook 0.37.0 → 0.38.0

package/lib/types/app.d.ts

@@ -17,6 +17,15 @@ export declare class StorybookWebApp implements StorybookView<StoryElement> {
     private _controller;
     private _options;
     private _container;
+    /**
+     * Colour scheme + accent for the whole storybook, not for one story.
+     *
+     * Scoped to the storybook's own container rather than `documentElement`: this
+     * app is EMBEDDED by the website, and stamping `.theme-dark` on the document
+     * would re-theme the host page around it. `_theme.scss` scopes on the class
+     * wherever it sits, so a subtree works.
+     */
+    private _appearance;
     private _listEl;
     private _previewEl;
     private _previewTitle;

package/lib/types/appearance.d.ts

@@ -0,0 +1,15 @@
+import { StorybookSettings } from '@gjsify/storybook-core';
+/** Owns the browser side of {@link StorybookSettings}: the theme scope and the accent. */
+export declare class StorybookWebAppearance {
+    readonly settings: StorybookSettings;
+    private readonly _root;
+    constructor(root?: HTMLElement);
+    private _apply;
+}
+/**
+ * The appearance dialog: the colour scheme, and the accent behind a switch.
+ *
+ * Built once and reused — unlike the GTK `Adw.Dialog`, `<adw-preferences-dialog>`
+ * reopens after a dismissal, so there is nothing to rebuild.
+ */
+export declare function buildAppearanceDialog(appearance: StorybookWebAppearance): HTMLElement;

package/lib/types/styles.d.ts

@@ -1,3 +1,3 @@
-export declare const STORYBOOK_WEB_CSS = "\n.sb-window {\n    width: 100%;\n    height: 100%;\n    min-width: 0;\n    min-height: 0;\n}\n\n/* Each pane in the outer split view is a flex column that fills its height. */\n.sb-sidebar-pane,\n.sb-content-pane {\n    display: flex;\n    flex-direction: column;\n    min-height: 0;\n    min-width: 0;\n    flex: 1 1 auto;\n}\n\n/* The toolbar-view content holds either a scroller (sidebar) or the split view\n   (content); the inner panes own the scrolling, so this level never scrolls. */\n.sb-sidebar-pane adw-toolbar-view > .adw-toolbar-view-content,\n.sb-content-pane adw-toolbar-view > .adw-toolbar-view-content {\n    overflow: hidden;\n}\n\n/* Background scheme: the content header + preview + controls all sit on the\n   window (story) background as one surface; only the left story-list column\n   (its header + list) keeps the distinct sidebar shade. Matches the native\n   renderer. The default adw-header-bar background is its own headerbar shade,\n   so override it per pane here. */\n.sb-content-pane adw-header-bar {\n    background-color: var(--window-bg-color);\n}\n.sb-sidebar-pane adw-header-bar {\n    background-color: var(--sidebar-bg-color);\n}\n\n.sb-sidebar-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    overflow-y: auto;\n    background-color: var(--sidebar-bg-color);\n}\n\n/* --- Story list (mirrors GTK .navigation-sidebar) --- */\n.sb-sidebar-list {\n    padding: var(--spacing-xs);\n    display: flex;\n    flex-direction: column;\n    gap: 1px;\n}\n\n.sb-category {\n    font-size: var(--font-size-small);\n    font-weight: 700;\n    opacity: var(--dim-opacity);\n    padding: 10px var(--spacing-m) 4px;\n}\n\n.sb-story-row {\n    padding: var(--spacing-xs) var(--spacing-m);\n    margin: 0 var(--spacing-xs);\n    border-radius: var(--button-radius);\n    cursor: pointer;\n    color: var(--window-fg-color);\n    font-size: var(--font-size-base);\n    white-space: nowrap;\n    overflow: hidden;\n    text-overflow: ellipsis;\n}\n\n.sb-story-row:hover {\n    background-color: var(--button-bg-color);\n}\n\n.sb-story-row.selected {\n    background-color: var(--accent-bg-color);\n    color: var(--accent-fg-color);\n}\n\n/* --- Preview area --- */\n.sb-preview-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    min-width: 0;\n    overflow: auto;\n    background-color: var(--window-bg-color);\n}\n\n.sb-story-page {\n    display: flex;\n    justify-content: center;\n    padding: var(--spacing-xl) var(--spacing-m);\n    min-height: 100%;\n    box-sizing: border-box;\n}\n\n.sb-story-clamp {\n    width: 100%;\n    max-width: 600px;\n}\n\n.sb-story-group-header {\n    padding: var(--spacing-xs) 2px;\n    display: flex;\n    flex-direction: column;\n    gap: 2px;\n}\n\n.sb-story-group-title {\n    font-size: var(--font-size-heading);\n    font-weight: 700;\n    color: var(--window-fg-color);\n}\n\n.sb-story-group-description {\n    font-size: var(--font-size-base);\n    opacity: var(--dim-opacity);\n    color: var(--window-fg-color);\n}\n\n/* Centered, dashed-framed preview stage (mirrors the native .story-stage). */\n.story-stage {\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    justify-content: center;\n    gap: var(--spacing-m);\n    padding: var(--spacing-l);\n    margin-top: var(--spacing-s);\n    border: 1px dashed rgba(127, 127, 127, 0.28);\n    border-radius: var(--card-radius);\n    min-height: 80px;\n}\n\n/* --- Controls panel --- */\n.sb-controls-scroll {\n    height: 100%;\n    overflow-y: auto;\n    background-color: var(--window-bg-color);\n}\n\n.sb-controls-page {\n    padding: var(--spacing-l);\n}\n\n/* Range-control card (mirrors the native .story-range-row). */\n.sb-range-row {\n    display: flex;\n    flex-direction: column;\n    gap: var(--spacing-xs);\n    padding: var(--spacing-m);\n    border-bottom: 1px solid var(--card-shade-color);\n}\n\n.sb-range-row:last-child {\n    border-bottom: none;\n}\n\n.sb-range-header {\n    display: flex;\n    justify-content: space-between;\n    align-items: baseline;\n    gap: var(--spacing-m);\n}\n\n.sb-range-title {\n    font-size: var(--font-size-base);\n    font-weight: 700;\n    color: var(--card-fg-color);\n}\n\n.sb-range-value {\n    font-size: var(--font-size-base);\n    font-variant-numeric: tabular-nums;\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-description {\n    font-size: var(--font-size-small);\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-input {\n    width: 100%;\n    accent-color: var(--accent-bg-color);\n}\n\n.sb-color-input {\n    width: 42px;\n    height: 28px;\n    padding: 0;\n    border: 1px solid var(--card-shade-color);\n    border-radius: var(--button-radius);\n    background: none;\n    cursor: pointer;\n}\n";
+export declare const STORYBOOK_WEB_CSS = "\n/* Appearance dialog \u2014 round swatches with a selection ring. The web twin of the GTK\n   renderer's rules, themselves adapted from Learn6502.\n\n   The CARD is not decoration: in the dark scheme the \"dark\" swatch is a near-black\n   circle on a near-black dialog and is invisible without a lighter surface behind\n   it. Centring happens INSIDE the full-width card, so the row does not read as\n   left-aligned under the group title. */\n.sb-swatch-card {\n    display: flex;\n    flex-wrap: wrap;\n    justify-content: center;\n    gap: 8px;\n    padding: 12px;\n}\n/* Squaring the card's top alone leaves a notch: the row above lives in the group's\n   own rounded list, so BOTH sides have to be squared for the join to read as one\n   list. The attached card and the group rule below are the two halves of that. */\n.sb-swatch-card--attached {\n    border-top-left-radius: 0;\n    border-top-right-radius: 0;\n}\n.sb-attached-group .boxed-list {\n    border-bottom-left-radius: 0;\n    border-bottom-right-radius: 0;\n}\n/* Desaturated rather than merely dimmed: while the accent follows the desktop the\n   palette must read as unavailable, not as nine slightly faded choices. */\n.sb-swatch-card--disabled {\n    filter: saturate(0.4) brightness(1.05);\n    opacity: 0.7;\n}\n/* A radio input, so grouping and arrow-key navigation are the platform's. Its own\n   glyph is switched off because the swatch IS the indicator \u2014 a dot drawn on a\n   colour competes with the ring that already says which one is selected. */\n.sb-swatch {\n    appearance: none;\n    -webkit-appearance: none;\n    margin: 0;\n    width: 24px;\n    height: 24px;\n    border-radius: 9999px;\n    box-shadow: 0 0 0 3px transparent;\n    cursor: pointer;\n    /* A hairline on the fill itself. Without it the LIGHT scheme swatch is a\n       near-white circle on a near-white card and vanishes \u2014 the exact mirror of the\n       dark swatch on a dark dialog, and a card alone only fixes one direction.\n       --border-color is a currentColor mix, so it holds in both schemes. */\n    border: 1px solid var(--border-color);\n}\n.sb-swatch:checked {\n    box-shadow: 0 0 0 3px var(--accent-bg-color);\n}\n.sb-swatch:focus-visible {\n    outline: 2px solid var(--accent-color);\n    outline-offset: 3px;\n}\n.sb-swatch:disabled {\n    cursor: default;\n}\n/* The scheme swatches are larger \u2014 they are the dialog's primary choice. */\n.sb-swatch--scheme {\n    width: 44px;\n    height: 44px;\n}\n/* \"Follow system\" is the two schemes meeting on a diagonal, so the option looks like\n   what it does instead of needing a word for it. */\n/* light_2 / dark_4 from libadwaita's palette (_palette.scss:37,44), which is what\n   Learn6502's selector uses. NOT light_1 (#ffffff): pure white is invisible against\n   a light card even with the hairline, and light_2 is the shade the palette offers\n   for exactly this. */\n.sb-swatch--scheme-system {\n    background: linear-gradient(to bottom right, #f6f5f4 49.99%, #241f31 50.01%);\n}\n.sb-swatch--scheme-light {\n    background-color: #f6f5f4;\n}\n.sb-swatch--scheme-dark {\n    background-color: #241f31;\n}\n\n.sb-window {\n    width: 100%;\n    height: 100%;\n    min-width: 0;\n    min-height: 0;\n}\n\n/* Each pane in the outer split view is a flex column that fills its height. */\n.sb-sidebar-pane,\n.sb-content-pane {\n    display: flex;\n    flex-direction: column;\n    min-height: 0;\n    min-width: 0;\n    flex: 1 1 auto;\n}\n\n/* The toolbar-view content holds either a scroller (sidebar) or the split view\n   (content); the inner panes own the scrolling, so this level never scrolls. */\n.sb-sidebar-pane adw-toolbar-view > .adw-toolbar-view-content,\n.sb-content-pane adw-toolbar-view > .adw-toolbar-view-content {\n    overflow: hidden;\n}\n\n/* Background scheme: the content header + preview + controls all sit on the\n   window (story) background as one surface; only the left story-list column\n   (its header + list) keeps the distinct sidebar shade. Matches the native\n   renderer. The default adw-header-bar background is its own headerbar shade,\n   so override it per pane here. */\n.sb-content-pane adw-header-bar {\n    background-color: var(--window-bg-color);\n}\n.sb-sidebar-pane adw-header-bar {\n    background-color: var(--sidebar-bg-color);\n}\n\n.sb-sidebar-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    overflow-y: auto;\n    background-color: var(--sidebar-bg-color);\n}\n\n/* --- Story list (mirrors GTK .navigation-sidebar) --- */\n.sb-sidebar-list {\n    padding: var(--spacing-xs);\n    display: flex;\n    flex-direction: column;\n    gap: 1px;\n}\n\n.sb-category {\n    font-size: var(--font-size-small);\n    font-weight: 700;\n    opacity: var(--dim-opacity);\n    padding: 10px var(--spacing-m) 4px;\n}\n\n.sb-story-row {\n    padding: var(--spacing-xs) var(--spacing-m);\n    margin: 0 var(--spacing-xs);\n    border-radius: var(--button-radius);\n    cursor: pointer;\n    color: var(--window-fg-color);\n    font-size: var(--font-size-base);\n    white-space: nowrap;\n    overflow: hidden;\n    text-overflow: ellipsis;\n}\n\n.sb-story-row:hover {\n    background-color: var(--button-bg-color);\n}\n\n.sb-story-row.selected {\n    background-color: var(--accent-bg-color);\n    color: var(--accent-fg-color);\n}\n\n/* --- Preview area --- */\n.sb-preview-scroll {\n    flex: 1 1 auto;\n    min-height: 0;\n    min-width: 0;\n    overflow: auto;\n    background-color: var(--window-bg-color);\n}\n\n.sb-story-page {\n    display: flex;\n    justify-content: center;\n    padding: var(--spacing-xl) var(--spacing-m);\n    min-height: 100%;\n    box-sizing: border-box;\n}\n\n.sb-story-clamp {\n    width: 100%;\n    max-width: 600px;\n}\n\n.sb-story-group-header {\n    padding: var(--spacing-xs) 2px;\n    display: flex;\n    flex-direction: column;\n    gap: 2px;\n}\n\n.sb-story-group-title {\n    font-size: var(--font-size-heading);\n    font-weight: 700;\n    color: var(--window-fg-color);\n}\n\n.sb-story-group-description {\n    font-size: var(--font-size-base);\n    opacity: var(--dim-opacity);\n    color: var(--window-fg-color);\n}\n\n/* Centered, dashed-framed preview stage (mirrors the native .story-stage). */\n.story-stage {\n    display: flex;\n    flex-direction: column;\n    align-items: center;\n    justify-content: center;\n    gap: var(--spacing-m);\n    padding: var(--spacing-l);\n    margin-top: var(--spacing-s);\n    border: 1px dashed rgba(127, 127, 127, 0.28);\n    border-radius: var(--card-radius);\n    min-height: 80px;\n}\n\n/* --- Controls panel --- */\n.sb-controls-scroll {\n    height: 100%;\n    overflow-y: auto;\n    background-color: var(--window-bg-color);\n}\n\n.sb-controls-page {\n    padding: var(--spacing-l);\n}\n\n/* Range-control card (mirrors the native .story-range-row). */\n.sb-range-row {\n    display: flex;\n    flex-direction: column;\n    gap: var(--spacing-xs);\n    padding: var(--spacing-m);\n    border-bottom: 1px solid var(--card-shade-color);\n}\n\n.sb-range-row:last-child {\n    border-bottom: none;\n}\n\n.sb-range-header {\n    display: flex;\n    justify-content: space-between;\n    align-items: baseline;\n    gap: var(--spacing-m);\n}\n\n.sb-range-title {\n    font-size: var(--font-size-base);\n    font-weight: 700;\n    color: var(--card-fg-color);\n}\n\n.sb-range-value {\n    font-size: var(--font-size-base);\n    font-variant-numeric: tabular-nums;\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-description {\n    font-size: var(--font-size-small);\n    opacity: var(--dim-opacity);\n}\n\n.sb-range-input {\n    width: 100%;\n    accent-color: var(--accent-bg-color);\n}\n\n.sb-color-input {\n    width: 42px;\n    height: 28px;\n    padding: 0;\n    border: 1px solid var(--card-shade-color);\n    border-radius: var(--button-radius);\n    background: none;\n    cursor: pointer;\n}\n";
 /** Inject the chrome stylesheet once (idempotent, browser-only). */
 export declare function injectStorybookStyles(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-storybook",
-    "version": "0.37.0",
+    "version": "0.38.0",
     "description": "Browser renderer for the @gjsify/stories contract — the web counterpart of @gjsify/storybook, built on @gjsify/adwaita-web",
     "type": "module",
     "main": "./src/index.ts",
@@ -29,12 +29,13 @@
         "browser"
     ],
     "dependencies": {
-        "@gjsify/adwaita-web": "^0.37.0",
-        "@gjsify/stories": "^0.37.0",
-        "@gjsify/storybook-core": "^0.37.0"
+        "@gjsify/adwaita-core": "^0.38.0",
+        "@gjsify/adwaita-web": "^0.38.0",
+        "@gjsify/stories": "^0.38.0",
+        "@gjsify/storybook-core": "^0.38.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.37.0",
+        "@gjsify/cli": "^0.38.0",
         "typescript": "^6.0.3"
     },
     "gjsify": {

package/src/app.ts

@@ -16,6 +16,7 @@ import {
     type StorybookView,
     type StorySummary,
 } from '@gjsify/storybook-core';
+import { buildAppearanceDialog, StorybookWebAppearance } from './appearance.js';
 import { createControlRow } from './controls.js';
 import type { StoryElement } from './story-element.js';
 import { injectStorybookStyles } from './styles.js';
@@ -57,6 +58,15 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
     private _controller = new StorybookController<StoryElement>(this, (story) => this._buildControls(story));
     private _options: StorybookWebOptions;
     private _container: HTMLElement;
+    /**
+     * Colour scheme + accent for the whole storybook, not for one story.
+     *
+     * Scoped to the storybook's own container rather than `documentElement`: this
+     * app is EMBEDDED by the website, and stamping `.theme-dark` on the document
+     * would re-theme the host page around it. `_theme.scss` scopes on the class
+     * wherever it sits, so a subtree works.
+     */
+    private _appearance: StorybookWebAppearance;
 
     private _listEl!: HTMLElement;
     private _previewEl!: HTMLElement;
@@ -71,6 +81,7 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
     constructor(container: HTMLElement, options: StorybookWebOptions) {
         this._container = container;
         this._options = options;
+        this._appearance = new StorybookWebAppearance(container);
     }
 
     /** Build the UI, instantiate stories, and select the first one. */
@@ -256,7 +267,29 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
                 controlsSplit as HTMLElement & { showSidebar: boolean }
             ).showSidebar;
         });
-        const previewHeader = h('adw-header-bar', { slot: 'top' }, [this._backBtn, this._previewTitle, toggleControls]);
+        // Appearance is a property of the STORYBOOK, not of any story — every story
+        // is previewed under it — so it belongs in the chrome, not in the controls.
+        const appearanceBtn = h('button', {
+            class: 'adw-header-btn sb-appearance-btn',
+            slot: 'end',
+            title: 'Appearance',
+            'aria-label': 'Appearance',
+        });
+        appearanceBtn.append(h('span', { class: 'adw-icon adw-icon--preferences-system' }));
+        const appearanceDialog = buildAppearanceDialog(this._appearance);
+        appearanceBtn.addEventListener('click', () => {
+            // Mounted on first press: a dialog nobody opens should not sit in the
+            // tree of every storybook that never asks for it.
+            if (!appearanceDialog.isConnected) this._container.append(appearanceDialog);
+            appearanceDialog.toggleAttribute('open', true);
+        });
+
+        const previewHeader = h('adw-header-bar', { slot: 'top' }, [
+            this._backBtn,
+            this._previewTitle,
+            appearanceBtn,
+            toggleControls,
+        ]);
 
         const contentPane = h('div', { slot: 'content', class: 'sb-content-pane' }, [
             h('adw-toolbar-view', {}, [previewHeader, controlsSplit]),

package/src/appearance.ts

@@ -0,0 +1,182 @@
+// Applying the storybook's appearance settings in the browser, and the dialog
+// that drives them — the web twin of `@gjsify/storybook`'s `appearance.ts`.
+//
+// The model is `@gjsify/storybook-core`'s `StorybookSettings`, so this target and
+// the GTK one agree on what a colour scheme and an accent ARE. Only the two halves
+// below are per-target:
+//
+//   scheme  → `.theme-dark` / `.theme-light` on the root, which is what
+//             `_theme.scss` scopes on. NEITHER class means "follow the desktop",
+//             so `'system'` removes both and lets `prefers-color-scheme` decide.
+//   accent  → the two custom properties, through `@gjsify/adwaita-web`'s
+//             `applyAdwaitaAccent`.
+//
+// Original implementation.
+
+import { ADW_ACCENT_COLOR_NAMES, adwaitaAccentBgColor, type AdwAccentColorName } from '@gjsify/adwaita-core';
+import { applyAdwaitaAccent, clearAdwaitaAccent } from '@gjsify/adwaita-web';
+import { STORYBOOK_COLOR_SCHEMES, StorybookSettings, type StorybookColorScheme } from '@gjsify/storybook-core';
+
+const SCHEME_LABELS: Record<StorybookColorScheme, string> = {
+    system: 'Follow system',
+    light: 'Light',
+    dark: 'Dark',
+};
+
+const ACCENT_LABELS: Record<AdwAccentColorName, string> = {
+    blue: 'Blue',
+    teal: 'Teal',
+    green: 'Green',
+    yellow: 'Yellow',
+    orange: 'Orange',
+    red: 'Red',
+    pink: 'Pink',
+    purple: 'Purple',
+    slate: 'Slate',
+};
+
+/** Owns the browser side of {@link StorybookSettings}: the theme scope and the accent. */
+export class StorybookWebAppearance {
+    readonly settings: StorybookSettings;
+    private readonly _root: HTMLElement;
+
+    constructor(root: HTMLElement = document.documentElement) {
+        this._root = root;
+        const query = globalThis.matchMedia?.('(prefers-color-scheme: dark)') ?? null;
+
+        this.settings = new StorybookSettings(() => query?.matches ?? false);
+        this.settings.subscribe(() => this._apply());
+        // Wired unconditionally — `systemChanged` no-ops unless the preference is
+        // `'system'`, so the guard lives in one place.
+        query?.addEventListener('change', () => this.settings.systemChanged());
+
+        this._apply();
+    }
+
+    private _apply(): void {
+        const scheme = this.settings.colorScheme;
+        // Both classes off is the "follow the desktop" state, not a third theme:
+        // `_theme.scss` applies its dark palette from `prefers-color-scheme` when
+        // no explicit scope is present.
+        this._root.classList.toggle('theme-dark', scheme === 'dark');
+        this._root.classList.toggle('theme-light', scheme === 'light');
+
+        const accent = this.settings.resolvedAccent;
+        if (accent) applyAdwaitaAccent(accent, { target: this._root, dark: this.settings.resolvedDark });
+        else clearAdwaitaAccent(this._root);
+    }
+}
+
+/** A round swatch: a radio input, so grouping and keyboard nav come for free. */
+function buildSwatch(name: string, value: string, label: string, classes: readonly string[]): HTMLInputElement {
+    const swatch = document.createElement('input');
+    swatch.type = 'radio';
+    swatch.name = name;
+    swatch.value = value;
+    swatch.title = label;
+    // A coloured circle has no text; without this a screen reader reads unnamed
+    // radios, and `title` is not an accessible name.
+    swatch.setAttribute('aria-label', label);
+    swatch.classList.add('sb-swatch', ...classes);
+    return swatch;
+}
+
+/**
+ * The appearance dialog: the colour scheme, and the accent behind a switch.
+ *
+ * Built once and reused — unlike the GTK `Adw.Dialog`, `<adw-preferences-dialog>`
+ * reopens after a dismissal, so there is nothing to rebuild.
+ */
+export function buildAppearanceDialog(appearance: StorybookWebAppearance): HTMLElement {
+    const settings = appearance.settings;
+
+    const dialog = document.createElement('adw-preferences-dialog');
+    dialog.setAttribute('title', 'Appearance');
+    const page = document.createElement('adw-preferences-page');
+
+    // --- Colour scheme ---
+    const schemeGroup = document.createElement('adw-preferences-group');
+    schemeGroup.setAttribute('title', 'Style');
+
+    const schemeCard = document.createElement('div');
+    schemeCard.className = 'card sb-swatch-card';
+    const schemeSwatches = new Map<string, HTMLInputElement>();
+
+    for (const scheme of STORYBOOK_COLOR_SCHEMES) {
+        const swatch = buildSwatch('sb-scheme', scheme, SCHEME_LABELS[scheme], [
+            'sb-swatch--scheme',
+            `sb-swatch--scheme-${scheme}`,
+        ]);
+        swatch.checked = settings.colorScheme === scheme;
+        swatch.addEventListener('change', () => {
+            if (swatch.checked) settings.colorScheme = scheme;
+        });
+        schemeSwatches.set(scheme, swatch);
+        schemeCard.append(swatch);
+    }
+    schemeGroup.append(schemeCard);
+    page.append(schemeGroup);
+
+    // --- Accent ---
+    const accentGroup = document.createElement('adw-preferences-group');
+    accentGroup.setAttribute('title', 'Accent colour');
+    // Squares the group list's BOTTOM corners. The attached card squares its top;
+    // without both, the row above keeps its round bottom and the two meet with a
+    // notch at each end.
+    accentGroup.classList.add('sb-attached-group');
+
+    const accentSwitch = document.createElement('adw-switch-row');
+    accentSwitch.setAttribute('title', 'Use a custom accent colour');
+    accentSwitch.setAttribute('subtitle', 'Off follows the desktop, which owns the accent');
+    accentSwitch.toggleAttribute('active', settings.accentMode === 'custom');
+    accentGroup.append(accentSwitch);
+
+    // Attached: the switch row and the palette read as one boxed list rather than
+    // two stacked cards with a seam between them.
+    const accentCard = document.createElement('div');
+    accentCard.className = 'card sb-swatch-card sb-swatch-card--attached';
+    const accentSwatches = new Map<string, HTMLInputElement>();
+
+    for (const accent of ADW_ACCENT_COLOR_NAMES) {
+        const swatch = buildSwatch('sb-accent', accent, ACCENT_LABELS[accent], []);
+        // The fill comes from core, per swatch — one source of truth for the nine
+        // colours, and a tenth upstream would need no CSS here.
+        swatch.style.backgroundColor = adwaitaAccentBgColor(accent);
+        swatch.checked = settings.accent === accent;
+        swatch.addEventListener('change', () => {
+            if (swatch.checked) settings.accent = accent;
+        });
+        accentSwatches.set(accent, swatch);
+        accentCard.append(swatch);
+    }
+
+    const syncAccentEnabled = (custom: boolean): void => {
+        accentCard.classList.toggle('sb-swatch-card--disabled', !custom);
+        for (const swatch of accentSwatches.values()) swatch.disabled = !custom;
+    };
+    syncAccentEnabled(settings.accentMode === 'custom');
+
+    accentSwitch.addEventListener('notify::active', () => {
+        settings.accentMode = accentSwitch.hasAttribute('active') ? 'custom' : 'system';
+    });
+    accentGroup.append(accentCard);
+    page.append(accentGroup);
+
+    dialog.append(page);
+
+    // One-way sync FROM the model, so the dialog keeps no second copy of the state
+    // and a change made anywhere else still shows here.
+    settings.subscribe((state) => {
+        const scheme = schemeSwatches.get(state.colorScheme);
+        if (scheme && !scheme.checked) scheme.checked = true;
+
+        const accent = accentSwatches.get(state.accent);
+        if (accent && !accent.checked) accent.checked = true;
+
+        const custom = state.accentMode === 'custom';
+        accentSwitch.toggleAttribute('active', custom);
+        syncAccentEnabled(custom);
+    });
+
+    return dialog;
+}

package/src/styles.ts

@@ -3,6 +3,86 @@
 // adwaita-web CSS custom properties, so it follows the active light/dark theme.
 
 export const STORYBOOK_WEB_CSS = `
+/* Appearance dialog — round swatches with a selection ring. The web twin of the GTK
+   renderer's rules, themselves adapted from Learn6502.
+
+   The CARD is not decoration: in the dark scheme the "dark" swatch is a near-black
+   circle on a near-black dialog and is invisible without a lighter surface behind
+   it. Centring happens INSIDE the full-width card, so the row does not read as
+   left-aligned under the group title. */
+.sb-swatch-card {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 8px;
+    padding: 12px;
+}
+/* Squaring the card's top alone leaves a notch: the row above lives in the group's
+   own rounded list, so BOTH sides have to be squared for the join to read as one
+   list. The attached card and the group rule below are the two halves of that. */
+.sb-swatch-card--attached {
+    border-top-left-radius: 0;
+    border-top-right-radius: 0;
+}
+.sb-attached-group .boxed-list {
+    border-bottom-left-radius: 0;
+    border-bottom-right-radius: 0;
+}
+/* Desaturated rather than merely dimmed: while the accent follows the desktop the
+   palette must read as unavailable, not as nine slightly faded choices. */
+.sb-swatch-card--disabled {
+    filter: saturate(0.4) brightness(1.05);
+    opacity: 0.7;
+}
+/* A radio input, so grouping and arrow-key navigation are the platform's. Its own
+   glyph is switched off because the swatch IS the indicator — a dot drawn on a
+   colour competes with the ring that already says which one is selected. */
+.sb-swatch {
+    appearance: none;
+    -webkit-appearance: none;
+    margin: 0;
+    width: 24px;
+    height: 24px;
+    border-radius: 9999px;
+    box-shadow: 0 0 0 3px transparent;
+    cursor: pointer;
+    /* A hairline on the fill itself. Without it the LIGHT scheme swatch is a
+       near-white circle on a near-white card and vanishes — the exact mirror of the
+       dark swatch on a dark dialog, and a card alone only fixes one direction.
+       --border-color is a currentColor mix, so it holds in both schemes. */
+    border: 1px solid var(--border-color);
+}
+.sb-swatch:checked {
+    box-shadow: 0 0 0 3px var(--accent-bg-color);
+}
+.sb-swatch:focus-visible {
+    outline: 2px solid var(--accent-color);
+    outline-offset: 3px;
+}
+.sb-swatch:disabled {
+    cursor: default;
+}
+/* The scheme swatches are larger — they are the dialog's primary choice. */
+.sb-swatch--scheme {
+    width: 44px;
+    height: 44px;
+}
+/* "Follow system" is the two schemes meeting on a diagonal, so the option looks like
+   what it does instead of needing a word for it. */
+/* light_2 / dark_4 from libadwaita's palette (_palette.scss:37,44), which is what
+   Learn6502's selector uses. NOT light_1 (#ffffff): pure white is invisible against
+   a light card even with the hairline, and light_2 is the shade the palette offers
+   for exactly this. */
+.sb-swatch--scheme-system {
+    background: linear-gradient(to bottom right, #f6f5f4 49.99%, #241f31 50.01%);
+}
+.sb-swatch--scheme-light {
+    background-color: #f6f5f4;
+}
+.sb-swatch--scheme-dark {
+    background-color: #241f31;
+}
+
 .sb-window {
     width: 100%;
     height: 100%;