@fusion.dev/helix 0.104.1 → 0.106.0

package/dist/code/root/code-root.d.ts

@@ -4,21 +4,21 @@ import type { CSSResultGroup } from 'lit';
  * @summary A fragment of code inside a line of prose.
  *
  * @description
- * A step down the scale, because a monospace face reads larger than the prose
- * around it at the same nominal size. `--code-size` overrides it.
+ * The text is one step smaller than the prose around it, because a monospace
+ * face looks larger than proportional text at the same nominal size. Set
+ * `--code-size` to change it.
  *
  * @since 0.1.0
  * @status stable
  * @category typography
  * @documentation https://fusion.dev/helix/components/code
  *
- * @cssproperty --code-background-color - Fill behind the fragment. Defaults to a 6%
- * wash of the ink, which composites the same against a light page and a dark one.
- * @cssproperty --code-foreground-color - The fragment's ink. Defaults to the prose's
- * own, pulled back towards `foreground-muted`.
- * @cssproperty --code-padding - Space either side of the fragment. Defaults to half
- * of `space-2xs`, which is what keeps a bracket beside the chip rather than a space
- * away from it.
+ * @cssproperty --code-background-color - Fill behind the fragment. Defaults to the
+ * foreground color at 6%, which looks the same on a light page and a dark one.
+ * @cssproperty --code-foreground-color - Color of the fragment's text. Defaults to the
+ * foreground color mixed toward `foreground-muted`.
+ * @cssproperty --code-padding - Space either side of the fragment. Defaults to half of
+ * `space-2xs`, so a bracket next to the fragment sits close to it.
  * @cssproperty --code-size - The fragment's size. Defaults to `text-sm`.
  */
 export declare class HelixCode extends HelixHeadlessCode {

package/dist/code-block/root/code-block-root.d.ts

@@ -2,31 +2,30 @@ import { HelixHeadlessCodeBlock } from '@fusion.dev/helix-headless/code-block';
 import type { CSSResultGroup } from 'lit';
 import '../../copy-button/index.js';
 /**
- * @summary A block of code, with somewhere to put its name and a way to take it.
+ * @summary A block of code with an optional name and a copy button.
  *
  * @description
- * The header sits above the code rather than floating on it, and the copy
- * button stands at its end. Overlaid, which is the usual build, the button
- * covers the first line, which is the one line of a snippet a reader is most
- * likely to be reading. A block with no name has no header, and the button
- * stands beside the code in room the block keeps clear: an end gutter for code,
- * a band above the first hunk for a diff.
+ * The header sits above the code with the copy button at its end, so the button
+ * never covers the first line. A block with no name has no header. The button
+ * then sits beside the code in space the block keeps clear: an end gutter for
+ * code, and a band above the first hunk for a diff.
  *
- * A diff is drawn a block per file in the same frame, each changed line washed
- * in its tone at Tag's resting strength with its `+` or `-` in the tone's ink,
- * so the change does not rest on telling two pale grounds apart. A split diff
- * stacks its two versions below about 40rem of the file's own width.
+ * A diff draws one block per file in the same frame. Each changed line is
+ * tinted in its tone at Tag's resting strength, with its `+` or `-` in the
+ * tone's ink color, so you can see the change without comparing two pale
+ * backgrounds. A split diff stacks its two versions when the file is narrower
+ * than about 40rem.
  *
  * @since 0.1.0
  * @status stable
  * @category typography
  * @documentation https://fusion.dev/helix/components/code-block
  *
- * @cssproperty --code-block-backdrop - A filter over what shows through the block and its header, for a translucent ground.
- * @cssproperty --code-block-background-color - The ground behind the code, for a block that is not on the page.
+ * @cssproperty --code-block-backdrop - A backdrop filter for the block and its header, for a translucent background.
+ * @cssproperty --code-block-background-color - The background behind the code. Set it for a block that sits on a surface other than the page background.
  * @cssproperty --code-block-border-color - The line around the block and its header.
- * @cssproperty --code-block-header-background-color - The ground behind the name, where it should not be `surface-raised`.
- * @cssproperty --code-block-radius - The corner on the header's top and the block's bottom, which are one shape.
+ * @cssproperty --code-block-header-background-color - The background behind the name. The default is `surface-raised`.
+ * @cssproperty --code-block-radius - The corner radius of the header's top and the block's bottom, which form one shape.
  */
 export declare class HelixCodeBlock extends HelixHeadlessCodeBlock {
     static tier: string;

package/dist/color-input/root/color-input-root.d.ts

@@ -2,24 +2,19 @@ import { HelixHeadlessColorInput } from '@fusion.dev/helix-headless/color-input'
 import type { CSSResultGroup } from 'lit';
 import '../../color-picker/index.js';
 /**
- * @summary A color, typed in any syntax or picked from a panel.
+ * @summary A field for a color, typed in any syntax or picked from a panel.
  *
  * @description
- * The frame is the field rather than the input, so the trigger sits inside the
- * same box as the text and the focus ring is drawn once around the whole
- * control.
+ * The frame wraps the whole field, so the trigger sits inside the same box as
+ * the text and one focus ring surrounds the control.
  *
- * **The trigger fills the trailing end rather than sitting in it as an icon.** A
- * color field has one thing to show and it is a color, so the swatch takes the
- * height of the control and reads as a block of it. It is the one field here
- * whose trailing affordance is the value itself: Date Input's calendar mark
- * stands for an action, and an action stretched to field height is a large icon
- * and nothing more.
+ * The trigger fills the trailing end of the field. It is a swatch of the
+ * current color at the full height of the control. Date Input's calendar
+ * trigger stays icon-sized, because it stands for an action.
  *
- * **The panel has no padding, and clips instead.** The square runs to its edge
- * and takes the panel's rounded corners from being clipped by it, rather than
- * sitting inset with a band of overlay showing on all four sides. The picker
- * pads its own lower rows.
+ * The panel has no padding and clips its content, so the square runs to the
+ * panel's edges and takes its rounded corners. The picker pads its own lower
+ * rows.
  *
  * @since 0.1.0
  * @status stable
@@ -29,15 +24,15 @@ import '../../color-picker/index.js';
  *
  * @cssproperty --color-input-background-color - Fill behind the field.
  * @cssproperty --color-input-border-color - Color of the panel's edge.
- * @cssproperty --color-input-border-width - Width of the panel's edge. Follows
+ * @cssproperty --color-input-border-width - Width of the panel's edge. Defaults to `--helix-border-floating`, which is `0`, so the panel stands out by its shadow unless a theme sets a border.
  *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
  *   theme says otherwise.
  * @cssproperty --color-input-panel-size - Width of the panel, and so of the square.
- * @cssproperty --color-input-shadow - Lift under the panel. Follows
+ * @cssproperty --color-input-shadow - Shadow under the panel. Defaults to `--helix-shadow-floating`, so the panel keeps a shadow over any content below it.
  *   `--helix-shadow-floating`: a floating surface sits over content nobody can predict, so it
  *   keeps a lift by default.
- * @cssproperty --color-input-swatch-radius - Corner radius of that block.
- * @cssproperty --color-input-swatch-size - Edge length of the block in `variant="swatch"`.
+ * @cssproperty --color-input-swatch-radius - Corner radius of the swatch in `variant="swatch"`.
+ * @cssproperty --color-input-swatch-size - Edge length of the swatch in `variant="swatch"`.
  */
 export declare class HelixColorInput extends HelixHeadlessColorInput {
     static tier: string;

package/dist/color-picker/root/color-picker-root.d.ts

@@ -5,30 +5,29 @@ import '../../button-group/index.js';
 import '../../icon/index.js';
 import '../../slider/index.js';
 /**
- * @summary Picks a color, from a square and two ramps.
+ * @summary A color picker made of a square and two ramps.
  *
  * @description
- * **The square is painted in three layers, not composited from elements**: the
- * hue underneath, white sliding in from the left to take the saturation out,
- * black rising from the bottom to take the brightness out. One element, one
- * declaration, and it repaints as the hue moves because the hue is a custom
- * property the tier below writes.
- *
- * **The two range inputs over it are invisible and still there.** Not
- * `display: none` and not `visibility: hidden`, either of which would take them
- * out of the tab order and out of the accessibility tree, which is the entire
- * reason a square built this way is reachable at all. They carry
- * `pointer-events: none` so the square answers the pointer itself, and the focus
- * ring is drawn on the square rather than on them, so it lands where the reader
- * is looking.
- *
- * **Every chip sits on a checkerboard.** A color with alpha painted on a solid
- * background is just a different color, and the one thing a preview owes a
- * reader is the difference between "pale blue" and "blue, half transparent".
- *
- * No padding and no surface of its own. Flat on a page it takes the space it is
- * given, and in Color Input's panel the panel supplies both: a picker that
- * brought its own card would be a card inside a card there.
+ * The square is one element painted in three layers:
+ *
+ * - the hue at the bottom
+ * - white from the left, which removes saturation
+ * - black from the bottom, which removes brightness
+ *
+ * It repaints as the hue changes, because the hue is a custom property that the
+ * headless tier writes.
+ *
+ * The two range inputs over the square are invisible and stay in the tab order
+ * and the accessibility tree, which is what makes the square reachable. They
+ * have `pointer-events: none`, so the square handles the pointer, and the focus
+ * ring is drawn on the square.
+ *
+ * Every color chip sits on a checkerboard, so a color with alpha looks
+ * transparent. On a solid background, half-transparent blue would look the same
+ * as pale blue.
+ *
+ * The picker has no padding or surface of its own. On a page it takes the space
+ * it is given, and inside Color Input the panel supplies both.
  *
  * @since 0.1.0
  * @status stable
@@ -36,11 +35,11 @@ import '../../slider/index.js';
  * @aliases Color, ColorArea, Swatch picker
  * @documentation https://fusion.dev/helix/components/color-picker
  *
- * @cssproperty --color-picker-grid-radius - Corner radius of the square.
- * @cssproperty --color-picker-grid-ratio - Aspect ratio of the square.
- * @cssproperty --color-picker-padding - Inset of the rows under the square, and the bottom.
- * @cssproperty --color-picker-sample-size - Edge length of the chip that copies the value.
- * @cssproperty --color-picker-swatch-size - Edge length of one preset.
+ * @cssproperty --color-picker-grid-radius - The corner radius of the square.
+ * @cssproperty --color-picker-grid-ratio - The aspect ratio of the square.
+ * @cssproperty --color-picker-padding - The inset of the rows under the square and of the picker's bottom edge.
+ * @cssproperty --color-picker-sample-size - The width and height of the chip that copies the value.
+ * @cssproperty --color-picker-swatch-size - The width and height of one preset.
  */
 export declare class HelixColorPicker extends HelixHeadlessColorPicker {
     static tier: string;

package/dist/combobox/root/combobox-root.css.js

@@ -88,9 +88,10 @@ flex: 0 0 auto;
 --_floating-shadow: var(--combobox-shadow, var(--helix-shadow-floating));
 
 box-sizing: border-box;
-inline-size: var(--combobox-panel-size, var(--floating-anchor-inline-size, 100%));
+inline-size: var(--combobox-panel-size, max-content);
 max-block-size: var(--floating-available-block-size, none);
-min-inline-size: max-content;
+max-inline-size: calc(100vw - var(--helix-space-md) * 2);
+min-inline-size: var(--floating-anchor-inline-size, 100%);
 overflow: hidden;
 padding: var(--helix-space-none);
 position: absolute;

package/dist/combobox/root/combobox-root.d.ts

@@ -3,12 +3,12 @@ import type { CSSResultGroup } from 'lit';
 import '../../listbox/index.js';
 import '../../tag/index.js';
 /**
- * @summary A field that filters a list as it is typed into.
+ * @summary A text field that filters a list of options as you type.
  *
  * @description
- * The frame is the field rather than the input, so the caret, the marks and the
- * focus ring are drawn once around the whole control, which is the arrangement
- * Input, Color Input and Date Input all take.
+ * The frame is drawn around the field, so the caret, the marks, and the focus
+ * ring sit inside one outline around the whole control. Input, Color Input, and
+ * Date Input use the same arrangement.
  *
  * @since 0.1.0
  * @status stable
@@ -19,12 +19,12 @@ import '../../tag/index.js';
  * @cssproperty --combobox-background-color - Fill behind the field.
  * @cssproperty --combobox-border-color - Color of the panel's edge.
  * @cssproperty --combobox-border-width - Width of the panel's edge. Follows
- *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
- *   theme says otherwise.
+ *   `--helix-border-floating`, which is `0` unless your theme sets it, so the panel's shadow
+ *   sets it apart.
  * @cssproperty --combobox-control-size - Smallest the text field shrinks to once tags share its line.
  * @cssproperty --combobox-panel-size - Width of the panel. Follows the field by default.
- * @cssproperty --combobox-shadow - Lift under the panel. Follows `--helix-shadow-floating`: a
- *   floating surface sits over content nobody can predict, so it keeps a lift by default.
+ * @cssproperty --combobox-shadow - Shadow under the panel. Follows `--helix-shadow-floating`.
+ *   A floating panel can sit over any content, so it has a shadow by default.
  */
 export declare class HelixCombobox extends HelixHeadlessCombobox {
     static tier: string;

package/dist/command/root/command-root.d.ts

@@ -3,14 +3,13 @@ import type { CSSResultGroup } from 'lit';
 import '../../dialog/index.js';
 import '../../listbox/index.js';
 /**
- * @summary A list of commands, opened from anywhere and filtered by typing.
+ * @summary A command palette: a list of commands that opens from anywhere on the page and filters as you type.
  *
  * @description
- * The palette is a dialog holding a filterable listbox, so what this tier adds
- * is where that dialog sits and how the list reads inside it. It opens against
- * the top of the window rather than centered, which is where every palette a
- * reader has used opens: a list that grows and shrinks as it is filtered would
- * otherwise walk up and down the screen under the words being typed.
+ * The palette is a dialog holding a filterable listbox. This tier sets where
+ * the dialog sits and how the list looks inside it. The dialog opens near the
+ * top of the window, so the text field stays in place while the list grows and
+ * shrinks as you type.
  *
  * @since 0.1.0
  * @status stable

package/dist/copy-button/root/copy-button-root.d.ts

@@ -3,13 +3,12 @@ import type { CSSResultGroup } from 'lit';
 import '../../tooltip/index.js';
 declare const HelixCopyButton_base: (new (...args: any[]) => import("../../shared/mixin-control-surface/mixin-control-surface.js").MixinControlSurfaceInterface) & typeof HelixHeadlessCopyButton;
 /**
- * @summary A button that puts a string on the clipboard and says it did.
+ * @summary A button that copies a string to the clipboard and confirms the copy.
  *
  * @description
- * Takes the icon button's square box, then stacks its two faces in one grid
- * cell so the press never changes the button's size. See the stylesheet: a
- * control that resizes under the pointer at the moment a reader is looking at
- * it for reassurance reads as a second, accidental press.
+ * Uses the icon button's square box and stacks its two faces in one grid cell,
+ * so a press never changes the button's size. A button that resizes as you
+ * press it looks like a second, accidental press.
  *
  * @since 0.1.0
  * @status stable

package/dist/data-table/root/data-table-root.d.ts

@@ -4,59 +4,52 @@ import '../../checkbox/index.js';
 import '../../pagination/index.js';
 import '../../table/index.js';
 /**
- * @summary A table that owns a result: rows as data, with sort, filter and paging.
+ * @summary A table drawn from an array of rows, with sorting, filtering, and paging.
  *
  * @description
- * Hairline rules between rows and no fill, per the rule that depth comes from a
- * single border rather than from elevation. A header band would be elevation
- * spelled differently, so the headings are weight and color instead.
+ * Rows have hairline rules between them and no fill, and the headings are set
+ * apart by weight and color. Helix shows depth with a single border and no
+ * elevation, and a header band would be elevation.
  *
- * The grid scrolls its own box and the toolbar and footer sit outside it: a
- * search field that slides sideways when a reader scrolls the columns is a
- * search field they lose.
+ * The grid scrolls in its own box, and the toolbar and footer sit outside it,
+ * so the search field stays in place when the columns scroll sideways.
  *
  * `windowed` draws only the rows in view, for a result too long to lay out at
- * once, and the headings stay put while they scroll. It is independent of
- * `paginated` and of `mode`, so a page can be windowed and a server-fed chunk
- * can be too.
+ * once, and the headings stay in place while the rows scroll. It works with or
+ * without `paginated` and with either `mode`, so a page or a chunk from a
+ * server can be windowed.
  *
- * **The cell values do not server-render**, which is the headless tier's
- * limitation and worth repeating where a consumer chooses between the two: use
- * `helix-table` where the content has to be in the served HTML.
+ * **The cell values do not server-render.** Use `helix-table` when the content
+ * has to be in the served HTML.
  *
  * @since 0.1.0
  * @status stable
  * @category data
  * @documentation https://fusion.dev/helix/components/data-table
  *
- * @slot - The columns, declared rather than drawn.
- * @slot footer - Below the grid, replacing the pagination this would otherwise draw.
- * @slot toolbar - Above the grid, for a search field or actions.
+ * @slot - The columns, as `TableColumn` elements.
+ * @slot footer - Content below the grid. It replaces the built-in pagination.
+ * @slot toolbar - Content above the grid, such as a search field or actions.
  *
  * @csspart cell - One cell.
- * @csspart cell-selected - A cell of a selected row, beside `cell`.
- * @csspart live - The empty and loading lines again, in a region a screen reader hears when they change. Visually hidden in the styled tier.
+ * @csspart cell-selected - Added to `cell` in a selected row.
+ * @csspart live - A copy of the empty and loading messages, which screen readers announce when they change. Visually hidden in the styled tier.
  * @csspart table - The grid.
  *
- * @cssproperty --data-table-block-size - How tall the scrolling box is while `windowed`.
- * Ignored otherwise, where the grid is as tall as its rows. A definite height rather than a
- * maximum, so a short result under `windowed` keeps the full box with space below it: a
- * maximum would leave the height a function of the rows drawn, and the rows drawn a function
- * of the height, which is the loop the window controller has to guard against rather than
- * one worth entering on purpose.
- * @cssproperty --data-table-color - Ink in a cell.
- * @cssproperty --data-table-columns - Track list for the columns, which wins over the one the columns worked out.
- * @cssproperty --data-table-heading-background-color - Fill behind a heading while `windowed`.
- * Opaque on purpose: rows scroll under a sticky heading and a transparent one lets them
- * through. Unset otherwise, so the headings stay weight rather than a band.
- * @cssproperty --data-table-heading-color - Ink in a heading.
- * @cssproperty --data-table-padding-block - Space above and below a cell's content.
- * @cssproperty --data-table-padding-inline - Space either side of a cell's content.
- * @cssproperty --data-table-rule-color - Color of the hairline between rows. A color
- * and not a border: it lands in the color slot of a shorthand, so a whole border
- * written into it produces invalid CSS and drops the rule. Drawn on the cells rather
- * than the row, which is `display: contents` and measures `0px`.
- * @cssproperty --data-table-text - Type size, headings and cells alike.
+ * @cssproperty --data-table-block-size - The height of the scrolling box while `windowed`.
+ * Ignored otherwise, where the grid is as tall as its rows. It is a fixed height, so a
+ * short result keeps the full box with space below it.
+ * @cssproperty --data-table-color - The text color of a cell.
+ * @cssproperty --data-table-columns - The grid track list for the columns. It overrides the list worked out from the columns.
+ * @cssproperty --data-table-heading-background-color - The fill behind a heading while `windowed`.
+ * It is opaque, because rows scroll under the sticky heading. Unset otherwise.
+ * @cssproperty --data-table-heading-color - The text color of a heading.
+ * @cssproperty --data-table-padding-block - The space above and below a cell's content.
+ * @cssproperty --data-table-padding-inline - The space on either side of a cell's content.
+ * @cssproperty --data-table-rule-color - The color of the line between rows. It takes a
+ * color only, because it fills the color in a border shorthand, and a full border value
+ * makes the rule invalid. It is drawn on the cells, because the row is `display: contents`.
+ * @cssproperty --data-table-text - The font size of headings and cells.
  */
 export declare class HelixDataTable extends HelixHeadlessDataTable {
     static tier: string;

package/dist/date-input/root/date-input-root.d.ts

@@ -6,18 +6,15 @@ import '../../tag/index.js';
  * @summary A date, typed or picked from a calendar.
  *
  * @description
- * The frame is the field rather than the input, so the trigger sits inside the
- * same box as the text and the focus ring is drawn once around the whole
- * control. The trigger is a mark within that box rather than a button beside it:
- * a second frame inside the first is two controls where a reader sees one.
+ * The frame is drawn around the whole field, so the trigger sits inside the
+ * same box as the text and the focus ring surrounds the whole control. The
+ * trigger is a mark inside that box, so the field reads as one control.
  *
- * The calendar is the real `helix-date-picker`, in a panel with no border of its
- * own. A surface over the page is told apart by its shadow and by what it
- * covers, and a line around it as well reads as a box drawn around something
- * already separate.
+ * The calendar is the real `helix-date-picker`, in a panel with no border. Its
+ * shadow and what it covers set it apart from the page.
  *
- * Height comes from the region, like every other control: `data-density` on
- * whatever holds it.
+ * Height comes from the region, like every other control. Set `data-density` on
+ * the element that holds it.
  *
  * @since 0.1.0
  * @status stable
@@ -25,13 +22,14 @@ import '../../tag/index.js';
  * @aliases DatePicker, DateField, InputDate
  * @documentation https://fusion.dev/helix/components/date-input
  *
- * @cssproperty --date-input-background-color - Fill behind the field.
- * @cssproperty --date-input-border-color - Color of the panel's edge.
- * @cssproperty --date-input-border-width - Width of the panel's edge. Follows
- *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
- *   theme says otherwise.
- * @cssproperty --date-input-shadow - Lift under the panel. Follows `--helix-shadow-floating`:
- *   a floating surface sits over content nobody can predict, so it keeps a lift by default.
+ * @cssproperty --date-input-background-color - The fill behind the field.
+ * @cssproperty --date-input-border-color - The color of the panel's border.
+ * @cssproperty --date-input-border-width - The width of the panel's border. It
+ *   follows `--helix-border-floating`, which is `0`, so the panel stands out by its
+ *   shadow unless a theme sets a border.
+ * @cssproperty --date-input-shadow - The shadow under the panel. It follows
+ *   `--helix-shadow-floating`. The panel can sit over any content, so it has a
+ *   shadow by default.
  */
 export declare class HelixDateInput extends HelixHeadlessDateInput {
     static tier: string;

package/dist/date-picker/root/date-picker-root.d.ts

@@ -1,22 +1,21 @@
 import { HelixHeadlessDatePicker } from '@fusion.dev/helix-headless/date-picker';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary Shows a month, and takes a date from it.
+ * @summary A month calendar for choosing one or more dates.
  *
  * @description
- * Six week rows always, so the grid keeps one height and a month change does
- * not move whatever sits beneath it.
+ * The grid always has six week rows, so it keeps one height and a month change
+ * does not move the content below it.
  *
- * The column track is wider than the day, and the day is centered in it. The
- * difference is the space between days, which belongs to the track rather than
- * to a `gap`, so a range can paint across the whole track and stay continuous.
+ * Each column track is wider than a day, with the day centered in it. The space
+ * between days belongs to the track and is not set with `gap`, so a range can
+ * paint across the whole track and stay continuous.
  *
- * Days from the neighboring months stay in place, marked quieter rather than
- * hidden, so the first and last weeks are whole rows rather than ragged ones.
- * They are filler and take no click, which the pointer says: no hover, and the
- * cursor a box that does nothing has. At `months="2"` the same date is a
- * trailing cell in one grid and a real one in the next, so a filler day that
- * could be chosen would put one answer on the page twice.
+ * Days from the neighboring months stay in place, styled quieter, so the first
+ * and last weeks are full rows. They cannot be chosen, have no hover style, and
+ * show the default cursor. With `months="2"`, a date can be a trailing cell in
+ * one grid and a real cell in the next, so a selectable filler day would put
+ * the same selection on the page twice.
  *
  * @since 0.1.0
  * @status stable

package/dist/description-list/item/description-list-item.d.ts

@@ -4,8 +4,8 @@ import type { CSSResultGroup } from 'lit';
  * @summary One label and its value.
  *
  * @description
- * A subgrid of the list, so the label and value stay one element, and one pair
- * to a screen reader, while lining up with every other pair in the list.
+ * Each item is a subgrid of the list, so the label and value stay one element,
+ * and one pair to a screen reader, while lining up with every other pair.
  *
  * @since 0.1.0
  * @status stable

package/dist/description-list/root/description-list-root.d.ts

@@ -1,23 +1,22 @@
 import { HelixHeadlessDescriptionList } from '@fusion.dev/helix-headless/description-list';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary Labels and their values, read as pairs: the details panel every
- * product has.
+ * @summary A list of labels and their values, such as a details panel.
  *
  * @description
- * Each label is quiet and each value takes the text around it, so the eye goes
- * to the values and the labels are there to find them by. With
- * `direction="row"` the labels share one column, as wide as the longest of
- * them, and the values start on one line beside it.
+ * Labels are muted and values use the style of the surrounding text, so the
+ * values stand out and the labels help you find them. With `direction="row"`,
+ * the labels share one column as wide as the longest label, and the values
+ * start on one line beside it.
  *
- * **Beside falls back to over below about 22rem of its own width**, measured on
- * the list rather than on the viewport, since a details panel is as often a
- * sidebar on a wide screen as the whole of a narrow one. Below that the label
- * column leaves the values too little room to be read.
+ * **Below about 22rem of its own width, the row layout stacks** each label
+ * above its value. The width is measured on the list, because a details panel
+ * can be a sidebar on a wide screen or the whole of a narrow one. Below that
+ * width the label column leaves too little room for the values.
  *
- * **`width="auto"` with `justify="between"` is a summary**: the list as wide as
- * its widest pair, labels on the start edge and values on the end one in
- * figures of one width, which is how a set of totals is read.
+ * **For a summary, set `width="auto"` and `justify="between"`.** The list is as
+ * wide as its widest pair, labels sit on the start edge, and values sit on the
+ * end edge in tabular figures, as in a set of totals.
  *
  * @since 0.1.0
  * @status stable
@@ -25,7 +24,7 @@ import type { CSSResultGroup } from 'lit';
  * @aliases Data list, Key-value list, Details, Properties
  * @documentation https://fusion.dev/helix/components/description-list
  *
- * @cssproperty --description-list-gap - Space between one pair and the next. Its resting value is tighter with `direction="row"` than stacked, a row of pairs needing less air between them than a column of them does, and setting this takes both.
+ * @cssproperty --description-list-gap - Space between one pair and the next. The default is smaller with `direction="row"` than when stacked. Setting this property replaces both defaults.
  */
 export declare class HelixDescriptionList extends HelixHeadlessDescriptionList {
     static styles: CSSResultGroup;

package/dist/dialog/root/dialog-root.d.ts

@@ -1,13 +1,12 @@
 import { HelixHeadlessDialog } from '@fusion.dev/helix-headless/dialog';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary A modal window, on the platform's own dialog.
+ * @summary A modal window built on the native `<dialog>` element.
  *
  * @description
- * The panel is `surface-overlay` with a shadow, because that is what it is: a
- * thing over the page rather than on it. The scrim is drawn on `::backdrop`,
- * which is the platform's own element for it and sits in the top layer with the
- * dialog rather than being a div somebody positioned.
+ * The panel uses `surface-overlay` with a shadow, because it sits over the
+ * page. The scrim is drawn on `::backdrop`, the platform's element for it,
+ * which sits in the top layer with the dialog.
  *
  * @since 0.1.0
  * @status stable
@@ -17,16 +16,16 @@ import type { CSSResultGroup } from 'lit';
  *
  * @cssproperty --dialog-border-color - Color of the panel's edge.
  * @cssproperty --dialog-border-width - Width of the panel's edge. Follows
- *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
- *   theme says otherwise.
+ *   `--helix-border-floating`, which is `0`, so the panel stands out by its shadow unless your
+ *   theme sets a border.
  * @cssproperty --dialog-icon-size - How big the mark above the title is.
  * @cssproperty --dialog-inline-size - Width of the panel.
  * @cssproperty --dialog-padding - Padding inside the panel.
  * @cssproperty --dialog-rise - How far the panel rises as it opens. Follows
  *   `--helix-space-lg`.
- * @cssproperty --dialog-scrim - The wash over the page behind the dialog. Set on the host, where a token still resolves: a `var()` written inside `::backdrop` cannot see one.
- * @cssproperty --dialog-shadow - Lift under the panel. Follows `--helix-shadow-floating`: a
- *   floating surface sits over content nobody can predict, so it keeps a lift by default.
+ * @cssproperty --dialog-scrim - The tint over the page behind the dialog. Set it on the host, because a `var()` written inside `::backdrop` cannot read a token.
+ * @cssproperty --dialog-shadow - Shadow under the panel. Follows `--helix-shadow-floating`. A
+ *   floating surface can sit over any content, so it has a shadow by default.
  */
 export declare class HelixDialog extends HelixHeadlessDialog {
     /**