@threadlabs/looma 0.9.1 → 0.9.2

package/components/ui-avatar/ui-avatar.html

@@ -1,9 +1,17 @@
 <template component="ui-avatar" controller="./ui-avatar.js">
   <defs>
-    <prop name="src" type="string">Image URL.</prop>
-    <prop name="alt" type="string" default="">alt token.</prop>
-    <prop name="name" type="string" default="">name token.</prop>
-    <prop name="fallback" type="string" default="">fallback token.</prop>
+    <prop name="src" type="string"
+    >The image to show, cropped to fill the circle. Until it loads, or if it fails, the avatar shows initials instead. An img element authored inside the avatar
+      takes precedence over src.</prop>
+    <prop name="alt" type="string" default=""
+    >The avatar's accessible name, announced for it as an image. When empty, name is used, then "Avatar". Initials come from name first, so alt supplies them
+      only when name is empty. An authored img carries its own alt instead.</prop>
+    <prop name="name" type="string" default=""
+    >The person's name. The initials are drawn from it: the first letters of the first two words, or the first two letters of a single word. It is also the
+      accessible name when alt is empty.</prop>
+    <prop name="fallback" type="string" default=""
+    >Text shown instead of the initials derived from name or alt, whenever there is no image. It is uppercased; keep it to a couple of characters, because the
+      circle clips anything wider.</prop>
     <state name="hasImage" :value="false"></state>
     <state name="hasAuthoredImage" :value="false"></state>
     <state name="initials" :value="'?'"></state>

package/components/ui-avatar-group/ui-avatar-group.html

@@ -1,7 +1,10 @@
 <template component="ui-avatar-group" controller="./ui-avatar-group.js">
   <defs>
-    <prop name="max" type="number" default="5">max token.</prop>
-    <prop name="label" type="string" default="People">label token.</prop>
+    <prop name="max" type="number" default="5"
+    >How many avatars to show. The rest are hidden and counted in a +N badge after the last visible one. Fractions round down, and 0 hides every avatar behind
+      the badge.</prop>
+    <prop name="label" type="string" default="People"
+    >The group's accessible name, announced for the set of avatars as a whole. Name who they are rather than repeating the default.</prop>
     <state name="overflowCount" :value="0"></state>
   </defs>
   <div role="group" :aria-label="label">

package/components/ui-badge/ui-badge.html

@@ -1,7 +1,11 @@
 <template component="ui-badge">
   <defs>
-    <prop name="variant" type="solid | subtle" default="subtle">variant token.</prop>
-    <prop name="tone" type="neutral | accent | info | success | warning | danger" default="neutral">tone token.</prop>
+    <prop name="variant" type="solid | subtle" default="subtle"
+    >Emphasis. subtle sets the text in its tone over a soft wash of it; solid fills with the tone and uses contrasting text, for a status that has to stand out.
+      The neutral tone looks the same in both.</prop>
+    <prop name="tone" type="neutral | accent | info | success | warning | danger" default="neutral"
+    >Which colour the badge speaks in. neutral is a quiet grey for plain labels; accent draws the eye in the accent colour; info, success, warning, and danger
+      mark a status, so match the tone to what the badge says.</prop>
     <prop name="shape" type="pill | tag" default="pill"
     >Silhouette. pill is rounded at both ends; tag is a label: flat at the start and coming to a point at the end, for a tag or a chosen chip.</prop>
   </defs>

package/components/ui-button/ui-button.html

@@ -3,11 +3,15 @@
     <prop name="variant" type="outline | solid | danger | ghost | link" default="outline"
     >Emphasis: how loudly the button asks. solid fills with its tone, outline draws its tone at the edge over a wash of it, ghost carries only text until it is
       hovered, and link is an inline text action that reads as a link. danger is solid in the danger tone, kept for the call sites that name it.</prop>
