@justanarthur/modo-ui 0.6.0-canary.6 → 0.6.0-canary.7

package/README.md

@@ -106,7 +106,7 @@ Every vendored file opens with a plain `/* */` header. The header names the
 upstream path and commit, carries the MIT notice, and lists every local
 modification. The vendored code below the header keeps upstream's formatting.
 Files written for this port (`preset.ts`, `uno.config.ts`, `vite.ts`, `index.ts`,
-`scripts/build-css.ts`, `modo.components.tsx`,
+`scripts/build-css.ts`, `docs/*`,
 `lib/use-controllable-state.ts`, `primitives/code/index.tsx`, `primitives/craft/*`, the morph files
 in `lib/` (`use-morph.ts`, `reduced-motion.ts`, `morph-layers.tsx`, `morph-part.tsx`, `goo-indicator.tsx`,
 `slot.ts`) and `primitives/morph/index.tsx`, `blocks/sidebar-app/index.tsx`,
@@ -137,13 +137,13 @@ positioning) are ported.
 | `DESIGN.md` | The design language in Google's [DESIGN.md](https://github.com/google-labs-code/design.md) format: the tokens as front matter, the rules as prose. Agents building here follow the `modo-ui` skill (`.claude/skills/modo-ui` at the repo root). |
 | `tokens/*.css` | Colors, typography (`--font-sans`, `--text-*`), motion (`--duration-*`), radius and spacing. Shipped per group as `dist/tokens/*.css` (`./tokens/*`). |
 | `base.css` | Theme switching, base styles, focus fallback, scrollbars, shimmer/spinner keyframes and `.scroll-fade`. Shipped in the package. The inline `code` chip applies only inside the docs shell, `data-modo="prose"` and `.modo-prose`. |
-| `global.css` | The docs site's stylesheet (`modo.config.ts` `css`): imports `base.css`, then the modo-only focus revert and the docs chrome. |
+| `global.css` | The docs site's stylesheet (`modo.config.ts` `css`): imports `base.css`, then `docs/chrome.css`. |
 | `preset.ts` | The UnoCSS preset (theme and token utilities), shipped as `@justanarthur/modo-ui/unocss`. |
-| `uno.config.ts`, `vite.ts` | The UnoCSS setup of the docs site and the prebuilt CSS (see below). |
+| `uno.config.ts`, `vite.ts` | The UnoCSS setup of the docs site and the prebuilt CSS (see below); `vite.ts` also applies the docs chrome's `docsTheme` plugin. |
 | `index.ts`, `bunup.config.ts`, `scripts/build-css.ts` | The package build: `bun run build` writes the components, their types and the stylesheets to `dist/`. The docs site builds with `bun run build:docs` into `docs-dist/`. |
 | `scripts/exports.ts`, `scripts/use-client.ts`, `scripts/check-singletons.ts` | Packaging around that build. `exports.ts` (first step of `bun run build`) writes one `./lib/<name>` export per `lib/` module into `package.json`, plus `./components/*/variants` and `./blocks/*/variants` for the items' server-callable `variants.ts` entries; commit the `package.json` it leaves. `use-client.ts` (after bunup) puts `"use client"` on the emitted modules that render, call a hook or create a context, or use a binding from one; pure helpers (`cn`, class tables, springs, `variants.ts`) and re-export entries stay directive-free so a React Server Component can call them (`--list` prints the split). `check-singletons.ts` (`bun run check:dist`) checks that every React context and the `toast()` manager exist once in `dist/`, and that every entry has its `.d.ts`. `typesVersions` in `package.json` maps every public subpath to `dist/**/*.d.ts`, so `moduleResolution: node` consumers do not type-check the shipped source. |
 | `lib/` | FF's shared system files (upstream `lib/`, `hooks/` and the fluid-hover highlight, flat, upstream names), imported relatively by items. modo only scans the tier folders, so it never mistakes them for items. |
-| `modo.components.tsx` | Components only the docs site uses: the `Icon`, `Select` and `DocsNav` shell-slot adapters and the `ThemeSwitcher` panel item, picked in `modo.config.ts` by export name (`./modo.components.tsx#Select`). |
+| `docs/` | The docs chrome, shipped: `chrome.tsx` (the `Button`, `Link`, `Icon`, `Select` and `DocsNav` shell-slot adapters and the `ThemeSwitcher` panel item, re-exported by `index.ts` as `@justanarthur/modo-ui/docs`), `chrome.css` (the inset layout and the look of the chrome, `@justanarthur/modo-ui/docs/chrome.css`) and `vite.ts` (`docsTheme`, the pre-paint theme controller, `@justanarthur/modo-ui/docs/vite`). `modo.config.ts` picks the slots by export name (`./docs#DocsNav`); another design system documented with modo points at the same module by package specifier (see **The docs chrome, for another design system**). The barrel (`index.ts`) never imports it, `bun run check:dist` fails if it does. |
 | `primitives/<id>/` | FF's "System" pages: `index.tsx` (component + TSDoc prose) and `examples.mdx`, pulled in by `@example {@include ./examples.mdx}`. |
 | `components/[<group>/]<id>/` | FF's "Components" pages, same shape. The `AI/`, `inputs/` (with `inputs/date-time/`), `navigation/` and `overlays/` group folders become sidebar sub-groups and overview sections; the core display items stay ungrouped. |
 | `blocks/<id>/` | Compositions of several items, same shape: `sidebar-app`, FF's sidebar preset `sa1FQfCxH6` as an app shell, with the header and footer blocks it is built from beside it. |
