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

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

@@ -0,0 +1,594 @@
+// Button: a native <button> on the two-axis treatment grid (@tone × @appearance),
+// em-scaled, with a built-in busy state. Everything that performs an action wraps it.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import {
+  PRETUI_APPEARANCES,
+  PRETUI_TONES,
+  firstDefined,
+  resolveSize,
+  resolveTone,
+} from '../pretui-primitives';
+import type {
+  PretuiAppearance,
+  PretuiSize,
+  PretuiSizeArg,
+  PretuiTone,
+  PretuiToneArg,
+} from '../pretui-primitives';
+
+// @variant is the single-axis spelling, resolved onto the two axes.
+export type ButtonVariant =
+  | 'primary'
+  | 'secondary'
+  | 'ghost'
+  | 'destructive'
+  | 'default'
+  | 'outline'
+  | 'outlined'
+  | 'subtle'
+  | 'filled'
+  | 'link';
+const DEFAULT_AXES: [PretuiTone, PretuiAppearance] = ['primary', 'accent'];
+// Null-prototype so a variant like 'constructor' misses the table instead of hitting Object.prototype.
+const VARIANT_AXES: Record<string, [PretuiTone, PretuiAppearance]> =
+  Object.assign(
+    Object.create(null) as Record<string, [PretuiTone, PretuiAppearance]>,
+    {
+      primary: ['primary', 'accent'],
+      secondary: ['neutral', 'outlined'],
+      ghost: ['neutral', 'plain'],
+      destructive: ['danger', 'accent'],
+      default: ['primary', 'accent'],
+      outline: ['neutral', 'outlined'],
+      outlined: ['neutral', 'outlined'],
+      subtle: ['neutral', 'plain'],
+      filled: ['primary', 'accent'],
+      link: ['primary', 'link'],
+    } as Record<string, [PretuiTone, PretuiAppearance]>,
+  );
+
+// Picks what a busy button shows, without ever changing its width: the
+// spinner with @busyLabel when that fits, else the spinner beside the dimmed
+// label when that fits (a stretched or min-width button), else the spinner
+// alone over the hidden label. Measured with the layout attribute cleared, so
+// the chosen layout can't widen the button and feed back into the check.
+// The busy label is an argument only so that changing it while busy re-runs
+// the measurement; the text itself is read from the DOM.
+const fitBusyContent = modifier(
+  (busyEl: HTMLElement, [busy, _busyLabel]: [boolean, string | undefined]) => {
+    let button = busyEl.parentElement;
+    let label = busyEl.previousElementSibling as HTMLElement | null;
+    let text = busyEl.lastElementChild as HTMLElement | null;
+    if (!button || !label || !text) return;
+    if (!busy) {
+      button.removeAttribute('data-busy-layout');
+      return;
+    }
+    let target = button;
+    let labelEl = label;
+    let textEl = text;
+    let measure = () => {
+      target.removeAttribute('data-busy-layout');
+      let style = getComputedStyle(target);
+      let room =
+        target.clientWidth -
+        parseFloat(style.paddingLeft) -
+        parseFloat(style.paddingRight) -
+        0.5;
+      // spinner 1.04em + gap 0.48em, as in the styles below
+      let spinner = parseFloat(style.fontSize) * 1.52;
+      // the busy text is visually hidden here, so scrollWidth is its full width
+      let textWidth = textEl.textContent?.trim() ? textEl.scrollWidth : 0;
+      if (textWidth && room >= textWidth + spinner) {
+        target.setAttribute('data-busy-layout', 'text');
+      } else if (room >= labelEl.offsetWidth + spinner) {
+        target.setAttribute('data-busy-layout', 'inline');
+      }
+    };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    let observer = new ResizeObserver(measure);
+    observer.observe(target);
+    return () => {
+      observer.disconnect();
+      target.removeAttribute('data-busy-layout');
+    };
+  },
+);
+
+export const BUTTON_SHAPES = ['rounded', 'pill', 'square'] as const;
+export type ButtonShape = (typeof BUTTON_SHAPES)[number];
+
+export interface ButtonSignature {
+  Args: {
+    /** single-axis alias over @tone + @appearance */
+    variant?: ButtonVariant;
+    tone?: PretuiToneArg;
+    appearance?: PretuiAppearance;
+    size?: PretuiSizeArg;
+    busy?: boolean;
+    /** added after the visible label in the accessible name while busy, for
+     *  when the label doesn't say so itself (e.g. 'Save' → 'Save Saving') */
+    busyLabel?: string;
+    disabled?: boolean;
+    /** renders an <a> that looks like this button; @busy does not apply */
+    href?: string;
+    /** corner treatment; 'rounded' (default) is the theme's --radius less 2px */
+    shape?: ButtonShape;
+    /** alias of @disabled */
+    isDisabled?: boolean;
+    /** aliases of @busy */
+    loading?: boolean;
+    isLoading?: boolean;
+    isPending?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLButtonElement | HTMLAnchorElement;
+}
+
+// The alias resolution, shared with the components that wrap Button and
+// need the same answer before they hand the arguments on.
+export function resolveBusy(args: ButtonSignature['Args']): boolean {
+  return (
+    firstDefined(args.busy, args.loading, args.isLoading, args.isPending) ??
+    false
+  );
+}
+export function resolveDisabled(args: ButtonSignature['Args']): boolean {
+  return firstDefined(args.disabled, args.isDisabled) ?? false;
+}
+
+export class Button extends Component<ButtonSignature> {
+  private get axes(): [PretuiTone, PretuiAppearance] {
+    return VARIANT_AXES[this.args.variant ?? 'primary'] ?? DEFAULT_AXES;
+  }
+  get tone(): PretuiTone {
+    return resolveTone(this.args.tone, PRETUI_TONES, this.axes[0]);
+  }
+  get appearance(): PretuiAppearance {
+    let appearance = this.args.appearance;
+    return appearance &&
+      (PRETUI_APPEARANCES as readonly string[]).includes(appearance)
+      ? appearance
+      : this.axes[1];
+  }
+  get size(): PretuiSize {
+    return resolveSize(this.args.size);
+  }
+  get shape(): ButtonShape {
+    let shape = this.args.shape;
+    return shape && (BUTTON_SHAPES as readonly string[]).includes(shape)
+      ? shape
+      : 'rounded';
+  }
+  get busy() {
+    return resolveBusy(this.args);
+  }
+  get disabled() {
+    return resolveDisabled(this.args);
+  }
+  // Busy keeps the button focusable (aria-disabled, not native disabled), so
+  // activation is blocked here instead. Never both attributes at once.
+  get ariaDisabled() {
+    return this.busy && !this.disabled ? 'true' : undefined;
+  }
+  // Capture phase on the element itself runs before the caller's own click
+  // listeners, and preventDefault stops a type='submit' from submitting.
+  blockWhileBusy = (event: Event) => {
+    if (this.ariaDisabled) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }
+  };
+  // An <a> has no disabled state: a disabled link loses its href (so it no
+  // longer navigates) and swallows clicks the same way.
+  blockWhileDisabled = (event: Event) => {
+    if (this.disabled) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }
+  };
+  <template>
+    {{#if @href}}
+      <a
+        class='pretui-btn'
+        href={{unless this.disabled @href}}
+        role={{if this.disabled 'link'}}
+        aria-disabled={{if this.disabled 'true'}}
+        data-tone={{this.tone}}
+        data-appearance={{this.appearance}}
+        data-size={{this.size}}
+        data-shape={{this.shape}}
+        {{on 'click' this.blockWhileDisabled capture=true}}
+        data-test-pretui-button
+        ...attributes
+      ><span class='pretui-btn-label'>{{yield}}</span></a>
+    {{else}}
+      <button
+        type='button'
+        class='pretui-btn'
+        data-tone={{this.tone}}
+        data-appearance={{this.appearance}}
+        data-size={{this.size}}
+        data-state={{if this.busy 'busy'}}
+        data-shape={{this.shape}}
+        disabled={{this.disabled}}
+        aria-disabled={{this.ariaDisabled}}
+        aria-busy={{if this.busy 'true'}}
+        {{on 'click' this.blockWhileBusy capture=true}}
+        data-test-pretui-button
+        ...attributes
+      >
+        <span class='pretui-btn-label'>{{yield}}</span>
+        {{! after the label, so the accessible name starts with the visible
+            label (WCAG 2.5.3); CSS order puts the spinner first visually }}
+        <span class='pretui-btn-busy' {{fitBusyContent this.busy @busyLabel}}>
+          {{#if this.busy}}<span
+              class='pretui-spinner'
+              aria-hidden='true'
+              data-test-pretui-button-spinner
+            ></span>{{/if}}
+          {{! always rendered, so the busy text lands in an existing node }}
+          <span
+            class='pretui-btn-busy-text'
+            data-test-pretui-button-busy-label
+          >{{if this.busy @busyLabel}}</span>
+        </span>
+      </button>
+    {{/if}}
+    <style scoped>
+      /* layered, so a caller's plain CSS wins without fighting specificity */
+      @layer PretComponent {
+        /* Each appearance only sets --pretui-btn-surface/-text/-edge (plus
+           their -hover twins); the rules below are the only ones that paint.
+           One border carries the edge, so fill and edge change together. */
+        .pretui-btn {
+          /* hover tints: the tone's lightness pulled toward --foreground, so a
+             light tone (warning, a mint primary) still reads on a light card
+             and a dark one on a dark card; chroma is restored (the mix took
+             30% of it) so the tint keeps the tone's hue instead of graying */
+          --pretui-btn-tint: oklch(
+            from color-mix(in oklch, var(--pretui-tone) 70%, var(--foreground))
+              l calc(c / 0.7) h
+          );
+
+          --pretui-btn-surface: initial;
+          --pretui-btn-surface-hover: initial;
+          --pretui-btn-text: initial;
+          --pretui-btn-text-hover: initial;
+          --pretui-btn-edge: initial;
+          --pretui-btn-edge-hover: initial;
+          --pretui-btn-elevation: initial;
+
+          position: relative;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          gap: 0.48em;
+          min-height: var(--pretui-button-h, 2.24em);
+          min-width: var(--pretui-button-min-w, 0);
+          padding: 0.2em var(--pretui-button-px, 0.96em);
+          border: 1px solid var(--pretui-btn-edge, transparent);
+          /* a step below the theme's --radius, so a button nests inside a
+             card or dialog of that radius */
+          border-radius: var(--pretui-button-radius, calc(var(--radius) - 2px));
+          background: var(--pretui-btn-surface, transparent);
+          color: var(--pretui-btn-text, inherit);
+          box-shadow: var(--pretui-btn-elevation, none);
+          font-family: inherit;
+          font-size: var(--pretui-size-m, var(--text-ui-md, 0.78rem));
+          font-weight: 500;
+          letter-spacing: var(--track-ui, 0.01em);
+          cursor: pointer;
+          white-space: nowrap;
+          transition:
+            background var(--pretui-dur-snap, 180ms)
+              var(--pretui-ease-snap, ease),
+            border-color var(--pretui-dur-snap, 180ms)
+              var(--pretui-ease-snap, ease),
+            color var(--pretui-dur-snap, 180ms) var(--pretui-ease-snap, ease),
+            transform 80ms ease;
+        }
+        @media (hover: hover) {
+          .pretui-btn:hover:not(:disabled, [aria-disabled='true']) {
+            background: var(
+              --pretui-btn-surface-hover,
+              var(--pretui-btn-surface, transparent)
+            );
+            border-color: var(
+              --pretui-btn-edge-hover,
+              var(--pretui-btn-edge, transparent)
+            );
+            color: var(
+              --pretui-btn-text-hover,
+              var(--pretui-btn-text, inherit)
+            );
+          }
+        }
+        .pretui-btn:active:not(:disabled, [aria-disabled='true']) {
+          transform: translateY(0.5px);
+        }
+        .pretui-btn:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 2px;
+        }
+        .pretui-btn:disabled,
+        a.pretui-btn[aria-disabled='true'] {
+          opacity: 0.45;
+          cursor: default;
+        }
+        a.pretui-btn {
+          text-decoration: none;
+        }
+        .pretui-btn[data-shape='pill'] {
+          border-radius: var(
+            --pretui-button-radius,
+            var(--boxel-border-radius-pill)
+          );
+        }
+        .pretui-btn[data-shape='square'] {
+          border-radius: var(--pretui-button-radius, 0);
+        }
+        /* size scale — font-size only; internals ride the em */
+        .pretui-btn[data-size='xs'] {
+          font-size: var(--pretui-size-xs, var(--text-ui-xs, 0.66rem));
+          /* keeps the 24px minimum target when the theme's xs step is small */
+          min-height: max(var(--pretui-button-h, 2.24em), 1.5rem);
+        }
+        .pretui-btn[data-size='s'] {
+          font-size: var(--pretui-size-s, var(--text-ui-sm, 0.72rem));
+        }
+        .pretui-btn[data-size='m'] {
+          font-size: var(--pretui-size-m, var(--text-ui-md, 0.78rem));
+        }
+        .pretui-btn[data-size='l'] {
+          font-size: var(--pretui-size-l, var(--text-ui-lg, 0.875rem));
+        }
+        .pretui-btn[data-size='xl'] {
+          font-size: var(--pretui-size-xl, var(--text-ui-xl, 1rem));
+        }
+        /* tone map — each tone only sets custom properties */
+        .pretui-btn[data-tone='neutral'] {
+          --pretui-tone-ink: var(--foreground);
+          --pretui-tone: 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)
+          );
+          /* the accent fill IS --foreground, so mixing it in changes nothing */
+          --pretui-btn-accent-hover: color-mix(
+            in oklch,
+            var(--pretui-tone-on) 30%,
+            var(--pretui-button-bg, var(--pretui-tone))
+          );
+        }
+        .pretui-btn[data-tone='primary'] {
+          --pretui-tone-ink: var(--primary-ink);
+          --pretui-tone: var(--primary);
+          --pretui-tone-on: var(--primary-foreground);
+        }
+        .pretui-btn[data-tone='info'] {
+          --pretui-tone-ink: var(--info-ink);
+          --pretui-tone: var(--info);
+          --pretui-tone-on: var(--info-foreground);
+        }
+        .pretui-btn[data-tone='success'] {
+          --pretui-tone-ink: var(--success-ink);
+          --pretui-tone: var(--success);
+          --pretui-tone-on: var(--success-foreground);
+        }
+        .pretui-btn[data-tone='warning'] {
+          --pretui-tone-ink: var(--warning-ink);
+          --pretui-tone: var(--warning);
+          --pretui-tone-on: var(--warning-foreground);
+        }
+        .pretui-btn[data-tone='danger'] {
+          --pretui-tone-ink: var(--destructive-ink);
+          --pretui-tone: var(--destructive);
+          --pretui-tone-on: var(--destructive-foreground);
+        }
+        .pretui-btn[data-tone='attention'] {
+          --pretui-tone-ink: var(--attention-ink);
+          --pretui-tone: var(--attention);
+          --pretui-tone-on: var(--attention-foreground);
+        }
+        /* appearance recipes — written once, read the tone vars */
+        .pretui-btn[data-appearance='accent'] {
+          --pretui-btn-surface: var(--pretui-button-bg, var(--pretui-tone));
+          /* a shade darker in both schemes; a mix toward --foreground would
+             lighten the fill in dark mode instead */
+          --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-btn[data-appearance='filled'] {
+          --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-btn[data-appearance='outlined'] {
+          --pretui-btn-surface: var(--pretui-button-secondary-bg, transparent);
+          --pretui-btn-edge: var(
+            --pretui-btn-hairline,
+            color-mix(in oklch, var(--pretui-tone) 45%, var(--border))
+          );
+          /* hover answers on the edge, not the fill: the hairline pulls
+             toward --foreground, so it strengthens in both schemes */
+          --pretui-btn-edge-hover: color-mix(
+            in oklch,
+            var(--foreground) 30%,
+            var(--pretui-btn-edge)
+          );
+          --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-btn[data-appearance='filled-outlined'] {
+          --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-btn[data-appearance='plain'] {
+          --pretui-btn-surface-hover: color-mix(
+            in oklch,
+            var(--pretui-btn-tint) 18%,
+            transparent
+          );
+          --pretui-btn-text: var(
+            --pretui-btn-ink-quiet,
+            color-mix(in oklch, var(--pretui-tone) 40%, var(--foreground))
+          );
+          --pretui-btn-text-hover: var(
+            --pretui-btn-ink,
+            color-mix(in oklch, var(--pretui-tone) 30%, var(--foreground))
+          );
+        }
+        /* a standalone text action: the tone's ink, no fill or edge, flush
+           with surrounding text (inline padding 0) but still a full-height
+           target; the underline marks hover and keyboard focus */
+        .pretui-btn[data-appearance='link'] {
+          --pretui-btn-text: var(--pretui-button-fg, var(--pretui-tone-ink));
+          padding-inline: 0;
+          text-underline-offset: 0.2em;
+        }
+        .pretui-btn[data-appearance='link']:focus-visible {
+          text-decoration-line: underline;
+        }
+        @media (hover: hover) {
+          .pretui-btn[data-appearance='link']:hover:not(
+              :disabled,
+              [aria-disabled='true']
+            ) {
+            text-decoration-line: underline;
+          }
+        }
+        .pretui-btn[data-state='busy'] {
+          cursor: progress;
+        }
+        /* Busy: the label keeps its box (and its place in the accessible
+           name) and the busy layer sits on top of it, so the width never
+           changes. fitBusyContent picks what the layer shows. */
+        .pretui-btn[data-state='busy'] .pretui-btn-label {
+          opacity: 0;
+        }
+        .pretui-btn-busy {
+          position: absolute;
+          inset: 0;
+          display: none;
+          align-items: center;
+          justify-content: center;
+          gap: 0.48em;
+          pointer-events: none;
+        }
+        .pretui-btn[data-state='busy'] .pretui-btn-busy {
+          display: flex;
+        }
+        /* room for the spinner beside the label: both in the row */
+        .pretui-btn[data-busy-layout='inline'] .pretui-btn-busy {
+          position: static;
+          order: -1;
+        }
+        .pretui-btn[data-busy-layout='inline'] .pretui-btn-label {
+          opacity: 0.6;
+        }
+        .pretui-btn-busy-text {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        /* room for the spinner and @busyLabel: show the busy label */
+        .pretui-btn[data-busy-layout='text'] .pretui-btn-busy-text {
+          position: static;
+          width: auto;
+          height: auto;
+          overflow: visible;
+          clip-path: none;
+        }
+        @keyframes pretui-spin {
+          to {
+            transform: rotate(360deg);
+          }
+        }
+        .pretui-spinner {
+          width: 1.04em;
+          height: 1.04em;
+          border-radius: 50%;
+          border: 1.5px solid color-mix(in oklch, currentColor 25%, transparent);
+          border-top-color: currentColor;
+          animation: pretui-spin 0.7s linear infinite;
+          flex: none;
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-spinner {
+            animation-duration: 1.6s;
+          }
+          .pretui-btn:active:not(:disabled, [aria-disabled='true']) {
+            transform: none;
+          }
+        }
+        /* forced colors drop backgrounds and shadows; the border above stays,
+           and disabled needs a cue beyond opacity */
+        @media (forced-colors: active) {
+          .pretui-btn:disabled,
+          .pretui-btn[aria-disabled='true'] {
+            color: GrayText;
+            border-color: GrayText;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,81 @@
+## What it is
+
+The kit's action primitive: a native `<button>` with a two-axis treatment system and a built-in busy state. Everything that performs an action is this, or wraps it: **IconButton** and **CopyButton** render a Button, and **ButtonGroup** arranges them. If the thing navigates rather than acts, pass `@href`: the Button renders a real `<a>` with the same treatment, because a `<button>` that only changes the URL lies to assistive tech. If you need a set of mutually exclusive choices styled as buttons, that is **SegmentedControl** (a selection, not an action).
+
+## The contract
+
+```
+@tone?      'neutral' | 'primary' | 'info' | 'success' | 'warning' | 'danger' | 'attention'
+@appearance? 'accent' | 'filled' | 'outlined' | 'filled-outlined' | 'plain' | 'link'
+@href?      renders an <a> instead of a <button>; @busy does not apply
+@size?      'xs' | 's' | 'm' | 'l' | 'xl'   (default 'm')
+@busy?, @disabled?
+@shape?     'rounded' | 'pill' | 'square'   (default 'rounded': the theme's --radius less 2px)
+@variant?   single-axis alias resolved onto @tone × @appearance:
+            primary|secondary|ghost|destructive|default|outline|outlined|subtle|filled|link
+```
+
+**Two axes, not a variant enum.** This is the kit's central control decision. `@tone` picks the hue and sets exactly two custom properties (`--pretui-tone`, `--pretui-tone-on`); `@appearance` picks the recipe and _reads_ those properties. Seven tones × five appearances is thirty-five looks from twelve CSS rules, and adding a tone is a two-line block. `@variant` is a lookup table into the same grid (`destructive` → `['danger','accent']`) — the single-axis spelling boxel-ui (`kind`) and shadcn callers pass.
+
+**`@size` sets host `font-size` only.** Minimum height (`2.24em`, floored at 24px for `xs`), padding (`0.96em`), gap, spinner and radius are all `em`, so the whole control scales from one number and `m` stays pixel-identical to the pre-scale cut (2.24 × 12.5px = 28px). No per-size rule duplication, and a theme can retune the scale by redefining `--pretui-size-*`.
+
+**`@busy` blocks activation but keeps focus.** It sets `aria-disabled` rather than native `disabled`, swallows clicks (and so form submission) in a capture-phase listener, and never changes the button's width: the label fades out but keeps its space, and a busy layer on top shows the spinner with `@busyLabel` when both fit, otherwise the spinner beside the dimmed label when the button has room (a stretched or `min-width` button), otherwise the spinner alone. `@busyLabel` is always in the accessible name while busy, visible or not. One arg, not three.
+
+## Prior art
+
+**Web Awesome `wa-button`** has `variant` (neutral/brand/success/warning/danger) × `appearance` (accent/filled/outlined/plain) plus `size`, `pill`, `loading`, `caret`, `href` — Pretui's grid is directly descended from it, with `info`/`attention` added and a `filled-outlined` fifth recipe. **shadcn** ships a `cva` variant map (`default/destructive/outline/secondary/ghost/link` × `default/sm/lg/icon`) — a flat cross-product that grows multiplicatively. **React Spectrum** has `variant` × `style` (`fill`/`outline`) and `staticColor`, plus `isPending` with an announced loading state.
+
+Where Pretui improves:
+
+- **Tone is a token indirection, not a colour.** Because tones only write `--pretui-tone`/`--pretui-tone-on`, an appearance recipe is written once and works for every current _and future_ tone. shadcn's `cva` map has to enumerate each combination.
+- **`color-mix` hover derivation.** Hover is `color-mix(in oklch, --foreground 10%, <bg>)` rather than a second hard-coded color per variant, so a theme that changes `--primary` gets a correct hover for free.
+- **Uniform `em` sizing** (above) — Web Awesome and shadcn both restate padding/height per size.
+- Per-instance escapes (`--pretui-button-h`, `--pretui-button-min-w`, `--pretui-button-px`, `--pretui-button-radius`, `--pretui-button-bg`, `--pretui-button-fg`) are custom properties, so a call site can deviate without `:deep()`.
+
+Deliberately absent versus the field: no `caret`, no icon slots — icons are just children, and no `as`/`asChild` polymorphism (`@href` is the one alternate element). Links inside running text belong to a separate text-link component, not to `@appearance='link'`, which is for standalone actions.
+
+## Accessibility
+
+No APG pattern is required: this is a native `<button>`, or with `@href` a native `<a>`, which is the whole point. `type='button'` is set _before_ `...attributes`, so a call site can still pass `type="submit"` and win.
+
+**Links.** `@href` renders `<a href>`, so middle-click, open-in-new-tab and the link role all work. `target`, `rel` and `download` pass through `...attributes`; pair `target='_blank'` with `rel='noopener noreferrer'`. A disabled link drops its `href`, takes `role="link"` with `aria-disabled="true"` so the state is still announced, and swallows clicks. Inside a card, a plain `href` is a full browser navigation: the host does not intercept it. To open a card in the stack, call `@context.actions.viewCard` (or the card's `viewCard`) from a click handler instead, or `preventDefault` in one if the element must stay a link.
+
+**`@appearance='link'`** is underlined on hover and on keyboard focus only, which suits standalone actions. It is not a substitute for an underlined link inside a paragraph (WCAG 1.4.1 needs a cue besides color there).
+
+Gaps worth knowing:
+
+- **`@busy` keeps the button in the tab order**: `aria-disabled="true"`, never together with native `disabled`, the same choice as Spectrum's `isPending`. `@disabled` still uses native `disabled`; with both set, native wins.
+- **The busy state reaches the accessible name only through the label.** Busy sets `aria-busy="true"`, which screen readers largely ignore on buttons, so a busy button should either say so visibly ("Saving…") or pass `@busyLabel`, which shows beside the spinner when it fits and is visually hidden otherwise. There is no default, because a label that already says it is busy would be announced twice ("Saving Loading"). The text node is always rendered and only filled while busy. Screen readers differ on whether they announce a name change on the focused control, so this still needs a pass with NVDA and VoiceOver.
+- The spinner is `aria-hidden="true"` and slows down under `prefers-reduced-motion`, which also drops the press nudge.
+- **Focus-visible paints its own ring**: `outline: 2px solid var(--ring)` with a 2px offset. How visible it is depends on the theme's `--ring` against the surface.
+- **Forced colors**: every appearance keeps a 1px border (transparent until forced colors paints it), and disabled switches to `GrayText`.
+- Disabled uses `opacity: 0.45`, which will fail contrast for label text in most themes. That is conventional, and conventionally wrong.
+- Icon-only usage must go through **IconButton**, which requires `@label` and applies it as `aria-label` _and_ `title`. A bare `<Button>` with only an icon child has no accessible name and nothing warns you.
+
+## Theming
+
+Tone tokens, all from the Boxel theme contract: `--primary`, `--destructive`, `--info`, `--success`, `--warning` and `--attention`, each with its `-foreground` pair, plus `--foreground`/`--background` for the neutral tone. Recipe tokens: `--background`, `--foreground`, `--border`, `--muted-foreground`, `--shadow-2xs`. Each appearance only sets `--pretui-btn-surface`, `--pretui-btn-text` and `--pretui-btn-edge` (plus `-hover` twins); one border carries the edge, so fill and edge move together on hover. Metrics: `--radius` (the `rounded` shape uses `calc(var(--radius) - 2px)`, so a button nests inside a card or dialog of the same radius; `pill` uses `--boxel-border-radius-pill`, `square` is 0, and `--pretui-button-radius` overrides any shape per instance), `--track-ui`, `--text-ui-xs|sm|md|lg|xl` under the `--pretui-size-xs|s|m|l|xl` override knobs, `--pretui-dur-snap`, `--pretui-ease-snap`.
+
+The `accent` recipe paints the tone as the background and its `-foreground` as the text, so a theme that changes `--warning` should change `--warning-foreground` with it. `theme.css` defaults every pair, so a theme that sets neither still renders a readable button.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+Button already accepts `@variant` as sugar. Agents will still emit the
+shadcn CVA names and Aria pending flags.
+
+| React agent                                                     | Pretui                                                        |
+| --------------------------------------------------------------- | ------------------------------------------------------------- |
+| `variant=default\|destructive\|outline\|secondary\|ghost\|link` | @variant sugar → tone×appearance (have)                       |
+| `size=sm\|default\|lg\|icon\|icon-sm`                           | `s`/`m`/`l` + **IconButton** for icon sizes                   |
+| `isDisabled` / `disabled`                                       | @disabled — accept both                                       |
+| `isPending` / `loading` / `isLoading`                           | @busy — prefer Aria pending (keep focus) over native disabled |
+| `asChild` / `<a>` / `href`                                      | `@href` renders a real `<a>` — do not port Slot               |
+| `variant=link`                                                  | `@variant='link'` → primary × `link`; add `@href` to navigate |
+| `rounded-full` / `shape`                                        | `@shape='pill'` (`'rounded'` default, `'square'`)             |
+| `type=submit`                                                   | ...attributes, already wins                                   |
+
+- [x] Accept `sm`/`md`/`lg` as `@size` aliases.
+- [x] Accept `isDisabled` / `isPending` / `loading`.
+- [x] Move `@busy` from `disabled` to `aria-disabled` so focus is retained (`aria-busy` is already set).