-    <prop name="size" type="sm | md | lg" default="md">Control size.</prop>
+    <prop name="size" type="sm | md | lg" default="md"
+    >Height, padding, and type size. 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.</prop>
     <prop name="tone" type="accent | neutral | danger | success | warning | info" default="accent"
     >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.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Makes the button unavailable: it cannot be pressed, its tone fades, and it loses its raised look. A disabled link (as="a" with href) drops its href and
+      states aria-disabled="true" instead, because a link has no native disabled state.</prop>
     <prop name="align" type="center | start" default="center"
     >Content alignment. start lays the content out like a list option: from the start edge, with start-aligned text.</prop>
     <prop name="stretch" type="boolean" default="false">Fills the inline size of its container.</prop>

package/components/ui-callout/ui-callout.html

@@ -1,6 +1,8 @@
 <template component="ui-callout">
   <defs>
-    <prop name="tone" type="info | note | warning | success | danger" default="info">Semantic message tone.</prop>
+    <prop name="tone" type="info | note | warning | success | danger" default="info"
+    >Which kind of message the callout carries, shown by its icon and colour: info (the default) for neutral information, note for an aside in muted grey,
+      warning for a caution, success for a confirmation, and danger for an error or a destructive consequence.</prop>
   </defs>
   <div role="note">
     <span class="icon" aria-hidden="true">

package/components/ui-checkbox/ui-checkbox.html

@@ -1,10 +1,15 @@
 <template component="ui-checkbox" controller="./ui-checkbox.js">
   <defs>
     <prop name="checked" type="boolean" default="false">Whether the checkbox is checked initially or when set externally.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="indeterminate" type="boolean" default="false">indeterminate token.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
-    <prop name="value" type="string" default="on">value token.</prop>
+    <prop name="disabled" type="boolean" default="false">Disables the native checkbox, so it cannot be toggled or focused.</prop>
+    <prop name="indeterminate" type="boolean" default="false"
+    >Shows the mixed state, for a checkbox that summarises a group whose items are partly checked. It sets the native indeterminate property, which is
+      independent of checked, so update it as the group changes.</prop>
+    <prop name="required" type="boolean" default="false"
+    >Marks the native checkbox required, so native form validation treats it as invalid until it is checked.</prop>
+    <prop name="value" type="string" default="on"
+    >The value set on the native input and reported in the change event's detail, so one handler can tell checkboxes apart. on by default, as on a native
+      checkbox.</prop>
     <state name="internalChecked" :value="false"></state>
     <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>
   </defs>

package/components/ui-cluster/ui-cluster.html

@@ -1,7 +1,11 @@
 <template component="ui-cluster">
   <defs>
-    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
-    <prop name="align" type="start | center | end | stretch">align token.</prop>
+    <prop name="gap" type="xs | s | m | l | xl"
+    >Space between items, on the spacing scale: xs is 0.5rem, s 0.75rem (also the default), m 1rem, l 1.5rem, and xl 2rem. The --ui-cluster-gap custom property,
+      when set, overrides it.</prop>
+    <prop name="align" type="start | center | end | stretch"
+    >How items line up within each row: center (the default) aligns their middles, start their tops, end their bottoms, and stretch makes every item as tall as
+      its row.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

package/components/ui-combobox/ui-combobox.html

@@ -2,25 +2,47 @@
 <link rel="component" href="../ui-tooltip/ui-tooltip.html">
 <template component="ui-combobox" controller="./ui-combobox.js">
   <defs>
-    <prop name="label" type="string" default="">label token.</prop>
-    <prop name="placeholder" type="string" default="">placeholder token.</prop>
-    <prop name="name" type="string" default="">name token.</prop>
+    <prop name="label" type="string" default=""
+    >The field's label, tied to its input and shown above it; required adds an asterisk. It also names the suggestion list. Pair it with
+      labelVisibility="sr-only" when the context already labels the field visibly.</prop>
+    <prop name="placeholder" type="string" default=""
+    >Hint text shown in the empty input, as on a native input. It disappears as the user types, so it never replaces label.</prop>
+    <prop name="name" type="string" default=""
+    >The form field name set on the native input. A form submits the input's text, which after a selection is the chosen option's label, not its value; read
+      value-change for the value.</prop>
     <prop name="value" type="string | null">The selected value in single mode.</prop>
     <prop name="items" type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))"
     >The selected items in multiple mode, as JSON.</prop>