@@ -292,17 +292,17 @@ only what is specific to it:
 | — | `registry/blocks/sidebar-app/inset-topbar.tsx` | `blocks/sidebar-app/inset-topbar.tsx` | the trigger's peek-time fade dropped (the sidebar opens on hover in flow, so the trigger stays) |
 | — | `registry/default/lib/sidebar-menu-grid.ts` | `blocks/sidebar-app/menu-grid.ts` | the width reads `--anchor-width` only; the `-ml-1` shift dropped (it would move the morph surface's content off its background) |
 
-`Select` in `modo.components.tsx` is not an item: modo's docs chrome renders its Select slot
+`Select` in `docs/chrome.tsx` is not an item: modo's docs chrome renders its Select slot
 with a flat `value` / `onChange` / `options` contract
 (`lib/src/lib/slots.tsx`), and this adapter maps it onto
 `Select.Trigger` / `Select.Content` / `Select.Item` so the chrome runs on the
 design system's own Select. The
 `components/inputs/select` item keeps the upstream API untouched.
 
-`DocsNav` in `modo.components.tsx` is the chrome's Sidebar slot, pinned as
+`DocsNav` in `docs/chrome.tsx` is the chrome's Sidebar slot, pinned as
 `shell.Sidebar` (by name alone modo would adopt the documented `Sidebar`, an
 app shell that needs its provider). Each aside is an inset `Sidebar` with its
-own provider, and `global.css` turns the content between them into the inset
+own provider, and `docs/chrome.css` turns the content between them into the inset
 card (the lib's grid columns become `auto`, so they follow the sidebars' width
 springs). Each provider has `openOnHover`, and its `Sidebar.Trigger` sits in
 the card's corner: the trigger, `[` for the nav and `]` for the panel, switch
@@ -315,7 +315,7 @@ below xl. A section of links is a collapsible `Sidebar.Group` with one
 highlight melt from link to link; a panel section (Theme) keeps its control
 under the group label.
 
-`ThemeSwitcher` in `modo.components.tsx` is not an item either: it is the `Theme` entry in
+`ThemeSwitcher` in `docs/chrome.tsx` is not an item either: it is the `Theme` entry in
 `modo.config.ts` `panel.items`, a `Select` of Light / Dark / System (each row
 with its icon, the trigger showing the active one) that reads and sets
 `window.__uiTheme` and re-reads it on `ui:themechange`. All switching logic lives in the pre-paint controller
@@ -323,6 +323,75 @@ described under **Tailwind → UnoCSS**, so the control holds no theme state of
 its own. `demo/scripts/run-design-systems.ts` appends its own `Switcher` panel
 item to whatever a design system declares, so both show up under the runner.
 
+The chrome's own elements (the corner triggers, the panel section's gutter) are
+styled in `docs/chrome.css` through `data-modo-ui` attributes, not utility
+classes: nothing in `docs/` needs a UnoCSS or Tailwind scan, so a host with
+either generator loads the same file. `Button` and `Link` are pinned too, so a
+design system with items of those names but another prop shape is not matched
+by name (modo would warn on every start).
+
+### The docs chrome, for another design system
+
+A design system documented with modo (an `@utegsk/ui`-style package that
+depends on `@justanarthur/modo-ui`) gets the same sidebars, inset card layout,
+panel and Theme switcher as this site by pointing its `modo.config.ts` at the
+shipped module. A `shell` / `panel` value may be a package specifier (the
+viewer resolves it from the project root through the package's `exports`, the
+`source` file first), which needs an `@justanarthur/modo` release after
+0.9.0-canary.0; with an older viewer keep a one-line local re-export instead
+(`export * from '@justanarthur/modo-ui/docs'` in a `docs/shell.tsx`, and point
+the slots at `./docs/shell.tsx#DocsNav`).
+
+```ts
+// modo.config.ts
+import { defineConfig } from '@justanarthur/modo/config'
+
+export default defineConfig({
+  name: 'My DS',
+  css: './docs.css',
+  vite: './vite.mjs',
+  shell: {
+    Button: '@justanarthur/modo-ui/docs#Button',
+    Link: '@justanarthur/modo-ui/docs#Link',
+    Select: '@justanarthur/modo-ui/docs#Select',
+    Icon: '@justanarthur/modo-ui/docs#Icon',
+    Sidebar: '@justanarthur/modo-ui/docs#DocsNav',
+  },
+  panel: { items: [{ label: 'Theme', component: '@justanarthur/modo-ui/docs#ThemeSwitcher' }] },
+})
+```
+
+```css
+/* docs.css: the package stylesheet (or base.css with your own utilities), then the chrome */
+@import "@justanarthur/modo-ui/styles.css";
+@import "@justanarthur/modo-ui/docs/chrome.css";
+```
+
+```js
+// vite.mjs: plain JS, Node loads it as is. Add your own plugins (Tailwind, UnoCSS) beside docsTheme.
+import { docsTheme } from '@justanarthur/modo-ui/docs/vite'
+
+export default config => {
+  config.plugins = [...(config.plugins ?? []), docsTheme({ storageKey: 'my-ds-theme' })]
+  return config
+}
+```
+
+- `chrome.css` also loads by itself, as the stylesheet beside the slot module,
+  when modo bundles `@justanarthur/modo-ui/docs` from its source; the explicit
+  `@import` fixes where it sits in your cascade and is the one to rely on.
+- `docsTheme` puts `.light` / `.dark` on `<html>` before first paint and
+  exposes `window.__uiTheme` for `ThemeSwitcher`; `storageKey` (default
+  `modo-ui-theme`) keeps two sites on one origin apart.
+- The panel's narrow-screen behavior (below xl the panel is a drawer, opened on
+  hover or with `]`, never a strip above the content) comes with `chrome.css`.
+  A stylesheet that re-implements the layout instead of importing it can
+  recreate the lib's `grid-template-rows: auto` strip: a viewport-tall blank
+  row with the Theme select behind it.
+- `lucide-react` (the `Icon` slot) is already a dependency of the package;
+  the docs entry adds no other. `@justanarthur/modo-ui` itself must be a
+  dependency of the host: modo resolves the specifier from the project root.
+
 ## Tier mapping
 
 The tiers mirror the FF docs navigation. FF's "System" pages become
@@ -371,7 +440,7 @@ No ported file imports any of them.
 
 The files only they, or the FF docs site's nav, use are left out too:
 `mobile-drawer`, `nav-item`, `nav-menu`, `lib/theme-context.tsx` (the
-`ThemeSwitcher` panel item and vite.ts's pre-paint controller take its
+`ThemeSwitcher` panel item and docs/vite.ts's pre-paint controller take its
 place) and the blocks other than the sidebar's (`queued-stack`,
 `dialog-sidebar`). Inside kept files, the same rule removed
 `SURFACE_HOVER_BG`, `SURFACE_HOVER_SHADOW` and `surfaceHoverClasses` from
@@ -398,7 +467,8 @@ prebuilt `styles.css`, and turns `preset.ts` into `tailwind.css`.
 
 - **Dark mode.** `dark: 'class'` produces `.dark .dark\:x`, the same "inside a
   `.dark` ancestor" contract as FF's `@custom-variant dark (&:is(.dark *))`.
-  modo ships no theme of its own, so `vite.ts` injects a small controller into
+  modo ships no theme of its own, so `docsTheme` (`docs/vite.ts`, applied by
+  `vite.ts`) injects a small controller into
   `index.html` (`transformIndexHtml`, `head-prepend`). Before first paint it
   puts `light` or `dark` on `<html>` — the stored preference, or the OS one
   under `system` — which is also what flips every `light-dark()` token through
@@ -411,7 +481,10 @@ prebuilt `styles.css`, and turns `preset.ts` into `tailwind.css`.
   `global.css` (and the `base.css` it imports) and fixes the order of the
   layer its `@layer base` rules join.
   `vite.ts` is loaded by Node with type stripping, so it may only use erasable
