@threadlabs/looma 0.37.5 → 0.38.0

package/docs/README.md

@@ -12,7 +12,7 @@ In a project with a `package.json`, install Looma and its documentation tools:
 
 ```sh
 pnpm add @threadlabs/looma @nextwebwg/html-next@1.0.0-alpha.69
-pnpm add -D markupress@^0.9.0 @nextwebwg/htmlkit@1.0.0-alpha.69 vite
+pnpm add -D markupress@^0.9.1 @nextwebwg/htmlkit@1.0.0-alpha.69 vite
 pnpm exec looma-docs init --title "The Fellowship"
 pnpm exec looma-docs dev
 ```
@@ -33,6 +33,12 @@ The CSS includes generated derivation rules as well as values. Re-export or save
 
 Open the local address printed by `dev`, choose **Customize**, and save your theme. Saving updates those shared theme files and rebuilds the documentation. Your application consumes the same CSS import. A static or public site instead offers CSS and recipe downloads.
 
+Starting points set a complete identity across color, typography, shape, spacing,
+material and motion. Palette and material refinements then change only their own
+families. The compact sampler includes heading, body and supporting text beside
+the controls. Search components searches your whole discovered catalog; nine
+previews render initially, and **Show more components** reveals the next group.
+
 ```sh
 pnpm exec looma-docs build
 pnpm exec looma-docs preview
@@ -74,15 +80,15 @@ 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 authoring model groups shared decisions as Colour, Type, Size & spacing, Material and Motion. The controls expose shared intent: control roominess relative to text, rhythm, 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. 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.
+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. Rhythm coordinates gaps and unitless line-height multipliers. Spacing fine-tunes gaps independently of text ratios. 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.
+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. Keep my colors preserves the base hues; Related colors and Contrasting colors tint quiet surfaces toward neighboring and opposite hues. 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 Base colors remain visible for precise edits; the light/dark range previews and resolved values explain adjustments.
 
 The customizer uses Starting point, Palette and Material as its controls sidebar, with documentation navigation left out of this workspace. Detailed type, size and motion controls, example selection and exports open when needed.
 
-The main customizer offers Material and Palette presets. **Refine material & light** opens a focused view with a movable light source, real component samples and bounded surface controls. **Refine palette** opens the coordinated light/dark ranges and their four color seeds. Both views edit the same theme as the main customizer. Returning to the overview, navigating to a component, or reloading keeps the result.
+The main customizer offers Material and Palette presets. **Refine material & light** opens a focused view with a movable light source, real component samples and bounded surface controls. **Refine palette** opens the coordinated light/dark ranges and their four Base colors. Both views edit the same theme as the main customizer. Returning to the overview, navigating to a component, or reloading keeps the result.
 
 A refined preset keeps its name with “customized” beside it. **Restore material preset** resets only material and light; **Restore palette preset** resets only the palette. These family choices are recorded in the recipe's optional `presets` mapping. The `values` mapping remains the complete source of the generated theme; a preset is a named combination of those values.
 
@@ -92,9 +98,14 @@ Lengths retain their CSS units, such as `rem`; times retain `ms` or `s`. The dow
 
 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.
+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 restores the selected starting theme’s values and remains undoable. Removing the header’s Custom theme chip instead clears the browser override and restores the repository baseline. Invalid input keeps the last valid preview and explains which decision needs attention.
+
+Text offers body, display, heading, label, caption, eyebrow and code roles. Choose a heading's document level with `as` independently from its visual role. Button and IconButton keep appearance and tone independent, with four optional shortcuts: primary (solid accent), standard (solid neutral), quiet (ghost neutral) and destructive (solid danger). A named preset takes precedence over the separate choices; `preset="none"` uses the separate choices. Both default to neutral; choose `tone="accent"` or `preset="primary"` explicitly for emphasis.
 
-Text offers body, display, heading, label, caption, eyebrow and code roles. Choose a heading's document level with `as` independently from its visual role. Button and IconButton keep appearance and tone independent, with four optional shortcuts: primary (solid accent), standard (solid neutral), quiet (ghost neutral) and destructive (solid danger). A named preset takes precedence over the separate choices; `preset="none"` preserves their existing defaults.
+**Font** sets body text and controls. Headings follow it while **Heading font** is
+**Same as main font**; choose a second face there for headings and display text.
+Google selections preview real faces and include their import in downloaded or
+locally saved CSS. System font uses the operating system and needs no download.
 
 ## Theme decisions and public properties
 
@@ -102,10 +113,10 @@ The [public token reference](https://github.com/threadlabs-studio/looma/blob/mai
 
 | Family | Recipe decisions → CSS properties |
 | --- | --- |
-| Palette seeds | `action` → `--ui-accent`; `canvas` → `--ui-surface`; `surface` → `--ui-surface-raised`; `text` → `--ui-text` |
+| Base colors | `action` → `--ui-accent`; `canvas` → `--ui-surface`; `surface` → `--ui-surface-raised`; `text` → `--ui-text` |
 | Palette generation (recipe only) | `warmth`, `color-intensity`, `palette-relationship`; compiled into resolved color roles, with no matching CSS custom properties |
 | Type | `body-font` → `--ui-font-sans`; `display-font` → `--ui-font-display`; `text-size` → `--ui-font-size`; `text-weight` → `--ui-font-medium` |
-| Size & spacing | `control-roominess` → `--ui-control-roominess`; `spacing` → `--ui-spacing`; `scale-contrast` → `--ui-scale-ratio`; `space-curve` → `--ui-space-curve`; `corner-roundness` → `--ui-radius-md`; `line-weight` → `--ui-border-width` |
+| Rhythm & spacing | `rhythm` → `--ui-rhythm`; `control-roominess` → `--ui-control-roominess`; `spacing` → `--ui-spacing`; `scale-contrast` → `--ui-scale-ratio`; `space-curve` → `--ui-space-curve`; `corner-roundness` → `--ui-radius-md`; `line-weight` → `--ui-border-width` |
 | Depth and transmission | `outer-depth` → `--ui-outer-depth`; `inner-depth` → `--ui-inner-depth`; `glassiness` → `--ui-glassiness`; `surface-separation` → `--ui-surface-separation`; `translucency` → `--ui-overlay-translucency` |
 | Finish and illumination | `finish` → `--ui-finish`; `edge-light` → `--ui-edge-light`; `glow` → `--ui-glow`; `light-x` → `--ui-light-x`; `light-y` → `--ui-light-y`; `light-spread` → `--ui-light-spread`; `light-strength` → `--ui-light-strength` |
 | Motion | `response-time` → `--ui-motion-fast`; `response-curve` → `--ui-motion-ease` |
@@ -140,7 +151,7 @@ To add a sample to the preview, search **Choose a component example**, select a
 
 ## Use light, dark, or both
 
-Every generated theme includes a coordinated light/dark pair. The type, geometry and motion decisions stay shared. Both palettes derive readable text, outlines, focus and action states from the same identity; the generator may adjust requested color seeds to maintain contrast.
+Every generated theme includes a coordinated light/dark pair. The type, geometry and motion decisions stay shared. Both palettes derive readable text, outlines, focus and action states from the same identity; the generator may adjust requested base colors to maintain contrast.
 
 Load the generated CSS after Looma's tokens and palette. Choose how it runs:
 
@@ -237,3 +248,5 @@ Use the `@threadlabs/looma/docs` entrypoint for programmatic discovery, catalog
 The local editor writes only the configured recipe and CSS inside the project. It rejects symlink paths, generated or dependency directories, cross-origin save requests and stale file revisions. A competing edit leaves your unsaved preview in place; reload and reconcile it before saving again. Examples run in isolated frames and receive theme CSS, never the local editing capability.
 
 The writer stages complete files, serializes saves with a project lock, and rolls back the recipe if replacing the CSS fails. If a process stops during a save or build, close the old editor before removing its `.looma/theme-write.lock` or `.looma/docs-build.lock`; restart and save the loaded recipe to regenerate a consistent pair. Change the server base, output directory or theme-file paths by restarting `dev`.
+
+Preset choices use the styled, searchable dropdown already used for fonts and component examples. Palette choices include four color swatches for the accent, neutral fill, canvas and text; the selected field previews the current theme. An inherited default keeps muted text while its options remain readable.

package/docs/catalog.json

@@ -365,6 +365,11 @@
       "package": "@threadlabs/looma",
       "resource": "@threadlabs/looma/components/ui-sidebar/ui-sidebar.html"
     },
+    {
+      "tag": "ui-skeleton",
+      "package": "@threadlabs/looma",
+      "resource": "@threadlabs/looma/components/ui-skeleton/ui-skeleton.html"
+    },
     {
       "tag": "ui-slider",
       "package": "@threadlabs/looma",
@@ -453,7 +458,7 @@
   ],
   "schemaVersion": 1,
   "package": "@threadlabs/looma",
-  "version": "0.37.5",
+  "version": "0.38.0",
   "groups": [
     {
       "id": "layout",
@@ -1980,7 +1985,7 @@
           {
             "name": "--ui-button-ghost-active-surface",
             "fallbacks": [
-              "color-mix(in oklch, var(--ui-surface), var(--_tone) 3%)"
+              "oklch(from var(--_tone) l c h / 18%)"
             ]
           },
           {
@@ -2002,6 +2007,7 @@
             ],
             "fallbacks": [
               "var(--ui-border-strong)",
+              "var(--ui-control-border-hover, var(--ui-control-border))",
               "var(--ui-control-border-hover, var(--ui-text-secondary))"
             ]
           },
@@ -2060,6 +2066,7 @@
             "fallbacks": [
               "oklch(from var(--_tone) l c h / 5%)",
               "var(--ui-neutral-surface)",
+              "transparent",
               "var(--ui-control-surface, var(--ui-surface-elevated))"
             ]
           },
@@ -2153,6 +2160,7 @@
           {
             "name": "--ui-control-border-hover",
             "fallbacks": [
+              "var(--ui-control-border)",
               "var(--ui-text-secondary)"
             ]
           },
@@ -2360,6 +2368,15 @@
           {
             "name": "--ui-radius-sm"
           },
+          {
+            "name": "--ui-selection-border"
+          },
+          {
+            "name": "--ui-selection-surface"
+          },
+          {
+            "name": "--ui-selection-text"
+          },
           {
             "name": "--ui-shadow-sm"
           },
@@ -2574,7 +2591,7 @@
           "property": "tone",
           "description": "Which colour the button speaks in. It applies to every variant, so an outline, a ghost, and a solid in the same tone are the same action at three volumes: tone=\"danger\" variant=\"outline\" is a destructive secondary action. neutral is the quiet one, for a button that should not claim a colour. The field variant always uses neutral field colors.",
           "type": "keyword",
-          "default": "accent",
+          "default": "neutral",
           "options": [
             "accent",
             "neutral",
@@ -2718,7 +2735,7 @@
           "name": "tone",
           "description": "Which colour the button speaks in. It applies to every variant, so an outline, a ghost, and a solid in the same tone are the same action at three volumes: tone=\"danger\" variant=\"outline\" is a destructive secondary action. neutral is the quiet one, for a button that should not claim a colour. The field variant always uses neutral field colors.",
           "type": "\"accent\" | \"neutral\" | \"danger\" | \"success\" | \"warning\" | \"info\"",
-          "default": "accent",
+          "default": "neutral",
           "options": [
             "accent",
             "neutral",
@@ -2798,7 +2815,7 @@
           "name": "02-variant",
           "title": "variant",
           "description": "Appearance sets emphasis independently from tone: solid neutral is a standard action, and danger can be an outline. Named presets combine those shared choices.",
-          "markup": "<ui-cluster gap=\"s\">\n  <ui-button variant=\"solid\">Solid</ui-button>\n  <ui-button variant=\"outline\">Outline</ui-button>\n  <ui-button variant=\"ghost\">Ghost</ui-button>\n  <ui-button variant=\"danger\">Danger</ui-button>\n  <ui-button variant=\"solid\" tone=\"neutral\">Solid neutral</ui-button>\n  <ui-button variant=\"outline\" tone=\"danger\">Danger outline</ui-button>\n  <ui-button preset=\"primary\">Primary</ui-button>\n  <ui-button preset=\"standard\">Standard</ui-button>\n  <ui-button preset=\"quiet\">Quiet</ui-button>\n  <ui-button preset=\"destructive\">Destructive</ui-button>\n</ui-cluster>",
+          "markup": "<ui-cluster gap=\"s\">\n  <ui-button variant=\"solid\" tone=\"accent\">Solid</ui-button>\n  <ui-button variant=\"outline\" tone=\"accent\">Outline</ui-button>\n  <ui-button variant=\"ghost\" tone=\"accent\">Ghost</ui-button>\n  <ui-button variant=\"danger\">Danger</ui-button>\n  <ui-button variant=\"solid\" tone=\"neutral\">Solid neutral</ui-button>\n  <ui-button variant=\"outline\" tone=\"danger\">Danger outline</ui-button>\n  <ui-button preset=\"primary\">Primary</ui-button>\n  <ui-button preset=\"standard\">Standard</ui-button>\n  <ui-button preset=\"quiet\">Quiet</ui-button>\n  <ui-button preset=\"destructive\">Destructive</ui-button>\n</ui-cluster>",
           "resizable": false,
           "bindings": "",
           "frameworks": {}
@@ -4203,9 +4220,9 @@
           "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>",
+          "markup": "<ui-card treatment=\"expressive\" padding=\"sm\"><ui-stack gap=\"s\">\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-text variant=\"heading\" as=\"h3\">Second breakfast, sorted.</ui-text>\n    <ui-text>Frodo plans. Sam follows through.</ui-text>\n    <ui-text variant=\"caption\">Briefing at nine · Bring the maps.</ui-text>\n    <ui-cluster gap=\"s\">\n      <ui-button size=\"sm\" variant=\"solid\" tone=\"accent\">Solid accent</ui-button>\n      <ui-button size=\"sm\" variant=\"outline\" tone=\"accent\">Outline accent</ui-button>\n      <ui-button size=\"sm\" variant=\"solid\" tone=\"neutral\">Solid neutral</ui-button>\n      <ui-button size=\"sm\" variant=\"outline\" tone=\"neutral\">Outline neutral</ui-button>\n      <ui-icon-button size=\"sm\" variant=\"outline\" tone=\"neutral\" match-button label=\"Acknowledge memo\"><ui-icon name=\"circle-check\"></ui-icon></ui-icon-button>\n      <ui-button size=\"sm\" variant=\"ghost\" tone=\"neutral\">Ghost</ui-button>\n    </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=\"s\"><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",
+          "bindings": "",
           "frameworks": {}
         }
       ]
@@ -4581,7 +4598,7 @@
           {
             "name": "--ui-combobox-popup-surface",
             "fallbacks": [
-              "var(--ui-overlay-surface, var(--ui-surface-elevated))"
+              "var(--ui-material-content, var(--ui-surface-elevated))"
             ]
           },
           {
@@ -4715,6 +4732,12 @@
           {
             "name": "--ui-line-height-tight"
           },
+          {
+            "name": "--ui-material-content",
+            "fallbacks": [
+              "var(--ui-surface-elevated)"
+            ]
+          },
           {
             "name": "--ui-motion-ease"
           },
@@ -4739,12 +4762,6 @@
               "var(--ui-elevation-overlay, var(--ui-shadow-lg))"
             ]
           },
-          {
-            "name": "--ui-overlay-surface",
-            "fallbacks": [
-              "var(--ui-surface-elevated)"
-            ]
-          },
           {
             "name": "--ui-radius-md"
           },
@@ -4969,6 +4986,13 @@
           "type": "boolean",
           "default": false
         },
+        {
+          "name": "muted",
+          "property": "muted",
+          "description": "Shows the selected field value with supporting-text emphasis, for an inherited or default choice. Suggestions keep normal emphasis and the field stays interactive.",
+          "type": "boolean",
+          "default": false
+        },
         {
           "name": "name",
           "property": "name",
@@ -4979,7 +5003,7 @@
         {
           "name": "open-on-focus",
           "property": "openOnFocus",
-          "description": "Opens suggestions when the input receives focus, before typing.",
+          "description": "Opens suggestions when the input receives focus or is clicked. A committed selection shows all choices until typing filters them; an explicitly supplied query keeps its filtering.",
           "type": "boolean",
           "default": false
         },
@@ -5210,6 +5234,12 @@
           "type": "boolean",
           "default": false
         },
+        {
+          "name": "muted",
+          "description": "Shows the selected field value with supporting-text emphasis, for an inherited or default choice. Suggestions keep normal emphasis and the field stays interactive.",
+          "type": "boolean",
+          "default": false
+        },
         {
           "name": "name",
           "description": "The form field name the combobox submits its value under, never the label shown in the field. Single mode sends one entry: the selected option's value, the typed text when allowFreeText is set and no option is selected, or an empty string. Multiple mode sends one entry per chosen item's value, and nothing when none is chosen. A disabled combobox sends nothing.",
@@ -5218,7 +5248,7 @@
         },
         {
           "name": "openOnFocus",
-          "description": "Opens suggestions when the input receives focus, before typing.",
+          "description": "Opens suggestions when the input receives focus or is clicked. A committed selection shows all choices until typing filters them; an explicitly supplied query keeps its filtering.",
           "type": "boolean",
           "default": false
         },
@@ -12569,6 +12599,7 @@
           {
             "name": "--ui-icon-button-active-surface",
             "fallbacks": [
+              "var(--ui-neutral-active)",
               "color-mix(in srgb, currentColor 16%, transparent)",
               "color-mix(in srgb, currentColor 12%, var(--ui-surface-default))"
             ]
@@ -12600,7 +12631,8 @@
           {
             "name": "--ui-icon-button-hover-surface",
             "fallbacks": [
-              "color-mix(in srgb, currentColor 8%, transparent)"
+              "color-mix(in srgb, currentColor 8%, transparent)",
+              "var(--ui-neutral-hover)"
             ]
           },
           {
@@ -12864,6 +12896,9 @@
               "var(--ui-motion-fast)"
             ]
           },
+          {
+            "name": "--ui-neutral-active"
+          },
           {
             "name": "--ui-neutral-glow",
             "fallbacks": [
@@ -13064,11 +13099,10 @@
         {
           "name": "tone",
           "property": "tone",
-          "description": "Colour for every variant. auto preserves the existing variant-specific default. When omitted, ghost and outline keep their neutral appearance and solid keeps its accent fill. Set accent for a coloured action or neutral for a quiet one. danger, success, warning and info share Button's intent colors. Native aria-pressed=\"true\" keeps an outline toggle visibly pressed; the consumer owns that state.",
+          "description": "Colour for every variant. The default neutral shares the quiet control family with fields and text buttons. Choose accent explicitly for a coloured action, or primary for solid accent. danger, success, warning and info share Button's intent colors. Native aria-pressed=\"true\" keeps an outline toggle visibly pressed; the consumer owns that state.",
           "type": "keyword",
-          "default": "auto",
+          "default": "neutral",
           "options": [
-            "auto",
             "accent",
             "neutral",
             "danger",
@@ -13080,7 +13114,7 @@
         {
           "name": "variant",
           "property": "variant",
-          "description": "Emphasis. ghost shows only the icon until it is hovered, for toolbars and dense rows; outline adds a border on the default surface; solid fills with the accent colour, for the one primary action in a group.",
+          "description": "Emphasis. ghost shows only the icon until it is hovered, for toolbars and dense rows; outline adds a border on the default surface; solid fills with its chosen tone.",
           "type": "keyword",
           "default": "ghost",
           "options": [
@@ -13174,11 +13208,10 @@
         },
         {
           "name": "tone",
-          "description": "Colour for every variant. auto preserves the existing variant-specific default. When omitted, ghost and outline keep their neutral appearance and solid keeps its accent fill. Set accent for a coloured action or neutral for a quiet one. danger, success, warning and info share Button's intent colors. Native aria-pressed=\"true\" keeps an outline toggle visibly pressed; the consumer owns that state.",
-          "type": "\"auto\" | \"accent\" | \"neutral\" | \"danger\" | \"success\" | \"warning\" | \"info\"",
-          "default": "auto",
+          "description": "Colour for every variant. The default neutral shares the quiet control family with fields and text buttons. Choose accent explicitly for a coloured action, or primary for solid accent. danger, success, warning and info share Button's intent colors. Native aria-pressed=\"true\" keeps an outline toggle visibly pressed; the consumer owns that state.",
+          "type": "\"accent\" | \"neutral\" | \"danger\" | \"success\" | \"warning\" | \"info\"",
+          "default": "neutral",
           "options": [
-            "auto",
             "accent",
             "neutral",
             "danger",
@@ -13189,7 +13222,7 @@
         },
         {
           "name": "variant",
-          "description": "Emphasis. ghost shows only the icon until it is hovered, for toolbars and dense rows; outline adds a border on the default surface; solid fills with the accent colour, for the one primary action in a group.",
+          "description": "Emphasis. ghost shows only the icon until it is hovered, for toolbars and dense rows; outline adds a border on the default surface; solid fills with its chosen tone.",
           "type": "\"ghost\" | \"outline\" | \"solid\"",
           "default": "ghost",
           "options": [
@@ -15925,7 +15958,7 @@
           {
             "name": "--ui-menu-item-hover-surface",
             "fallbacks": [
-              "var(--ui-surface-subtle)"
+              "var(--ui-accent-subtle)"
             ]
           },
           {
@@ -15957,6 +15990,9 @@
           {
             "name": "--ui-accent"
           },
+          {
+            "name": "--ui-accent-subtle"
+          },
           {
             "name": "--ui-border-width"
           },
@@ -16014,6 +16050,12 @@
           {
             "name": "--ui-selection-radius"
           },
+          {
+            "name": "--ui-selection-surface"
+          },
+          {
+            "name": "--ui-selection-text"
+          },
           {
             "name": "--ui-space-2"
           },
@@ -16023,9 +16065,6 @@
           {
             "name": "--ui-surface"
           },
-          {
-            "name": "--ui-surface-subtle"
-          },
           {
             "name": "--ui-text-primary"
           },
@@ -19755,6 +19794,13 @@
           "type": "boolean",
           "default": false
         },
+        {
+          "name": "muted",
+          "property": "muted",
+          "description": "Shows the selected value with supporting-text emphasis, for an inherited or default choice. The select remains interactive and its options retain normal emphasis.",
+          "type": "boolean",
+          "default": false
+        },
         {
           "name": "required",
           "property": "required",
@@ -19794,6 +19840,12 @@
           "type": "boolean",
           "default": false
         },
+        {
+          "name": "muted",
+          "description": "Shows the selected value with supporting-text emphasis, for an inherited or default choice. The select remains interactive and its options retain normal emphasis.",
+          "type": "boolean",
+          "default": false
+        },
         {
           "name": "required",
           "description": "Requires a non-empty option for form validation.",
@@ -20382,7 +20434,7 @@
           "name": "01-app-shell",
           "title": "App shell",
           "description": "The sidebar is the panel only; the page places it beside its main content. The button toggles it with commandfor and command=\"--toggle\": docked it collapses, and below the breakpoint (40rem in this example) it opens as a drawer. Each open and close is one toggle event, whose detail gives open, mode, and trigger; as a drawer the popover's own toggle event, which has no detail, reaches the panel too.",
-          "markup": "<ui-cluster wrap=\"nowrap\" align=\"stretch\" gap=\"m\">\n  <ui-sidebar breakpoint=\"sm\" id=\"sidebar-nav\" aria-label=\"Workspace\">\n    <ui-stack gap=\"s\" role=\"navigation\" aria-label=\"Office sections\">\n      <ui-text variant=\"eyebrow\">Fellowship office</ui-text>\n      <ui-nav-item href=\"#inbox\" current=\"true\">Inbox</ui-nav-item>\n      <ui-nav-item href=\"#projects\">Quest planning</ui-nav-item>\n      <ui-nav-item href=\"#settings\">Office settings</ui-nav-item>\n    </ui-stack>\n  </ui-sidebar>\n  <ui-stack fill role=\"main\">\n    <ui-icon-button commandfor=\"sidebar-nav\" command=\"--toggle\" label=\"Toggle sidebar\">\n      <svg aria-hidden=\"true\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n        <rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\" />\n        <path d=\"M9 3v18\" />\n      </svg>\n    </ui-icon-button>\n    <ui-card padding=\"sm\">Frodo and Sam’s team updates sit beside the office navigation.</ui-card>\n  </ui-stack>\n</ui-cluster>",
+          "markup": "<ui-cluster wrap=\"nowrap\" align=\"stretch\" gap=\"m\">\n  <ui-sidebar breakpoint=\"sm\" id=\"sidebar-nav\" aria-label=\"Workspace\">\n    <ui-stack gap=\"s\" role=\"navigation\" aria-label=\"Office sections\">\n      <ui-text variant=\"eyebrow\">Fellowship office</ui-text>\n      <ui-nav-item as=\"a\" href=\"#inbox\" current=\"true\">Inbox</ui-nav-item>\n      <ui-nav-item as=\"a\" href=\"#projects\">Quest planning</ui-nav-item>\n      <ui-nav-item as=\"a\" href=\"#settings\">Office settings</ui-nav-item>\n    </ui-stack>\n  </ui-sidebar>\n  <ui-stack fill role=\"main\">\n    <ui-icon-button commandfor=\"sidebar-nav\" command=\"--toggle\" label=\"Toggle sidebar\">\n      <svg aria-hidden=\"true\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">\n        <rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\" />\n        <path d=\"M9 3v18\" />\n      </svg>\n    </ui-icon-button>\n    <ui-card padding=\"sm\">Frodo and Sam’s team updates sit beside the office navigation.</ui-card>\n  </ui-stack>\n</ui-cluster>",
           "resizable": true,
           "bindings": "",
           "frameworks": {}
@@ -20399,6 +20451,169 @@
         }
       ]
     },
+    {
+      "tag": "ui-skeleton",
+      "package": "@threadlabs/looma",
+      "root": "span",
+      "description": "Reserve the shape of incoming content without announcing each placeholder. Text follows the surrounding line metrics; circles and rectangles stand in for avatars and media. Use one status message and aria-busy on the loading region, then replace the placeholders with real content. Keep existing content visible during refresh when possible. Animation is optional and respects reduced motion.",
+      "designTokens": {
+        "sources": [
+          "packages/looma/src/components/ui-skeleton/ui-skeleton.html"
+        ],
+        "component": [
+          {
+            "name": "--ui-skeleton-height",
+            "fallbacks": [
+              "1lh",
+              "auto",
+              "8rem"
+            ]
+          },
+          {
+            "name": "--ui-skeleton-width",
+            "fallbacks": [
+              "100%",
+              "calc(2.5rem + 2 * var(--ui-border-width))"
+            ]
+          }
+        ],
+        "shared": [
+          {
+            "name": "--ui-border-width"
+          },
+          {
+            "name": "--ui-radius-md"
+          },
+          {
+            "name": "--ui-radius-round"
+          },
+          {
+            "name": "--ui-radius-sm"
+          },
+          {
+            "name": "--ui-text-primary"
+          }
+        ]
+      },
+      "attributes": [
+        {
+          "name": "animated",
+          "property": "animated",
+          "description": "Gently pulses the placeholder. Off by default, and always still when the reader requests reduced motion.",
+          "type": "boolean",
+          "default": false
+        },
+        {
+          "name": "height",
+          "property": "height",
+          "description": "Block size as a CSS length. Empty reserves one line for text, a square for circles, or 8rem for rectangles. Set only width to keep a circle square.",
+          "type": "string",
+          "default": ""
+        },
+        {
+          "name": "shape",
+          "property": "shape",
+          "description": "The content's silhouette. text reserves one inherited line box with a shorter bar inside it; circle matches a medium Avatar; rectangle reserves a media area.",
+          "type": "keyword",
+          "default": "text",
+          "options": [
+            "text",
+            "circle",
+            "rectangle"
+          ]
+        },
+        {
+          "name": "width",
+          "property": "width",
+          "description": "Inline size as a CSS length or percentage, constrained to the container. Empty fills the available width for text and rectangles, or matches a medium Avatar's outer size for circles.",
+          "type": "string",
+          "default": ""
+        }
+      ],
+      "properties": [
+        {
+          "name": "animated",
+          "description": "Gently pulses the placeholder. Off by default, and always still when the reader requests reduced motion.",
+          "type": "boolean",
+          "default": false
+        },
+        {
+          "name": "height",
+          "description": "Block size as a CSS length. Empty reserves one line for text, a square for circles, or 8rem for rectangles. Set only width to keep a circle square.",
+          "type": "string",
+          "default": ""
+        },
+        {
+          "name": "shape",
+          "description": "The content's silhouette. text reserves one inherited line box with a shorter bar inside it; circle matches a medium Avatar; rectangle reserves a media area.",
+          "type": "\"text\" | \"circle\" | \"rectangle\"",
+          "default": "text",
+          "options": [
+            "text",
+            "circle",
+            "rectangle"
+          ]
+        },
+        {
+          "name": "width",
+          "description": "Inline size as a CSS length or percentage, constrained to the container. Empty fills the available width for text and rectangles, or matches a medium Avatar's outer size for circles.",
+          "type": "string",
+          "default": ""
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "group": "display",
+      "id": "@threadlabs/looma/ui-skeleton",
+      "title": "Skeleton",
+      "resource": "@threadlabs/looma/components/ui-skeleton/ui-skeleton.html",
+      "targets": [
+        "html-next",
+        "vue"
+      ],
+      "examples": [
+        {
+          "id": "@threadlabs/looma/ui-skeleton/01-text",
+          "name": "01-text",
+          "title": "Text lines",
+          "description": "Each placeholder reserves a whole text line. Vary the widths to suggest the content without pretending to know its words.",
+          "markup": "<ui-stack gap=\"none\">\n  <ui-skeleton></ui-skeleton>\n  <ui-skeleton width=\"85%\"></ui-skeleton>\n  <ui-skeleton width=\"60%\"></ui-skeleton>\n</ui-stack>",
+          "resizable": false,
+          "bindings": "",
+          "frameworks": {}
+        },
+        {
+          "id": "@threadlabs/looma/ui-skeleton/02-shapes",
+          "name": "02-shapes",
+          "title": "Avatar and media shapes",
+          "description": "The default circle matches a medium Avatar. Supply dimensions for a thumbnail or a larger media area; narrow containers constrain the width.",
+          "markup": "<ui-stack gap=\"m\">\n  <ui-cluster gap=\"m\">\n    <ui-skeleton shape=\"circle\"></ui-skeleton>\n    <ui-skeleton shape=\"circle\" width=\"1.75rem\"></ui-skeleton>\n    <ui-skeleton shape=\"rectangle\" width=\"6rem\" height=\"2.5rem\"></ui-skeleton>\n  </ui-cluster>\n  <ui-skeleton shape=\"rectangle\"></ui-skeleton>\n</ui-stack>",
+          "resizable": false,
+          "bindings": "",
+          "frameworks": {}
+        },
+        {
+          "id": "@threadlabs/looma/ui-skeleton/03-loading-card",
+          "name": "03-loading-card",
+          "title": "Loading a profile",
+          "description": "One status describes the work; the section stays busy until the application replaces its decorative placeholders. Compare the loaded card's avatar and text metrics.",
+          "markup": "<ui-stack gap=\"m\">\n  <ui-status-message kind=\"loading\">Loading a profile…</ui-status-message>\n  <ui-grid>\n    <ui-card as=\"section\" aria-label=\"Profile\" aria-busy=\"true\">\n      <ui-cluster gap=\"s\">\n        <ui-skeleton shape=\"circle\"></ui-skeleton>\n        <ui-stack fill gap=\"none\">\n          <ui-skeleton width=\"65%\"></ui-skeleton>\n          <ui-skeleton width=\"45%\"></ui-skeleton>\n        </ui-stack>\n      </ui-cluster>\n      <ui-stack gap=\"none\">\n        <ui-skeleton></ui-skeleton>\n        <ui-skeleton width=\"80%\"></ui-skeleton>\n      </ui-stack>\n    </ui-card>\n    <ui-card as=\"section\" aria-label=\"Loaded profile\">\n      <ui-cluster gap=\"s\">\n        <ui-avatar name=\"Ada Lovelace\" decorative></ui-avatar>\n        <ui-stack fill gap=\"none\">\n          <ui-text weight=\"semibold\">Ada Lovelace</ui-text>\n          <ui-text tone=\"secondary\">Mathematician</ui-text>\n        </ui-stack>\n      </ui-cluster>\n      <ui-text>Notes on an analytical engine and the possibilities of computation.</ui-text>\n    </ui-card>\n  </ui-grid>\n</ui-stack>",
+          "resizable": false,
+          "bindings": "",
+          "frameworks": {}
+        },
+        {
+          "id": "@threadlabs/looma/ui-skeleton/04-animation",
+          "name": "04-animation",
+          "title": "Optional motion",
+          "description": "Still by default. Opt in to a gentle pulse when it helps convey loading; reduced-motion preferences always keep it still.",
+          "markup": "<ui-stack gap=\"s\">\n  <ui-text tone=\"secondary\" size=\"sm\">Still</ui-text>\n  <ui-skeleton width=\"75%\"></ui-skeleton>\n  <ui-text tone=\"secondary\" size=\"sm\">Animated when motion is welcome</ui-text>\n  <ui-skeleton animated width=\"75%\"></ui-skeleton>\n</ui-stack>",
+          "resizable": false,
+          "bindings": "",
+          "frameworks": {}
+        }
+      ]
+    },
     {
       "tag": "ui-slider",
       "package": "@threadlabs/looma",