-    <prop name="multiple" type="boolean" default="false">multiple token.</prop>
-    <prop name="tokenSeparators" type="list(string)">tokenSeparators token.</prop>
-    <prop name="query" type="string">query token.</prop>
+    <prop name="multiple" type="boolean" default="false"
+    >Lets the user choose several options. Each choice becomes a removable badge before the input, the list stays open between picks, and choosing a checked
+      option removes it. value-change then reports the whole list of items; use items, not value, in this mode.</prop>
+    <prop name="tokenSeparators" type="list(string)"
+    >Keys that commit the typed text in multiple mode, as KeyboardEvent key values such as "," or ";". The text is added as the option whose label matches it,
+      ignoring case, or with allowCreate is reported as create-item; otherwise it stays in the input.</prop>
+    <prop name="query" type="string"
+    >The input's text, when the consumer controls it. Once set, the consumer owns the text: typing reports query-change, and the input returns to query unless
+      query is updated to match. Leave it unset to let the combobox manage its own text, showing the chosen option's label.</prop>
     <prop name="allowFreeText" type="boolean" default="false">Allows values that do not match an authored option.</prop>
     <prop name="allowCreate" type="boolean" default="false">Offers the current query as a new option.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables the input, the chosen-item badges, and the help button. The list closes and cannot be opened.</prop>
     <prop name="readonly" type="boolean" default="false">Whether the current value may be selected but not edited.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
-    <prop name="size" type="sm | md" default="md">size token.</prop>
-    <prop name="labelVisibility" type="visible | sr-only" default="visible">labelVisibility token.</prop>
-    <prop name="disclosure" type="boolean" default="false">disclosure token.</prop>
-    <prop name="clearable" type="boolean" default="false">clearable token.</prop>
-    <prop name="help" type="string" default="">help token.</prop>
+    <prop name="required" type="boolean" default="false"
+    >Marks the input required, adds an asterisk to the label, and makes validation report "A value is required." when the field is left empty.</prop>
+    <prop name="size" type="sm | md" default="md"
+    >Field height. md is the standard control height; sm is the small control height with tighter padding, for dense forms.</prop>
+    <prop name="labelVisibility" type="visible | sr-only" default="visible"
+    >visible shows the label above the field; sr-only hides it visually but keeps it as the input's accessible name. Use sr-only only when the surrounding
+      layout already makes the field's purpose clear.</prop>
+    <prop name="disclosure" type="boolean" default="false"
+    >Adds a chevron button that opens and closes the full, unfiltered list of options, for users who would rather browse than type. ArrowDown opens the same
+      list with or without it.</prop>
+    <prop name="clearable" type="boolean" default="false"
+    >Adds a clear button to the field that empties the input and clears the selection, reported as value-change with kind "clear". In multiple mode it clears
+      only the typed text; chosen items stay.</prop>
+    <prop name="help" type="string" default=""
+    >Help text for the field. When set, a help button appears beside the field and opens a tooltip with this text; while it is open, the input is described by
+      it.</prop>
     <state name="internalItems" type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))" :value="[]"></state>
     <state name="raw" :value="''"></state>
     <state name="display" :value="''"></state>

package/components/ui-container/ui-container.html

@@ -1,7 +1,10 @@
 <template component="ui-container">
   <defs>
-    <prop name="measure" type="narrow | wide">measure token.</prop>
-    <prop name="gutters" type="s | m | l">gutters token.</prop>
+    <prop name="measure" type="narrow | wide"
+    >The container's maximum width, in characters of the current font: narrow is 45ch, wide is 80ch, and unset is 65ch, a comfortable reading line. The
+      container centres itself when its parent is wider. The --ui-container-measure custom property, when set, overrides it.</prop>
+    <prop name="gutters" type="s | m | l"
+    >Inline padding on both sides, which keeps content off the edges of a narrow screen: s is 0.75rem, m is 1rem (also the default), and l is 1.5rem.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

