@threadlabs/looma 0.37.0 → 0.37.1

package/docs/README.md

@@ -17,7 +17,7 @@ pnpm exec looma-docs init --title "The Fellowship"
 pnpm exec looma-docs dev
 ```
 
-Use the tool versions accepted by Looma's optional peer dependencies (Markupress 0.8.5 or newer on the supported 0.8 line). Regular component imports do not load the documentation server. Vue and Tiptap remain optional; install them when your own authored documentation mounts the Vue editor.
+Use the tool versions accepted by Looma's optional peer dependencies (Markupress 0.8.7 or newer on the supported 0.8 line). Regular component imports do not load the documentation server. Vue and Tiptap remain optional; install them when your own authored documentation mounts the Vue editor.
 
 Initialization creates three project-owned files:
 
@@ -38,11 +38,43 @@ pnpm exec looma-docs preview
 
 `build` produces a static HTMLKit site in the configured output directory. `preview` serves that output without a repository writer. All commands accept `--root`; `dev` and `preview` also accept `--port`.
 
+## Name your local design system
+
+`looma-docs init --title "Fellowship UI"` sets your site's name. To rename an
+existing local documentation site, edit `title` in `looma.docs.json`; the local
+server rebuilds the header, generated landing page and page titles with that
+name. You do not need to fork Looma or change component imports.
+
+You can also supply your logo and navigation:
+
+```json
+{
+  "title": "Fellowship UI",
+  "logo": {
+    "light": "/assets/fellowship-light.svg",
+    "dark": "/assets/fellowship-dark.svg"
+  },
+  "nav": [{ "label": "Our application", "href": "https://example.com" }]
+}
+```
+
+Merge these fields into your existing configuration. Serve the logo URLs from
+your application's public assets, such as `public/assets/`. Leave `logo` unset
+for a text-only brand. To author your own introduction, set `content` to your
+Markdown directory and add its `index.md`; it replaces the generated landing
+page without replacing component reference pages.
+
+The site name is yours. Component ownership stays accurate: built-in cards
+still identify `@threadlabs/looma`, while your discovered components identify
+the `packageName` you configure below. That is package attribution, not the
+name of your design system. Shared CSS and recipe filenames are configured
+under `theme`; changing a site title does not require renaming those files.
+
 ## Change the rule, keep the family consistent
 
 The authoring model groups shared decisions as Colour, Type, Size & spacing, Material and Motion. The controls expose shared intent: control roominess relative to text, spacing, corners, inner and outer depth, and response pace.
 
-The generated values follow rules. The medium control height is base text size times control roominess; small and large heights follow the size ratio. On touch, small rises to at least the comfortable 44px floor and medium/large grow from it, preserving the ratio. Spacing derives from base text independently of control roominess and follows its own curve: linear at 1, increasingly curved toward 2, with stable endpoints so the largest gaps do not grow without bound. Depth generates families of shadows; it does not add motion amplitude. Fields and buttons with the same size setting use the same box height, while content can still grow when it needs more room.
+The generated values follow rules. The medium control height is base text size times control roominess; small and large heights follow the size ratio. Touch does not inflate the visible size ladder. Hit-area guidance is contextual and adjustable; 44px is a comfort preference for expanded targets, not a mandatory visible height. Invisible targets must not steal neighbouring controls. Spacing derives from base text independently of control roominess and follows its own curve: linear at 1, increasingly curved toward 2, with stable endpoints so the largest gaps do not grow without bound. Depth generates families of shadows; it does not add motion amplitude. Fields and buttons with the same size setting use the same box height, while content can still grow when it needs more room.
 
 Choose a coordinated palette, then refine surface warmth, color intensity and palette relationship. Warmth runs from cool to warm paper and ink, with 0.5 neutral; intensity runs from quiet to vivid, with 0.5 retaining original seed intensity. Tonal keeps seed hues; neighboring and complementary relate quiet hues to the action hue. These decisions regenerate paired light/dark colors through Oklab/OKLCH operations, gamut repair and readability checks. They do not transform existing CSS colors live. Four color seeds remain available for precise edits; the light/dark range previews and resolved values explain adjustments.
 
@@ -56,7 +88,7 @@ Number controls accept arithmetic such as `1rem / 1.2` or `150ms * 2`, calculate
 
 Lengths retain their CSS units, such as `rem`; times retain `ms` or `s`. The downloaded CSS includes the canonical shared CSS derivation rules as well as resolved theme values. Download JSON separately to retain editable decisions and font/preset provenance. Import a downloaded JSON recipe to continue editing it. Keep hand-written CSS in a separate overrides file so regenerating the theme does not replace it.
 
-Undo and Redo move through accepted recipe changes. **Compare entry theme** temporarily previews the theme present when this customizer opened; it does not replace your edits. **Explore nearby styles** previews Warmer, Quieter, More expressive or More compact before you apply it. Palette, Material and Type & spacing locks preserve those families during variations. Cancel preview returns to the current recipe.
+Undo and Redo move through accepted recipe changes. There is no page-entry comparison state: reopening the customizer does not create a hidden before/after reference. **Explore nearby styles** previews Warmer, Quieter, More expressive or More compact before you apply it. Palette, Material and Type & spacing locks preserve those families during variations. Cancel preview returns to the current recipe.
 
 Changes apply throughout the documentation and remain in this browser across navigation and reload until reset. Repository files change only when you save locally. Starting points update the shell and all selected cards. Reset returns to the repository baseline. Invalid input keeps the last valid preview and explains which decision needs attention.
 
@@ -90,7 +122,7 @@ An optional recipe `fonts` mapping records Google family names by `body-font` an
 
 Light position is relative to each surface: horizontal and vertical positions run from 0 to 1, with 0.5, 0 at top centre. Drag the source, use its arrow keys (Shift moves faster), or enter exact percentages. Home returns it to top centre. Spread runs from a concentrated spot to broad illumination; strength controls its intensity. The source influences reflections, illuminated edges and the direction of depth shadows throughout the theme.
 
-Depth controls elevation and recession independently from finish, transmission and motion. Finish controls how strongly a material catches a reflection, from matte to polished; it needs nonzero light strength. Light spread shapes that reflection, while position also directs shadows. A light strength of zero does not remove depth shadows. Edge light catches its boundary; glow spills softly beyond it. Glassiness and surface separation govern the decorative material around floating content, scaled by popup purpose and rendered size. The content plane stays opaque. Overlay translucency changes the shared overlay fill and decorative glass; it does not turn material content transparent. Separation can create a rim even with glassiness at zero. Reflection peaks are bounded for readable text, and reduced transparency disables the ornamental reflection and glow as well as backdrop blur.
+Depth controls elevation and recession independently from finish, transmission and motion. Finish controls how strongly a material catches a reflection, from matte to polished; it needs nonzero light strength. Light spread shapes that reflection, while position also directs shadows. A light strength of zero does not remove depth shadows. Edge light catches its boundary; glow spills beyond it. Glassiness and glow use a gently increasing lower range and an expressive upper response (`g + 2g⁴`), so the maximum can be exuberant without raising restrained defaults. Glassiness and surface separation govern the decorative material around floating content, scaled by popup purpose and rendered size. The content plane stays opaque. Overlay translucency changes the shared overlay fill and decorative glass; it does not turn material content transparent. Separation can create a rim even with glassiness at zero. Reflection peaks are bounded for readable text, and reduced transparency disables the ornamental reflection and glow as well as backdrop blur.
 
 Card keeps surface structure and decorative treatment independent:
 
@@ -128,9 +160,16 @@ Use the public semantic color properties inside those regions. A floating surfac
 
 ## Add your components
 
-Build your design-system components in HTML Next. Their definitions, description attributes, controllers and HTML examples are the source for the generated documentation and customizer cards. Use Looma’s public semantic properties to make your components respond to the same theme.
+Build your design-system components in HTML Next. Their definitions, description attributes, modules and HTML examples are the source for the generated documentation and customizer cards. Use Looma’s public semantic properties to make your components respond to the same theme.
+
+1. Create a directory for your HTML Next component resources, such as `app/components`.
+2. Opt that directory into `components` in `looma.docs.json`, with your package's name.
+3. Put `docs.json` and an `examples/` directory beside each resource, as shown below.
+4. Run `looma-docs dev`. Your components appear beside Looma's in the reference,
+   search and customizer example picker. Resources under registered directories
+   are rediscovered when the local server rebuilds.
 
-Opt into source directories in `looma.docs.json`:
+The configuration can combine your name, authored guides and discovery roots:
 
 ```json
 {

package/docs/card.html

@@ -8,6 +8,7 @@
     <prop name="title" type="string" default="Example">The documented component name.</prop>
     <prop name="description" type="string" default="">The component's authored description.</prop>
     <prop name="exampleTitle" type="string" default="">The selected authored example.</prop>
+    <prop name="previewOnly" type="boolean" default="false">Show only the live example, for compact theme samplers whose host supplies the heading.</prop>
     <prop name="reference" type="boolean" default="false">Use the spacious full-reference example presentation.</prop>
     <prop name="src" type="string" default="">The compiled isolated example page.</prop>
     <prop name="resizable" type="boolean" default="false">Expose a width control for responsive examples.</prop>
@@ -24,7 +25,7 @@
     <div class="preview"><iframe $ref="frame" from:title="$title" from:src="$src" sandbox="allow-scripts" from:loading="$loading" width="100%" height="208"></iframe></div>
     <section $if="$reference" class="example-code"><h4>Code</h4><slot name="code"></slot></section>
     <div $if="$resizable" class="preview-width">      <ui-form-field><label slot="label">Preview width</label><span slot="help">Explore the example at a narrower width.</span><ui-input $ref="width" type="number" min="240" max="1600" value="720" aria-label="Preview width in pixels" size="sm"></ui-input></ui-form-field></div>
-    <div $if="not $reference" class="body"><ui-stack gap="xs">
+    <div $if="not $reference and not $previewOnly" class="body"><ui-stack gap="xs">
       <div class="meta"><span>{$category}</span><code>{$nativeRoot}</code></div>
       <h3><a from:href="$href">{$title}</a></h3>
       <p class="description">{$description}</p>

package/docs/catalog.json

@@ -90,6 +90,11 @@
       "package": "@threadlabs/looma",
       "resource": "@threadlabs/looma/components/ui-curve-editor/ui-curve-editor.html"
     },