-  TypeScript and hands `uno.config.ts` to UnoCSS by absolute path.
+  TypeScript, names the `.ts` extension of the one relative module it imports
+  (`./docs/vite.ts`) and hands `uno.config.ts` to UnoCSS by absolute path.
+  `docs/vite.ts` ships built (`dist/docs/vite.js`): Node never strips types
+  from a file under `node_modules`.
 - **Colors.** Theme colors point at the CSS variables directly (for example
   `accent: 'var(--accent)'`, `surface.1..8`). wind4 applies opacity modifiers
   to `var()` colors with `color-mix(in srgb, …)`, so `bg-accent/12` works on
@@ -435,7 +508,7 @@ prebuilt `styles.css`, and turns `preset.ts` into `tailwind.css`.
   after the reset, so utilities (in `default`) still win. This is the same
   arrangement as Tailwind's base/utilities split.
 - **Content.** UnoCSS scans `{lib,primitives,components,blocks}/**/*.{ts,tsx,mdx}`
-  and `modo.components.tsx` from disk (`content.filesystem`, and the same
+  from disk (`content.filesystem`, and the same
   globs in `content.pipeline.include`, since the default pipeline skips
   `.ts`). Two reasons:
   - modo serves items pre-bundled, so the sources never pass through Vite's

package/dist/docs/index.d.ts

@@ -0,0 +1,83 @@
+import { AnchorHTMLAttributes, ReactNode } from "react";
+import { ForwardRefExoticComponent as ForwardRefExoticComponent_tcubfn } from "react";
+import { ButtonProps as ButtonProps_1qs1xe } from "..";
+import { RefAttributes as RefAttributes_miuf56 } from "react";
+import { JSX as JSX_1kxb } from "react";
+import { LucideIcon as LucideIcon_b49o7r } from "lucide-react";
+/**
+* Button slot: the chrome's icon buttons (Show code, Copy, the anchor toggles). The chrome passes
+* `variant="ghost"`, `size="icon-sm"`, `aria-label` and `aria-pressed`; the design system's Button takes them as is.
+* Pinned so a host with an item named `Button` of another shape is not matched by name.
+*/
+declare const Button: ForwardRefExoticComponent_tcubfn<ButtonProps_1qs1xe & RefAttributes_miuf56<HTMLButtonElement>>;
+type Element_12xgc = JSX_1kxb["Element"];
+/**
+* Link slot: every chrome and Markdown link, a plain anchor so the chrome's own link styling applies.
+* Pinned so a host with an item named `Link` of another shape is not matched by name.
+*/
+declare function Link(props: AnchorHTMLAttributes<HTMLAnchorElement> & {
+	href: string;
+}): Element_12xgc;
+declare const icons: {
+	code: LucideIcon_b49o7r;
+	copy: LucideIcon_b49o7r;
+	check: LucideIcon_b49o7r;
+	link: LucideIcon_b49o7r;
+};
+/** Icon slot: the chrome asks for icons by name; lucide draws them. */
+declare function Icon({ name }: {
+	/** Which chrome icon to draw. */
+	name: keyof typeof icons;
+	/** Accessible text; the button around the icon carries it. */
+	label: string;
+}): Element_12xgc;
+/**
+* Select slot: the chrome passes a flat `value` / `onChange` / `options`
+* contract; FF's Select is compositional, so this maps one onto the other.
+*/
+declare function Select({ value, onChange, options }: {
+	value: string;
+	onChange: (value: string) => void;
+	options: {
+		value: string;
+		label: string;
+	}[];
+}): Element_12xgc;
+/**
+* Sidebar slot: both asides of the chrome, each an inset `Sidebar` with its
+* own `openOnHover` provider, so the content between them is the inset card
+* (chrome.css). The trigger in the card's corner (or `[` for the nav, `]` for
+* the panel) switches a side between open and on hover. Below md each side
+* is a drawer. The panel starts on hover below xl.
+*
+* A section of links is a collapsible `Sidebar.Group` whose rows share one
+* `Sidebar.Menu`, so the current page and the hover highlight melt from link
+* to link (the TOC's current heading too, as the page scrolls); a panel
+* section (the Theme select) keeps its control under the group label. Pin it
+* in modo.config.ts: by name alone modo would adopt a documented `Sidebar`
+* item, an app shell that needs its provider.
+*/
+declare function DocsNav({ children }: {
+	children?: ReactNode;
+}): Element_12xgc;
+declare namespace DocsNav {
+	var Item: typeof DocsNavItem;
+	var Section: typeof DocsNavSection;
+}
+declare function DocsNavItem({ href, active, children }: {
+	href: string;
+	active?: boolean;
+	children?: ReactNode;
+}): Element_12xgc;
+declare function DocsNavSection({ title, children }: {
+	title: string;
+	children?: ReactNode;
+}): Element_12xgc;
+/**
+* Theme panel item. The switching itself is the pre-paint script the vite
+* helper injects (`docsTheme` in `@justanarthur/modo-ui/docs/vite`, `window.__uiTheme`), so a stored preference applies before first
+* paint; this only reflects and sets it. `ui:themechange` also fires when the
+* OS flips underneath 'system'.
+*/
+declare function ThemeSwitcher(): Element_12xgc;
+export { Button, DocsNav, Icon, Link, Select, ThemeSwitcher };

package/dist/docs/index.js

@@ -0,0 +1,287 @@
+"use client";
+import"../shared/components-de99ykt7.js";
+import"../shared/components-78x40gee.js";
+import"../shared/components-34txk9rj.js";
+import"../shared/components-h83az0bz.js";
+import"../shared/components-3ey0hzpb.js";
+import"../shared/components-jcnjay5g.js";
+import"../shared/components-4vfm04wq.js";
+import {
+  button_default
+} from "../shared/components-4swzve2d.js";
+import"../shared/components-awra5sff.js";
+import"../shared/components-pw06rbxq.js";
+import"../shared/components-qdm3yh26.js";
+import"../shared/components-8nwsqjn8.js";
+import"../shared/components-b1e239g3.js";
+import"../shared/components-4y816hwp.js";
+import"../shared/components-h6p86be3.js";
+import"../shared/components-krtx3m5b.js";
+import"../shared/components-mrbaxt8q.js";
+import"../shared/components-vf45j12c.js";
+import"../shared/components-dhgk6mbt.js";
+import"../shared/components-yhgq0qxx.js";
+import"../shared/components-tz4gaf1v.js";
+import"../shared/components-drxrtnp2.js";
+import"../shared/components-2z48g4fp.js";
+import"../shared/components-dcc02hs2.js";
+import"../shared/components-xdqmt6ed.js";
+import {
+  select_default
+} from "../shared/components-hx4a4cvm.js";
+import"../shared/components-tz1fv35x.js";
+import"../shared/components-jqpefjsn.js";
+import"../shared/components-030n1m1v.js";
+import"../shared/components-nd1baxp1.js";
+import"../shared/components-124epb7f.js";
+import"../shared/components-6zng858q.js";
+import"../shared/components-z3v0n0de.js";
+import"../shared/components-rrbpmfx4.js";
+import"../shared/components-vqqapw72.js";
+import {
+  SIDEBAR_KEYBOARD_SHORTCUT2,
+  SIDEBAR_KEYBOARD_SHORTCUT_RIGHT2
+} from "../shared/components-kswxnm3h.js";
+import {
+  useSidebar2,
+  sidebar_default
+} from "../shared/components-9n43qf8y.js";
+
+// docs/chrome.tsx
+import { Check, CodeXml, Copy, Link2, Monitor, Moon, Sun } from "lucide-react";
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useEffect,
+  useState
+} from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Button = button_default;
+function Link(props) {
+  return /* @__PURE__ */ jsx("a", {
+    ...props
+  });
+}
+var icons = { code: CodeXml, copy: Copy, check: Check, link: Link2 };
+function Icon({
+  name
+}) {
+  const Glyph = icons[name];
+  return /* @__PURE__ */ jsx(Glyph, {
+    size: 16,
+    strokeWidth: 1.5,
+    "aria-hidden": true
+  });
+}
+function Select({
+  value,
+  onChange,
+  options
+}) {
+  return /* @__PURE__ */ jsxs(select_default, {
+    value,
+    onValueChange: onChange,
+    children: [
+      /* @__PURE__ */ jsx(select_default.Trigger, {}),
+      /* @__PURE__ */ jsx(select_default.Content, {
+        children: options.map((option, index) => /* @__PURE__ */ jsx(select_default.Item, {
+          value: option.value,
+          index,
+          children: option.label
+        }, option.value))
+      })
+    ]
+  });
+}
+function DocsNav({ children }) {
+  const [side, setSide] = useState();
+  if (!side)
+    return /* @__PURE__ */ jsx("div", {
+      ref: (node) => node && setSide(node.closest('[data-modo="panel"]') ? "right" : "left")
+    });
+  return /* @__PURE__ */ jsx(DocsSidebar, {
+    side,
+    children
+  });
+}
+function DocsSidebar({ side, children }) {
+  return /* @__PURE__ */ jsxs(sidebar_default.Provider, {
+    defaultOpen: side === "left" || window.matchMedia("(min-width: 1280px)").matches,
+    openOnHover: true,
+    persist: false,
+    shortcut: null,
+    children: [
+      /* @__PURE__ */ jsx(sidebar_default, {
+        variant: "inset",
+        side,
+        children: /* @__PURE__ */ jsx(sidebar_default.Content, {
+          children: /* @__PURE__ */ jsx("nav", {
+            "aria-label": side === "left" ? "Docs" : "Page",
+            children
+          })
+        })
+      }),
+      /* @__PURE__ */ jsx(DocsNavTrigger, {
+        side
+      })
+    ]
+  });
+}
+function DocsNavTrigger({ side }) {
+  const { state, isMobile, toggleSidebar } = useSidebar2();
+  useDocsShortcut(side === "left" ? SIDEBAR_KEYBOARD_SHORTCUT2 : SIDEBAR_KEYBOARD_SHORTCUT_RIGHT2, toggleSidebar);
+  return /* @__PURE__ */ jsx("div", {
+    "data-modo-ui": "nav-trigger",
+    "data-side": side,
+    "data-gutter": state === "collapsed" || isMobile ? "" : undefined,
+    children: /* @__PURE__ */ jsx(sidebar_default.Trigger, {})
+  });
+}
+function useDocsShortcut(key, toggle) {
+  useEffect(() => {
+    const onKeyDown = (event) => {
+      if (event.key !== key || event.metaKey || event.ctrlKey || event.altKey)
+        return;
+      const target = event.target;
+      if (target.isContentEditable)
+        return;
+      if (target.closest('input, textarea, select, [data-modo="content"] [data-slot="sidebar-wrapper"]'))
+        return;
+      event.stopImmediatePropagation();
+      event.preventDefault();
+      toggle();
+    };
+    window.addEventListener("keydown", onKeyDown, true);
+    return () => window.removeEventListener("keydown", onKeyDown, true);
+  }, [key, toggle]);
+}
+var NavDepth = createContext(0);
+function DocsNavItem({ href, active, children }) {
+  const { setOpenMobile } = useSidebar2();
+  if (useContext(NavDepth) >= 2) {
+    return /* @__PURE__ */ jsx(sidebar_default.MenuSubItem, {
+      children: /* @__PURE__ */ jsx(sidebar_default.MenuSubButton, {
+        href,
+        isActive: active,
+        onClick: () => setOpenMobile(false),
+        children
+      })
+    });
+  }
+  return /* @__PURE__ */ jsx(sidebar_default.MenuItem, {
+    children: /* @__PURE__ */ jsx(sidebar_default.MenuButton, {
+      isActive: active,
+      render: /* @__PURE__ */ jsx("a", {
+        href
+      }),
+      onClick: () => setOpenMobile(false),
+      children
+    })
+  });
+}
+function DocsNavSection({ title, children }) {
+  const depth = useContext(NavDepth);
+  if (depth >= 1)
+    return /* @__PURE__ */ jsx(DocsNavGroup, {
+      title,
+      children
+    });
+  const onlyLinks = Children.toArray(children).every((child) => isValidElement(child) && (child.type === DocsNavItem || child.type === DocsNavSection));
+  if (onlyLinks) {
+    return /* @__PURE__ */ jsxs(sidebar_default.Group, {
+      collapsible: true,
+      children: [
+        /* @__PURE__ */ jsx(sidebar_default.GroupLabel, {
+          children: title
+        }),
+        /* @__PURE__ */ jsx(NavDepth.Provider, {
+          value: 1,
+          children: /* @__PURE__ */ jsx(sidebar_default.Menu, {
+            children
+          })
+        })
+      ]
+    });
+  }
+  return /* @__PURE__ */ jsxs(sidebar_default.Group, {
+    children: [
+      /* @__PURE__ */ jsx(sidebar_default.GroupLabel, {
+        children: title
+      }),
+      /* @__PURE__ */ jsx("div", {
+        "data-modo-ui": "nav-controls",
+        children
+      })
+    ]
+  });
+}
+var holdsActive = (children) => Children.toArray(children).some((child) => isValidElement(child) && (child.props.active || holdsActive(child.props.children)));
+function DocsNavGroup({ title, children }) {
+  const depth = useContext(NavDepth);
+  const current = holdsActive(children);
+  const [open, setOpen] = useState(current);
+  useEffect(() => {
+    if (current)
+      setOpen(true);
+  }, [current]);
+  return /* @__PURE__ */ jsxs(sidebar_default.MenuItem, {
+    collapsible: true,
+    open,
+    onOpenChange: setOpen,
+    children: [
+      /* @__PURE__ */ jsx(sidebar_default.MenuButton, {
+        children: title
+      }),
+      /* @__PURE__ */ jsx(NavDepth.Provider, {
+        value: depth + 1,
+        children: /* @__PURE__ */ jsx(sidebar_default.MenuSub, {
+          children
+        })
+      })
+    ]
+  });
+}
+DocsNav.Item = DocsNavItem;
+DocsNav.Section = DocsNavSection;
+var THEMES = [
+  { value: "light", label: "Light", icon: Sun },
+  { value: "dark", label: "Dark", icon: Moon },
+  { value: "system", label: "System", icon: Monitor }
+];
+function ThemeSwitcher() {
+  const [preference, setPreference] = useState(() => window.__uiTheme?.get() ?? "system");
+  useEffect(() => {
+    const sync = () => setPreference(window.__uiTheme?.get() ?? "system");
+    window.addEventListener("ui:themechange", sync);
+    return () => window.removeEventListener("ui:themechange", sync);
+  }, []);
+  const active = THEMES.find((theme) => theme.value === preference) ?? THEMES[2];
+  return /* @__PURE__ */ jsxs(select_default, {
+    value: preference,
+    onValueChange: (next) => window.__uiTheme?.set(next),
+    children: [
+      /* @__PURE__ */ jsx(select_default.Trigger, {
+        "aria-label": "Color theme",
+        icon: active.icon
+      }),
+      /* @__PURE__ */ jsx(select_default.Content, {
+        children: THEMES.map((theme, index) => /* @__PURE__ */ jsx(select_default.Item, {
+          index,
+          value: theme.value,
+          icon: theme.icon,
+          children: theme.label
+        }, theme.value))
+      })
+    ]
+  });
+}
+export {
+  Button,
+  DocsNav,
+  Icon,
+  Link,
+  Select,
+  ThemeSwitcher
+};