package/components/ui-disclosure/ui-disclosure.html

@@ -1,9 +1,12 @@
 <template component="ui-disclosure" controller="./ui-disclosure.js">
   <defs>
     <prop name="density" type="comfortable | compact" default="comfortable">Compact trades padding and type size for rows that fit more on screen.</prop>
-    <prop name="summary" type="string" default="Details">summary token.</prop>
-    <prop name="open" type="boolean" default="false">open token.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="summary" type="string" default="Details"
+    >The text of the trigger row that opens and closes the disclosure. It is the trigger button's accessible name, so name what the content is.</prop>
+    <prop name="open" type="boolean" default="false"
+    >Whether the disclosure is open initially or when set externally. The trigger toggles it from there, reporting each change as an open or close event.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables the trigger and mutes its text, so the disclosure keeps its current state and the user cannot toggle it.</prop>
     <state name="internalOpen" :value="false"></state>
     <state name="contentId" :value="''"></state>
     <event

package/components/ui-editor-mention-menu/ui-editor-mention-menu.html

@@ -3,7 +3,9 @@
     <prop name="open" type="boolean" default="false">Whether the menu is open.</prop>
     <prop name="query" type="string" default="">The text typed after the @.</prop>
     <prop name="items" type="list(object({ id: string, label: string, detail?: string, initials?: string }))">The people the menu offers.</prop>
-    <prop name="selectedIndex" type="integer" default="0">The highlighted person.</prop>
+    <prop name="selectedIndex" type="integer" default="0"
+    >The zero-based index of the highlighted person, capped at the last one shown, and announced through aria-activedescendant. The menu does not handle arrow
+      keys itself: the editor sets this as the user moves, while hovering a person highlights them and reports a highlight event.</prop>
     <prop name="loading" type="boolean" default="false">Whether a search is in progress.</prop>
     <prop
       name="anchorRect"

package/components/ui-editor-slash-menu/ui-editor-slash-menu.html

@@ -4,7 +4,9 @@
     <prop name="open" type="boolean" default="false">Whether the menu is open.</prop>
     <prop name="query" type="string" default="">The text typed after the slash.</prop>
     <prop name="items" type="list(object({ title: string, description: string, icon: string }))">The blocks the menu offers.</prop>
-    <prop name="selectedIndex" type="integer" default="0">The highlighted item.</prop>
+    <prop name="selectedIndex" type="integer" default="0"
+    >The zero-based index of the highlighted item. The menu does not handle arrow keys itself: the editor sets this as the user moves, while hovering an item
+      highlights it and reports a highlight event.</prop>
     <prop
       name="anchorRect"
       type="object({ left?: number, top?: number, right?: number, bottom?: number, x?: number, y?: number, width?: number, height?: number }) | null"

package/components/ui-floating-action-button/ui-floating-action-button.html

@@ -1,8 +1,10 @@
 <template component="ui-floating-action-button">
   <defs>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="mobileOnly" type="boolean" default="false">mobileOnly token.</prop>
-    <prop name="label" type="string" default="">label token.</prop>
+    <prop name="disabled" type="boolean" default="false">Disables the button, so it cannot be pressed or focused, and fades it to 60% opacity.</prop>
+    <prop name="mobileOnly" type="boolean" default="false"
+    >Hides the button on viewports 768px wide and wider, for a shortcut that only phones need. Make sure the action is reachable another way at those
+      widths.</prop>
+    <prop name="label" type="string" default="">The button's accessible name. The button usually holds only an icon, so name the action it performs.</prop>
   </defs>
   <button type="button" :aria-label="label" :disabled="disabled"><slot></slot></button>
   <style>

package/components/ui-form-field/ui-form-field.html

@@ -1,8 +1,14 @@
 <template component="ui-form-field" controller="./ui-form-field.js">
   <defs>
