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

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

@@ -0,0 +1,56 @@
+// Pretui — Breadcrumb: the trail of locations above the current page.
+import Component from '@glimmer/component';
+
+export interface CrumbSpec {
+  label: string;
+  href?: string;
+}
+
+export interface BreadcrumbSignature {
+  Args: { items: CrumbSpec[] };
+  Element: HTMLElement;
+}
+
+export class Breadcrumb extends Component<BreadcrumbSignature> {
+  isLast = (index: number) => index === this.args.items.length - 1;
+  <template>
+    <nav class='pretui-breadcrumb' aria-label='Breadcrumb' data-test-pretui-breadcrumb ...attributes>
+      {{#each @items as |item index|}}
+        {{#if index}}<span class='sep' aria-hidden='true' data-test-pretui-breadcrumb-sep>/</span>{{/if}}
+        {{#if (this.isLast index)}}
+          <b aria-current='page'>{{item.label}}</b>
+        {{else if item.href}}
+          <a href={{item.href}}>{{item.label}}</a>
+        {{else}}
+          <span>{{item.label}}</span>
+        {{/if}}
+      {{/each}}
+    </nav>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-breadcrumb {
+          display: flex;
+          align-items: center;
+          gap: var(--boxel-sp-2xs);
+          font-size: var(--boxel-font-size-xs);
+          color: var(--muted-foreground);
+        }
+        .pretui-breadcrumb b {
+          color: var(--foreground);
+          font-weight: 500;
+        }
+        .pretui-breadcrumb a {
+          color: inherit;
+          text-decoration: none;
+        }
+        .pretui-breadcrumb a:hover {
+          text-decoration: underline;
+          text-underline-offset: 2px;
+        }
+        .sep {
+          color: var(--subtle-foreground);
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,52 @@
+## What it is
+
+The trail showing where you are in a hierarchy, with each ancestor a link and the current location in bold. Use it above a **Toolbar** on any record or view that sits inside a structure. It is _location_, not navigation history — a breadcrumb that reflects where the user came from rather than where they are is the classic misuse. If you are showing steps through a process, use **StepList**; if you are showing a list of pages, **Pagination**.
+
+## The contract
+
+```
+@items: { label: string; href?: string }[]   (required)
+Element: HTMLElement (a <nav>)
+```
+
+One arg. Three render branches per item, in priority order: **the last item is always `<b aria-current="page">`** regardless of whether it has an `href`; otherwise an item with `href` is an `<a>`; otherwise a plain `<span>`.
+
+That last-item rule is the whole opinion. The current location is not a link even if you gave it one, because linking to where you already are is a dead affordance — and making it structurally impossible means no call site has to remember. The `<span>` branch exists for intermediate ancestors that are real but unreachable (a folder you cannot open, a realm you cannot read), which is a genuine Boxel case.
+
+Separators are `/` characters rendered between items, styled `--subtle-foreground`.
+
+## Prior art
+
+**APG's Breadcrumb pattern is three bullets total**, and it is worth knowing exactly what it does and does not require: contained in a **navigation landmark**; that landmark labeled; and `aria-current="page"` on the link to the current page. **`<ol>` is not required** — the APG example uses one, the normative text never mentions it — and the keyboard interaction section reads "Not applicable".
+
+**Web Awesome `wa-breadcrumb`** takes only a `label` prop, renders `<nav aria-label>`, and on `slotchange` **auto-applies `aria-current="page"` to the last item and strips it from the rest**. **React Aria `useBreadcrumbs`** returns only `navProps` with a localized default label and sets no role; `useBreadcrumbItem` treats the current item as **disabled** (it delegates to `useLink` with `isDisabled: isDisabled || isCurrent`) and defaults `aria-current` to `'page'`. **shadcn** ships styled `<nav>` + `<ol>` markup with `aria-current="page"` and `aria-hidden` separators.
+
+Pretui's data API (`@items` array) is closer to Ark than to the children-based kits, and it makes a breadcrumb one line derived from a model. The last-item-is-not-a-link rule matches React Aria's instinct exactly, arrived at structurally rather than through a disabled state.
+
+Where it is behind: no overflow handling. Web Awesome and SLDS both collapse long trails into a `…` menu; here a deep hierarchy simply runs off the edge, and `flex` with no `wrap` and no `overflow` means it will either overflow its container or squash. That is the most visible practical gap.
+
+## Accessibility
+
+Governing pattern: APG **Breadcrumb**. All three bullets are met.
+
+- **Navigation landmark: yes.** The root is a `<nav aria-label="Breadcrumb">`, correctly labeled and correctly distinguished from other navs.
+- **Keyboard: nothing to do**, and correctly nothing is done — links are ordinary tab stops.
+- **`aria-current="page"`: yes.** The current item is a `<b aria-current="page">`, so assistive tech announces it as the current page; the bold weight on its own is visual only. It sits on the one branch that renders the last item, so every trail marks exactly one crumb as current, with or without an `href` — the same result Web Awesome reaches by applying it to the last item automatically. APG puts the attribute on a link to the current page; here the current item is never a link (above), and `aria-current` is a global state, valid on a non-link element.
+
+The separators are hidden from assistive tech: each `/` is `aria-hidden="true"`, so a three-level trail is read as its three crumbs, not as "Realm slash Projects slash Q3 Report" — the treatment shadcn and Web Awesome use.
+
+Further gaps:
+
+- **No list semantics.** APG does not require `<ol>`, so this is not a failure — but a list would let a screen reader announce "3 items", which is useful context in a deep hierarchy. Every reference implementation uses one.
+- **The `<b>` element carries no heading or landmark role**, so the current location is not reachable except by reading the nav.
+- **Links have `text-decoration: none` at rest** and underline only on hover. Since they sit in `--muted-foreground` against the page and the current item is `--foreground`, **color and weight are the only resting distinction between a link and non-link item** — a WCAG **1.4.1 Use of Color** concern for the link/non-link distinction specifically. Underlining at rest, or accepting that breadcrumbs are a known convention, are the two defensible answers.
+- **No overflow behaviour** (above) is an accessibility issue as well as a visual one: a trail that overflows horizontally with no scroll container fails WCAG **1.4.10 Reflow** at 320px.
+- Target size: link text at 12px with a gap of about 7px is well below WCAG 2.5.8's 24×24 minimum on the vertical axis. Breadcrumbs are conventionally exempt in practice, not in the spec.
+
+## Theming
+
+`--muted-foreground` (trail ink and links), `--foreground` (current item), `--subtle-foreground` (separators), `--boxel-font-size-xs` (the trail's size), `--boxel-sp-2xs` (the gap between items). The `500` weight on the current item and the 2px underline offset are fixed.
+
+There is no surface, no border and no padding — a Breadcrumb inherits whatever it sits on, which is why it composes above a **Toolbar** without a seam. A theme must keep `--muted-foreground` and `--foreground` separable, since the current item is distinguished from its ancestors by ink and weight alone.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,24 @@
+// Pretui — Breadcrumb usage page.
+import Component from '@glimmer/component';
+import { FreestyleUsage } from './freestyle-usage';
+import { Breadcrumb } from './breadcrumb';
+
+const CRUMBS = [
+  { label: 'Auctions', href: '#auctions' },
+  { label: 'Spring 2026', href: '#spring-2026' },
+  { label: 'Lot B-103' },
+];
+
+class BreadcrumbUsage extends Component {
+  items = CRUMBS;
+  <template>
+    <FreestyleUsage @name='Breadcrumb' @description='A semantic navigation trail whose current location is plain emphasized text and whose ancestors remain links.' @source='<Breadcrumb @items={{this.items}} />'>
+      <:example><Breadcrumb @items={{this.items}} /></:example>
+      <:api as |Args|><Args.Object @name='items' @value={{this.items}} /></:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_BREADCRUMB: Record<string, unknown> = {
+  Breadcrumb: BreadcrumbUsage,
+};

package/bundled-realms/pretui/components/broken-link.gts

@@ -0,0 +1,46 @@
+// Pretui — BrokenLink: an honest "this reference is gone" marker.
+import Component from '@glimmer/component';
+
+export interface BrokenLinkSignature {
+  Args: { label?: string; refId?: string };
+  Element: HTMLSpanElement;
+}
+
+// An honest "this reference is gone" (Boxel-specific obligation).
+export class BrokenLink extends Component<BrokenLinkSignature> {
+  get label() {
+    return this.args.label ?? 'missing card';
+  }
+  <template>
+    <span class='pretui-broken' title='This reference is gone' data-test-pretui-broken-link ...attributes>
+      <svg width='11' height='11' viewBox='0 0 12 12' aria-hidden='true'><path d='M4.5 7.5 2.8 9.2a1.7 1.7 0 0 1-2.4-2.4L2.8 4.4M7.5 4.5l1.7-1.7a1.7 1.7 0 0 1 2.4 2.4L9.2 7.6M1 1l10 10' fill='none' stroke='currentColor' stroke-width='1.3' stroke-linecap='round' /></svg>
+      <span>{{this.label}}</span>
+      {{#if @refId}}<span class='pretui-broken-id'>{{@refId}}</span>{{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-broken {
+          display: inline-flex;
+          align-items: center;
+          gap: 6px;
+          padding: 2px 8px;
+          border-radius: 6px;
+          background: var(--inset, var(--boxel-100));
+          color: var(--ink-3, var(--boxel-400));
+          font-size: var(--text-ui-sm, 11.5px);
+          font-family: var(--font-mono);
+          outline: 1px dashed var(--line-strong, var(--boxel-400));
+          outline-offset: -1px;
+          text-decoration: line-through;
+          text-decoration-color: color-mix(in oklch, var(--ink-3, var(--boxel-400)) 50%, transparent);
+        }
+        .pretui-broken svg {
+          flex: none;
+        }
+        .pretui-broken-id {
+          opacity: 0.7;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/broken-link.md

@@ -0,0 +1,50 @@
+## What it is
+
+An honest "this reference is gone". When a card links to another card that has been deleted, moved, or is not readable, something has to render — and the wrong answer is a blank, a raw id, or a link that goes nowhere. This is a Boxel-specific obligation rather than a general UI pattern, which is why no other kit ships an equivalent. Use it anywhere a `linksTo` resolves to nothing. If the reference is present but still loading, use **Skeleton** or **Spinner**. If the _whole_ region is empty rather than one reference, use **EmptyState**.
+
+## The contract
+
+```
+@label? (default 'missing card')
+@refId?
+Element: HTMLSpanElement
+```
+
+Two args and no actions. It is a marker, not an affordance — there is nothing to click, nothing to retry, nothing to dismiss.
+
+**`@refId` is optional and shown at 70% opacity after the label.** That is the whole recovery story: a developer or an author who sees the id can go find out what happened; an end user sees a quiet grey chip and moves on. Showing the id by default would be noise; hiding it entirely would make the failure undebuggable.
+
+The visual vocabulary is chosen to read as _absence_ rather than _error_: `--ink-3` mono type, a dashed outline drawn with `outline` + `outline-offset: -1px` (so it does not affect layout the way a border would), a strike-through at 50% alpha, and an `--inset` fill. It deliberately does **not** use `--destructive` — a missing reference is a fact about the data, not something the user did wrong, and painting it red trains people to panic about a normal state.
+
+## Prior art
+
+There is no direct prior art, and that is worth saying plainly: Radix, React Spectrum, Web Awesome and shadcn all assume references resolve, because they are component kits for applications that own their data. A realm-based system where a card can link to a card in another realm that may be deleted or unreadable has a failure mode those kits do not.
+
+The nearest analogues are editor conventions rather than component APIs — Notion's "Deleted page" inline mention, Figma's missing-component placeholder, and a broken image's `alt` fallback. All three share the same instinct as this component: keep the slot occupied, name the absence, stay visually quiet.
+
+Where Pretui's version is better than the ad-hoc thing most codebases write: it is **one component with a stable look**, so every broken reference in every card reads identically, and a reviewer scanning a page can tell missing-data from styled-error at a glance. The improvement is consistency, not cleverness.
+
+The obvious gap versus what it could be: **no retry, no "why", no distinction between deleted, unauthorised and still-loading.** Those are three different situations with three different user responses, and the component flattens them to one. `@reason` would be a natural addition.
+
+## Accessibility
+
+No pattern governs it; the relevant criteria are WCAG **1.3.1**, **1.4.1 Use of Colour** and **4.1.2**.
+
+What is right: the SVG is `aria-hidden`, so the broken-link glyph does not pollute the announced text, and the label text is real content rather than a background image.
+
+Gaps:
+
+- **`title='This reference is gone'` is the only explanation**, and `title` is unreliable: it is not shown on touch, not reachable by keyboard, and announced inconsistently. Worse, on a non-interactive `<span>` many screen readers ignore it entirely — so for most assistive-tech users the element announces as "missing card" with no indication of what that means. Making that sentence visible text, or wiring it via `aria-describedby`, would fix it.
+- **Strike-through is decorative styling, not semantic.** `text-decoration: line-through` on a `<span>` conveys nothing to assistive tech. If the strike is meant to say "this used to be a link", `<del>` or `<s>` would carry it — though `<s>` is a stretch here.
+- **The state is conveyed visually by colour, dash pattern and strike**, none of which reach assistive tech. The word "missing" in the default label is doing all the semantic work, which is why overriding `@label` with something that omits the word ("Q3 Report") silently removes the only accessible signal that anything is wrong. Prefer labels that keep it.
+- **`--ink-3` on `--inset` is the kit's quietest ink on its quietest surface**, and at 11.5px mono it is close to the WCAG **1.4.3** floor. Verify per theme; this is the component most likely to fail contrast in light mode.
+- `@refId` at `opacity: 0.7` on top of `--ink-3` compounds that — it is decorative-grade contrast carrying debugging information.
+- Nothing is focusable, which is correct: there is nothing to do.
+
+## Theming
+
+`--inset` (fill), `--ink-3` (ink and the 50%-alpha strike), `--line-strong` (the dashed outline), `--font-mono`, `--text-ui-sm`. The 6px radius, 2px/8px padding and 11px glyph are fixed.
+
+Note this component uses **no semantic tone token at all** — no `--destructive`, no `--warning`. That is deliberate (see above) and a theme should resist re-pointing it at an error color. The one thing a theme must get right is `--ink-3` against `--inset`: everything here is drawn at the quiet end of the palette, so a theme that compresses its grays will render broken links effectively invisible.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/broken-link.usage.gts

@@ -0,0 +1,57 @@
+// Pretui — BrokenLink usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { BrokenLink } from './broken-link';
+
+// ── BrokenLink ← broken-link/usage.gts ───────────────────────────────────
+// Dropped knobs: itemType + state + format (Pretui renders one inline token,
+// no card/file or not-found/error variants), errorDoc.status / errorDoc.title
+// / errorDoc.message / errorDoc.stack (no diagnostics reveal overlay).
+// viewCard is documented below as an Args.Action row from the boxel-ui
+// lineage; Pretui's signature does not carry it.
+class BrokenLinkUsage extends GlimmerComponent {
+  @tracked label = 'Author';
+  @tracked refId = 'exploded-card-id';
+  setLabel = (v: string) => (this.label = v);
+  setRefId = (v: string) => (this.refId = v);
+  get labelVal() {
+    return this.label || undefined;
+  }
+  get refIdVal() {
+    return this.refId || undefined;
+  }
+  <template>
+    <FreestyleUsage
+      @name='BrokenLink'
+      @description='Placeholder shown when a card/file reference fails to resolve (deleted, moved, or no permission). Renders an identical box across failures — a link-off icon with the type/file label — and hides the diagnostics (status, message, stack, additional errors) behind a warning-triangle reveal overlay that also carries the reference URL and a copy button. Used by broken linksTo / linksToMany field values and the markdown-embed chooser.'
+    >
+      <:example>
+        <BrokenLink @label={{this.labelVal}} @refId={{this.refIdVal}} />
+        <BrokenLink />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='refId'
+          @description='The unresolvable reference. Shown (as plain text, never a link) — in Pretui inline beside the label rather than in a reveal overlay.'
+          @value={{this.refId}}
+          @onInput={{this.setRefId}}
+        />
+        <Args.String
+          @name='label'
+          @description="Human-readable label next to the link-off icon — the card type name, or a filename for file refs. Falls back to 'missing card'."
+          @value={{this.label}}
+          @onInput={{this.setLabel}}
+        />
+        <Args.Action
+          @name='viewCard'
+          @description='Wire an "Open anyway" handler. The affordance shows only when set and the reference is a navigable http(s) URL. Not in the Pretui signature yet — documented from the boxel-ui lineage.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_BROKEN_LINK: Record<string, unknown> = {
+  BrokenLink: BrokenLinkUsage,
+};

package/bundled-realms/pretui/components/button-group.gts

@@ -0,0 +1,246 @@
+// Pretui — ButtonGroup: related Buttons fused into one visual unit.
+import Component from '@glimmer/component';
+import type {
+  PretuiAppearance,
+  PretuiSize,
+  PretuiTone,
+} from '../pretui-primitives';
+import type { ButtonShape } from './button';
+
+// Transcribed from wa-button-group: related Pretui Buttons fused into one
+// visual unit — role='group' with a strongly-recommended label, horizontal
+// or vertical orientation, inner corners squared and adjacent hairlines
+// collapsed to one (the -1px overlap; hover/focus raise z-index so the
+// full ring of the active button always draws on top, WA's stacking rule).
+// Children are plain <Button>s and need NO args: the group's @tone rides
+// the same custom-prop channel Button's recipes already read (each rule
+// re-points --pretui-tone/--pretui-tone-on; the neutral-only vars reset to
+// `initial` so recipe fallbacks re-engage), while @appearance restates the
+// five recipe declarations at group specificity — appearance recipes are
+// attribute-selected in Button, so they cannot travel as inherited props;
+// the formulas are copied verbatim from button.gts and read the same
+// tone vars. Dropped (wave-0): WA's slotted radio-button support and its
+// focus/hover class relay (CSS handles both here).
+
+export interface ButtonGroupSignature {
+  Args: {
+    /** group label for assistive tech — strongly recommended (WA note) */
+    label?: string;
+    orientation?: 'horizontal' | 'vertical';
+    /** tone inherited by every child Button via the custom-prop channel */
+    tone?: PretuiTone;
+    /** appearance recipe applied to every child Button */
+    appearance?: PretuiAppearance;
+    /** size (font-size scale) applied to every child Button */
+    size?: PretuiSize;
+    /** outer-corner treatment for the whole group; the inner corners stay square */
+    shape?: ButtonShape;
+  };
+  Blocks: { default: [] };
+  Element: HTMLDivElement;
+}
+
+export class ButtonGroup extends Component<ButtonGroupSignature> {
+  get orientation() {
+    return this.args.orientation ?? 'horizontal';
+  }
+  <template>
+    {{! template-lint-disable no-unsupported-role-attributes }}
+    <div
+      class='pretui-btngroup'
+      role='group'
+      aria-label={{@label}}
+      aria-orientation={{this.orientation}}
+      data-orientation={{this.orientation}}
+      data-tone={{@tone}}
+      data-appearance={{@appearance}}
+      data-size={{@size}}
+      data-shape={{@shape}}
+      data-test-pretui-button-group
+      ...attributes
+    >
+      {{yield}}
+    </div>
+    <style scoped>
+      /* above Button's layer, so the group's restyling wins by layer order;
+         the order statement holds whichever stylesheet loads first */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-btngroup {
+          display: inline-flex;
+          position: relative;
+          isolation: isolate;
+        }
+        .pretui-btngroup[data-orientation='vertical'] {
+          flex-direction: column;
+          align-items: stretch;
+        }
+        .pretui-btngroup :deep(.pretui-btn) {
+          position: relative;
+        }
+        /* the hovered / focused button draws on top of the shared edge */
+        .pretui-btngroup :deep(.pretui-btn:hover) {
+          z-index: 1;
+        }
+        .pretui-btngroup :deep(.pretui-btn:focus-visible) {
+          z-index: 2;
+        }
+        .pretui-btngroup[data-shape='rounded'] :deep(.pretui-btn) {
+          border-radius: var(--pretui-button-radius, calc(var(--radius) - 2px));
+        }
+        .pretui-btngroup[data-shape='pill'] :deep(.pretui-btn) {
+          border-radius: var(--pretui-button-radius, var(--boxel-border-radius-pill));
+        }
+        .pretui-btngroup[data-shape='square'] :deep(.pretui-btn) {
+          border-radius: var(--pretui-button-radius, 0);
+        }
+        /* attach: square the inner corners, overlap the borders by 1px so
+           adjacent edges collapse into one shared line. Siblings are matched
+           by class, so a non-button child (CopyButton's status region) does
+           not count as a neighbor */
+        .pretui-btngroup[data-orientation='horizontal'] :deep(.pretui-btn ~ .pretui-btn) {
+          margin-left: -1px;
+          border-top-left-radius: 0;
+          border-bottom-left-radius: 0;
+        }
+        .pretui-btngroup[data-orientation='horizontal'] :deep(.pretui-btn:has(~ .pretui-btn)) {
+          border-top-right-radius: 0;
+          border-bottom-right-radius: 0;
+        }
+        .pretui-btngroup[data-orientation='vertical'] :deep(.pretui-btn ~ .pretui-btn) {
+          margin-top: -1px;
+          border-top-left-radius: 0;
+          border-top-right-radius: 0;
+        }
+        .pretui-btngroup[data-orientation='vertical'] :deep(.pretui-btn:has(~ .pretui-btn)) {
+          border-bottom-left-radius: 0;
+          border-bottom-right-radius: 0;
+        }
+        /* ── tone inheritance: re-point the channel Button's recipes read.
+           The neutral-only vars reset to `initial` (guaranteed-invalid) so
+           var() fallbacks re-engage for hue tones. ── */
+        .pretui-btngroup[data-tone] :deep(.pretui-btn[data-tone]) {
+          --pretui-btn-accent-hover: initial;
+          --pretui-btn-hairline: initial;
+          --pretui-btn-ink: initial;
+          --pretui-btn-ink-quiet: initial;
+        }
+        .pretui-btngroup[data-tone='neutral'] :deep(.pretui-btn[data-tone]) {
+          --pretui-tone: var(--foreground);
+          --pretui-tone-ink: var(--foreground);
+          --pretui-tone-on: var(--background);
+          --pretui-btn-hairline: var(--border);
+          --pretui-btn-ink: var(--foreground);
+          --pretui-btn-ink-quiet: color-mix(in oklch, var(--muted-foreground) 55%, var(--foreground));
+          --pretui-btn-accent-hover: color-mix(in oklch, var(--pretui-tone-on) 30%, var(--pretui-button-bg, var(--pretui-tone)));
+        }
+        .pretui-btngroup[data-tone='primary'] :deep(.pretui-btn[data-tone]) {
+          --pretui-tone: var(--primary);
+          --pretui-tone-ink: var(--primary-ink);
+          --pretui-tone-on: var(--primary-foreground);
+        }
+        .pretui-btngroup[data-tone='info'] :deep(.pretui-btn[data-tone]) {
+          --pretui-tone: var(--info);
+          --pretui-tone-ink: var(--info-ink);
+          --pretui-tone-on: var(--info-foreground);
+        }
+        .pretui-btngroup[data-tone='success'] :deep(.pretui-btn[data-tone]) {
+          --pretui-tone: var(--success);
+          --pretui-tone-ink: var(--success-ink);
+          --pretui-tone-on: var(--success-foreground);
+        }
+        .pretui-btngroup[data-tone='warning'] :deep(.pretui-btn[data-tone]) {
+          --pretui-tone: var(--warning);
+          --pretui-tone-ink: var(--warning-ink);
+          --pretui-tone-on: var(--warning-foreground);
+        }
+        .pretui-btngroup[data-tone='danger'] :deep(.pretui-btn[data-tone]) {
+          --pretui-tone: var(--destructive);
+          --pretui-tone-ink: var(--destructive-ink);
+          --pretui-tone-on: var(--destructive-foreground);
+        }
+        .pretui-btngroup[data-tone='attention'] :deep(.pretui-btn[data-tone]) {
+          --pretui-tone: var(--attention);
+          --pretui-tone-ink: var(--attention-ink);
+          --pretui-tone-on: var(--attention-foreground);
+        }
+        /* ── appearance inheritance: Button's recipes restated at group
+           specificity. They only set Button's paint vars, so the formulas
+           must stay identical to button.gts. ── */
+        .pretui-btngroup[data-appearance] :deep(.pretui-btn[data-appearance]) {
+          --pretui-btn-surface: initial;
+          --pretui-btn-surface-hover: initial;
+          --pretui-btn-text-hover: initial;
+          --pretui-btn-edge: initial;
+          --pretui-btn-elevation: initial;
+        }
+        .pretui-btngroup[data-appearance='accent'] :deep(.pretui-btn[data-appearance]) {
+          --pretui-btn-surface: var(--pretui-button-bg, var(--pretui-tone));
+          --pretui-btn-surface-hover: var(--pretui-btn-accent-hover, oklch(from var(--pretui-button-bg, var(--pretui-tone)) calc(l * 0.9) c h));
+          --pretui-btn-text: var(--pretui-button-fg, var(--pretui-tone-on));
+          --pretui-btn-elevation: var(--shadow-2xs);
+        }
+        .pretui-btngroup[data-appearance='filled'] :deep(.pretui-btn[data-appearance]) {
+          --pretui-btn-surface: color-mix(in oklch, var(--pretui-tone) 15%, var(--background));
+          --pretui-btn-surface-hover: color-mix(in oklch, var(--pretui-btn-tint) 22%, var(--background));
+          --pretui-btn-text: var(--pretui-btn-ink, color-mix(in oklch, var(--pretui-tone) 45%, var(--foreground)));
+          --pretui-btn-text-hover: var(--pretui-btn-ink, color-mix(in oklch, var(--pretui-tone) 35%, var(--foreground)));
+        }
+        .pretui-btngroup[data-appearance='outlined'] :deep(.pretui-btn[data-appearance]) {
+          --pretui-btn-surface: var(--pretui-button-secondary-bg, transparent);
+          --pretui-btn-surface-hover: color-mix(in oklch, var(--pretui-btn-tint) 18%, var(--pretui-button-secondary-bg, transparent));
+          --pretui-btn-edge: var(--pretui-btn-hairline, color-mix(in oklch, var(--pretui-tone) 45%, var(--border)));
+          --pretui-btn-text: var(--pretui-btn-ink, color-mix(in oklch, var(--pretui-tone) 45%, var(--foreground)));
+          --pretui-btn-text-hover: var(--pretui-btn-ink, color-mix(in oklch, var(--pretui-tone) 40%, var(--foreground)));
+        }
+        .pretui-btngroup[data-appearance='filled-outlined'] :deep(.pretui-btn[data-appearance]) {
+          --pretui-btn-surface: color-mix(in oklch, var(--pretui-tone) 12%, var(--background));
+          --pretui-btn-surface-hover: color-mix(in oklch, var(--pretui-btn-tint) 20%, var(--background));
+          --pretui-btn-edge: var(--pretui-btn-hairline, color-mix(in oklch, var(--pretui-tone) 40%, var(--border)));
+          --pretui-btn-text: var(--pretui-btn-ink, color-mix(in oklch, var(--pretui-tone) 45%, var(--foreground)));
+          --pretui-btn-text-hover: var(--pretui-btn-ink, color-mix(in oklch, var(--pretui-tone) 35%, var(--foreground)));
+        }
+        .pretui-btngroup[data-appearance='plain'] :deep(.pretui-btn[data-appearance]) {
+          --pretui-btn-text: var(--pretui-btn-ink-quiet, color-mix(in oklch, var(--pretui-tone) 40%, var(--foreground)));
+          --pretui-btn-surface-hover: color-mix(in oklch, var(--pretui-btn-tint) 18%, transparent);
+          --pretui-btn-text-hover: var(--pretui-btn-ink, color-mix(in oklch, var(--pretui-tone) 30%, var(--foreground)));
+        }
+        .pretui-btngroup[data-appearance='link'] :deep(.pretui-btn[data-appearance]) {
+          --pretui-btn-text: var(--pretui-button-fg, var(--pretui-tone-ink));
+          text-underline-offset: 0.2em;
+        }
+        /* Button's link underline keys on the child's own appearance, which a
+           group-applied link look doesn't change, so it is restated here */
+        .pretui-btngroup[data-appearance='link'] :deep(.pretui-btn[data-appearance]:focus-visible) {
+          text-decoration-line: underline;
+        }
+        @media (hover: hover) {
+          .pretui-btngroup[data-appearance='link'] :deep(.pretui-btn[data-appearance]:hover:not(:disabled, [aria-disabled='true'])) {
+            text-decoration-line: underline;
+          }
+        }
+        /* a link-look Button sits flush with text on its own; in a group the
+           labels would run together, so it keeps Button's normal padding */
+        .pretui-btngroup :deep(.pretui-btn[data-appearance='link']) {
+          padding-inline: var(--pretui-button-px, 0.96em);
+        }
+        /* ── size inheritance: font-size only, Button's own em scale rides ── */
+        .pretui-btngroup[data-size='xs'] :deep(.pretui-btn[data-size]) {
+          font-size: var(--pretui-size-xs, var(--text-ui-xs, 0.66rem));
+        }
+        .pretui-btngroup[data-size='s'] :deep(.pretui-btn[data-size]) {
+          font-size: var(--pretui-size-s, var(--text-ui-sm, 0.72rem));
+        }
+        .pretui-btngroup[data-size='m'] :deep(.pretui-btn[data-size]) {
+          font-size: var(--pretui-size-m, var(--text-ui-md, 0.78rem));
+        }
+        .pretui-btngroup[data-size='l'] :deep(.pretui-btn[data-size]) {
+          font-size: var(--pretui-size-l, var(--text-ui-lg, 0.875rem));
+        }
+        .pretui-btngroup[data-size='xl'] :deep(.pretui-btn[data-size]) {
+          font-size: var(--pretui-size-xl, var(--text-ui-xl, 1rem));
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/button-group.md

@@ -0,0 +1,46 @@
+## What it is
+
+A row or column of buttons treated as one object: shared edges, shared tone, shared size.
+
+It is not a **ToggleGroup** — nothing here has a pressed state. These are actions that happen to sit together.
+
+## The contract
+
+```
+@label?       — group label for assistive tech; strongly recommended
+@orientation? — 'horizontal' | 'vertical'
+@tone?        — inherited by every child Button
+@appearance?  — recipe applied to every child Button
+@size?        — font-size scale applied to every child Button
+
+<:default> — the buttons
+```
+
+**The three treatment axes are inherited through a custom-property channel**, not by cloning props onto children. A child **Button** reads them from the group, which is why an ordinary Button placed inside picks them up without the group needing to know what it contains.
+
+**`@label` is strongly recommended rather than required**, and that is a real gap: an unnamed group of three buttons is announced as three loose buttons.
+
+## Prior art
+
+Web Awesome's button group, and the same component in every kit.
+
+Where Pretui is better: the inheritance channel. Most implementations either clone props onto children — which breaks the moment a child is wrapped in anything — or require a special child component.
+
+Where it is thinner: no split-button behaviour, no overflow, and no per-child override of the inherited axes short of setting them on the child directly.
+
+**An open design tension, worth knowing:** the group restyles plain children rather than yielding a contextual `G.Button`. Yielding would make the contract explicit and let the group know its own membership; restyling keeps ordinary buttons usable inside it, including ones wrapped in something the group cannot see through.
+
+## Accessibility
+
+- **`role='group'` with `aria-orientation`**, so the arrangement is announced rather than only drawn.
+- **`@label` is what makes the group meaningful.** Without it the role is announced with no name, which is close to no information.
+- **Nothing here has a pressed state**, which is the semantic difference from **ToggleGroup** — and it is why there is no roving tabindex: every button is a separate action and a separate tab stop.
+- **Shared edges are visual.** The grouping is conveyed by the role, not by the fact the buttons touch.
+
+## Theming
+
+`@tone`, `@appearance` and `@size` resolve through the kit's shared recipe system and reach children through custom properties.
+
+That channel is the component's whole implementation: a theme changes what `accent` means once, and every grouped button follows, including ones the group never knew about.
+
+The styles sit in `@layer PretComposite`, above Button's `PretComponent` layer, so what this component sets on Button wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.