@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/delta.gts

@@ -0,0 +1,45 @@
+// Pretui — Delta: a signed change with its direction made legible.
+import Component from '@glimmer/component';
+
+export interface DeltaSignature {
+  Args: { value: number | string; format?: (n: number) => string };
+  Element: HTMLSpanElement;
+}
+
+// Signed delta — the pill-less Token variant: bare mono, colored by sign.
+export class Delta extends Component<DeltaSignature> {
+  get n() {
+    return Number(this.args.value);
+  }
+  get sign() {
+    return this.n > 0 ? 'up' : this.n < 0 ? 'down' : 'flat';
+  }
+  get text() {
+    if (this.args.format) {
+      return this.args.format(this.n);
+    }
+    return (this.n > 0 ? '+' : '') + this.n;
+  }
+  <template>
+    <span class='pretui-delta' data-sign={{this.sign}} data-test-pretui-delta ...attributes>{{this.text}}</span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-delta {
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-sm, 11.5px);
+          font-variant-numeric: tabular-nums;
+          font-weight: 500;
+        }
+        .pretui-delta[data-sign='up'] {
+          color: var(--success-ink);
+        }
+        .pretui-delta[data-sign='down'] {
+          color: var(--pretui-destructive-ink, var(--boxel-danger));
+        }
+        .pretui-delta[data-sign='flat'] {
+          color: var(--muted-foreground);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/delta.md

@@ -0,0 +1,53 @@
+## What it is
+
+A signed number, coloured by its sign: green up, red down, grey flat. Use it beside a metric to show change — a **Stat**'s trend, a diff count, a variance column. It is the pill-less **Token**: same mono, tabular-figure voice, no background. If the number is not a change, use **Token** or plain text. If it is a proportion of a whole, **Meter** or **ProgressBar**. If the change needs an explanation, **Chip** with a label.
+
+## The contract
+
+```
+@value: number | string   (required)
+@format?: (n: number) => string
+```
+
+`@value` is coerced with `Number()`, so `'12'` and `12` behave identically — convenient when the value comes from JSON, and worth knowing because a non-numeric string becomes `NaN`, which is `flat` and renders as "NaN".
+
+**The default format is `(n > 0 ? '+' : '') + n`.** The explicit `+` on positives is the decision: without it, "12" and "-12" are distinguished by a character that is easy to miss at 11.5px, and the sign is the whole message. Negatives keep their native minus.
+
+`@format` replaces the whole string, so it is where percentages, currency and rounding go — `{{fn this.pct}}` producing `'+4.2%'`. Note the sign prefix is _not_ re-applied over a custom format, so a formatter must add its own `+`.
+
+## Prior art
+
+There is no component for this in Radix, Web Awesome, shadcn or React Spectrum — it is a formatting concern everyone solves at the call site with a ternary and two colour classes. The closest analogues are product conventions: a stock ticker's delta, Stripe Dashboard's trend figures, Linear's cycle-change indicators.
+
+Where making it a component pays off:
+
+- **The sign→colour mapping is decided once.** Green-up/red-down is a convention, not a law — it is inverted in several East Asian markets, and it means the opposite for a cost metric than for a revenue metric. Having one component means changing that convention is one edit, and having it _not_ be a component means the ternary is copy-pasted into forty call sites with three different green tokens.
+- **`data-sign` is reflected**, so a call site can restyle by sign without touching the logic.
+- **Tabular figures by default**, so a column of deltas aligns on the decimal point. This is the detail hand-rolled deltas always miss.
+
+Where it is thinner than it should be:
+
+- **No arrow or glyph.** Colour and the `+`/`-` character are the entire signal (see below).
+- **No neutral-zero handling beyond `flat`**: exactly `0` is grey, but `0.0001` is green. For a metric with noise you want a threshold, and there is no `@epsilon`.
+- **No semantic inversion.** A component that knows "down is good here" — falling error rate, falling cost — would need `@invert`, and there is none. Currently you must pass a negated value and a custom format, which is a lie in the data.
+
+## Accessibility
+
+No pattern governs it. It is text.
+
+Gaps, and the first is the real one:
+
+- **Colour and a `+`/`-` character are the only signal, and the character is nearly invisible.** At `--text-ui-sm` (11.5px), a minus sign is a two-pixel dash and a plus is barely wider. For a user who cannot distinguish the green from the red, the direction of change is effectively unavailable. That is a **WCAG 1.4.1 Use of Colour** concern in practice even though a text character technically exists. An arrow glyph (▲ / ▼), or `aria-label`s like "up 12 percent", would close it — and note that **Rating**, **Alert** and **FieldError** in this kit all pair hue with a glyph for exactly this reason. Delta is the outlier.
+- **`data-sign` reaches CSS but not assistive tech.** There is no `aria-label`, no visually-hidden "increase"/"decrease", nothing. The announced text is "+12" — better than nothing, and `+` is announced as "plus" by most readers, which does carry it. Verify with your target readers; this is the mitigating factor.
+- **`NaN` renders as "NaN"** with `flat` styling. A malformed value produces visible garbage rather than an empty cell.
+- **No relationship to what it measures.** A Delta beside a Stat is loose adjacent text; **Stat** composes it, which is the right way to use it.
+- **`--success-ink` and `--destructive` must both clear WCAG 1.4.3 at 11.5px weight 500** against `--card`. Green in particular is the token most often set too light for small text.
+- Nothing is focusable, correctly.
+
+## Theming
+
+`--success-ink` (up), `--destructive` (down), `--muted-foreground` (flat), `--font-mono`, `--text-ui-sm`. The 500 weight and tabular figures are fixed.
+
+Three tokens and nothing else — which makes this the cheapest component in the kit to theme, and also means a theme that wants a different sign convention (or a color-blind-safe blue/orange pair instead of green/red) can get it entirely by repointing `--success` and `--destructive` _for this component's context_, without touching the code. That is worth knowing: the sign→token mapping is fixed, but the token→color mapping is not.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/delta.usage.gts

@@ -0,0 +1,31 @@
+// Pretui — Delta usage page.
+import Component from '@glimmer/component';
+import { FreestyleUsage } from './freestyle-usage';
+import { Delta } from './delta';
+
+class DeltaUsage extends Component {
+  values = [12, -4, 0];
+  <template>
+    <FreestyleUsage
+      @name='Delta'
+      @description='Signed change as bare mono text. Sign is always present in text, so success and destructive hues never carry meaning alone.'
+      @source='<Delta @value={{12}} />'
+    >
+      <:example>
+        <div class='foundation-row'>
+          {{#each this.values as |value|}}<Delta @value={{value}} />{{/each}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='sample values' @value={{this.values}} />
+        <Args.Base @name='value' @description='Number or numeric string. Positive values receive a leading plus.' />
+        <Args.Action @name='format' @description='Optional number-to-string formatter.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>.foundation-row { display: flex; gap: var(--space-5, 14px); align-items: baseline; }</style>
+  </template>
+}
+
+export const DEMOS_DELTA: Record<string, unknown> = {
+  Delta: DeltaUsage,
+};

package/bundled-realms/pretui/components/descriptions.gts

@@ -0,0 +1,365 @@
+// Pretui — Descriptions: read-only labeled fields in a responsive grid.
+import Component from '@glimmer/component';
+import { cssDeclaration, cssStyleFrom } from '../pretui-css';
+import type { PretuiSize } from '../pretui-primitives';
+import { printValue } from '../internal/reading-listing';
+import type { ListingSizeArg } from '../internal/reading-listing';
+import { resolveSize } from '../pretui-primitives';
+
+// ═════════════════════════════════════════════════════════════════════════
+// Descriptions — the read-only record display
+// ═════════════════════════════════════════════════════════════════════════
+//
+// ALIAS VERDICT, stated here because the question is worth closing:
+//   • NOT an alias for `RecordDetail` (forms-record.gts). That is an EDITING
+//     machine — a draft batch, one open editor, dirty counts, save/cancel.
+//     Different job, different territory.
+//   • NOT an alias for `KeyValue` either, though it is the
+//     nearest thing. `KeyValue` is a fixed two-column `<dl>`: one pair per
+//     row, no borders, no header, no spans, no density, no fold. It stays
+//     exactly that and this does not deprecate it — six facts beside a card
+//     still want `KeyValue`.
+//   • `Descriptions` is the multi-column, optionally bordered record GRID
+//     agents type after `Descriptions` in Ant: N pairs per row, per-item
+//     `@span`, a title/extra header, and a fold to stacked.
+//
+// Better than Ant's:
+//   • Ant emits a `<table>` for label/value pairs — tabular markup for
+//     non-tabular data, with `<th>` label cells only in bordered mode, so the
+//     semantics change when you flip a visual flag. This is a `<dl>` with
+//     `<div>` grouping (valid HTML since 5.2) in every mode: `<dt>` is the
+//     term and `<dd>` the description whether it is bordered or not.
+//   • Ant's responsive `column` is a `matchMedia` map against the WINDOW.
+//     A card does not know the window. This folds on unnamed container
+//     queries against its own inline size — no JS, no client-render gate,
+//     and correct inside a 320px pane on a 5K display.
+//   • Ant's `Descriptions` has no `aria-*` and no `role` anywhere.
+
+export interface DescriptionsItem {
+  /** the term */
+  label: string;
+  /** the description, when it is plain text. The `<:value>` block wins when
+   * one is supplied, so markup never has to be smuggled through a string. */
+  value?: string;
+  /** how many of the grid's columns this pair takes (default 1). `'fill'`
+   * takes the rest of the row. Clamped down when the container folds. */
+  span?: number | 'fill';
+  /** stable `{{#each}}` key; falls back to the label */
+  key?: string;
+  /** machine value — mono + tabular numerals (mono is for machine
+   * values only) */
+  mono?: boolean;
+}
+
+interface DescriptionsEntry {
+  key: string;
+  item: DescriptionsItem;
+  index: number;
+  span: string;
+  mono: string | undefined;
+}
+
+export interface DescriptionsSignature {
+  Args: {
+    /** the label/value pairs, in reading order */
+    items: DescriptionsItem[];
+    /** pairs per row at full width, 1–4 (default 3 — Ant's default). The
+     * container query only ever REDUCES this. */
+    columns?: number;
+    /** Ant's spelling of `@columns` */
+    column?: number;
+    /** rule the grid and tint the label cells */
+    bordered?: boolean;
+    /** `'horizontal'` (default) puts the label beside its value;
+     * `'vertical'` puts it above */
+    layout?: 'horizontal' | 'vertical';
+    /** density — `xs|s|m|l|xl`, `sm`/`md`/`lg` accepted */
+    size?: ListingSizeArg;
+    /** header text; the `<:title>` block wins over it */
+    title?: string;
+    /** trailing colon after every label (default false — a bordered grid
+     * does not need one, and Ant's `true` default puts a colon on labels
+     * that already sit in their own tinted cell) */
+    colon?: boolean;
+    /** width of the label column in horizontal layout (any CSS length;
+     * default `max-content`) */
+    labelWidth?: string;
+    /** rendered for an item with no value and no `<:value>` block
+     * (default '—') */
+    placeholder?: string;
+  };
+  Blocks: {
+    /** one description — receives the item and its index. Rendering this
+     * block for an item that also has `@value` uses the block. */
+    value: [item: DescriptionsItem, index: number];
+    /** header, when a string title is not enough */
+    title: [];
+    /** trailing header slot: an Edit button, a status chip */
+    extra: [];
+  };
+  Element: HTMLDivElement;
+}
+
+export class Descriptions extends Component<DescriptionsSignature> {
+  get columns(): number {
+    let raw = this.args.columns ?? this.args.column ?? 3;
+    return Math.min(4, Math.max(1, Math.round(raw)));
+  }
+  get size(): PretuiSize {
+    return resolveSize(this.args.size);
+  }
+  get layout(): 'horizontal' | 'vertical' {
+    return this.args.layout === 'vertical' ? 'vertical' : 'horizontal';
+  }
+  get bordered(): string | undefined {
+    return this.args.bordered ? 'true' : undefined;
+  }
+  get colon(): boolean {
+    return this.args.colon ?? false;
+  }
+  get placeholder(): string {
+    return this.args.placeholder ?? '—';
+  }
+  get hasHeader(): boolean {
+    return this.args.title !== undefined;
+  }
+
+  /** Requested column count and label width ride custom properties on the
+   * ROOT, never on the grid: the container query overrides the grid's own
+   * `--pretui-desc-cols`, and an inline style on the same element would
+   * outrank it. Requesting on the parent and resolving on the child is what
+   * makes "the caller asks for 4, the pane only fits 2" resolve to 2. */
+  get rootStyle() {
+    return cssStyleFrom([
+      '--pretui-desc-cols-req: ' + String(this.columns),
+      cssDeclaration('--pretui-desc-label-w', this.args.labelWidth),
+    ]);
+  }
+
+  get entries(): DescriptionsEntry[] {
+    let items = this.args.items ?? [];
+    return items.map((item, index) => ({
+      key: item.key ?? item.label + '#' + String(index),
+      item,
+      index,
+      span: item.span === 'fill' ? 'fill' : String(Math.min(4, Math.max(1, Math.round(item.span ?? 1)))),
+      mono: item.mono ? 'true' : undefined,
+    }));
+  }
+
+  textFor = (item: DescriptionsItem): string =>
+    printValue(item.value, this.placeholder);
+
+  <template>
+    <div
+      class='pretui-desc'
+      data-test-pretui-descriptions
+      data-size={{this.size}}
+      data-layout={{this.layout}}
+      data-cols={{this.columns}}
+      data-bordered={{this.bordered}}
+      style={{this.rootStyle}}
+      ...attributes
+    >
+      {{#if (has-block 'title')}}
+        <div class='pretui-desc-head'>
+          <div class='pretui-desc-title'>{{yield to='title'}}</div>
+          {{#if (has-block 'extra')}}
+            <div class='pretui-desc-extra'>{{yield to='extra'}}</div>
+          {{/if}}
+        </div>
+      {{else if this.hasHeader}}
+        <div class='pretui-desc-head'>
+          <div class='pretui-desc-title'>{{@title}}</div>
+          {{#if (has-block 'extra')}}
+            <div class='pretui-desc-extra'>{{yield to='extra'}}</div>
+          {{/if}}
+        </div>
+      {{/if}}
+
+      <dl class='pretui-desc-grid'>
+        {{#each this.entries key='key' as |entry|}}
+          <div
+            class='pretui-desc-pair'
+            data-span={{entry.span}}
+            data-mono={{entry.mono}}
+            data-test-pretui-descriptions-pair
+          >
+            <dt class='pretui-desc-label'>
+              {{entry.item.label}}{{#if this.colon}}<span
+                  class='pretui-desc-colon'
+                  aria-hidden='true'
+                  data-test-pretui-descriptions-colon
+                >:</span>{{/if}}
+            </dt>
+            <dd class='pretui-desc-value'>
+              {{#if (has-block 'value')}}
+                {{yield entry.item entry.index to='value'}}
+              {{else}}
+                {{this.textFor entry.item}}
+              {{/if}}
+            </dd>
+          </div>
+        {{/each}}
+      </dl>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-desc {
+          container-type: inline-size;
+          min-width: 0;
+          color: var(--foreground);
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+        }
+        .pretui-desc[data-size='xs'] {
+          font-size: 10.5px;
+        }
+        .pretui-desc[data-size='s'] {
+          font-size: var(--text-ui-sm, 11.5px);
+        }
+        .pretui-desc[data-size='l'] {
+          font-size: 14px;
+        }
+        .pretui-desc[data-size='xl'] {
+          font-size: 16px;
+        }
+        .pretui-desc-head {
+          display: flex;
+          align-items: baseline;
+          justify-content: space-between;
+          gap: var(--space-4, 11px);
+          margin-block-end: var(--space-4, 11px);
+        }
+        .pretui-desc-title {
+          font-family: var(--font-serif);
+          font-size: 1.5em;
+          letter-spacing: var(--track-heading, -0.02em);
+        }
+        .pretui-desc-extra {
+          display: flex;
+          align-items: center;
+          gap: var(--space-2, 6px);
+          flex: none;
+        }
+        /* The caller's count is requested on the root and RESOLVED here, so a
+           container query below can narrow it. */
+        .pretui-desc-grid {
+          --pretui-desc-cols: var(--pretui-desc-cols-req, 3);
+          display: grid;
+          grid-template-columns: repeat(var(--pretui-desc-cols), minmax(0, 1fr));
+          margin: 0;
+          min-width: 0;
+        }
+        .pretui-desc-pair {
+          min-width: 0;
+          padding-block: 0.55em;
+          padding-inline: 0;
+        }
+        .pretui-desc-pair[data-span='2'] {
+          grid-column: span 2;
+        }
+        .pretui-desc-pair[data-span='3'] {
+          grid-column: span 3;
+        }
+        .pretui-desc-pair[data-span='4'] {
+          grid-column: span 4;
+        }
+        .pretui-desc-pair[data-span='fill'] {
+          grid-column: 1 / -1;
+        }
+        .pretui-desc[data-layout='horizontal'] .pretui-desc-pair {
+          display: grid;
+          grid-template-columns: var(--pretui-desc-label-w, max-content) minmax(0, 1fr);
+          column-gap: var(--space-5, 14px);
+          align-items: baseline;
+        }
+        .pretui-desc-label {
+          color: var(--muted-foreground);
+          font-size: 0.94em;
+          line-height: 1.45;
+          min-width: 0;
+        }
+        .pretui-desc-colon {
+          margin-inline-start: 1px;
+        }
+        .pretui-desc-value {
+          margin: 0;
+          min-width: 0;
+          line-height: 1.45;
+          overflow-wrap: anywhere;
+        }
+        .pretui-desc-pair[data-mono='true'] .pretui-desc-value {
+          font-family: var(--font-mono);
+          font-size: 0.94em;
+          font-variant-numeric: tabular-nums;
+        }
+        /* Unbordered: a hairline under each row, drawn on the pair so it
+           follows the fold without a single measurement. */
+        .pretui-desc:not([data-bordered]) .pretui-desc-pair {
+          box-shadow: inset 0 -1px 0 var(--border);
+          padding-inline-end: var(--space-5, 14px);
+        }
+        .pretui-desc[data-bordered] .pretui-desc-grid {
+          border-radius: var(--radius-surface, 10px);
+          overflow: hidden;
+          box-shadow: 0 0 0 1px var(--line-strong, var(--boxel-400));
+          background: var(--card);
+        }
+        .pretui-desc[data-bordered] .pretui-desc-pair {
+          padding: 0;
+          box-shadow:
+            inset -1px 0 0 var(--border),
+            inset 0 -1px 0 var(--border);
+        }
+        .pretui-desc[data-bordered] .pretui-desc-label {
+          background: var(--inset, var(--boxel-100));
+          padding: 0.62em var(--space-4, 11px);
+          font-weight: 500;
+          box-shadow: inset -1px 0 0 var(--border);
+        }
+        .pretui-desc[data-bordered] .pretui-desc-value {
+          padding: 0.62em var(--space-4, 11px);
+        }
+        .pretui-desc[data-layout='vertical'] .pretui-desc-label {
+          display: block;
+          margin-block-end: 0.2em;
+        }
+        /* Unnamed container query only — a NAMED one silently deletes every
+           rule that follows it in the transpiled stylesheet. It resolves
+           against the .pretui-desc ancestor, so it styles descendants. */
+        @container (max-width: 44rem) {
+          /* narrows 3 and 4; a request for 1 or 2 is already at or under it */
+          .pretui-desc[data-cols='3'] .pretui-desc-grid,
+          .pretui-desc[data-cols='4'] .pretui-desc-grid {
+            --pretui-desc-cols: 2;
+          }
+          .pretui-desc-pair[data-span='3'],
+          .pretui-desc-pair[data-span='4'] {
+            grid-column: 1 / -1;
+          }
+        }
+        @container (max-width: 26rem) {
+          /* outweighs the 44rem block's [data-cols] selectors: @container adds no specificity */
+          .pretui-desc[data-cols] .pretui-desc-grid {
+            --pretui-desc-cols: 1;
+          }
+          .pretui-desc-pair {
+            grid-column: 1 / -1;
+          }
+          /* The fold: label above value, whatever @layout asked for. Two
+             columns of text in a 26rem pane is not a record, it is a wrap. */
+          .pretui-desc[data-layout='horizontal'] .pretui-desc-pair {
+            display: block;
+          }
+          .pretui-desc[data-layout='horizontal'] .pretui-desc-label {
+            margin-block-end: 0.2em;
+          }
+          .pretui-desc[data-bordered] .pretui-desc-label {
+            box-shadow: inset 0 -1px 0 var(--border);
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/descriptions.md

@@ -0,0 +1,73 @@
+## What it is
+
+A read-only record as label/value pairs in an N-column grid that folds to stacked: the thing an agent types after Ant's `Descriptions`. N pairs per row, a per-item `span`, an optional title with a trailing `<:extra>` slot, borders that tint the label cells, and a container query that reduces the column count as the pane narrows.
+
+It is not **RecordDetail**, which is the editing machine: a draft batch, one open editor, dirty counts, save and cancel. It is not **KeyValue** either, though that is the nearest thing: **KeyValue** is a fixed two-column `<dl>` with no borders, no header, no spans, no density and no fold, and six facts beside a card still want it. Descriptions is the page-scale form of the same idea. **PropertyRow** is one labelled value in a form; **Field** is the form control's frame.
+
+## The contract
+
+```
+@items                      — { label, value?, span?, key?, mono? }[] in reading order
+@columns? | @column?        — pairs per row at full width, 1–4 (default 3; Ant's spelling accepted)
+@bordered?                  — rule the grid and tint the label cells
+@layout?                    — 'horizontal' (default) | 'vertical'
+@size?                      — xs|s|m|l|xl; sm/md/lg accepted
+@title?                     — header text; the <:title> block wins
+@colon?                     — trailing colon after every label (default false)
+@labelWidth?                — any CSS length for the label column in horizontal layout
+@placeholder?               — printed for an item with no value and no block (default '—')
+<:value as |item index|>    — markup for a description; wins over item.value
+<:title> <:extra>           — the header, and its trailing slot
+```
+
+**The column count is requested on the root and resolved on the grid.** `@columns` sets `--pretui-desc-cols-req` on the component root; the grid reads it into `--pretui-desc-cols`, and the container queries override that inner property at 44rem (3 and 4 become 2) and 26rem (everything becomes 1). Asking for 4 in a pane that fits 2 resolves to 2 with no JavaScript, and a request for 1 or 2 is never raised: the queries only ever reduce the count.
+
+**`span` is clamped the same way.** A number is clamped to 1–4 and to the row when the grid folds; `'fill'` takes the rest of the row at every width.
+
+**The `<:value>` block wins over `value`.** It is rendered for every item, with the item and its index, so markup never has to be smuggled through a string. An item with neither prints `@placeholder`, never the string "undefined".
+
+**`@labelWidth` goes through the kit's CSS-value guard**, so a caller string cannot inject a second declaration.
+
+## Prior art
+
+**Ant `Descriptions`** takes `column` (a number or a breakpoint map), `layout`, `bordered`, `colon` (default true), `size`, `title`, `extra` and `items` with per-item `span`. **Mantine `DataList`** and **Chakra `DataList`** are the same shape with `orientation` in place of `layout`. **shadcn** has no equivalent; the recipe is a `<dl>` with grid classes.
+
+Where this is better: **it is a `<dl>` in every mode.** Ant emits a `<table>` for label/value pairs, with `<th>` label cells only when `bordered` is on, so the semantics change when you flip a visual flag. Here `<dt>` is the term and `<dd>` the description whether or not there is a border. **The responsive column count is a container query, not a window media query.** Ant resolves `column: { xs: 1, md: 2, lg: 3 }` through `matchMedia` on the viewport; inside a Boxel card that is the wrong box, and a 320px pane on a 5K display gets three columns. **`colon` is opt-in**, because a bordered grid already puts each label in its own tinted cell.
+
+Where it is thinner: **no breakpoint map** — the fold points are the kit's, at 44rem and 26rem, and a caller cannot move them; **no per-item `labelStyle` / `contentStyle`** (the `<:value>` block is the escape hatch for content, and there is none for labels); **no `size` beyond the house scale**; **no `extra` per item**. Ant's `Descriptions.Item` children API is not supported at all — pass `@items`.
+
+## Accessibility
+
+Governing pattern: a description list. There is no APG widget here and the component claims no role beyond the native `<dl>`, `<dt>` and `<dd>`.
+
+What the component does, from its rendered markup and its tests:
+
+- **A `<dl>` in every mode, never a `<table>`.** Each pair is a `<div>` wrapping one `<dt>` and one `<dd>`, valid grouping since HTML 5.2.
+- **The colon is decorative:** `aria-hidden='true'`, so a screen reader hears "Lot" and not "Lot colon".
+- **A missing value prints the placeholder**, not "undefined".
+- **The `<:value>` block replaces the string.**
+
+The caller's failures to avoid: `@title` renders a styled `<div>`, not a heading — if the record has a heading in the page outline, put it in `<:title>`; a `<:value>` holding a control puts that control inside a `<dd>`, which is valid but means the label reaches it only through reading order, not through `<label for>`; and `mono` is a visual treatment for machine values (Appendix J), not a semantic one — a value that is a code or an id should also be a **Token** if it needs to be copied.
+
+## Theming
+
+Consumed directly: `--foreground`, `--muted-foreground`, `--card`, `--border`, `--inset`, `--line-strong`, `--radius-surface`, `--font-serif`, `--font-mono`, `--text-ui-md`, `--text-ui-sm`, `--track-ui`, `--track-heading`, `--space-2`, `--space-4`, `--space-5`.
+
+Its own properties: `--pretui-desc-cols-req` (set from `@columns` on the root), `--pretui-desc-cols` (resolved on the grid and overridden by the container queries), `--pretui-desc-label-w` (set from `@labelWidth`; default `max-content`).
+
+The title is the serif heading voice at 1.5em with `--track-heading`. Labels are `--muted-foreground` at 0.94em; in bordered mode they sit on `--inset` at weight 500 with a `--border` hairline. Density is `@size` on the root `font-size`. A theme retunes the whole record through the type tokens and `--inset`; the 44rem and 26rem fold points are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Ant / Mantine / Chakra       | Pretui                                                                     |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `items` / `data`             | `@items`                                                                   |
+| `column`                     | `@columns` (`@column` accepted) — reduced by the pane, never by the window |
+| `layout` / `orientation`     | `@layout`                                                                  |
+| `bordered`                   | `@bordered`                                                                |
+| `colon` (default true)       | `@colon` (default false)                                                   |
+| `size`                       | `@size`                                                                    |
+| `title` / `extra`            | `@title` or `<:title>`; `<:extra>`                                         |
+| `Descriptions.Item` children | not supported; pass `@items`                                               |