-    <prop name="invalid" type="boolean" default="false">invalid token.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
+    <prop name="invalid" type="boolean" default="false"
+    >Marks the field's control invalid by setting aria-invalid on it. Pair it with content in the error slot, which the field already links to the control as
+      its description.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables the field's control: the first input, textarea, or select inside it. The field writes this to the control whenever it updates, so set it here
+      rather than on the control.</prop>
+    <prop name="required" type="boolean" default="false"
+    >Marks the field's control required, for native form validation. Like disabled, it is written to the control, so set it here rather than on the control. It
+      adds no visual marker; show one in the label if the form needs it.</prop>
   </defs>
   <div>
     <div class="label"><slot name="label"></slot></div>

package/components/ui-grid/ui-grid.html

@@ -1,7 +1,11 @@
 <template component="ui-grid">
   <defs>
-    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
-    <prop name="min" type="sm | md | lg">min token.</prop>
+    <prop name="gap" type="xs | s | m | l | xl"
+    >Space between cells, on the spacing scale: xs is 0.5rem, s 0.75rem, m 1rem (also the default), l 1.5rem, and xl 2rem. The --ui-grid-gap custom property,
+      when set, overrides it.</prop>
+    <prop name="min" type="sm | md | lg"
+    >The narrowest a column may get before the grid drops to fewer columns: sm is 12rem (also the default), md is 16rem, and lg is 20rem. The grid fits as many
+      equal columns as its width allows, and a single column never overflows a narrower container.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

package/components/ui-icon/ui-icon.html

@@ -1,6 +1,8 @@
 <template component="ui-icon" controller="./ui-icon.js">
   <defs>
-    <prop name="name" type="string" default="">The icon's name.</prop>
+    <prop name="name" type="string" default=""
+    >Which icon to draw, by its name in Looma's icon set (LOOMA_ICONS), such as "align-left". An unknown or empty name draws nothing. The icon is hidden from
+      assistive technology, so name the control it sits in.</prop>
     <state
       name="shapes"
       type="list(object({ tag: path | circle | rect, d?: string, cx?: string, cy?: string, r?: string, x?: string, y?: string, width?: string, height?: string, rx?: string }))"

package/components/ui-icon-button/ui-icon-button.html

@@ -1,10 +1,17 @@
 <template component="ui-icon-button" controller="./ui-icon-button.js">
   <defs>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables the button, so it cannot be pressed or focused, and greys the icon; outline and solid also take the disabled surface.</prop>
     <prop name="label" type="string">Accessible name for the icon.</prop>
-    <prop name="size" type="sm | md | lg" default="md">size token.</prop>
-    <prop name="variant" type="ghost | outline | solid" default="ghost">variant token.</prop>
-    <prop name="anticipatory" type="boolean" default="false">anticipatory token.</prop>
+    <prop name="size" type="sm | md | lg" default="md"
+    >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.</prop>
+    <prop name="variant" type="ghost | outline | solid" default="ghost"
+    >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.</prop>
+    <prop name="anticipatory" type="boolean" default="false"
+    >Keeps the button out of sight until it is wanted: at rest a fine pointer sees only a small guide dot, and the button appears on hover, on focus, or when
+      the pointer comes near inside a ui-affordance-scope. Touch devices and the solid variant always show it.</prop>
     <prop name="round" type="boolean" default="false">Use a fully circular shape.</prop>
   </defs>
   <button :disabled="disabled" type="button" :aria-label="label"><slot></slot></button>

package/components/ui-input/ui-input.html

@@ -1,6 +1,8 @@
 <template component="ui-input" controller="./ui-input.js">
   <defs>
-    <prop name="value" type="string">Current text value.</prop>
+    <prop name="value" type="string"
+    >The input's text. Setting or changing it replaces the live text; between changes the user's typing stands, so follow input events to keep it in
+      step.</prop>
     <prop name="disabled" type="boolean" default="false">Prevents editing and form submission.</prop>
     <prop name="invalid" type="boolean" default="false">Exposes invalid state to assistive technology and styling.</prop>
     <prop name="readonly" type="boolean" default="false">Allows selection without allowing edits.</prop>