package/dist/docs/vite.d.ts

@@ -0,0 +1,31 @@
+/** The Vite plugin `docsTheme` returns: assignable to Vite's own `Plugin`. */
+interface DocsThemePlugin {
+	name: string;
+	/** Puts the theme controller in `<head>`, ahead of everything else. */
+	transformIndexHtml(): Array<{
+		tag: "script";
+		children: string;
+		injectTo: "head-prepend";
+	}>;
+}
+/** What `docsTheme` takes. */
+interface DocsThemeOptions {
+	/** The localStorage key holding the stored preference. Give each site its own. Default `modo-ui-theme`. */
+	storageKey?: string;
+}
+/**
+* A Vite plugin that puts the theme controller in `<head>` ahead of everything
+* else: the stored preference (or the OS one) lands as `.light` / `.dark` on
+* `<html>` before first paint, and `window.__uiTheme` (`get` / `set`) plus the
+* `ui:themechange` event serve the `ThemeSwitcher` panel item.
+*
+* @example
+* // vite.mjs, modo.config.ts `vite: './vite.mjs'`
+* import { docsTheme } from '@justanarthur/modo-ui/docs/vite'
+* config => {
+*   config.plugins = [...(config.plugins ?? []), docsTheme({ storageKey: 'my-ds-theme' })]
+*   return config
+* }
+*/
+declare function docsTheme({ storageKey }?: DocsThemeOptions): DocsThemePlugin;
+export { DocsThemeOptions, DocsThemePlugin, docsTheme };

