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

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

@@ -0,0 +1,60 @@
+// Pretui — Kbd: the shortcut token, one spec rendered per platform.
+import Component from '@glimmer/component';
+import { formatShortcut, ariaKeyShortcuts } from '../internal/menu';
+import type { ShortcutPlatform } from '../internal/menu';
+
+export interface KbdSignature {
+  Args: {
+    /** shortcut spec (`'Mod+K'`) or a literal face */
+    value: string;
+    /** force a platform instead of detecting it — the docs pages use this to
+     * show both spellings side by side */
+    platform?: ShortcutPlatform;
+  };
+  Element: HTMLElement;
+}
+
+/**
+ * The shortcut token. One `kbd` spec renders the Apple glyph run and the
+ * Ctrl/Alt/Shift spelling, so no caller ever hard-codes a platform.
+ */
+export class Kbd extends Component<KbdSignature> {
+  get face(): string | undefined {
+    return formatShortcut(this.args.value, this.args.platform);
+  }
+  get spoken(): string | undefined {
+    return ariaKeyShortcuts(this.args.value, this.args.platform);
+  }
+  <template>
+    <kbd
+      class='pretui-kbd'
+      aria-label={{this.spoken}}
+      data-test-pretui-kbd
+      ...attributes
+    >{{this.face}}</kbd>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-kbd {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          min-width: 1.5em;
+          padding-block: 1px;
+          padding-inline: 5px;
+          border-radius: var(--radius-chip, 4px);
+          background: var(--pretui-kbd-background, var(--inset, var(--boxel-100)));
+          box-shadow: var(
+            --pretui-shadow-hairline,
+            0 0 0 1px var(--border)
+          );
+          color: var(--pretui-kbd-foreground, var(--muted-foreground));
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          font-variant-numeric: tabular-nums;
+          line-height: 1.5;
+          white-space: nowrap;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,50 @@
+## What it is
+
+The face of a keyboard shortcut. You give it one spec — `Mod+K` — and it renders `⌘K` on Apple platforms and `Ctrl+K` everywhere else, so no call site hard-codes a platform. It is display only: it renders a shortcut, it does not bind one. Wiring the key handler is the caller's job, and **Menu** and **CommandPalette** use this to draw the shortcut column of rows they already handle keys for.
+
+If you want a monospace pill for a machine-readable value that is not a shortcut, that is **Token**. If you want a categorical label, **Chip**.
+
+## The contract
+
+```
+@value (required) — a shortcut spec ('Mod+Shift+K') or a literal face ('⌘K', 'F2')
+@platform?        — 'apple' | 'other', forced; detected from the browser when absent
+```
+
+**`Mod` is the whole point.** It resolves to `Meta` on Apple and `Control` elsewhere, which is the one decision that lets a single spec serve both platforms. Modifiers can be typed however the author thinks of them — `cmd`, `command`, `meta`, `super`, `win` all mean `Meta`; `opt` and `option` mean `Alt` — and are then reordered into the canonical `Control, Alt, Shift, Meta` regardless of the order they arrived in. Apple renders them as a glyph run with no separator (`⇧⌘K`), everyone else as `+`-joined words (`Ctrl+Shift+K`).
+
+**Named keys pick up glyphs only where the platform expects them.** Arrows are universal (`↑↓←→`). `Enter`, `Backspace`, `Delete`, `Tab`, `Space`, `PageUp`, `Home` and their neighbours become `↩⌫⌦⇥␣⇞↖` on Apple and stay as words elsewhere, except `Escape`, which is `⎋` on Apple and `Esc` otherwise. A single-character key is upper-cased.
+
+**A spec it cannot parse passes through verbatim.** Anything with no `+`, or with a modifier it does not recognise, is treated as a literal face and rendered as written. That is deliberate: the call sites that typed `⌘K` by hand before this component existed keep rendering, rather than becoming an error or an empty token.
+
+**Platform detection is defensive.** `detectShortcutPlatform` prefers `navigator.userAgentData.platform`, falls back to `navigator.platform` and then the user-agent string, and answers `other` when there is no `navigator` at all — because this module is evaluated by the indexer as well as the browser.
+
+`formatShortcut` and `ariaKeyShortcuts` are exported beside the component, so a caller that needs the string rather than the element (a `title`, a tooltip, a plain-text export) gets it from the same logic.
+
+## Prior art
+
+Most kits ship `<kbd>` as a styled element and nothing more: the caller types the glyphs, which means every shortcut in the product is authored twice, once per platform, and usually only once in practice. This component's addition is the shortcut _model_ — one spec, two faces, canonical modifier order — and it is the reason a shortcut can be stored in data rather than baked into a template.
+
+The two sources it answers to are specifications rather than kits. **Apple's Human Interface Guidelines** fix the modifier order as ⌃⌥⇧⌘, which is why the parser sorts rather than preserving what the author typed. **WAI-ARIA's `aria-keyshortcuts`** fixes the spoken spelling: platform-neutral key names joined with `+`, never a glyph, which is what `ariaKeyShortcuts` produces.
+
+Where it is thinner: there is no key-binding side. The component knows how to _say_ `Mod+Shift+K` and nothing about listening for it, so the spec and the handler are two separate declarations that can drift apart with nothing to catch it. A kit that owns both would register the shortcut and render its face from the same object.
+
+## Accessibility
+
+The glyph run is the problem this component exists to manage: `⇧⌘K` is four characters that a screen reader has no reliable name for, and reading them aloud produces noise rather than a shortcut.
+
+- **The spoken form is mirrored into `aria-label`** as the platform-neutral spelling, so `Mod+K` on Apple announces "Meta+K" rather than a symbol. That is the right _content_.
+- **Whether `aria-label` is the right attribute is an open question.** `aria-keyshortcuts` is the attribute specified for this purpose, but it belongs on the element that _has_ the shortcut, not on the token that draws it; `aria-label` here overrides the element's text, which is what makes the glyph announceable. The consequence to watch is a `Kbd` inside a control that already names itself: the label is announced as a second string, not as part of the control's name.
+- **A literal face gets no `aria-label` at all.** `ariaKeyShortcuts` returns nothing for a spec it cannot parse, because there is no honest way to spell out `⌘K` without guessing. So hand-typed shortcuts are announced as raw glyphs — one more reason to pass a spec.
+- **The element is a `<kbd>`**, which is the correct semantic and carries no role of its own.
+- Nothing is focusable, which is right: there is nothing here to operate.
+
+## Theming
+
+`--pretui-kbd-background` (falling back to `--inset`, then `--boxel-100`), `--pretui-kbd-foreground` (falling back to `--muted-foreground`), `--pretui-shadow-hairline` (falling back to a 1px ring in `--border`), `--radius-chip` (4px), `--font-mono`, `--text-ui-xs` (11px).
+
+The 1.5em minimum width, the 1px/5px padding, `tabular-nums` and `white-space: nowrap` are fixed. The minimum width and tabular figures exist together so a column of shortcuts in a menu aligns instead of ragging.
+
+A theme retunes every shortcut in the product through the two `--pretui-kbd-*` tokens; leaving them unset means the token follows `--inset` and `--muted-foreground`, so it stays quieter than the label beside it without any per-theme work. The hairline comes from the shared `--pretui-shadow-hairline`, so a theme that changes ring weight changes it here too.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,98 @@
+// Pretui — Kbd usage page.
+import GlimmerComponent from '@glimmer/component';
+import { FreestyleUsage } from './freestyle-usage';
+import { Kbd } from './kbd';
+
+// ── Kbd ──────────────────────────────────────────────────────────────────
+const KBD_SAMPLES = [
+  'Mod+K',
+  'Mod+Shift+P',
+  'Meta+Shift+Alt+Ctrl+D',
+  'Mod+Backspace',
+  'ArrowUp',
+  'Enter',
+  'Escape',
+  'F2',
+];
+
+class KbdUsage extends GlimmerComponent {
+  samples = KBD_SAMPLES;
+  <template>
+    <FreestyleUsage
+      @name='Kbd'
+      @description='The shortcut token. One spec renders both platforms: "Mod" is ⌘ on Apple and Ctrl elsewhere, modifiers are ordered ⌃⌥⇧⌘ the way Apple orders them regardless of how they were typed, and named keys pick up their glyphs where the platform expects them. A literal face ("⌘K", "F2") passes through untouched, so hand-written shortcuts keep rendering. The visible glyphs are mirrored into aria-label as the platform-neutral aria-keyshortcuts spelling, so a screen reader announces "Command K" rather than reading a symbol it has no name for.'
+    >
+      <:example>
+        <table class='kbd-table'>
+          <thead>
+            <tr><th>spec</th><th>Apple</th><th>other</th><th>announced</th></tr>
+          </thead>
+          <tbody>
+            {{#each this.samples key='@index' as |spec|}}
+              <tr>
+                <td><code>{{spec}}</code></td>
+                <td><Kbd @value={{spec}} @platform='apple' /></td>
+                <td><Kbd @value={{spec}} @platform='other' /></td>
+                <td class='kbd-spoken'>{{spec}}</td>
+              </tr>
+            {{/each}}
+          </tbody>
+        </table>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @description='A shortcut spec ("Mod+Shift+P") or a literal face ("⌘K"). Modifier aliases: mod, cmd/command/meta/super/win, ctrl/control, alt/opt/option, shift.'
+          @value='Mod+K'
+        />
+        <Args.String
+          @name='platform'
+          @description='"apple" or "other". Omit it and the platform is detected once, defensively — the module is evaluated by the indexer too, where navigator is not a browser.'
+          @defaultValue='(detected)'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .kbd-table {
+        border-collapse: collapse;
+        font-size: var(--text-ui-md, 12.5px);
+      }
+      .kbd-table th {
+        text-align: start;
+        padding-block: 4px;
+        padding-inline: 0 20px;
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 600;
+        letter-spacing: var(--track-eyebrow, 0.06em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+        border-bottom: 1px solid var(--border);
+      }
+      .kbd-table td {
+        padding-block: 6px;
+        padding-inline: 0 20px;
+        vertical-align: middle;
+      }
+      .kbd-table code {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .kbd-spoken {
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+//
+// The same `MenuNode` tree, one pattern over: an application menu bar rather
+// than a menu button. The tree below is written exactly as a `Menu` tree —
+// commands, shortcuts, an ellipsis item, a toggle, a radio group, a nested
+// submenu, a section, a separator, a destructive item and a dimmed one — and
+// nothing about it knows which surface will render it.
+
+export const DEMOS_KBD: Record<string, unknown> = {
+  Kbd: KbdUsage,
+};

package/bundled-realms/pretui/components/key-value.gts

@@ -0,0 +1,150 @@
+// Pretui — KeyValue: read-only labeled values in a definition list.
+import Component from '@glimmer/component';
+
+export interface KeyValueItem {
+  key: string;
+  value: string;
+}
+
+export type KeyValueLayout = 'horizontal' | 'stacked' | 'inline';
+
+export interface KeyValueSignature {
+  Args: {
+    items: KeyValueItem[];
+    /** 'horizontal' (default): keys in one column, values beside them.
+     *  'stacked': each key above its value. 'inline': pairs side by side,
+     *  wrapping onto the next line. 'vertical' is an alias of 'stacked'. */
+    layout?: KeyValueLayout | 'vertical';
+    /** 'eyebrow' sets the keys in the theme's eyebrow role (uppercase,
+     *  tracked out). Default 'default'. */
+    labelStyle?: 'default' | 'eyebrow';
+  };
+  Blocks: { value: [item: KeyValueItem] };
+  Element: HTMLDListElement;
+}
+
+export class KeyValue extends Component<KeyValueSignature> {
+  get layout(): KeyValueLayout {
+    let { layout } = this.args;
+    if (layout === 'stacked' || layout === 'vertical') {
+      return 'stacked';
+    }
+    return layout === 'inline' ? 'inline' : 'horizontal';
+  }
+  get isInline(): boolean {
+    return this.layout === 'inline';
+  }
+  get labelStyle(): 'eyebrow' | undefined {
+    return this.args.labelStyle === 'eyebrow' ? 'eyebrow' : undefined;
+  }
+  <template>
+    <dl
+      class='pretui-kv'
+      data-layout={{this.layout}}
+      data-label-style={{this.labelStyle}}
+      data-test-pretui-kv
+      ...attributes
+    >
+      {{#if this.isInline}}
+        {{! A div per pair keeps each key on the same line as its value when the strip wraps; HTML allows a div around each dt/dd group. }}
+        {{#each @items as |item|}}
+          <div class='pretui-kv-pair'>
+            <dt>{{item.key}}</dt>
+            <dd>{{#if (has-block 'value')}}{{yield item to='value'}}{{else}}{{item.value}}{{/if}}</dd>
+          </div>
+        {{/each}}
+      {{else}}
+        {{#each @items as |item|}}
+          <dt>{{item.key}}</dt>
+          <dd>{{#if (has-block 'value')}}{{yield item to='value'}}{{else}}{{item.value}}{{/if}}</dd>
+        {{/each}}
+      {{/if}}
+    </dl>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-kv {
+          display: grid;
+          grid-template-columns: max-content 1fr;
+          column-gap: var(--boxel-sp-lg);
+          row-gap: var(--boxel-sp-2xs);
+          align-content: start;
+          align-items: center;
+          margin: 0;
+        }
+        /* Keys default to the theme's ui-label role; the knobs win. */
+        .pretui-kv dt {
+          color: var(--pretui-kv-label-color, var(--muted-foreground));
+          font-family: var(
+            --pretui-kv-label-font-family,
+            var(--boxel-ui-label-font-family)
+          );
+          font-size: var(
+            --pretui-kv-label-font-size,
+            var(--boxel-ui-label-font-size)
+          );
+          font-weight: var(
+            --pretui-kv-label-font-weight,
+            var(--boxel-ui-label-font-weight)
+          );
+          line-height: var(
+            --pretui-kv-label-line-height,
+            var(--boxel-ui-label-line-height)
+          );
+          letter-spacing: var(
+            --pretui-kv-label-letter-spacing,
+            var(--boxel-ui-label-letter-spacing)
+          );
+          text-transform: var(--pretui-kv-label-text-transform);
+        }
+        /* The theme's eyebrow role. The knobs above still win. */
+        .pretui-kv[data-label-style='eyebrow'] dt {
+          font-family: var(
+            --pretui-kv-label-font-family,
+            var(--boxel-eyebrow-font-family)
+          );
+          font-size: var(
+            --pretui-kv-label-font-size,
+            var(--boxel-eyebrow-font-size)
+          );
+          font-weight: var(
+            --pretui-kv-label-font-weight,
+            var(--boxel-eyebrow-font-weight)
+          );
+          line-height: var(
+            --pretui-kv-label-line-height,
+            var(--boxel-eyebrow-line-height)
+          );
+          letter-spacing: var(
+            --pretui-kv-label-letter-spacing,
+            var(--boxel-eyebrow-letter-spacing)
+          );
+          text-transform: var(--pretui-kv-label-text-transform, uppercase);
+        }
+        .pretui-kv dd {
+          margin: 0;
+          display: flex;
+          align-items: center;
+          gap: var(--boxel-sp-2xs);
+        }
+        .pretui-kv[data-layout='stacked'] {
+          grid-template-columns: minmax(0, 1fr);
+          row-gap: var(--boxel-sp-6xs);
+        }
+        .pretui-kv[data-layout='stacked'] dt:not(:first-child) {
+          margin-block-start: var(--boxel-sp-xs);
+        }
+        .pretui-kv[data-layout='inline'] {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+        }
+        .pretui-kv-pair {
+          display: flex;
+          align-items: center;
+          gap: var(--boxel-sp-2xs);
+          min-inline-size: 0;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/key-value.md

@@ -0,0 +1,81 @@
+## What it is
+
+A definition list of property names and their values: by default in two columns, names on the left and values on the right, or stacked, or inline as a wrapping strip. Use it for the read view of a record — metadata panels, detail sidebars, a card's summary. If the values are editable, use **FormField** with `@static` (or **RecordDetail**, which is the whole record-page pattern). If the data is a list of _rows_ rather than one object's properties, that is **DataGrid** or **Table**.
+
+## The contract
+
+```
+@items: { key: string; value: string }[]   (required)
+@layout?: 'horizontal' | 'stacked' | 'inline'   (default 'horizontal'; 'vertical' = 'stacked')
+@labelStyle?: 'default' | 'eyebrow'   (default 'default')
+<:value as |item|>   — optional per-row override
+Element: HTMLDListElement
+```
+
+**It renders a real `<dl>`/`<dt>`/`<dd>`**, which is the correct markup for name/value pairs and is what most implementations of this pattern get wrong (a grid of `<div>`s carries no relationship).
+
+**The two-column alignment is `grid-template-columns: max-content 1fr` on the `<dl>` itself**, with the `<dt>`/`<dd>` pairs flowing into it. That is the good version of this layout: keys size to the longest key and stop, values take the rest, and every row aligns — without a fixed label width, without a wrapper per row, and without the `<dl>` losing its semantics to a `display: flex` on each pair. `align-items: center` means a single-line key sits centered against a multi-line value.
+
+**`@layout` picks one of three arrangements**, landing as `data-layout`:
+
+- `'horizontal'` (the default) is the two-column grid above.
+- `'stacked'` puts each key above its value in a single column, for a narrow side panel or a value too long to sit beside its key. `'vertical'` is accepted as an alias. The markup stays a flat run of `<dt>`/`<dd>`.
+- `'inline'` sets the pairs side by side on one line and wraps them onto the next when space runs out, for a compact strip such as a period's start, end and term. Each pair sits in a `<div>`, so a key always wraps together with its value. HTML allows a `<div>` around each `<dt>`/`<dd>` group in a `<dl>`, and the list keeps its semantics.
+
+**`@labelStyle='eyebrow'`** sets the keys in the theme's eyebrow role: the `--boxel-eyebrow-*` font, size, weight, line height and tracking, uppercase. Inside a card those come from the card's theme, and outside one from the `theme.css` defaults. It lands as `data-label-style`.
+
+**The keys' typography has its own properties**, `--pretui-kv-label-*` (see Theming). Set them on the KeyValue, through a class, or on any ancestor; they win over `@labelStyle`. A caller restyles the keys this way rather than reaching into the `<dt>` with `:deep()`.
+
+**`<:value>` is the escape hatch that makes it useful.** `@items` types values as strings, but the block yields the whole item, so a row's value can be a **Token**, a **StatusChip**, an **Avatar** or a link. Note the type still says `string` — the block is how you get past that, and the item's own `value` property is then effectively a key you read yourself.
+
+## Prior art
+
+**SLDS's `description-list`** is the closest — horizontal and stacked variants over a real `<dl>`. **Web Awesome**, **Radix** and **React Spectrum** all ship nothing here; Spectrum's guidance is to use a `Grid` with `Text` pairs. **shadcn** has no equivalent; the community recipe is a `<dl>` with Tailwind grid classes.
+
+So this is another case of "everyone writes it by hand", and the improvements over the hand-rolled version are concrete:
+
+- **Real `<dl>` semantics with grid alignment.** The usual hand-rolled version either uses `<div>`s (losing semantics) or puts `display: flex` on each `<dt>`/`<dd>` pair (losing column alignment across rows). The `max-content 1fr` grid on the list keeps both.
+- **`max-content` rather than a fixed label width**, so a panel of short keys is not padded to fit a hypothetical long one. Compare **FormLayout**'s `horizontal` direction, which uses a fixed `9rem` label column because its labels sit beside _controls_ that need a stable left edge — the two are different problems and get different answers, deliberately.
+- **`Token`'s flush-margin rule is coordinated with this component**: `:where(td, dd) > .pretui-token` drops the token's side margins, so ids in a `<dd>` align with the column edge. That kind of cross-component detail is what a kit buys you over a snippet.
+
+Where it is thin: **the layout does not adapt to its container.** `@layout='stacked'` matches SLDS's stacked variant, but the caller picks it; at a narrow container the default `max-content 1fr` grid still holds two columns and squeezes the values, since there is no container query to stack it automatically.
+
+## Accessibility
+
+No APG pattern. `<dl>` is a semantic structure, governed by WCAG **1.3.1 Info and Relationships**.
+
+What is right, and it is most of the value:
+
+- **`<dl>`/`<dt>`/`<dd>` gives a real programmatic association** between name and value. Screen readers announce the pairing, and many announce the list's item count on entry. This is the single reason to use this component over a grid of divs.
+- **The grid layout does not break the semantics.** `display: grid` on a `<dl>` with `<dt>`/`<dd>` as direct children is well-supported and preserves the list's accessibility tree in current browsers — worth knowing, because putting a wrapper `<div>` around each pair (the obvious way to lay this out) _does_ break it in some readers.
+
+Gaps:
+
+- **No accessible name for the list.** A card with three KeyValue lists gives three unnamed definition lists. There is no `@label` arg; pass `aria-label` through `...attributes`, or precede it with a heading.
+- **Values are plain text with no type information.** A date, an id and a name are announced identically. Using `<:value>` to wrap machine values in **Token** (`<code>`) gives the reader a hint; nothing does it for you.
+- **No empty-value handling.** An item with `value: ''` renders an empty `<dd>`, announced as nothing — indistinguishable from a value the reader missed. **FormField** has `@emptyText` (default `'—'`) for exactly this; KeyValue has no equivalent and should.
+- **Long values do not truncate and keys do not wrap-protect.** A very long key expands the `max-content` column and squeezes every value in the list, which at narrow widths becomes a **WCAG 1.4.10 Reflow** problem. `@layout='stacked'` or `'inline'` avoids it, but the default layout does not switch on its own.
+- **Keys in `--muted-foreground` have less contrast margin than the values.** The default keys are in the ui-label role (0.75rem with the default theme). `@labelStyle='eyebrow'` sets them smaller, at the eyebrow role's 0.6875rem and uppercase, in the same `--muted-foreground`. That is still normal-size text, so the bar stays 4.5:1 and the smaller size leaves less margin. With the default theme the key ink is 6.91:1 against `--card` and `--background` in light, and 5.57:1 against `--card` and 7.61:1 against `--background` in dark, so both key styles pass. Inside a themed card the card's theme sets the ink; check it there.
+- Nothing is focusable, correctly — unless you yield interactive content into `<:value>`, which then joins the tab order in reading order.
+
+## Theming
+
+`--muted-foreground` and the ui-label role (`--boxel-ui-label-*`) for the keys, `--boxel-sp-lg` (the column gap, and the gap between inline pairs) and `--boxel-sp-2xs` (the row gap). The values set no typography of their own, so they inherit the surrounding text: the body role inside a card. The eyebrow keys read `--boxel-eyebrow-font-family`, `--boxel-eyebrow-font-size`, `--boxel-eyebrow-font-weight`, `--boxel-eyebrow-line-height` and `--boxel-eyebrow-letter-spacing`.
+
+The keys' own properties, each unset by default:
+
+- `--pretui-kv-label-color` (unset: `--muted-foreground`)
+- `--pretui-kv-label-font-family` (unset: `--boxel-ui-label-font-family`)
+- `--pretui-kv-label-font-size` (unset: `--boxel-ui-label-font-size`)
+- `--pretui-kv-label-font-weight` (unset: `--boxel-ui-label-font-weight`)
+- `--pretui-kv-label-line-height` (unset: `--boxel-ui-label-line-height`)
+- `--pretui-kv-label-letter-spacing` (unset: `--boxel-ui-label-letter-spacing`)
+- `--pretui-kv-label-text-transform`
+
+With `@labelStyle='eyebrow'`, the unset typography properties take the eyebrow role instead and the text transform becomes uppercase. The color stays `--muted-foreground`.
+
+The arrangement is `@layout`, not a token, and there is still no way to set a fixed key column or right-align keys.
+
+Because keys use `--muted-foreground` and values inherit `--foreground`, the key/value distinction is carried by ink, weight and size. A theme that compresses its gray ramp will make the two columns read as one; keep at least a step between them.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/key-value.usage.gts

@@ -0,0 +1,125 @@
+// Pretui — KeyValue usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Token } from './token';
+import { KeyValue } from './key-value';
+import type { KeyValueLayout } from './key-value';
+
+const LOT_DETAILS = [
+  { key: 'Lot', value: 'B-103' },
+  { key: 'Tea', value: 'Gyokuro' },
+  { key: 'Origin', value: 'Shizuoka' },
+  { key: 'Harvest', value: 'First flush' },
+];
+const LAYOUTS: KeyValueLayout[] = ['horizontal', 'stacked', 'inline'];
+const LABEL_STYLES = ['default', 'eyebrow'];
+
+class KeyValueUsage extends Component {
+  items = LOT_DETAILS;
+  @tracked layout: KeyValueLayout = 'horizontal';
+  @tracked labelStyle = 'default';
+  setLayout = (v: string) => (this.layout = v as KeyValueLayout);
+  setLabelStyle = (v: string) => (this.labelStyle = v);
+  get labelStyleVal(): 'eyebrow' | undefined {
+    return this.labelStyle === 'eyebrow' ? 'eyebrow' : undefined;
+  }
+  get usage() {
+    let bits = ['@items={{this.items}}'];
+    if (this.layout !== 'horizontal') {
+      bits.push(`@layout='${this.layout}'`);
+    }
+    if (this.labelStyleVal) {
+      bits.push(`@labelStyle='${this.labelStyleVal}'`);
+    }
+    return `<KeyValue ${bits.join(' ')} />`;
+  }
+  isLot = (item: { key: string }) => item.key === 'Lot';
+  <template>
+    <FreestyleUsage
+      @name='KeyValue'
+      @description='A semantic description list for compact record facts, with an optional value block for links, tokens or status.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <KeyValue
+          @items={{this.items}}
+          @layout={{this.layout}}
+          @labelStyle={{this.labelStyleVal}}
+        ><:value as |item|>{{#if (this.isLot item)}}<Token
+                @value={{item.value}}
+              />{{else}}{{item.value}}{{/if}}</:value></KeyValue>
+      </:example>
+      <:api as |Args|>
+        <Args.Object @name='items' @value={{this.items}} />
+        <Args.String
+          @name='layout'
+          @value={{this.layout}}
+          @options={{LAYOUTS}}
+          @defaultValue='horizontal'
+          @description="'horizontal': keys in one column, values beside them. 'stacked': each key above its value ('vertical' is an alias). 'inline': pairs side by side on one line, wrapping when space runs out (Pretui addition)."
+          @onInput={{this.setLayout}}
+        />
+        <Args.String
+          @name='labelStyle'
+          @value={{this.labelStyle}}
+          @options={{LABEL_STYLES}}
+          @defaultValue='default'
+          @description="'eyebrow' sets the keys in the theme's eyebrow role, uppercase; the --pretui-kv-label-* properties still win (Pretui addition)."
+          @onInput={{this.setLabelStyle}}
+        />
+        <Args.Yield
+          @name='value'
+          @description='Receives the current item.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-kv-label-color'
+          @type='color'
+          @description='Key ink. Set on the KeyValue or any ancestor.'
+          @defaultValue='var(--muted-foreground)'
+        />
+        <Css.Basic
+          @name='pretui-kv-label-font-family'
+          @type='string'
+          @description="Key font family; the eyebrow role's with @labelStyle."
+          @defaultValue='var(--boxel-ui-label-font-family)'
+        />
+        <Css.Basic
+          @name='pretui-kv-label-font-size'
+          @type='dimension'
+          @description="Key font size; the eyebrow role's with @labelStyle."
+          @defaultValue='var(--boxel-ui-label-font-size)'
+        />
+        <Css.Basic
+          @name='pretui-kv-label-font-weight'
+          @type='string'
+          @description="Key font weight; the eyebrow role's with @labelStyle."
+          @defaultValue='var(--boxel-ui-label-font-weight)'
+        />
+        <Css.Basic
+          @name='pretui-kv-label-line-height'
+          @type='dimension'
+          @description="Key line height; the eyebrow role's with @labelStyle."
+          @defaultValue='var(--boxel-ui-label-line-height)'
+        />
+        <Css.Basic
+          @name='pretui-kv-label-letter-spacing'
+          @type='dimension'
+          @description="Key tracking; the eyebrow role's with @labelStyle."
+          @defaultValue='var(--boxel-ui-label-letter-spacing)'
+        />
+        <Css.Basic
+          @name='pretui-kv-label-text-transform'
+          @type='keyword'
+          @description='Key case. Unset, the keys inherit it, or are uppercase with @labelStyle.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_KEY_VALUE: Record<string, unknown> = {
+  KeyValue: KeyValueUsage,
+};