@threadlabs/looma 0.11.6 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadlabs/looma",
-  "version": "0.11.6",
+  "version": "0.12.1",
   "type": "module",
   "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
   "license": "MIT",

package/styles/ui-button.css

@@ -182,31 +182,19 @@
         var(--ui-focus-halo);
     }
 
-    /* Disabled drops the tone rather than the shape: every variant keeps its own structure, so a
-       disabled outline is still an outline and a disabled ghost still has no edge. Intent goes — an
-       unavailable action says "unavailable", not "unavailable, and destructive" — and so do the
-       highlight and shadow, because nothing that cannot be pressed should look raised. */
+    /* Disabled keeps the shape and washes out the rest: every variant keeps its own structure, so a
+       disabled outline is still an outline and a disabled ghost still has no edge. One filter fades
+       fill, border, and text together (--ui-disabled-filter), and the theme decides which way is
+       toward the page. The highlight and shadow go, because nothing that cannot be pressed should
+       look raised. */
     :scope:is(:disabled, [aria-disabled="true"]) {
-      /* Derived from the tone itself, not from a separate disabled palette: faded toward the
-         page, which desaturates it at the same time. Toward the page rather than toward white,
-         so a dark theme dims where a light one lightens — the same rule, both schemes. */
-      --_tone: color-mix(in oklab, var(--_hue) 58%, var(--ui-surface));
-      --_tone-hover: var(--_tone);
-      --_tone-active: var(--_tone);
-      --_tone-text: color-mix(in oklab, var(--_hue-text) 72%, var(--ui-surface));
-      --_on-tone: var(--_tone-text);
-
+      filter: var(--ui-button-disabled-filter, var(--ui-disabled-filter));
       opacity: var(--ui-button-disabled-opacity, 1);
       cursor: not-allowed;
       background-image: none;
       box-shadow: none;
     }
 
-    /* A filled button keeps its fill, faded further so its text stays legible on it. */
-    :is(:scope[data-ui-button-state~="variant=solid"], :scope[data-ui-button-state~="variant=danger"]):is(:disabled, [aria-disabled="true"]) {
-      --_tone: color-mix(in oklab, var(--_hue) 34%, var(--ui-surface));
-    }
-
     /* Ghost has no hover to fall back on, so disabled is the one state it has to state outright:
        it takes a surface rather than reading as plain text. The surface is a wash of the faded tone,
        the way hover washes the live one, so it stays light in every tone. An opaque mix toward the
@@ -273,7 +261,6 @@
     :scope[data-ui-button-state~="variant=link"]:is(:disabled, [aria-disabled="true"]) {
       background: none;
       border-color: transparent;
-      color: var(--ui-button-disabled-text, var(--ui-disabled-text));
     }
 
     :scope[data-ui-button-state~="variant=link"]:focus-visible {
@@ -304,12 +291,11 @@
 
     /* A soft halo that transitions in with the other box-shadow changes, layered on the raised shadow. */
 
-    /* Disabled drops the tone rather than the shape: every variant keeps its own structure, so a
-       disabled outline is still an outline and a disabled ghost still has no edge. Intent goes — an
-       unavailable action says "unavailable", not "unavailable, and destructive" — and so do the
-       highlight and shadow, because nothing that cannot be pressed should look raised. */
-
-    /* A filled button keeps its fill, faded further so its text stays legible on it. */
+    /* Disabled keeps the shape and washes out the rest: every variant keeps its own structure, so a
+       disabled outline is still an outline and a disabled ghost still has no edge. One filter fades
+       fill, border, and text together (--ui-disabled-filter), and the theme decides which way is
+       toward the page. The highlight and shadow go, because nothing that cannot be pressed should
+       look raised. */
 
     /* Ghost has no hover to fall back on, so disabled is the one state it has to state outright:
        it takes a surface rather than reading as plain text. The surface is a wash of the faded tone,

package/styles/ui-checkbox.css

@@ -9,11 +9,29 @@
       cursor: pointer;
     }
 
+    /* The label, and under it an optional line saying what the choice means. */
+    .text {
+      display: flex;
+      flex-direction: column;
+      gap: var(--ui-space-1);
+      min-inline-size: 0;
+    }
+
     .label {
       min-inline-size: 0;
       line-height: var(--ui-line-height-md);
     }
 