package/components/ui-menu-item/ui-menu-item.html

@@ -1,7 +1,10 @@
 <template component="ui-menu-item">
   <defs>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="value" type="string" default="">value token.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Makes the item unavailable: it is faded, skipped by the arrow keys, and choosing it does nothing. It stays visible and is announced as disabled.</prop>
+    <prop name="value" type="string" default=""
+    >The value the enclosing menu reports in its select event when this item is chosen. Give each item a distinct value so one handler can tell them
+      apart.</prop>
   </defs>
   <div role="menuitem" tabindex="-1" :aria-disabled="disabled" :data-value="value"><slot></slot></div>
   <style>

package/components/ui-radio/ui-radio.html

@@ -1,10 +1,15 @@
 <template component="ui-radio" controller="./ui-radio.js">
   <defs>
     <prop name="checked" type="boolean" default="false">Whether the radio is checked initially or when set externally.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="name" type="string" default="">name token.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
-    <prop name="value" type="string" default="on">value token.</prop>
+    <prop name="disabled" type="boolean" default="false">Disables the native radio, so it cannot be chosen, focused, or reached with the arrow keys.</prop>
+    <prop name="name" type="string" default=""
+    >The native name that groups radios: of the radios that share a name, only one can be checked, and the arrow keys move between them. Inside a ui-radio-group
+      the group sets the name, so leave this empty there.</prop>
+    <prop name="required" type="boolean" default="false"
+    >Marks the native radio required, so native form validation fails until a radio with the same name is checked.</prop>
+    <prop name="value" type="string" default="on"
+    >The value this radio stands for: submitted with a form, reported in its change event, and matched against a ui-radio-group's value to decide which radio is
+      checked.</prop>
     <state name="internalChecked" :value="false"></state>
     <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>
   </defs>

package/components/ui-radio-group/ui-radio-group.html

@@ -1,11 +1,19 @@
 <template component="ui-radio-group" controller="./ui-radio-group.js">
   <defs>
-    <prop name="value" type="string" default="">value token.</prop>
-    <prop name="name" type="string" default="">name token.</prop>
-    <prop name="label" type="string" default="Options">label token.</prop>
-    <prop name="orientation" type="horizontal | vertical" default="horizontal">orientation token.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
+    <prop name="value" type="string" default=""
+    >The value of the checked radio, initially or when set externally; empty checks none. The user's choice updates it from there and is reported as select and
+      change events.</prop>
+    <prop name="name" type="string" default=""
+    >The native name given to every radio in the group, under which a form submits the chosen value. Left empty, the group generates a unique name that keeps
+      the radios together, so set it when the choice submits with a form.</prop>
+    <prop name="label" type="string" default="Options"
+    >The group's legend, shown above the radios and announced as the group's name. Phrase it as the question the radios answer.</prop>
+    <prop name="orientation" type="horizontal | vertical" default="horizontal"
+    >horizontal lays the radios out in a row; vertical stacks them in a column. The arrow keys move between radios either way.</prop>
+    <prop name="disabled" type="boolean" default="false">Disables every radio in the group, so no choice can be made.</prop>
+    <prop name="required" type="boolean" default="false"
+    >Not applied yet: the group neither marks its radios required nor checks that one is chosen. Set required on the ui-radio children instead, which native
+      form validation honours for the whole group.</prop>
     <state name="internalValue" :value="''"></state>
     <event name="select" type="object({ value: string, previousValue: string, trigger: keyboard | pointer | programmatic })"></event>
     <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>

package/components/ui-reel/ui-reel.html

@@ -1,8 +1,14 @@
 <template component="ui-reel">
   <defs>