package/dist/docs/vite.js

@@ -0,0 +1,45 @@
+// docs/vite.ts
+var controller = (storageKey) => `(() => {
+  const KEY = ${JSON.stringify(storageKey)}
+  const root = document.documentElement
+  const mq = window.matchMedia('(prefers-color-scheme: dark)')
+  const read = () => {
+    try {
+      const stored = localStorage.getItem(KEY)
+      return stored === 'light' || stored === 'dark' ? stored : 'system'
+    } catch {
+      return 'system'
+    }
+  }
+  let preference = read()
+  const apply = () => {
+    const resolved = preference === 'system' ? (mq.matches ? 'dark' : 'light') : preference
+    root.classList.toggle('dark', resolved === 'dark')
+    root.classList.toggle('light', resolved === 'light')
+    window.dispatchEvent(new Event('ui:themechange'))
+  }
+  window.__uiTheme = {
+    get: () => preference,
+    set: (next) => {
+      preference = next === 'light' || next === 'dark' ? next : 'system'
+      try {
+        if (preference === 'system') localStorage.removeItem(KEY)
+        else localStorage.setItem(KEY, preference)
+      } catch {}
+      apply()
+    },
+  }
+  mq.addEventListener('change', () => { if (preference === 'system') apply() })
+  apply()
+})()`;
+function docsTheme({ storageKey = "modo-ui-theme" } = {}) {
+  return {
+    name: "modo-ui:docs-theme",
+    transformIndexHtml() {
+      return [{ tag: "script", children: controller(storageKey), injectTo: "head-prepend" }];
+    }
+  };
+}
+export {
+  docsTheme
+};

package/docs/chrome.css