+    .description {
+      color: var(--ui-text-secondary);
+      font-size: var(--ui-font-size-sm);
+      line-height: var(--ui-line-height);
+    }
+
+    .description:empty {
+      display: none;
+    }
+
     input {
       appearance: none;
       -webkit-appearance: none;
@@ -95,7 +113,9 @@
     }
 }
 @scope ([data-component~="ui-checkbox"]) to ([data-component]) {
-/* Centre the tick's box, then lift it: a rotated L's ink sits ~0.11rem below its box centre. */
+/* The label, and under it an optional line saying what the choice means. */
+
+    /* Centre the tick's box, then lift it: a rotated L's ink sits ~0.11rem below its box centre. */
 
     /* A component that sets its display still honours the hidden attribute on its root. */
 }

package/styles/ui-icon-button.css

@@ -161,22 +161,12 @@
     }
 
     /* Disabled colours fall back to each variant's own; ghost takes only the icon colour. */
+    /* Disabled washes the button out the way Button does: the same shape, one filter. */
     :scope:disabled {
+      filter: var(--ui-icon-button-disabled-filter, var(--ui-disabled-filter));
       opacity: var(--ui-icon-button-disabled-opacity, 1);
-      color: var(--ui-icon-button-disabled-text, var(--ui-disabled-text));
       cursor: not-allowed;
-    }
-
-    :scope[data-ui-icon-button-state~="variant=outline"]:disabled {
-      border-color: var(--ui-icon-button-disabled-border, var(--ui-border));
-      background-color: var(--ui-icon-button-disabled-surface, var(--ui-disabled-surface));
-      color: var(--ui-icon-button-disabled-text, var(--ui-disabled-text));
-    }
-
-    :scope[data-ui-icon-button-state~="variant=solid"]:disabled {
-      border-color: var(--ui-icon-button-disabled-border, var(--ui-border));
-      background-color: var(--ui-icon-button-disabled-surface, var(--ui-disabled-surface));
-      color: var(--ui-icon-button-disabled-text, var(--ui-disabled-text));
+      box-shadow: none;
     }
 
     :scope {
@@ -212,6 +202,7 @@
     }
 
     /* Disabled colours fall back to each variant's own; ghost takes only the icon colour. */