+    {
+      "tag": "ui-cycle-button",
+      "package": "@threadlabs/looma",
+      "resource": "@threadlabs/looma/components/ui-cycle-button/ui-cycle-button.html"
+    },
     {
       "tag": "ui-description-item",
       "package": "@threadlabs/looma",
@@ -443,7 +448,7 @@
   ],
   "schemaVersion": 1,
   "package": "@threadlabs/looma",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "groups": [
     {
       "id": "layout",
@@ -2529,7 +2534,7 @@
         {
           "name": "size",
           "property": "size",
-          "description": "Height, padding, and type size. xs is 1.5rem with the smallest text, for a control inside a line of small text; sm is the small control height (2rem by default) with tighter padding and smaller text, md is the standard control height (2.5rem), and lg is taller (3rem) with roomier padding. Under touch, sm grows to the touch minimum, while xs keeps its size inside its line and gains an invisible touch-sized hit area.",
+          "description": "Height, padding, and type size. xs is 1.5rem with the smallest text, for a control inside a line of small text; sm is the small control height (2rem by default) with tighter padding and smaller text, md is the standard control height (2.5rem), and lg is taller (3rem) with roomier padding. Visible sizes stay the same on touch. Inline xs and link actions can gain an adjustable invisible hit area.",
           "type": "keyword",
           "default": "md",
           "options": [
@@ -2670,7 +2675,7 @@
         },
         {
           "name": "size",
-          "description": "Height, padding, and type size. xs is 1.5rem with the smallest text, for a control inside a line of small text; sm is the small control height (2rem by default) with tighter padding and smaller text, md is the standard control height (2.5rem), and lg is taller (3rem) with roomier padding. Under touch, sm grows to the touch minimum, while xs keeps its size inside its line and gains an invisible touch-sized hit area.",
+          "description": "Height, padding, and type size. xs is 1.5rem with the smallest text, for a control inside a line of small text; sm is the small control height (2rem by default) with tighter padding and smaller text, md is the standard control height (2.5rem), and lg is taller (3rem) with roomier padding. Visible sizes stay the same on touch. Inline xs and link actions can gain an adjustable invisible hit area.",
           "type": "\"xs\" | \"sm\" | \"md\" | \"lg\"",
           "default": "md",
           "options": [
@@ -3543,9 +3548,6 @@
           {
             "name": "--ui-control-inset"
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-size-lg"
           },
@@ -4167,6 +4169,16 @@
           "resizable": false,
           "bindings": "",
           "frameworks": {}
+        },
+        {
+          "id": "@threadlabs/looma/ui-cluster/99-theme-sampler",
+          "name": "99-theme-sampler",
+          "title": "Theme sampler",
+          "description": "A compact collection of real controls and a surface for judging a shared theme together.",
+          "markup": "<ui-card treatment=\"expressive\" padding=\"sm\"><ui-stack gap=\"xs\">\n    <ui-cluster gap=\"xs\" justify=\"between\"><ui-text variant=\"eyebrow\">Fellowship office</ui-text><ui-badge tone=\"success\">Ready</ui-badge></ui-cluster>\n    <ui-cluster gap=\"xs\"><ui-button size=\"sm\" preset=\"primary\">Send memo</ui-button><ui-button size=\"sm\" preset=\"standard\">Save draft</ui-button><ui-button\n        size=\"sm\"\n        variant=\"outline\"\n      >Archive</ui-button><ui-cycle-button\n        id=\"sampler-availability\"\n        size=\"sm\"\n        label=\"Availability\"\n        items='[{\"value\":\"available\",\"label\":\"Available\",\"icon\":\"circle-check\"},{\"value\":\"busy\",\"label\":\"Busy\",\"icon\":\"circle-dot\"},{\"value\":\"away\",\"label\":\"Away\",\"icon\":\"moon\"}]'\n      ></ui-cycle-button></ui-cluster>\n    <ui-input-group><ui-icon slot=\"prefix\" name=\"search\"></ui-icon><ui-input\n        size=\"sm\"\n        aria-label=\"Search office\"\n        placeholder=\"Search Fellowship office\"\n      ></ui-input></ui-input-group>\n    <ui-cluster gap=\"xs\"><ui-checkbox size=\"sm\" checked>Notify Sam</ui-checkbox><ui-switch size=\"sm\" checked>Available</ui-switch><ui-badge tone=\"accent\"\n      >Draft</ui-badge></ui-cluster>\n  </ui-stack></ui-card>",
+          "resizable": false,
+          "bindings": "items=availabilityStates",
+          "frameworks": {}
         }
       ]
     },
@@ -4217,9 +4229,6 @@
               "var(--ui-space-1)"
             ]
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-size-lg"
           },