@@ -0,0 +1,120 @@
+/*
+ * The docs chrome's look and layout (modo-ui's own docs, and any design system
+ * documented with modo that loads this file). The lib ships structure only;
+ * these give its hooks the design system's look, tokens only. Both asides are
+ * inset Sidebars (`DocsNav` in ./chrome.tsx), which bring their own look; the
+ * rules for ./chrome.tsx's own elements key on `data-modo-ui`, so no utility
+ * generator has to scan the module.
+ *
+ * Load it after the package stylesheet (base.css / styles.css) and the lib's
+ * structural shell.css, which modo already puts first.
+ */
+
+/* modo's structural shell.css draws an unlayered `*:focus-visible` outline,
+   which would outrank the layered fallbacks and every component's own
+   ring (a second ring on every control). Reverting both properties to the
+   layered cascade hands focus styling back to @layer base and the utilities. */
+*:focus-visible {
+  outline: revert-layer;
+  outline-offset: revert-layer;
+}
+
+:root {
+  /* A fixed length: the lib's 72ch resolves per element, so the lead,
+     captions and paragraphs each ended at a different width. */
+  --modo-measure: 45rem;
+}
+
+/* One reading column on every page: the article (example cards and prop
+   tables included), and an overview's header and grid, keep to the measure,
+   centered in the content area. */
+[data-modo="content"] > * {
+  max-width: var(--modo-measure);
+  margin-inline: auto;
+}
+
+/* The inset layout, as Sidebar.Inset draws it: both asides are inset
+   Sidebars (DocsNav) and the content is the card between them. Each aside's
+   column follows its sidebar's width spring, so hiding one reflows the card;
+   below md both are drawers and the card takes the row. */
+[data-modo="app"] {
+  grid-template-columns: auto minmax(0, 1fr) auto;
+  grid-template-rows: none;
+  grid-template-areas: "sidebar content panel";
+}
+
+[data-modo="sidebar"],
+[data-modo="panel"] {
+  position: sticky;
+  top: 0;
+  /* Over the card: the corner triggers overlap it. */
+  z-index: 1;
+  height: 100vh;
+  max-height: none;
+  /* The Sidebar scrolls its own rows. */
+  overflow: visible;
+}
+
+[data-modo="content"] {
+  margin: var(--space-2);
+  /* The inset topbar's band, where the corner triggers sit. */
+  padding-top: calc(3rem + var(--space-2));
+  border-radius: var(--radius-xl);
+  background-color: var(--surface-2);
+  box-shadow: var(--shadow-2);
+  transition: margin var(--duration-fast);
+}
+
+/* Flush with an open sidebar: its rows keep their own gutter. */
+@media (min-width: 768px) {
+  [data-modo="app"]:has(> [data-modo="sidebar"] [data-slot="sidebar"][data-state="expanded"]) > [data-modo="content"] {
+    margin-left: 0;
+  }
+
+  [data-modo="app"]:has(> [data-modo="panel"] [data-slot="sidebar"][data-state="expanded"]) > [data-modo="content"] {
+    margin-right: 0;
+  }
+}
+
+/* The lib drops the TOC below xl; here the panel is a sidebar at any width. */
+[data-modo="toc"] {
+  display: block;
+}
+
+/* The code panel under an example is flush with the frame, not a card in a card. */
+[data-modo="example-code"] > * {
+  border-radius: 0;
+}
+
+/* The trigger in the card's top corner (DocsNav): level with the topbar band,
+   just outside the aside's edge, a gutter further out while that aside is hidden. */
+[data-modo-ui="nav-trigger"] {
+  position: absolute;
+  top: var(--space-2);
+  display: flex;
+  height: 3rem;
+  align-items: center;
+  padding-inline: calc(var(--space-1) * 1.5);
+  transition: margin var(--duration-fast) cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+[data-modo-ui="nav-trigger"][data-side="left"] {
+  left: 100%;
+}
+
+[data-modo-ui="nav-trigger"][data-side="right"] {
+  right: 100%;
+}
+
+[data-modo-ui="nav-trigger"][data-side="left"][data-gutter] {
+  margin-left: var(--space-2);
+}
+
+[data-modo-ui="nav-trigger"][data-side="right"][data-gutter] {
+  margin-right: var(--space-2);
+}
+
+/* A panel section's control (the Theme select) under its group label. */
+[data-modo-ui="nav-controls"] {
+  padding-inline: var(--space-2);
+}

package/docs/chrome.tsx

@@ -0,0 +1,283 @@
+/*
+ * The docs chrome: every slot adapter modo's viewer needs to render a design
+ * system's docs the way modo-ui's own site is drawn. modo.config.ts picks each
+ * one by export name (`./docs#DocsNav`, or `@justanarthur/modo-ui/docs#DocsNav`
+ * from another package); chrome.css holds the layout rules and the look they
+ * share, so nothing here needs a utility generator to scan this file.
+ */
+
+import { Check, CodeXml, Copy, Link2, Monitor, Moon, Sun } from 'lucide-react'
+import {
+  type AnchorHTMLAttributes,
+  Children,
+  createContext,
+  isValidElement,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState,
+} from 'react'
+import ModoButton from '../components/button'
+import FluidSelect from '../components/inputs/select'
+import Sidebar, {
+  SIDEBAR_KEYBOARD_SHORTCUT,
+  SIDEBAR_KEYBOARD_SHORTCUT_RIGHT,
+  type SidebarSide,
+  useSidebar,
+} from '../components/navigation/sidebar'
+
+/**
+ * Button slot: the chrome's icon buttons (Show code, Copy, the anchor toggles). The chrome passes
+ * `variant="ghost"`, `size="icon-sm"`, `aria-label` and `aria-pressed`; the design system's Button takes them as is.
+ * Pinned so a host with an item named `Button` of another shape is not matched by name.
+ */
+export const Button = ModoButton
+
+/**
+ * Link slot: every chrome and Markdown link, a plain anchor so the chrome's own link styling applies.
+ * Pinned so a host with an item named `Link` of another shape is not matched by name.
+ */
+export function Link(props: AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }) {
+  return <a {...props} />
+}
+
+const icons = { code: CodeXml, copy: Copy, check: Check, link: Link2 }
+
+/** Icon slot: the chrome asks for icons by name; lucide draws them. */
+export function Icon({
+  name,
+}: {
+  /** Which chrome icon to draw. */
+  name: keyof typeof icons
+  /** Accessible text; the button around the icon carries it. */
+  label: string
+}) {
+  const Glyph = icons[name]
+  return <Glyph size={16} strokeWidth={1.5} aria-hidden />
+}
+
+/**
+ * Select slot: the chrome passes a flat `value` / `onChange` / `options`
+ * contract; FF's Select is compositional, so this maps one onto the other.
+ */
+export function Select({
+  value,
+  onChange,
+  options,
+}: {
+  value: string
+  onChange: (value: string) => void
+  options: { value: string; label: string }[]
+}) {
+  return (
+    <FluidSelect value={value} onValueChange={onChange}>
+      <FluidSelect.Trigger />
+      <FluidSelect.Content>
+        {options.map((option, index) => (
+          <FluidSelect.Item key={option.value} value={option.value} index={index}>
+            {option.label}
+          </FluidSelect.Item>
+        ))}
+      </FluidSelect.Content>
+    </FluidSelect>
+  )
+}
+
+type ThemePreference = 'light' | 'dark' | 'system'
+
+declare global {
+  interface Window {
+    __uiTheme?: { get: () => ThemePreference; set: (next: ThemePreference) => void }
+  }
+}
+
+/**
+ * Sidebar slot: both asides of the chrome, each an inset `Sidebar` with its
+ * own `openOnHover` provider, so the content between them is the inset card
+ * (chrome.css). The trigger in the card's corner (or `[` for the nav, `]` for
+ * the panel) switches a side between open and on hover. Below md each side
+ * is a drawer. The panel starts on hover below xl.
+ *
+ * A section of links is a collapsible `Sidebar.Group` whose rows share one
+ * `Sidebar.Menu`, so the current page and the hover highlight melt from link
+ * to link (the TOC's current heading too, as the page scrolls); a panel
+ * section (the Theme select) keeps its control under the group label. Pin it
+ * in modo.config.ts: by name alone modo would adopt a documented `Sidebar`
+ * item, an app shell that needs its provider.
+ */
+export function DocsNav({ children }: { children?: ReactNode }) {
+  const [side, setSide] = useState<SidebarSide>()
+  // The slot gets no side: which aside it landed in tells, before first paint.
+  if (!side) return <div ref={node => node && setSide(node.closest('[data-modo="panel"]') ? 'right' : 'left')} />
+  return <DocsSidebar side={side}>{children}</DocsSidebar>
+}
+
+function DocsSidebar({ side, children }: { side: SidebarSide; children?: ReactNode }) {
+  return (
+    <Sidebar.Provider
+      defaultOpen={side === 'left' || window.matchMedia('(min-width: 1280px)').matches}
+      openOnHover
+      persist={false}
+      shortcut={null}
+    >
+      <Sidebar variant="inset" side={side}>
+        <Sidebar.Content>
+          <nav aria-label={side === 'left' ? 'Docs' : 'Page'}>{children}</nav>
+        </Sidebar.Content>
+      </Sidebar>
+      <DocsNavTrigger side={side} />
+    </Sidebar.Provider>
+  )
+}
+
+/**
+ * The trigger, in the card's top corner where the inset topbar keeps it. The
+ * card sits flush with an open sidebar and a gutter away from a hidden one,
+ * so the trigger follows.
+ */
+function DocsNavTrigger({ side }: { side: SidebarSide }) {
+  const { state, isMobile, toggleSidebar } = useSidebar()
+  useDocsShortcut(side === 'left' ? SIDEBAR_KEYBOARD_SHORTCUT : SIDEBAR_KEYBOARD_SHORTCUT_RIGHT, toggleSidebar)
+
+  return (
+    <div data-modo-ui="nav-trigger" data-side={side} data-gutter={state === 'collapsed' || isMobile ? '' : undefined}>
+      <Sidebar.Trigger />
+    </div>
+  )
+}
+
+/**
+ * `[` / `]` for the docs sidebars, owned here rather than by their providers:
+ * a provider's key goes to the first one mounted when focus is on the page,
+ * and on a fresh load that is a demo in the content, mounted a render before
+ * the chrome's. The demos keep the key while focus is inside one.
+ */
+function useDocsShortcut(key: string, toggle: () => void) {
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== key || event.metaKey || event.ctrlKey || event.altKey) return
+      const target = event.target as HTMLElement
+      if (target.isContentEditable) return
+      if (target.closest('input, textarea, select, [data-modo="content"] [data-slot="sidebar-wrapper"]')) return
+      // Capture phase: the demos' providers listen on window too, and must not toggle with it.
+      event.stopImmediatePropagation()
+      event.preventDefault()
+      toggle()
+    }
+    window.addEventListener('keydown', onKeyDown, true)
+    return () => window.removeEventListener('keydown', onKeyDown, true)
+  }, [key, toggle])
+}
+
+/** How deep a nav element sits: a tier is a section, a group folder a section inside it, a nested group deeper still. */
+const NavDepth = createContext(0)
+
+function DocsNavItem({ href, active, children }: { href: string; active?: boolean; children?: ReactNode }) {
+  const { setOpenMobile } = useSidebar()
+  if (useContext(NavDepth) >= 2) {
+    return (
+      <Sidebar.MenuSubItem>
+        <Sidebar.MenuSubButton href={href} isActive={active} onClick={() => setOpenMobile(false)}>
+          {children}
+        </Sidebar.MenuSubButton>
+      </Sidebar.MenuSubItem>
+    )
+  }
+  return (
+    <Sidebar.MenuItem>
+      <Sidebar.MenuButton isActive={active} render={<a href={href} />} onClick={() => setOpenMobile(false)}>
+        {children}
+      </Sidebar.MenuButton>
+    </Sidebar.MenuItem>
+  )
+}
+
+function DocsNavSection({ title, children }: { title: string; children?: ReactNode }) {
+  const depth = useContext(NavDepth)
+  if (depth >= 1) return <DocsNavGroup title={title}>{children}</DocsNavGroup>
+  const onlyLinks = Children.toArray(children).every(
+    child => isValidElement(child) && (child.type === DocsNavItem || child.type === DocsNavSection),
+  )
+  if (onlyLinks) {
+    return (
+      <Sidebar.Group collapsible>
+        <Sidebar.GroupLabel>{title}</Sidebar.GroupLabel>
+        <NavDepth.Provider value={1}>
+          <Sidebar.Menu>{children}</Sidebar.Menu>
+        </NavDepth.Provider>
+      </Sidebar.Group>
+    )
+  }
+  return (
+    <Sidebar.Group>
+      <Sidebar.GroupLabel>{title}</Sidebar.GroupLabel>
+      <div data-modo-ui="nav-controls">{children}</div>
+    </Sidebar.Group>
+  )
+}
+
+/** Whether a nav subtree holds the current page, nested groups included. */
+const holdsActive = (children: ReactNode): boolean =>
+  Children.toArray(children).some(
+    child =>
+      isValidElement<{ active?: boolean; children?: ReactNode }>(child) &&
+      (child.props.active || holdsActive(child.props.children)),
+  )
+
+/** A group folder inside a tier (or inside another group): a collapsible row, opened while it holds the current page. */
+function DocsNavGroup({ title, children }: { title: string; children?: ReactNode }) {
+  const depth = useContext(NavDepth)
+  const current = holdsActive(children)
+  const [open, setOpen] = useState(current)
+  useEffect(() => {
+    if (current) setOpen(true)
+  }, [current])
+  return (
+    <Sidebar.MenuItem collapsible open={open} onOpenChange={setOpen}>
+      <Sidebar.MenuButton>{title}</Sidebar.MenuButton>
+      <NavDepth.Provider value={depth + 1}>
+        <Sidebar.MenuSub>{children}</Sidebar.MenuSub>
+      </NavDepth.Provider>
+    </Sidebar.MenuItem>
+  )
+}
+
+DocsNav.Item = DocsNavItem
+DocsNav.Section = DocsNavSection
+
+const THEMES = [
+  { value: 'light' as const, label: 'Light', icon: Sun },
+  { value: 'dark' as const, label: 'Dark', icon: Moon },
+  { value: 'system' as const, label: 'System', icon: Monitor },
+]
+
+/**
+ * Theme panel item. The switching itself is the pre-paint script the vite
+ * helper injects (`docsTheme` in `@justanarthur/modo-ui/docs/vite`, `window.__uiTheme`), so a stored preference applies before first
+ * paint; this only reflects and sets it. `ui:themechange` also fires when the
+ * OS flips underneath 'system'.
+ */
+export function ThemeSwitcher() {
+  const [preference, setPreference] = useState<ThemePreference>(() => window.__uiTheme?.get() ?? 'system')
+
+  useEffect(() => {
+    const sync = () => setPreference(window.__uiTheme?.get() ?? 'system')
+    window.addEventListener('ui:themechange', sync)
+    return () => window.removeEventListener('ui:themechange', sync)
+  }, [])
+
+  const active = THEMES.find(theme => theme.value === preference) ?? THEMES[2]!
+
+  return (
+    <FluidSelect value={preference} onValueChange={next => window.__uiTheme?.set(next as ThemePreference)}>
+      <FluidSelect.Trigger aria-label="Color theme" icon={active.icon} />
+      <FluidSelect.Content>
+        {THEMES.map((theme, index) => (
+          <FluidSelect.Item key={theme.value} index={index} value={theme.value} icon={theme.icon}>
+            {theme.label}
+          </FluidSelect.Item>
+        ))}
+      </FluidSelect.Content>
+    </FluidSelect>
+  )
+}