+    /* Disabled washes the button out the way Button does: the same shape, one filter. */
 
     :where([data-slotted], [data-slotted] *):is(svg) {
       inline-size: var(--ui-icon-button-icon-size, var(--_icon-button-icon-default));

package/styles/ui-input-group.css

@@ -5,7 +5,9 @@
        focus ring around the input and its affixes together; the input inside drops its own through
        its custom properties, so it is still the one ui-input, with its form behaviour intact. The
        affixes are plain text beside the input, so name the input with a label that says what the
-       whole value is. */
+       whole value is. The action slot takes one button at the end, inside the border, for the one
+       thing the field is for ("Continue" after a site's address), so it reads as the field's action
+       and not the form's. */
     :scope {
       --ui-input-border: transparent;
       --ui-input-border-hover: transparent;
@@ -35,7 +37,8 @@
       border-color: var(--ui-text-secondary);
     }
 
-    :scope:focus-within {
+    /* The field's focus, not the action's: a focused button draws its own ring. */
+    :scope:has(.field :focus) {
       border-color: var(--ui-accent-solid);
       box-shadow:
         var(--ui-control-inset),
@@ -68,7 +71,15 @@
       white-space: nowrap;
     }
 
-    .affix:empty {
+    .action {
+      display: flex;
+      flex: none;
+      align-items: stretch;
+      padding: var(--ui-space-1);
+    }
+
+    .affix:empty,
+    .action:empty {
       display: none;
     }
 
@@ -83,7 +94,11 @@
        focus ring around the input and its affixes together; the input inside drops its own through
        its custom properties, so it is still the one ui-input, with its form behaviour intact. The
        affixes are plain text beside the input, so name the input with a label that says what the
-       whole value is. */
+       whole value is. The action slot takes one button at the end, inside the border, for the one
+       thing the field is for ("Continue" after a site's address), so it reads as the field's action
+       and not the form's. */
+
+    /* The field's focus, not the action's: a focused button draws its own ring. */
 
     /* A component that sets its display still honours the hidden attribute on its root. */
 }

package/styles/ui-radio.css

@@ -9,11 +9,29 @@
       cursor: pointer;
     }
 
+    /* The label, and under it an optional line saying what the choice means. */
+    .text {
+      display: flex;
+      flex-direction: column;
+      gap: var(--ui-space-1);
+      min-inline-size: 0;
+    }
+
     .label {
       min-inline-size: 0;
       line-height: var(--ui-line-height-md);
     }
 
+    .description {
+      color: var(--ui-text-secondary);
+      font-size: var(--ui-font-size-sm);
+      line-height: var(--ui-line-height);
+    }
+
+    .description:empty {
+      display: none;
+    }
+
     input {
       flex: 0 0 auto;
       inline-size: var(--ui-radio-size, 1.125rem);
@@ -42,5 +60,7 @@
     }
 }
 @scope ([data-component~="ui-radio"]) to ([data-component]) {
-/* A component that sets its display still honours the hidden attribute on its root. */
+/* The label, and under it an optional line saying what the choice means. */
+
+    /* A component that sets its display still honours the hidden attribute on its root. */
 }

package/styles/ui-switch.css

@@ -9,11 +9,29 @@
       cursor: pointer;
     }
 
+    /* The label, and under it an optional line saying what the choice means. */
+    .text {
+      display: flex;
+      flex-direction: column;
+      gap: var(--ui-space-1);
+      min-inline-size: 0;
+    }
+
     .label {
       min-inline-size: 0;
       line-height: var(--ui-line-height-md);
     }
 
+    .description {
+      color: var(--ui-text-secondary);
+      font-size: var(--ui-font-size-sm);
+      line-height: var(--ui-line-height);
+    }
+
+    .description:empty {
+      display: none;
+    }
+
     input {
       appearance: none;
       -webkit-appearance: none;
@@ -81,7 +99,9 @@
     }
 }
 @scope ([data-component~="ui-switch"]) to ([data-component]) {
-@media (prefers-reduced-motion: reduce) {
+/* The label, and under it an optional line saying what the choice means. */
+
+    @media (prefers-reduced-motion: reduce) {
     }
 
     /* A component that sets its display still honours the hidden attribute on its root. */

package/theme-dark.css

@@ -23,6 +23,7 @@
       --ui-shadow-lg: 0 10px 28px rgb(0 0 0 / 0.55), 0 4px 10px rgb(0 0 0 / 0.35);
       --ui-control-inset: inset 0 1px 2px rgb(0 0 0 / 0.35);
       --ui-raised: 0 1px 2px rgb(0 0 0 / 0.4), inset 0 1px 0 rgb(255 255 255 / 0.06);
+      --ui-disabled-filter: saturate(0.2) contrast(0.75) brightness(0.8);
       --ui-raised-highlight: linear-gradient(rgb(255 255 255 / 0.04), rgb(255 255 255 / 0));
       --ui-select-chevron: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23a0a09c' stroke-width='2.25' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E");
     }
@@ -51,6 +52,7 @@
     --ui-shadow-lg: 0 10px 28px rgb(0 0 0 / 0.55), 0 4px 10px rgb(0 0 0 / 0.35);
     --ui-control-inset: inset 0 1px 2px rgb(0 0 0 / 0.35);
     --ui-raised: 0 1px 2px rgb(0 0 0 / 0.4), inset 0 1px 0 rgb(255 255 255 / 0.06);
+    --ui-disabled-filter: saturate(0.2) contrast(0.75) brightness(0.8);
     --ui-raised-highlight: linear-gradient(rgb(255 255 255 / 0.04), rgb(255 255 255 / 0));
     --ui-select-chevron: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23a0a09c' stroke-width='2.25' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E");
   }

package/theme-high-contrast.css

@@ -24,6 +24,7 @@
       --ui-text-secondary: #111111;
       --ui-text-muted: #222222;
       --ui-disabled-text: #333333;
+      --ui-disabled-filter: saturate(0);
       --ui-focus-ring: #0000ff;
     }
   }
@@ -52,6 +53,8 @@
     --ui-text-secondary: #111111;
     --ui-text-muted: #222222;
     --ui-disabled-text: #333333;
+    /* Disabled loses its colour, never its contrast. */
+    --ui-disabled-filter: saturate(0);
     --ui-focus-ring: #0000ff;
   }
 }

package/tokens.css

@@ -141,6 +141,9 @@
        full opacity, so a disabled control reads as unavailable rather than as a faded variant. */
     --ui-disabled-surface: var(--ui-surface-sunken);
     --ui-disabled-text: var(--ui-text-muted);
+    /* A disabled button keeps its own look, washed out: less colour, less contrast, toward the page.
+       A filter rather than a second palette, so every variant and tone fades the same way. */
+    --ui-disabled-filter: saturate(0.2) contrast(0.75) brightness(1.25);
 
     --ui-focus-ring: var(--ui-accent);
 

package/vanilla/UiCheckbox.js

@@ -3,7 +3,7 @@ import { manageComponentLifecycle } from "@nextwebwg/html-next/runtime";
 import * as controller from "../components/ui-checkbox/ui-checkbox.js";
 import "../styles/ui-checkbox.css";
 