-    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
-    <prop name="itemWidth" type="sm | md | lg">itemWidth token.</prop>
-    <prop name="snap" type="start | center">snap token.</prop>
+    <prop name="gap" type="xs | s | m | l | xl"
+    >Space between items, on the spacing scale: xs is 0.5rem, s 0.75rem, m 1rem (also the default), l 1.5rem, and xl 2rem. The --ui-reel-gap custom property,
+      when set, overrides it.</prop>
+    <prop name="itemWidth" type="sm | md | lg"
+    >A fixed width for every item: sm is 12rem, md is 16rem, and lg is 20rem. Unset, each item keeps its content's width. Items never shrink to fit, so the reel
+      scrolls sideways once they overflow.</prop>
+    <prop name="snap" type="start | center"
+    >Snaps scrolling to items: start comes to rest with an item's start edge at the reel's start, and center with an item centred in the reel. Unset, the reel
+      scrolls freely.</prop>
   </defs>
   <div role="region" tabindex="0"><slot></slot></div>
   <style>

package/components/ui-search-result-row/ui-search-result-row.html

@@ -1,7 +1,9 @@
 <template component="ui-search-result-row">
   <defs>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="selected" type="boolean" default="false">selected token.</prop>
+    <prop name="disabled" type="boolean" default="false">Disables the row's button, so it cannot be chosen or focused, and fades it to 60% opacity.</prop>
+    <prop name="selected" type="boolean" default="false"
+    >Highlights the row with its hover surface, to mark the current result. It is visual only and sets no ARIA state, so convey the selection to assistive
+      technology another way where it matters.</prop>
   </defs>
   <button type="button" :disabled="disabled">
     <span class="leading"><slot name="leading"></slot></span>

package/components/ui-stack/ui-stack.html

@@ -1,8 +1,14 @@
 <template component="ui-stack">
   <defs>
-    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
-    <prop name="align" type="start | center | end | stretch">align token.</prop>
-    <prop name="justify" type="start | center | end | between">justify token.</prop>
+    <prop name="gap" type="xs | s | m | l | xl"
+    >Space between items, on the spacing scale: xs is 0.5rem, s 0.75rem, m 1rem (also the default), l 1.5rem, and xl 2rem. The --ui-stack-gap custom property,
+      when set, overrides it.</prop>
+    <prop name="align" type="start | center | end | stretch"
+    >How items sit across the stack: stretch (the default) makes each fill the stack's width; start, center, and end keep each at its own width, against the
+      start, in the middle, or against the end.</prop>
+    <prop name="justify" type="start | center | end | between"
+    >Where items sit along a stack that is taller than its content: start (the default), center, end, or between, which spreads the spare space between items.
+      It has no effect unless the stack is given a height or stretched to one.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

package/components/ui-switch/ui-switch.html

@@ -1,9 +1,11 @@
 <template component="ui-switch" controller="./ui-switch.js">
   <defs>
     <prop name="checked" type="boolean" default="false">Whether the switch is checked initially or when set externally.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
-    <prop name="value" type="string" default="on">value token.</prop>
+    <prop name="disabled" type="boolean" default="false">Disables the native switch, so it cannot be toggled or focused.</prop>
+    <prop name="required" type="boolean" default="false">Marks the native switch required, so native form validation treats it as invalid until it is on.</prop>
+    <prop name="value" type="string" default="on"
+    >The value set on the native input and reported in the change event's detail, so one handler can tell switches apart. on by default, as on a native
+      checkbox.</prop>
     <state name="internalChecked" :value="false"></state>
     <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>
   </defs>

package/components/ui-switcher/ui-switcher.html

@@ -1,8 +1,14 @@
 <template component="ui-switcher">
   <defs>