@@ -4487,9 +4496,7 @@
             "declarations": [
               "var(--ui-control-size-md)",
               "var(--ui-control-size-sm)",
-              "var(--ui-control-size-lg)",
-              "max(var(--ui-control-size-md), var(--ui-control-min-block-size))",
-              "max(var(--ui-control-size-sm), var(--ui-control-min-block-size))"
+              "var(--ui-control-size-lg)"
             ]
           },
           {
@@ -4608,9 +4615,6 @@
               "var(--ui-space-1)"
             ]
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-size-lg"
           },
@@ -6847,6 +6851,194 @@
         }
       ]
     },
+    {
+      "tag": "ui-cycle-button",
+      "package": "@threadlabs/looma",
+      "root": "span",
+      "description": "One compact native button that cycles an ordered set of named icon states without moving focus.",
+      "designTokens": {
+        "sources": [
+          "packages/looma/src/components/ui-cycle-button/ui-cycle-button.html"
+        ],
+        "component": [],
+        "shared": []
+      },
+      "attributes": [
+        {
+          "name": "disabled",
+          "property": "disabled",
+          "description": "Prevents cycling while keeping the selected state visible.",
+          "type": "boolean",
+          "default": false
+        },
+        {
+          "name": "index",
+          "property": "index",
+          "description": "Initial or externally selected zero-based state. The first state is the default.",
+          "type": "number",
+          "default": 0
+        },
+        {
+          "name": "items",
+          "property": "items",
+          "description": "Ordered states with a value, readable label and Looma icon name. Activation advances to the next state and wraps.",
+          "type": "list(object)",
+          "fields": [
+            {
+              "path": "[].value",
+              "type": "string",
+              "required": true
+            },
+            {
+              "path": "[].label",
+              "type": "string",
+              "required": true
+            },
+            {
+              "path": "[].icon",
+              "type": "string",
+              "required": true
+            }
+          ]
+        },
+        {
+          "name": "label",
+          "property": "label",
+          "description": "What the button changes, such as Appearance. The selected state is included in its accessible name.",
+          "type": "string",
+          "default": "State"
+        },
+        {
+          "name": "size",
+          "property": "size",
+          "description": "Uses IconButton's compact visible sizes and adjustable invisible touch area.",
+          "type": "keyword",
+          "default": "md",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        {
+          "name": "variant",
+          "property": "variant",
+          "description": "Uses IconButton's standard emphasis.",
+          "type": "keyword",
+          "default": "outline",
+          "options": [
+            "ghost",
+            "outline",
+            "solid"
+          ]
+        }
+      ],
+      "properties": [
+        {
+          "name": "disabled",
+          "description": "Prevents cycling while keeping the selected state visible.",
+          "type": "boolean",
+          "default": false
+        },
+        {
+          "name": "index",
+          "description": "Initial or externally selected zero-based state. The first state is the default.",
+          "type": "number",
+          "default": 0
+        },
+        {
+          "name": "items",
+          "description": "Ordered states with a value, readable label and Looma icon name. Activation advances to the next state and wraps.",
+          "type": "readonly ({ readonly value: string; readonly label: string; readonly icon: string })[]",
+          "fields": [
+            {
+              "path": "[].value",
+              "type": "string",
+              "required": true
+            },
+            {
+              "path": "[].label",
+              "type": "string",
+              "required": true
+            },
+            {
+              "path": "[].icon",
+              "type": "string",
+              "required": true
+            }
+          ]
+        },
+        {
+          "name": "label",
+          "description": "What the button changes, such as Appearance. The selected state is included in its accessible name.",
+          "type": "string",
+          "default": "State"
+        },
+        {
+          "name": "size",
+          "description": "Uses IconButton's compact visible sizes and adjustable invisible touch area.",
+          "type": "\"sm\" | \"md\" | \"lg\"",
+          "default": "md",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        {
+          "name": "variant",
+          "description": "Uses IconButton's standard emphasis.",
+          "type": "\"ghost\" | \"outline\" | \"solid\"",
+          "default": "outline",
+          "options": [
+            "ghost",
+            "outline",
+            "solid"
+          ]
+        }
+      ],
+      "events": [
+        {
+          "name": "change",
+          "detailType": "{ readonly value: string; readonly index: number }",
+          "detailSchema": "object",
+          "fields": [
+            {
+              "path": "value",
+              "type": "string",
+              "required": true
+            },
+            {
+              "path": "index",
+              "type": "number",
+              "required": true
+            }
+          ],
+          "detailDocs": "Emitted when a toggleable control changes checked state."
+        }
+      ],
+      "slots": [],
+      "group": "forms",
+      "id": "@threadlabs/looma/ui-cycle-button",
+      "title": "Cycle Button",
+      "resource": "@threadlabs/looma/components/ui-cycle-button/ui-cycle-button.html",
+      "targets": [
+        "html-next",
+        "vue"
+      ],
+      "examples": [
+        {
+          "id": "@threadlabs/looma/ui-cycle-button/01-appearance",
+          "name": "01-appearance",
+          "title": "Cycling appearance",
+          "description": "One native button cycles Automatic, Light and Dark while preserving keyboard focus.",
+          "markup": "<ui-cluster gap=\"s\"><ui-text>Appearance</ui-text><ui-cycle-button\n    id=\"appearance-cycle\"\n    label=\"Appearance\"\n    items='[{\"value\":\"automatic\",\"label\":\"Automatic\",\"icon\":\"monitor\"},{\"value\":\"light\",\"label\":\"Light\",\"icon\":\"sun\"},{\"value\":\"dark\",\"label\":\"Dark\",\"icon\":\"moon\"}]'\n  ></ui-cycle-button></ui-cluster>",
+          "resizable": false,
+          "bindings": "items=appearanceStates",
+          "frameworks": {}
+        }
+      ]
+    },
     {
       "tag": "ui-description-item",
       "package": "@threadlabs/looma",
@@ -12790,7 +12982,7 @@
         {
           "name": "match-button",
           "property": "matchButton",
-          "description": "Matches a boxed Button of the same size when the two share a flex row. Uses the control-size theme tokens and stretches to the row's height, including touch-sized controls. Leave it off for compact toolbar and inline icon buttons.",
+          "description": "Matches a boxed Button of the same size when the two share a flex row. Uses the control-size theme tokens and stretches to the row's height, on mouse and touch alike. Leave it off for compact toolbar and inline icon buttons.",
           "type": "boolean",
           "default": false
         },
@@ -12832,7 +13024,7 @@
         {
           "name": "size",
           "property": "size",
-          "description": "Button and icon size together: sm is 1.75rem with a small icon, md is 2rem, and lg is 2.5rem with a large icon. On touch, every size gets an invisible hit area of at least 44px.",
+          "description": "Button and icon size together: sm is 1.75rem with a small icon, md is 2rem, and lg is 2.5rem with a large icon. Touch can use an invisible hit area sized by the adjustable control target preference.",
           "type": "keyword",
           "default": "md",
           "options": [
@@ -12906,7 +13098,7 @@
         },
         {
           "name": "matchButton",
-          "description": "Matches a boxed Button of the same size when the two share a flex row. Uses the control-size theme tokens and stretches to the row's height, including touch-sized controls. Leave it off for compact toolbar and inline icon buttons.",
+          "description": "Matches a boxed Button of the same size when the two share a flex row. Uses the control-size theme tokens and stretches to the row's height, on mouse and touch alike. Leave it off for compact toolbar and inline icon buttons.",
           "type": "boolean",
           "default": false
         },
@@ -12943,7 +13135,7 @@
         },
         {
           "name": "size",
-          "description": "Button and icon size together: sm is 1.75rem with a small icon, md is 2rem, and lg is 2.5rem with a large icon. On touch, every size gets an invisible hit area of at least 44px.",
+          "description": "Button and icon size together: sm is 1.75rem with a small icon, md is 2rem, and lg is 2.5rem with a large icon. Touch can use an invisible hit area sized by the adjustable control target preference.",
           "type": "\"sm\" | \"md\" | \"lg\"",
           "default": "md",
           "options": [
@@ -13376,9 +13568,7 @@
             "fallbacks": [
               "var(--ui-control-size-md)",
               "var(--ui-control-size-sm)",
-              "var(--ui-control-size-lg)",
-              "max(var(--ui-control-size-md), var(--ui-control-min-block-size))",
-              "max(var(--ui-control-size-sm), var(--ui-control-min-block-size))"
+              "var(--ui-control-size-lg)"
             ]
           },
           {
@@ -13452,9 +13642,6 @@
               "var(--ui-space-1)"
             ]
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-placeholder",
             "fallbacks": [
@@ -13822,9 +14009,6 @@
           {
             "name": "--ui-control-inset"
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-size-lg"
           },
@@ -17415,9 +17599,6 @@
           {
             "name": "--ui-choice-mark-size"
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-size-lg"
           },
@@ -19139,9 +19320,6 @@
               "var(--ui-space-1)"
             ]
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-size-lg"
           },
@@ -20767,9 +20945,6 @@
           {
             "name": "--ui-control-inset"
           },
-          {
-            "name": "--ui-control-min-block-size"
-          },
           {
             "name": "--ui-control-size-lg"
           },

package/docs/customizer-render.mjs

@@ -11,9 +11,9 @@ export function customizerResource(site, input = defaultRecipe()) {
   const toCard = example => Object.fromEntries(cardFields.map(key => [key, example[key]]));
   const initial = ['ui-button', 'ui-input', 'ui-color-picker', 'ui-checkbox', 'ui-card', 'ui-switch', 'ui-text', 'ui-dialog', 'ui-popover'].map(tag => examples.find(example => example.tag === tag && (tag !== 'ui-button' || example.id.endsWith('/02-variant')) && (tag !== 'ui-text' || example.id.endsWith('/02-variants')) && (tag !== 'ui-card' || example.id.endsWith('/04-expressive-surface'))) ?? examples.find(example => example.tag === tag)).filter(Boolean).map(toCard);
   if (!initial.length && examples.length) initial.push(toCard(examples[0]));
-  const documentationCard = (tag, suffix) => {
+  const documentationCard = (tag, suffix, previewOnly = false) => {
     const example = examples.find(item => item.tag === tag && (!suffix || item.id.endsWith(suffix))) ?? examples.find(item => item.tag === tag);
-    return example ? `<looma-example-card ${cardFields.filter(key => key !== 'id').map(key => `${key.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="${escape(String(example[key]))}"`).join(' ')} identity="${escape(example.id)}" loading="lazy"></looma-example-card>` : '';
+    return example ? `<looma-example-card ${previewOnly ? 'preview-only' : ''} ${cardFields.filter(key => key !== 'id').map(key => `${key.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="${escape(String(example[key]))}"`).join(' ')} identity="${escape(example.id)}" loading="lazy"></looma-example-card>` : '';
   };
   const renderField = field => {
     const value = recipe.values[field.id], editor = valueEditor(field, value, { remPixels: parseFloat(recipe.values['text-size']) });
@@ -45,7 +45,7 @@ export function customizerResource(site, input = defaultRecipe()) {
     'Colour': `${renderPreset('palette', 'overview')}<ui-text variant="caption">Coordinated light and dark ranges.</ui-text><ui-button data-action="refine-palette">Refine palette</ui-button>`,
     'Material': `${renderPreset('material', 'overview')}<ui-text variant="caption">Material and light, shared everywhere.</ui-text><ui-button data-action="refine-material">Refine material & light</ui-button>`,
     'Motion': `<ui-text variant="caption">Open and close this real documentation example to feel the response pace and curve. Reduced motion follows your system preference.</ui-text>${documentationCard('ui-popover')}`,
-    'Size & spacing': `<ui-text variant="caption">Shared size ladder: buttons, fields and swatches align at each step. Touch raises the family together.</ui-text><ui-stack>${['sm','md','lg'].map((size,index) => `<ui-stack gap="xs" data-size-sample="${size}"><ui-text variant="caption">${['Small','Medium','Large'][index]}<span data-size-readout></span></ui-text><ui-cluster><ui-button size="${size}">Action</ui-button><ui-input size="${size}" style="--ui-input-inline-size: 10ch" label="${size} size sample" value="Frodo"></ui-input><ui-color-picker size="${size}" label="${size} swatch sample"></ui-color-picker></ui-cluster></ui-stack>`).join('')}</ui-stack><div class="spacing-samples" data-spacing-samples role="img" aria-label="Spacing progression"><span></span><span></span><span></span><span></span></div><ui-disclosure summary="How the scale grows"><ui-stack><p>Control roominess relates every field and button to base text. Size ratio separates small from large. On touch, the whole family grows together to keep targets comfortable. Spacing and its curve shape page rhythm independently.</p>${themeFields.filter(item => ['scale-contrast','space-curve'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
+    'Size & spacing': `<ui-text variant="caption">Shared size ladder: buttons, fields and swatches align at each step.</ui-text><ui-stack>${['sm','md','lg'].map((size,index) => `<ui-stack gap="xs" data-size-sample="${size}"><ui-text variant="caption">${['Small','Medium','Large'][index]}<span data-size-readout></span></ui-text><ui-cluster><ui-button size="${size}">Action</ui-button><ui-input size="${size}" style="--ui-input-inline-size: 10ch" label="${size} size sample" value="Frodo"></ui-input><ui-color-picker size="${size}" label="${size} swatch sample"></ui-color-picker></ui-cluster></ui-stack>`).join('')}</ui-stack><div class="spacing-samples" data-spacing-samples role="img" aria-label="Spacing progression"><span></span><span></span><span></span><span></span></div><ui-disclosure summary="How the scale grows"><ui-stack><p>Control roominess relates every field and button to base text. Size ratio separates small from large. Visible proportions stay the same on touch; hit areas are a separate design choice. Spacing and its curve shape page rhythm independently.</p>${themeFields.filter(item => ['scale-contrast','space-curve'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
   };
   const families = [...new Set(themeFields.map(field => field.family))].filter(family => !['Colour', 'Material'].includes(family)).map(family => `<ui-disclosure summary="${family}"><ui-stack>${themeFields.filter(item => item.family === family && !['scale-contrast', 'space-curve'].includes(item.id)).map(renderField).join('')}${supplements[family] ?? ''}</ui-stack></ui-disclosure>`).join('');
   const refinement = (family, content) => `<section data-refinement-view="${family}" hidden tabindex="-1" aria-label="${family === 'material' ? 'Material and light refinement' : 'Palette refinement'}"><ui-stack gap="xl"><ui-cluster justify="between"><ui-button data-action="back">Back to customization</ui-button><ui-button data-action="restore-${family}">Restore ${family} preset</ui-button></ui-cluster><ui-text variant="heading" as="h2">${family === 'material' ? 'Refine material & light' : 'Refine your palette'}</ui-text><p>These are advanced refinements of the same persistent theme. Every change applies throughout your documentation.</p>${renderPreset(family, 'refinement')}${content}</ui-stack></section>`;
@@ -59,7 +59,7 @@ export function customizerResource(site, input = defaultRecipe()) {
   <div data-looma-customizer data-recipe="${escape(JSON.stringify(recipe))}" data-base="${escape(site.base)}" data-mode="${site.config.local ? 'local' : 'public'}" data-revision="${escape(site.config.revision ?? '')}">
   <ui-stack gap="l"><ui-text>Choose a starting point, refine shared decisions, and see them on real documentation examples.</ui-text>
   <ui-text variant="caption" role="status" aria-live="polite" data-message>Changes are remembered across the documentation.</ui-text>
-  <ui-cluster><ui-text variant="label" data-theme-origin></ui-text><ui-button size="sm" data-action="undo" disabled>Undo</ui-button><ui-button size="sm" data-action="redo" disabled>Redo</ui-button><ui-button size="sm" data-action="compare" aria-pressed="false">Compare entry theme</ui-button></ui-cluster>
+  <ui-cluster><ui-text variant="label" data-theme-origin></ui-text><ui-button size="sm" data-action="undo" disabled>Undo</ui-button><ui-button size="sm" data-action="redo" disabled>Redo</ui-button></ui-cluster>
   <ui-disclosure summary="Explore nearby styles"><ui-stack><ui-text variant="caption">Preview a small change before applying it. Locks preserve your selected families.</ui-text><ui-cluster>${[['palette','Palette'],['material','Material'],['type','Type & spacing']].map(([id,label]) => `<ui-checkbox size="sm" data-family-lock="${id}">Lock ${label}</ui-checkbox>`).join('')}</ui-cluster><ui-form-field><label slot="label" for="nearby-style">Nearby style</label><ui-select id="nearby-style" data-variation-choice>${Object.entries(themeVariations).map(([id,label]) => `<option value="${id}">${label}</option>`).join('')}</ui-select></ui-form-field><ui-button data-action="preview-variation">Preview variation</ui-button><div data-variation-confirm hidden><ui-stack><ui-text data-variation-description role="status"></ui-text><ui-cluster><ui-button preset="primary" data-action="apply-variation">Apply variation</ui-button><ui-button data-action="cancel-variation">Cancel preview</ui-button></ui-cluster></ui-stack></div></ui-stack></ui-disclosure>
   ${materialView}${paletteView}
   <div class="customizer-layout" data-customizer-overview>
@@ -73,6 +73,7 @@ export function customizerResource(site, input = defaultRecipe()) {
   <ui-disclosure summary="Use your theme"><p>Every export includes light and dark. Leave data-theme off the page to follow system preference, or set it to light or dark on the page or a section. <a href="${escape(site.base)}design-system/">Installation and mode guidance</a></p></ui-disclosure>
   <ui-disclosure summary="Theme CSS"><ui-textarea data-css readonly rows="12" aria-label="Generated theme CSS" value="${escape(themeCSS(recipe))}"></ui-textarea></ui-disclosure></ui-stack></ui-disclosure>
   </ui-stack></aside>
+  <section data-theme-sampler><ui-stack gap="xs"><ui-text variant="heading" as="h2">Theme sampler</ui-text>${documentationCard('ui-cluster', '/99-theme-sampler', true)}</ui-stack></section>
   <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Filter previews</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><ui-text variant="caption" role="status" aria-live="polite" data-example-count></ui-text><ui-disclosure summary="Add an example"><ui-stack><ui-combobox id="example-choice" data-add-example label="Choose a component example" placeholder="Search buttons, fields, dialogs…" disclosure clearable>${options}</ui-combobox><ui-button data-action="add" disabled>Add to preview</ui-button></ui-stack></ui-disclosure>
   <ui-grid columns="2" min="sm"><section $each="card of $cards" $key="$card.id"><looma-example-card ${cardFields.filter(name => name !== 'id').map(name => `from:${name.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="$card.${name}"`).join(' ')} from:identity="$card.id" loading="eager" removable></looma-example-card></section></ui-grid>
   <noscript>Enable JavaScript to edit the theme. The component reference and example previews remain available.</noscript>
@@ -80,7 +81,7 @@ export function customizerResource(site, input = defaultRecipe()) {
   <style>
     [data-customizer-overview][hidden], [data-refinement-view][hidden], [data-variation-confirm][hidden] { display: none !important; }
     .customizer-layout { display: grid !important; grid-template-columns: minmax(16rem, 20rem) minmax(0, 1fr); gap: var(--ui-space-6) !important; align-items: start !important; }
-    aside { position: sticky; inset-block-start: 5rem; max-block-size: calc(100dvh - 6rem); overflow: auto; padding-inline-end: var(--ui-space-2) !important; }
+    aside { grid-row: 1 / span 2; position: sticky; inset-block-start: 5rem; max-block-size: calc(100dvh - 6rem); overflow: auto; padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)) !important; scroll-padding: max(var(--ui-space-2), calc(var(--ui-focus-width) * 2)); }
     .examples { min-inline-size: 0; }
     .refinement-layout { display: grid !important; grid-template-columns: minmax(0, 1.2fr) minmax(16rem, 1fr); gap: var(--ui-space-6) !important; align-items: start !important; }
     [data-refinement-view] { scroll-margin-block-start: 5rem; }
@@ -94,6 +95,6 @@ export function customizerResource(site, input = defaultRecipe()) {
     .palette-canvas { background: var(--ui-surface); }
     .palette-content { background: var(--ui-surface-raised); }
     .palette-action { background: var(--ui-accent); }
-    @media (max-width: 64rem) { .customizer-layout, .refinement-layout { grid-template-columns: minmax(0, 1fr); } aside { position: static; max-block-size: none; } }
+    @media (max-width: 64rem) { .customizer-layout, .refinement-layout { grid-template-columns: minmax(0, 1fr); } aside { grid-row: auto; order: 2; position: static; max-block-size: none; } [data-theme-sampler] { order: 1; } .examples { order: 3; } }
   </style></template>`;
 }