-const definition = {...{"contract":{"tag":"ui-checkbox","props":{"checked":{"type":"boolean","required":false,"target":{"attribute":"checked"},"default":false},"disabled":{"type":"boolean","required":false,"target":{"attribute":"disabled"},"default":false},"indeterminate":{"type":"boolean","required":false,"target":{"property":"indeterminate"},"default":false},"name":{"type":"string","required":false,"target":{"attribute":"name"},"default":""},"required":{"type":"boolean","required":false,"target":{"attribute":"required"},"default":false},"value":{"type":"string","required":false,"target":{"attribute":"value"},"default":"on"}}},"template":{"kind":"element","name":"label","attributes":[],"children":[{"kind":"element","name":"input","attributes":[{"kind":"literal","name":"type","value":"checkbox"},{"kind":"property","key":"checked","name":"checked","expression":"internalChecked","expressionPlan":{"source":"internalChecked","ast":{"kind":"id","name":"internalChecked"},"dependencies":["internalChecked"]}},{"kind":"property","key":"indeterminate","name":"indeterminate","expression":"indeterminate","expressionPlan":{"source":"indeterminate","ast":{"kind":"id","name":"indeterminate"},"dependencies":["indeterminate"]}},{"kind":"attribute","name":"disabled","expression":"disabled","expressionPlan":{"source":"disabled","ast":{"kind":"id","name":"disabled"},"dependencies":["disabled"]}},{"kind":"attribute","name":"required","expression":"required","expressionPlan":{"source":"required","ast":{"kind":"id","name":"required"},"dependencies":["required"]}},{"kind":"attribute","name":"name","expression":"name","expressionPlan":{"source":"name","ast":{"kind":"id","name":"name"},"dependencies":["name"]}},{"kind":"attribute","name":"value","expression":"value","expressionPlan":{"source":"value","ast":{"kind":"id","name":"value"},"dependencies":["value"]}}],"children":[],"ref":"input"},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"label"}],"children":[{"kind":"slot"}]}]},"declarations":[{"kind":"state","name":"internalChecked","expression":{"source":"false","ast":{"kind":"literal","value":false},"dependencies":[]}},{"kind":"event","name":"change","type":"object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })","bubbles":true,"composed":true,"cancelable":false}],"root":{"kind":"native","element":"label","choices":["label"]}},source:{file:import.meta.url},css:""};
+const definition = {...{"contract":{"tag":"ui-checkbox","props":{"checked":{"type":"boolean","required":false,"target":{"attribute":"checked"},"default":false},"disabled":{"type":"boolean","required":false,"target":{"attribute":"disabled"},"default":false},"indeterminate":{"type":"boolean","required":false,"target":{"property":"indeterminate"},"default":false},"name":{"type":"string","required":false,"target":{"attribute":"name"},"default":""},"required":{"type":"boolean","required":false,"target":{"attribute":"required"},"default":false},"value":{"type":"string","required":false,"target":{"attribute":"value"},"default":"on"}}},"template":{"kind":"element","name":"label","attributes":[],"children":[{"kind":"element","name":"input","attributes":[{"kind":"literal","name":"type","value":"checkbox"},{"kind":"property","key":"checked","name":"checked","expression":"internalChecked","expressionPlan":{"source":"internalChecked","ast":{"kind":"id","name":"internalChecked"},"dependencies":["internalChecked"]}},{"kind":"property","key":"indeterminate","name":"indeterminate","expression":"indeterminate","expressionPlan":{"source":"indeterminate","ast":{"kind":"id","name":"indeterminate"},"dependencies":["indeterminate"]}},{"kind":"attribute","name":"disabled","expression":"disabled","expressionPlan":{"source":"disabled","ast":{"kind":"id","name":"disabled"},"dependencies":["disabled"]}},{"kind":"attribute","name":"required","expression":"required","expressionPlan":{"source":"required","ast":{"kind":"id","name":"required"},"dependencies":["required"]}},{"kind":"attribute","name":"name","expression":"name","expressionPlan":{"source":"name","ast":{"kind":"id","name":"name"},"dependencies":["name"]}},{"kind":"attribute","name":"value","expression":"value","expressionPlan":{"source":"value","ast":{"kind":"id","name":"value"},"dependencies":["value"]}}],"children":[],"ref":"input"},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"text"}],"children":[{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"label"}],"children":[{"kind":"slot"}]},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"description"},{"kind":"literal","name":"aria-hidden","value":"true"}],"children":[{"kind":"slot","fallback":[],"name":"description"}],"ref":"description"}]}]},"declarations":[{"kind":"state","name":"internalChecked","expression":{"source":"false","ast":{"kind":"literal","value":false},"dependencies":[]}},{"kind":"event","name":"change","type":"object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })","bubbles":true,"composed":true,"cancelable":false}],"root":{"kind":"native","element":"label","choices":["label"]}},source:{file:import.meta.url},css:""};
 
 export function createUiCheckbox(options = {}) {
   const { attributes = {}, children = [], slots = {}, as, ...componentProps } = options;
@@ -32,15 +32,30 @@ export function createUiCheckbox(options = {}) {
   else element0.setAttribute("value", String(value4));
   element.append(element0);
   const element1 = document.createElement("span");
-  element1.setAttribute("class", "label");
+  element1.setAttribute("class", "text");
+  const element2 = document.createElement("span");
+  element2.setAttribute("class", "label");
   if (children.length > 0) {
     for (const child of children) {
       const node = typeof child === "string" ? document.createTextNode(child) : child;
       projected.push([node, ""]);
-      element1.append(node);
+      element2.append(node);
     }
   } else {
   }
+  element1.append(element2);
+  const element3 = document.createElement("span");
+  element3.setAttribute("class", "description");
+  element3.setAttribute("aria-hidden", "true");
+  if (slots["description"] ?? [].length > 0) {
+    for (const child of slots["description"] ?? []) {
+      const node = typeof child === "string" ? document.createTextNode(child) : child;
+      projected.push([node, "description"]);
+      element3.append(node);
+    }
+  } else {
+  }
+  element1.append(element3);
   element.append(element1);
   manageComponentLifecycle(element, definition, { props: componentProps, projected,
     controller,

package/vanilla/UiInputGroup.js

@@ -45,6 +45,17 @@ export function createUiInputGroup(options = {}) {
   } else {
   }
   element.append(element2);
+  const element3 = document.createElement("span");
+  element3.setAttribute("class", "action");
+  if (slots["action"] ?? [].length > 0) {
+    for (const child of slots["action"] ?? []) {
+      const node = typeof child === "string" ? document.createTextNode(child) : child;
+      projected.push([node, "action"]);
+      element3.append(node);
+    }
+  } else {
+  }
+  element.append(element3);
   manageGeneratedProps(element, [
     { name: "disabled", attribute: "data-disabled", value: componentProps["disabled"], default: false, type: "boolean", required: false },
   ]);

package/vanilla/UiRadio.js

@@ -3,7 +3,7 @@ import { manageComponentLifecycle } from "@nextwebwg/html-next/runtime";
 import * as controller from "../components/ui-radio/ui-radio.js";
 import "../styles/ui-radio.css";
 
-const definition = {...{"contract":{"tag":"ui-radio","props":{"checked":{"type":"boolean","required":false,"target":{"attribute":"checked"},"default":false},"disabled":{"type":"boolean","required":false,"target":{"attribute":"disabled"},"default":false},"name":{"type":"string","required":false,"target":{"attribute":"name"},"default":""},"required":{"type":"boolean","required":false,"target":{"attribute":"required"},"default":false},"value":{"type":"string","required":false,"target":{"attribute":"value"},"default":"on"}}},"template":{"kind":"element","name":"label","attributes":[],"children":[{"kind":"element","name":"input","attributes":[{"kind":"literal","name":"type","value":"radio"},{"kind":"property","key":"checked","name":"checked","expression":"internalChecked","expressionPlan":{"source":"internalChecked","ast":{"kind":"id","name":"internalChecked"},"dependencies":["internalChecked"]}},{"kind":"attribute","name":"disabled","expression":"disabled","expressionPlan":{"source":"disabled","ast":{"kind":"id","name":"disabled"},"dependencies":["disabled"]}},{"kind":"attribute","name":"required","expression":"required","expressionPlan":{"source":"required","ast":{"kind":"id","name":"required"},"dependencies":["required"]}},{"kind":"attribute","name":"value","expression":"value","expressionPlan":{"source":"value","ast":{"kind":"id","name":"value"},"dependencies":["value"]}},{"kind":"attribute","name":"name","expression":"name","expressionPlan":{"source":"name","ast":{"kind":"id","name":"name"},"dependencies":["name"]}}],"children":[],"ref":"input"},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"label"}],"children":[{"kind":"slot"}]}]},"declarations":[{"kind":"state","name":"internalChecked","expression":{"source":"false","ast":{"kind":"literal","value":false},"dependencies":[]}},{"kind":"event","name":"change","type":"object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })","bubbles":true,"composed":true,"cancelable":false}],"root":{"kind":"native","element":"label","choices":["label"]}},source:{file:import.meta.url},css:""};
+const definition = {...{"contract":{"tag":"ui-radio","props":{"checked":{"type":"boolean","required":false,"target":{"attribute":"checked"},"default":false},"disabled":{"type":"boolean","required":false,"target":{"attribute":"disabled"},"default":false},"name":{"type":"string","required":false,"target":{"attribute":"name"},"default":""},"required":{"type":"boolean","required":false,"target":{"attribute":"required"},"default":false},"value":{"type":"string","required":false,"target":{"attribute":"value"},"default":"on"}}},"template":{"kind":"element","name":"label","attributes":[],"children":[{"kind":"element","name":"input","attributes":[{"kind":"literal","name":"type","value":"radio"},{"kind":"property","key":"checked","name":"checked","expression":"internalChecked","expressionPlan":{"source":"internalChecked","ast":{"kind":"id","name":"internalChecked"},"dependencies":["internalChecked"]}},{"kind":"attribute","name":"disabled","expression":"disabled","expressionPlan":{"source":"disabled","ast":{"kind":"id","name":"disabled"},"dependencies":["disabled"]}},{"kind":"attribute","name":"required","expression":"required","expressionPlan":{"source":"required","ast":{"kind":"id","name":"required"},"dependencies":["required"]}},{"kind":"attribute","name":"value","expression":"value","expressionPlan":{"source":"value","ast":{"kind":"id","name":"value"},"dependencies":["value"]}},{"kind":"attribute","name":"name","expression":"name","expressionPlan":{"source":"name","ast":{"kind":"id","name":"name"},"dependencies":["name"]}}],"children":[],"ref":"input"},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"text"}],"children":[{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"label"}],"children":[{"kind":"slot"}]},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"description"},{"kind":"literal","name":"aria-hidden","value":"true"}],"children":[{"kind":"slot","fallback":[],"name":"description"}],"ref":"description"}]}]},"declarations":[{"kind":"state","name":"internalChecked","expression":{"source":"false","ast":{"kind":"literal","value":false},"dependencies":[]}},{"kind":"event","name":"change","type":"object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })","bubbles":true,"composed":true,"cancelable":false}],"root":{"kind":"native","element":"label","choices":["label"]}},source:{file:import.meta.url},css:""};
 
 export function createUiRadio(options = {}) {
   const { attributes = {}, children = [], slots = {}, as, ...componentProps } = options;
@@ -30,15 +30,30 @@ export function createUiRadio(options = {}) {
   else element0.setAttribute("name", String(value3));
   element.append(element0);
   const element1 = document.createElement("span");
-  element1.setAttribute("class", "label");
+  element1.setAttribute("class", "text");
+  const element2 = document.createElement("span");
+  element2.setAttribute("class", "label");
   if (children.length > 0) {
     for (const child of children) {
       const node = typeof child === "string" ? document.createTextNode(child) : child;
       projected.push([node, ""]);
-      element1.append(node);
+      element2.append(node);
     }
   } else {
   }
+  element1.append(element2);
+  const element3 = document.createElement("span");
+  element3.setAttribute("class", "description");
+  element3.setAttribute("aria-hidden", "true");
+  if (slots["description"] ?? [].length > 0) {
+    for (const child of slots["description"] ?? []) {
+      const node = typeof child === "string" ? document.createTextNode(child) : child;
+      projected.push([node, "description"]);
+      element3.append(node);
+    }
+  } else {
+  }
+  element1.append(element3);
   element.append(element1);
   manageComponentLifecycle(element, definition, { props: componentProps, projected,
     controller,

package/vanilla/UiSwitch.js

@@ -3,7 +3,7 @@ import { manageComponentLifecycle } from "@nextwebwg/html-next/runtime";
 import * as controller from "../components/ui-switch/ui-switch.js";
 import "../styles/ui-switch.css";
 
-const definition = {...{"contract":{"tag":"ui-switch","props":{"checked":{"type":"boolean","required":false,"target":{"attribute":"checked"},"default":false},"disabled":{"type":"boolean","required":false,"target":{"attribute":"disabled"},"default":false},"name":{"type":"string","required":false,"target":{"attribute":"name"},"default":""},"required":{"type":"boolean","required":false,"target":{"attribute":"required"},"default":false},"value":{"type":"string","required":false,"target":{"attribute":"value"},"default":"on"}}},"template":{"kind":"element","name":"label","attributes":[],"children":[{"kind":"element","name":"input","attributes":[{"kind":"literal","name":"type","value":"checkbox"},{"kind":"literal","name":"role","value":"switch"},{"kind":"property","key":"checked","name":"checked","expression":"internalChecked","expressionPlan":{"source":"internalChecked","ast":{"kind":"id","name":"internalChecked"},"dependencies":["internalChecked"]}},{"kind":"attribute","name":"disabled","expression":"disabled","expressionPlan":{"source":"disabled","ast":{"kind":"id","name":"disabled"},"dependencies":["disabled"]}},{"kind":"attribute","name":"required","expression":"required","expressionPlan":{"source":"required","ast":{"kind":"id","name":"required"},"dependencies":["required"]}},{"kind":"attribute","name":"name","expression":"name","expressionPlan":{"source":"name","ast":{"kind":"id","name":"name"},"dependencies":["name"]}},{"kind":"attribute","name":"value","expression":"value","expressionPlan":{"source":"value","ast":{"kind":"id","name":"value"},"dependencies":["value"]}}],"children":[],"ref":"input"},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"label"}],"children":[{"kind":"slot"}]}]},"declarations":[{"kind":"state","name":"internalChecked","expression":{"source":"false","ast":{"kind":"literal","value":false},"dependencies":[]}},{"kind":"event","name":"change","type":"object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })","bubbles":true,"composed":true,"cancelable":false}],"root":{"kind":"native","element":"label","choices":["label"]}},source:{file:import.meta.url},css:""};
+const definition = {...{"contract":{"tag":"ui-switch","props":{"checked":{"type":"boolean","required":false,"target":{"attribute":"checked"},"default":false},"disabled":{"type":"boolean","required":false,"target":{"attribute":"disabled"},"default":false},"name":{"type":"string","required":false,"target":{"attribute":"name"},"default":""},"required":{"type":"boolean","required":false,"target":{"attribute":"required"},"default":false},"value":{"type":"string","required":false,"target":{"attribute":"value"},"default":"on"}}},"template":{"kind":"element","name":"label","attributes":[],"children":[{"kind":"element","name":"input","attributes":[{"kind":"literal","name":"type","value":"checkbox"},{"kind":"literal","name":"role","value":"switch"},{"kind":"property","key":"checked","name":"checked","expression":"internalChecked","expressionPlan":{"source":"internalChecked","ast":{"kind":"id","name":"internalChecked"},"dependencies":["internalChecked"]}},{"kind":"attribute","name":"disabled","expression":"disabled","expressionPlan":{"source":"disabled","ast":{"kind":"id","name":"disabled"},"dependencies":["disabled"]}},{"kind":"attribute","name":"required","expression":"required","expressionPlan":{"source":"required","ast":{"kind":"id","name":"required"},"dependencies":["required"]}},{"kind":"attribute","name":"name","expression":"name","expressionPlan":{"source":"name","ast":{"kind":"id","name":"name"},"dependencies":["name"]}},{"kind":"attribute","name":"value","expression":"value","expressionPlan":{"source":"value","ast":{"kind":"id","name":"value"},"dependencies":["value"]}}],"children":[],"ref":"input"},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"text"}],"children":[{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"label"}],"children":[{"kind":"slot"}]},{"kind":"element","name":"span","attributes":[{"kind":"literal","name":"class","value":"description"},{"kind":"literal","name":"aria-hidden","value":"true"}],"children":[{"kind":"slot","fallback":[],"name":"description"}],"ref":"description"}]}]},"declarations":[{"kind":"state","name":"internalChecked","expression":{"source":"false","ast":{"kind":"literal","value":false},"dependencies":[]}},{"kind":"event","name":"change","type":"object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })","bubbles":true,"composed":true,"cancelable":false}],"root":{"kind":"native","element":"label","choices":["label"]}},source:{file:import.meta.url},css:""};
 
 export function createUiSwitch(options = {}) {
   const { attributes = {}, children = [], slots = {}, as, ...componentProps } = options;
@@ -31,15 +31,30 @@ export function createUiSwitch(options = {}) {
   else element0.setAttribute("value", String(value3));
   element.append(element0);
   const element1 = document.createElement("span");
-  element1.setAttribute("class", "label");
+  element1.setAttribute("class", "text");
+  const element2 = document.createElement("span");
+  element2.setAttribute("class", "label");
   if (children.length > 0) {
     for (const child of children) {
       const node = typeof child === "string" ? document.createTextNode(child) : child;
       projected.push([node, ""]);
-      element1.append(node);
+      element2.append(node);
     }
   } else {
   }
+  element1.append(element2);
+  const element3 = document.createElement("span");
+  element3.setAttribute("class", "description");
+  element3.setAttribute("aria-hidden", "true");
+  if (slots["description"] ?? [].length > 0) {
+    for (const child of slots["description"] ?? []) {
+      const node = typeof child === "string" ? document.createTextNode(child) : child;
+      projected.push([node, "description"]);
+      element3.append(node);
+    }
+  } else {
+  }
+  element1.append(element3);
   element.append(element1);
   manageComponentLifecycle(element, definition, { props: componentProps, projected,
     controller,

package/vue/UiButton.vue

@@ -259,31 +259,19 @@ function attribute(value: unknown): any {
     var(--ui-focus-halo);
 }
 
-/* Disabled drops the tone rather than the shape: every variant keeps its own structure, so a
-   disabled outline is still an outline and a disabled ghost still has no edge. Intent goes — an
-   unavailable action says "unavailable", not "unavailable, and destructive" — and so do the
-   highlight and shadow, because nothing that cannot be pressed should look raised. */
+/* Disabled keeps the shape and washes out the rest: every variant keeps its own structure, so a
+   disabled outline is still an outline and a disabled ghost still has no edge. One filter fades
+   fill, border, and text together (--ui-disabled-filter), and the theme decides which way is
+   toward the page. The highlight and shadow go, because nothing that cannot be pressed should
+   look raised. */
 [data-component~="ui-button"]:is(:disabled, [aria-disabled="true"]) {
-  /* Derived from the tone itself, not from a separate disabled palette: faded toward the
-     page, which desaturates it at the same time. Toward the page rather than toward white,
-     so a dark theme dims where a light one lightens — the same rule, both schemes. */
-  --_tone: color-mix(in oklab, var(--_hue) 58%, var(--ui-surface));
-  --_tone-hover: var(--_tone);
-  --_tone-active: var(--_tone);
-  --_tone-text: color-mix(in oklab, var(--_hue-text) 72%, var(--ui-surface));
-  --_on-tone: var(--_tone-text);
-
+  filter: var(--ui-button-disabled-filter, var(--ui-disabled-filter));
   opacity: var(--ui-button-disabled-opacity, 1);
   cursor: not-allowed;
   background-image: none;
   box-shadow: none;
 }
 
-/* A filled button keeps its fill, faded further so its text stays legible on it. */
-:is([data-component~="ui-button"][data-ui-button-state~="variant=solid"], [data-component~="ui-button"][data-ui-button-state~="variant=danger"]):is(:disabled, [aria-disabled="true"]) {
-  --_tone: color-mix(in oklab, var(--_hue) 34%, var(--ui-surface));
-}
-
 /* Ghost has no hover to fall back on, so disabled is the one state it has to state outright:
    it takes a surface rather than reading as plain text. The surface is a wash of the faded tone,
    the way hover washes the live one, so it stays light in every tone. An opaque mix toward the
@@ -354,7 +342,6 @@ html[data-ui-input-modality="touch"]
 [data-component~="ui-button"][data-ui-button-state~="variant=link"]:is(:disabled, [aria-disabled="true"]) {
   background: none;
   border-color: transparent;
-  color: var(--ui-button-disabled-text, var(--ui-disabled-text));
 }
 
 [data-component~="ui-button"][data-ui-button-state~="variant=link"]:focus-visible {

package/vue/UiCheckbox.d.ts

@@ -6,9 +6,11 @@ type __VLS_Props = {
     required?: boolean;
     value?: string;
 };
-declare var __VLS_1: {};
+declare var __VLS_1: {}, __VLS_3: {};
 type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
+} & {
+    description?: (props: typeof __VLS_3) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     change: (detail: {

package/vue/UiCheckbox.vue

@@ -38,6 +38,7 @@ const emit = defineEmits<{
 
 const root = ref<HTMLElement | null>(null)
 const inputElement = useTemplateRef<HTMLElement>('input')
+const descriptionElement = useTemplateRef<HTMLElement>('description')
 const internalChecked = ref(false)
 
 /** The values the styles' :host-state() rules test. */
@@ -66,7 +67,7 @@ useComponentHost(controllerModule.default, {
   root,
   dispatch,
   props,
-  refs: { input: inputElement },
+  refs: { input: inputElement, description: descriptionElement },
   state: { internalChecked },
 })
 </script>
@@ -87,7 +88,10 @@ useComponentHost(controllerModule.default, {
       :value="value"
       ref="input"
     >
-    <span class="label"><slot /></span></label>
+    <span class="text"><span class="label"><slot /></span>
+      <span class="description" aria-hidden="true" ref="description"><slot
+          name="description"
+        /></span></span></label>
 </template>
 
 <style scoped>
@@ -100,11 +104,29 @@ useComponentHost(controllerModule.default, {
   cursor: pointer;
 }
 
+/* The label, and under it an optional line saying what the choice means. */
+.text {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ui-space-1);
+  min-inline-size: 0;
+}
+
 .label {
   min-inline-size: 0;
   line-height: var(--ui-line-height-md);
 }
 
+.description {
+  color: var(--ui-text-secondary);
+  font-size: var(--ui-font-size-sm);
+  line-height: var(--ui-line-height);
+}
+
+.description:empty {
+  display: none;
+}
+
 input {
   appearance: none;
   -webkit-appearance: none;