-    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
-    <prop name="threshold" type="xs | sm | md | lg">threshold token.</prop>
-    <prop name="align" type="start | center | end | stretch">align token.</prop>
+    <prop name="gap" type="xs | s | m | l | xl"
+    >Space between items, on the spacing scale: xs is 0.5rem, s 0.75rem, m 1rem (also the default), l 1.5rem, and xl 2rem. The --ui-switcher-gap custom
+      property, when set, overrides it.</prop>
+    <prop name="threshold" type="xs | sm | md | lg"
+    >The container width at which items switch between a row and a stack: wider, they all sit side by side; narrower, each takes the full width. xs is 20rem, sm
+      is 30rem (also the default), md is 45rem, and lg is 60rem.</prop>
+    <prop name="align" type="start | center | end | stretch"
+    >How items line up while they sit in a row: stretch (the default) makes them equally tall; start, center, and end align their tops, middles, or
+      bottoms.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

package/components/ui-tabs/ui-tabs.html

@@ -1,9 +1,14 @@
 <template component="ui-tabs" controller="./ui-tabs.js">
   <defs>
     <prop name="density" type="comfortable | compact" default="comfortable">Compact trades padding and type size for rows that fit more on screen.</prop>
-    <prop name="label" type="string" default="Tabs">label token.</prop>
-    <prop name="value" type="string" default="">value token.</prop>
-    <prop name="orientation" type="horizontal | vertical" default="horizontal">orientation token.</prop>
+    <prop name="label" type="string" default="Tabs"
+    >The tab list's accessible name, announced when focus enters the list. Name what the tabs switch between.</prop>
+    <prop name="value" type="string" default=""
+    >The id of the selected panel, initially or when set externally; empty selects the first panel. Choosing a tab updates it from there and reports a select
+      event. A panel without an id is given a generated one.</prop>
+    <prop name="orientation" type="horizontal | vertical" default="horizontal"
+    >horizontal puts the tabs in a row above the panels, moved between with the Left and Right arrow keys; vertical puts them in a column beside the panels,
+      moved between with Up and Down.</prop>
     <prop name="stretch" type="boolean" default="false">Share the full width of the tab list equally between tabs instead of sizing each to its label.</prop>
     <state name="internalValue" :value="''"></state>
     <state name="tabs" type="list(object({ id: string, label: string }))" :value="[]"></state>

package/components/ui-textarea/ui-textarea.html

@@ -1,6 +1,8 @@
 <template component="ui-textarea" controller="./ui-textarea.js">
   <defs>
-    <prop name="value" type="string">Current text value.</prop>
+    <prop name="value" type="string"
+    >The textarea's text. Setting or changing it replaces the live text; between changes the user's typing stands, so follow input events to keep it in
+      step.</prop>
     <prop name="disabled" type="boolean" default="false">Prevents editing and form submission.</prop>
     <prop name="invalid" type="boolean" default="false">Exposes invalid state to assistive technology and styling.</prop>
     <prop name="readonly" type="boolean" default="false">Allows selection without allowing edits.</prop>

package/components/ui-tree/ui-tree.html

@@ -2,9 +2,13 @@
 <template component="ui-tree" controller="./ui-tree.js">
   <defs>
     <prop name="density" type="comfortable | compact" default="comfortable">Compact trades padding and type size for rows that fit more on screen.</prop>
-    <prop name="label" type="string" default="Tree">label token.</prop>
-    <prop name="hoverExpandDelay" type="number" default="700">hoverExpandDelay token.</prop>
-    <prop name="maxDepth" type="number" default="0">maxDepth token.</prop>
+    <prop name="label" type="string" default="Tree">The tree's accessible name, announced when focus enters it. Name what the tree holds.</prop>
+    <prop name="hoverExpandDelay" type="number" default="700"
+    >How long, in milliseconds, a dragged item must hover over the middle of a collapsed branch before the branch opens to receive it. 0 opens it at
+      once.</prop>
+    <prop name="maxDepth" type="number" default="0"
+    >The deepest level a drag may produce, counting the top level as 1. A drop that would place the dragged item, or any item beneath it, deeper than this is
+      refused and reported as reorder-rejected. 0 means no limit.</prop>
     <event
       name="reorder"
       type="object({ sourceId: string, targetId: string, position: before | inside | after, sourceType: string, targetType: string, sourceScope: string, targetScope: string, trigger: keyboard | pointer | programmatic })"