package/docs/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The docs chrome as one module, for a design system documented with modo:
+ * `shell: { Sidebar: '@justanarthur/modo-ui/docs#DocsNav', … }` and
+ * `panel: { items: [{ label: 'Theme', component: '@justanarthur/modo-ui/docs#ThemeSwitcher' }] }`.
+ * The layout and look are `@justanarthur/modo-ui/docs/chrome.css`; the pre-paint theme
+ * controller is `docsTheme` in `@justanarthur/modo-ui/docs/vite`. Never imported by the
+ * package's main entry.
+ */
+export * from './chrome'

package/docs/vite.ts

@@ -0,0 +1,85 @@
+/*
+ * The docs chrome's vite glue, for a modo.config.ts `vite` extension. Node
+ * loads that extension natively, and never strips types from a file under
+ * node_modules, so this ships built (dist/docs/vite.js); it may only use
+ * erasable TypeScript. It imports no `vite` types: `DocsThemePlugin` is the
+ * structural slice of a Vite plugin it returns, so the package needs no
+ * `vite` dependency of its own.
+ */
+
+/** The Vite plugin `docsTheme` returns: assignable to Vite's own `Plugin`. */
+export interface DocsThemePlugin {
+  name: string
+  /** Puts the theme controller in `<head>`, ahead of everything else. */
+  transformIndexHtml(): Array<{ tag: 'script'; children: string; injectTo: 'head-prepend' }>
+}
+
+/** What `docsTheme` takes. */
+export interface DocsThemeOptions {
+  /** The localStorage key holding the stored preference. Give each site its own. Default `modo-ui-theme`. */
+  storageKey?: string
+}
+
+// The design system's `dark:` variant needs a `.dark` ancestor (upstream
+// ThemeProvider sets it on <html>), and `color-scheme` drives every
+// light-dark() token. modo has no theme of its own, so this runs before first
+// paint: it applies the stored preference (or the OS one under 'system') and
+// exposes `window.__uiTheme` for the Theme panel item (`ThemeSwitcher` in
+// chrome.tsx). The 'ui:themechange' event keeps that control in sync when the
+// OS flips underneath 'system'.
+const controller = (storageKey: string) => `(() => {
+  const KEY = ${JSON.stringify(storageKey)}
+  const root = document.documentElement
+  const mq = window.matchMedia('(prefers-color-scheme: dark)')
+  const read = () => {
+    try {
+      const stored = localStorage.getItem(KEY)
+      return stored === 'light' || stored === 'dark' ? stored : 'system'
+    } catch {
+      return 'system'
+    }
+  }
+  let preference = read()
+  const apply = () => {
+    const resolved = preference === 'system' ? (mq.matches ? 'dark' : 'light') : preference
+    root.classList.toggle('dark', resolved === 'dark')
+    root.classList.toggle('light', resolved === 'light')
+    window.dispatchEvent(new Event('ui:themechange'))
+  }
+  window.__uiTheme = {
+    get: () => preference,
+    set: (next) => {
+      preference = next === 'light' || next === 'dark' ? next : 'system'
+      try {
+        if (preference === 'system') localStorage.removeItem(KEY)
+        else localStorage.setItem(KEY, preference)
+      } catch {}
+      apply()
+    },
+  }
+  mq.addEventListener('change', () => { if (preference === 'system') apply() })
+  apply()
+})()`
+
+/**
+ * A Vite plugin that puts the theme controller in `<head>` ahead of everything
+ * else: the stored preference (or the OS one) lands as `.light` / `.dark` on
+ * `<html>` before first paint, and `window.__uiTheme` (`get` / `set`) plus the
+ * `ui:themechange` event serve the `ThemeSwitcher` panel item.
+ *
+ * @example
+ * // vite.mjs, modo.config.ts `vite: './vite.mjs'`
+ * import { docsTheme } from '@justanarthur/modo-ui/docs/vite'
+ * export default config => {
+ *   config.plugins = [...(config.plugins ?? []), docsTheme({ storageKey: 'my-ds-theme' })]
+ *   return config
+ * }
+ */
+export function docsTheme({ storageKey = 'modo-ui-theme' }: DocsThemeOptions = {}): DocsThemePlugin {
+  return {
+    name: 'modo-ui:docs-theme',
+    transformIndexHtml() {
+      return [{ tag: 'script', children: controller(storageKey), injectTo: 'head-prepend' }]
+    },
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justanarthur/modo-ui",
   "type": "module",
-  "version": "0.6.0-canary.6",
+  "version": "0.6.0-canary.7",
   "description": "Fluid Functionalism (Base UI flavor, MIT © 2026 Micka Touillaud) ported to UnoCSS: motion springs, fluid hover, a two-step size ladder and an eight-level elevated surface system. Documented with modo.",
   "license": "MIT",
   "keywords": [
@@ -42,6 +42,7 @@
     "primitives",
     "components",
     "blocks",
+    "docs",
     "DESIGN.md",
     "README.md",
     "LICENSE*"
@@ -234,6 +235,17 @@
       "source": "./preset.ts",
       "default": "./dist/preset.js"
     },
+    "./docs": {
+      "types": "./dist/docs/index.d.ts",
+      "source": "./docs/index.ts",
+      "default": "./dist/docs/index.js"
+    },
+    "./docs/vite": {
+      "types": "./dist/docs/vite.d.ts",
+      "source": "./docs/vite.ts",
+      "default": "./dist/docs/vite.js"
+    },
+    "./docs/chrome.css": "./docs/chrome.css",
     "./styles.css": "./dist/styles.css",
     "./base.css": "./dist/base.css",
     "./tokens.css": "./dist/tokens.css",
@@ -263,6 +275,12 @@
       ],
       "unocss": [
         "dist/preset.d.ts"
+      ],
+      "docs/vite": [
+        "dist/docs/vite.d.ts"
+      ],
+      "docs": [
+        "dist/docs/index.d.ts"
       ]
     }
   },
@@ -290,7 +308,7 @@
     "react-dom": ">=18"
   },
   "devDependencies": {
-    "@justanarthur/modo": "0.9.0-canary.0",
+    "@justanarthur/modo": "0.9.0-canary.1",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
     "bunup": "^0.16.0",