@cosxai/ui 1.0.0-alpha.0 → 1.0.0-alpha.2

package/src/components/AsyncSelect.tsx

@@ -0,0 +1,205 @@
+import * as Popover from '@radix-ui/react-popover';
+import { Search, X } from 'lucide-react';
+import { useId, useRef, useState, type KeyboardEvent } from 'react';
+
+import { cn } from '../lib/cn';
+import { useField } from './Field';
+import { controlFrame, controlInner } from './forms-control';
+import { Avatar, DEFAULT_LABELS, ListboxBody, type ListboxLabels, type ListItem } from './inputs-listbox';
+import { useDebouncedSearch } from './inputs-search';
+import { Spinner } from './Spinner';
+
+export type AsyncSelectProps = {
+  /** Look up matches; the signal aborts when newer input arrives. */
+  search: (query: string, signal: AbortSignal) => Promise<ListItem[]>;
+  value?: ListItem | null | undefined;
+  onChange?: ((item: ListItem | null) => void) | undefined;
+  /** Offer “Create …” for text that matches nothing exactly. */
+  onCreate?: ((query: string) => void | ListItem | Promise<ListItem | void>) | undefined;
+  /** @default "Search" */
+  placeholder?: string | undefined;
+  /** ms. @default 250 */
+  debounce?: number | undefined;
+  labels?: Partial<ListboxLabels> & { clear?: string | undefined };
+  invalid?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Start with this search typed and its results open. */
+  defaultQuery?: string | undefined;
+  size?: 'sm' | 'md' | 'lg' | undefined;
+  id?: string | undefined;
+  'aria-label'?: string | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * AsyncSelect — choose one from a large or remote set (a customer, a
+ * project). Typing searches after a short pause and drops stale answers;
+ * a spinner shows until the answer comes, then results with their meta, a
+ * Create row, “nothing matches”, or an error with Retry. The choice
+ * becomes a card that clears with ×.
+ */
+export function AsyncSelect({
+  search,
+  value,
+  onChange,
+  onCreate,
+  placeholder = 'Search',
+  debounce = 250,
+  labels: labelsIn,
+  invalid,
+  disabled,
+  defaultQuery = '',
+  size,
+  id,
+  className,
+  ...aria
+}: AsyncSelectProps) {
+  const field = useField();
+  const auto = useId();
+  const listId = `as${auto}-list`;
+  const optionId = (i: number) => `as${auto}-o${i}`;
+  const labels = { ...DEFAULT_LABELS, ...labelsIn };
+  const [own, setOwn] = useState<ListItem | null>(null);
+  const chosen = value === undefined ? own : value;
+  const [query, setQuery] = useState(defaultQuery);
+  const [open, setOpen] = useState(defaultQuery !== '');
+  const [active, setActive] = useState(0);
+  const input = useRef<HTMLInputElement | null>(null);
+  const { status, result, retry } = useDebouncedSearch(query, search, { delay: debounce });
+  const items = status === 'done' ? (result ?? []) : [];
+  const q = query.trim();
+  const canCreate = Boolean(onCreate) && q.length > 0 && !items.some((i) => i.label.toLowerCase() === q.toLowerCase());
+  const count = items.length + (canCreate ? 1 : 0);
+  const bad = Boolean(invalid || field?.invalid);
+  const off = Boolean(disabled || field?.disabled);
+
+  const pick = (item: ListItem | null) => {
+    if (value === undefined) setOwn(item);
+    onChange?.(item);
+    setQuery('');
+    setOpen(false);
+  };
+  const choose = async (i: number) => {
+    if (i < items.length) return pick(items[i]!);
+    if (i === items.length && canCreate) {
+      const made = await onCreate!(q);
+      if (made && typeof made === 'object') pick(made);
+      else {
+        setQuery('');
+        setOpen(false);
+      }
+    }
+  };
+  const onKey = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setOpen(true);
+      setActive((a) => Math.min(count - 1, a + 1));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setActive((a) => Math.max(0, a - 1));
+    } else if (e.key === 'Enter' && open && count > 0) {
+      e.preventDefault();
+      void choose(active);
+    } else if (e.key === 'Escape') {
+      setOpen(false);
+    }
+  };
+
+  if (chosen) {
+    return (
+      <div
+        className={cn(
+          'flex min-h-[38px] items-center gap-2.5 rounded-md border bg-sunk px-2 py-1.5 font-sans text-ui text-fg',
+          bad ? 'border-error' : 'border-rule-soft',
+          off && 'bg-well text-fg-secondary',
+          className,
+        )}
+      >
+        <Avatar item={chosen} className="size-8 rounded-sm bg-ink text-linen ink:bg-yellow-accent ink:text-ink" />
+        <span className="flex min-w-0 flex-1 flex-col">
+          <span id={id ?? field?.id} className="truncate font-medium">
+            {chosen.label}
+          </span>
+          {chosen.meta && <span className="truncate text-meta text-fg-secondary">{chosen.meta}</span>}
+        </span>
+        {!off && (
+          <button
+            type="button"
+            aria-label={`${labelsIn?.clear ?? 'Clear'} ${chosen.label}`}
+            onClick={() => {
+              pick(null);
+              requestAnimationFrame(() => input.current?.focus());
+            }}
+            className="inline-grid shrink-0 cursor-pointer place-items-center rounded-xs p-0.5 text-fg-secondary outline-none hover:text-fg focus-visible:shadow-(--focus-ring)"
+          >
+            <X size={13} aria-hidden />
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  const showList = open && q.length > 0;
+  return (
+    <Popover.Root open={showList} onOpenChange={setOpen}>
+      <Popover.Anchor asChild>
+        <div className={cn(controlFrame({ size, invalid: bad, disabled: off }), className)}>
+          <Search size={14} aria-hidden className="shrink-0 text-fg-secondary" />
+          <input
+            ref={input}
+            id={id ?? field?.id}
+            role="combobox"
+            aria-expanded={showList}
+            aria-controls={showList ? listId : undefined}
+            aria-autocomplete="list"
+            aria-activedescendant={showList && status === 'done' && count > 0 ? optionId(active) : undefined}
+            aria-invalid={bad || undefined}
+            aria-describedby={field?.describedBy}
+            aria-label={aria['aria-label']}
+            disabled={off}
+            value={query}
+            placeholder={placeholder}
+            autoComplete="off"
+            onChange={(e) => {
+              setQuery(e.target.value);
+              setActive(0);
+              setOpen(true);
+            }}
+            onFocus={() => q && setOpen(true)}
+            onKeyDown={onKey}
+            className={controlInner}
+          />
+          {status === 'searching' && <Spinner size={12} className="text-fg-secondary" />}
+        </div>
+      </Popover.Anchor>
+      <Popover.Portal>
+        <Popover.Content
+          align="start"
+          sideOffset={6}
+          collisionPadding={12}
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          onInteractOutside={(e) => {
+            if (e.target instanceof Node && input.current?.parentElement?.contains(e.target)) e.preventDefault();
+          }}
+          className="rise z-60 rounded-lg border border-rule bg-page p-1 font-sans [--motion-reveal:200ms]"
+          style={{ width: 'var(--radix-popover-trigger-width)' }}
+        >
+          <ListboxBody
+            id={listId}
+            optionId={optionId}
+            items={items}
+            active={active}
+            status={status}
+            query={q}
+            canCreate={canCreate}
+            labels={labels}
+            onActive={setActive}
+            onChoose={(i) => void choose(i)}
+            onRetry={retry}
+          />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}

package/src/components/Badge.tsx

@@ -0,0 +1,68 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type BadgeStatus = 'neutral' | 'attention' | 'error' | 'progress' | 'complete';
+export type BadgeAppearance = 'fill' | 'outline' | 'dot';
+
+const DEFAULT_APPEARANCE: Record<BadgeStatus, BadgeAppearance> = {
+  attention: 'fill',
+  error: 'fill',
+  progress: 'outline',
+  complete: 'dot',
+  neutral: 'dot',
+};
+const STATUSES = new Set<string>(Object.keys(DEFAULT_APPEARANCE));
+
+export type BadgeProps = Omit<ComponentProps<'span'>, 'children'> & {
+  /** The state. Unknown values fall back to neutral. @default "neutral" */
+  status?: BadgeStatus | (string & {}) | undefined;
+  /** fill · outline · dot. Defaults by status; change it only to match density in a column. */
+  appearance?: BadgeAppearance | undefined;
+  /** Dot density for rows: only the dot shows; the wording stays for screen readers and appears on hover. */
+  compact?: boolean | undefined;
+  /** The wording — always present: name the state (Awaiting you), not the action. */
+  children: ReactNode;
+};
+
+/**
+ * Badge — product status in yellow, ink and one red. Shape carries urgency:
+ * a fill needs a person (attention: brand fill, ink text; error: the red),
+ * an outline is under way (progress), a dot is a known state (complete:
+ * ink dot, neutral: grey dot). Colour is never the only signal.
+ * Product UI only — never on brand, marketing or decks.
+ */
+export function Badge({ status = 'neutral', appearance, compact = false, className, children, title, ...rest }: BadgeProps) {
+  const s = (STATUSES.has(status) ? status : 'neutral') as BadgeStatus;
+  const mode = compact ? 'dot' : (appearance ?? DEFAULT_APPEARANCE[s]);
+  const base = 'inline-flex items-center gap-[7px] whitespace-nowrap rounded-sm text-meta leading-none font-semibold';
+
+  if (mode === 'fill') {
+    const fill = s === 'error' ? 'bg-error text-white' : s === 'attention' ? 'bg-brand-mark text-ink' : 'bg-fg text-page';
+    return (
+      <span data-status={s} className={cn(base, 'px-2 py-[5px]', fill, className)} title={title} {...rest}>
+        {children}
+      </span>
+    );
+  }
+  if (mode === 'outline') {
+    return (
+      <span data-status={s} className={cn(base, 'border border-fg px-[7px] py-1 text-fg', className)} title={title} {...rest}>
+        {children}
+      </span>
+    );
+  }
+  const dot =
+    s === 'error' ? 'bg-error' : s === 'attention' ? 'bg-brand-mark' : s === 'complete' || s === 'progress' ? 'bg-fg' : 'bg-fg-secondary';
+  return (
+    <span
+      data-status={s}
+      className={cn(base, 'text-fg-secondary', className)}
+      title={compact ? (title ?? (typeof children === 'string' ? children : undefined)) : title}
+      {...rest}
+    >
+      <span aria-hidden className={cn('size-[9px] shrink-0 rounded-pill', dot)} />
+      <span className={compact ? 'sr-only' : undefined}>{children}</span>
+    </span>
+  );
+}

package/src/components/Breadcrumb.tsx

@@ -0,0 +1,129 @@
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type BreadcrumbItem = {
+  label: ReactNode;
+  /** A link; or use onSelect for in-app navigation. */
+  href?: string | undefined;
+  onSelect?: (() => void) | undefined;
+  /** A trailing tag on the current page: its format (PDF). */
+  tag?: ReactNode;
+};
+
+export type BreadcrumbProps = Omit<ComponentProps<'nav'>, 'children'> & {
+  items: BreadcrumbItem[];
+  /** What starts the trail — the workspace brand (on a customer domain it replaces the platform name). */
+  root?: ReactNode;
+  /** Beyond this many segments the middle folds into a menu. @default 4 */
+  max?: number | undefined;
+  /** @default "Breadcrumb" */
+  label?: string | undefined;
+  /** Accessible name of the fold button. @default "Show hidden folders" */
+  foldLabel?: string | undefined;
+  /** A line under the trail: the current item's status. */
+  status?: ReactNode;
+};
+
+const linkClass = 'cursor-pointer text-fg-secondary outline-none hover:text-fg hover:underline underline-offset-2 focus-visible:shadow-(--focus-ring) rounded-xs';
+
+function Crumb({ item }: { item: BreadcrumbItem }) {
+  if (item.href)
+    return (
+      <a href={item.href} onClick={item.onSelect} className={linkClass}>
+        {item.label}
+      </a>
+    );
+  if (item.onSelect)
+    return (
+      <button type="button" onClick={item.onSelect} className={linkClass}>
+        {item.label}
+      </button>
+    );
+  return <span className="text-fg-secondary">{item.label}</span>;
+}
+
+const Sep = () => (
+  <span aria-hidden className="text-fg-secondary">
+    /
+  </span>
+);
+
+/**
+ * Breadcrumb — where this page sits. The current page is the last segment
+ * and not a link; beyond four segments the middle folds into a menu. On a
+ * customer domain the trail starts at the workspace brand (root).
+ */
+export function Breadcrumb({ items, root, max = 4, label = 'Breadcrumb', foldLabel = 'Show hidden folders', status, className, ...rest }: BreadcrumbProps) {
+  const last = items[items.length - 1];
+  const before = items.slice(0, -1);
+  const total = items.length + (root ? 1 : 0);
+  const fold = total > max && before.length > 1;
+  // Folded: [root or the first ancestor] / … / parent / current.
+  const head = fold ? (root ? [] : before.slice(0, 1)) : before;
+  const folded = fold ? before.slice(root ? 0 : 1, -1) : [];
+  const tail = fold ? before.slice(-1) : [];
+  const segment = 'flex items-center gap-2';
+
+  return (
+    <nav aria-label={label} className={cn('flex flex-col gap-1.5', className)} {...rest}>
+      <ol className="m-0 flex list-none flex-wrap items-center gap-x-2 gap-y-1 p-0 text-ui">
+        {root && (
+          <li className={segment}>
+            {root}
+            {items.length > 0 && <Sep />}
+          </li>
+        )}
+        {head.map((it, i) => (
+          <li key={`h${i}`} className={segment}>
+            <Crumb item={it} />
+            <Sep />
+          </li>
+        ))}
+        {folded.length > 0 && (
+          <li className={segment}>
+            <DropdownMenu.Root>
+              <DropdownMenu.Trigger
+                aria-label={foldLabel}
+                className="inline-grid h-6 min-w-6 cursor-pointer place-items-center rounded-sm bg-sunk px-1.5 text-meta font-semibold text-fg outline-none hover:bg-well focus-visible:shadow-(--focus-ring)"
+              >
+                …
+              </DropdownMenu.Trigger>
+              <DropdownMenu.Portal>
+                <DropdownMenu.Content align="start" sideOffset={6} className="z-50 min-w-[180px] rounded-lg border border-rule bg-page p-1.5 text-ui text-fg">
+                  {folded.map((it, i) => (
+                    <DropdownMenu.Item
+                      key={i}
+                      onSelect={() => {
+                        if (it.href) window.location.assign(it.href);
+                        else it.onSelect?.();
+                      }}
+                      className="flex h-8 cursor-pointer items-center rounded-md px-2.5 outline-none data-[highlighted]:bg-hover"
+                    >
+                      {it.label}
+                    </DropdownMenu.Item>
+                  ))}
+                </DropdownMenu.Content>
+              </DropdownMenu.Portal>
+            </DropdownMenu.Root>
+            <Sep />
+          </li>
+        )}
+        {tail.map((it, i) => (
+          <li key={`t${i}`} className={segment}>
+            <Crumb item={it} />
+            <Sep />
+          </li>
+        ))}
+        {last && (
+          <li aria-current="page" className="flex items-center gap-2 font-medium text-fg">
+            {last.label}
+            {last.tag && <span className="rounded-sm bg-sunk px-1.5 py-0.5 text-[11px] font-semibold text-fg">{last.tag}</span>}
+          </li>
+        )}
+      </ol>
+      {status && <div className="text-meta text-fg-secondary">{status}</div>}
+    </nav>
+  );
+}

package/src/components/Button.tsx

@@ -0,0 +1,193 @@
+import { Slot } from '@radix-ui/react-slot';
+import { cva } from 'class-variance-authority';
+import { Check } from 'lucide-react';
+import { useLayoutEffect, useRef, useState, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { Spinner } from './Spinner';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'yellow' | 'ink' | 'danger';
+export type ButtonGround = 'paper' | 'yellow' | 'ink';
+/** idle → busy (spinner, width locked, clicks ignored) → done (confirmed in place) → idle. */
+export type ButtonState = 'idle' | 'busy' | 'done';
+
+const button = cva(
+  [
+    'relative inline-flex items-center justify-center gap-2 whitespace-nowrap select-none',
+    'rounded-md border border-transparent font-sans font-semibold leading-none',
+    'transition-[background-color,border-color,color] duration-[120ms] ease-standard',
+    'cursor-pointer outline-none focus-visible:shadow-(--focus-ring)',
+    // Disabled sinks: the well with grey text (3.0 readme and design.cosx.co;
+    // the 3.0 Button source used opacity). "!" so hover never lifts it back.
+    'disabled:cursor-not-allowed aria-disabled:cursor-not-allowed',
+  ],
+  {
+    variants: {
+      size: {
+        sm: 'h-8 px-3.5 text-[13px]',
+        md: 'h-[38px] px-[18px] text-ui',
+        lg: 'h-11 px-6 text-[16px]',
+      },
+      variant: { primary: '', secondary: 'bg-transparent', ghost: 'bg-transparent', yellow: 'bg-yellow text-ink hover:bg-yellow-hover', ink: 'bg-ink text-linen hover:bg-ink-raised ink:border-inv-rule ink:bg-ink-raised ink:hover:border-linen', danger: 'bg-error text-white hover:bg-error-text' },
+      ground: { auto: '', paper: '', yellow: '', ink: '' },
+    },
+    compoundVariants: [
+      // Primary: ink on paper and on the yellow; the yellow on ink (and in ink mode).
+      { variant: 'primary', ground: 'auto', class: 'bg-ink text-linen hover:bg-ink-raised ink:bg-yellow-accent ink:text-ink ink:hover:bg-yellow-accent-hover' },
+      { variant: 'primary', ground: ['paper', 'yellow'], class: 'bg-ink text-linen hover:bg-ink-raised' },
+      { variant: 'primary', ground: 'ink', class: 'bg-yellow-accent text-ink hover:bg-yellow-accent-hover' },
+      // Secondary: a hairline that turns ink on hover.
+      { variant: 'secondary', ground: 'auto', class: 'text-fg border-[rgba(17,17,17,.18)] hover:border-fg ink:border-rule' },
+      { variant: 'secondary', ground: ['paper', 'yellow'], class: 'text-ink border-[rgba(17,17,17,.18)] hover:border-ink' },
+      { variant: 'secondary', ground: 'ink', class: 'text-linen border-inv-rule hover:border-linen' },
+      // Ghost (subtle): text only; hover deepens one step.
+      { variant: 'ghost', ground: 'auto', class: 'text-fg hover:bg-hover' },
+      { variant: 'ghost', ground: ['paper', 'yellow'], class: 'text-ink hover:bg-[rgba(17,17,17,.05)]' },
+      { variant: 'ghost', ground: 'ink', class: 'text-linen hover:bg-ink-raised' },
+      // Focus ring follows the ground.
+      { ground: 'yellow', class: 'focus-visible:shadow-[0_0_0_3px_var(--yellow),0_0_0_5px_var(--ink)]' },
+      { ground: 'ink', class: 'focus-visible:shadow-[0_0_0_3px_var(--ink),0_0_0_5px_var(--yellow)]' },
+      // Disabled: filled types sink into the well; outlined and text-only turn grey.
+      {
+        variant: ['primary', 'yellow', 'ink', 'danger'],
+        class:
+          'disabled:border-transparent! disabled:bg-well! disabled:text-fg-secondary! aria-disabled:border-transparent! aria-disabled:bg-well! aria-disabled:text-fg-secondary!',
+      },
+      {
+        variant: ['secondary', 'ghost'],
+        class:
+          'disabled:bg-transparent! disabled:text-fg-secondary! aria-disabled:bg-transparent! aria-disabled:text-fg-secondary! disabled:hover:border-[rgba(17,17,17,.18)] aria-disabled:hover:border-[rgba(17,17,17,.18)]',
+      },
+    ],
+    defaultVariants: { size: 'md', variant: 'primary', ground: 'auto' },
+  },
+);
+
+export type ButtonProps = Omit<ComponentProps<'button'>, 'disabled'> & {
+  /** primary (one per view) · secondary · ghost (subtle: cancel, secondary links) · yellow (inline attention) · ink · danger (destructive, inside a confirming dialog). @default "primary" */
+  variant?: ButtonVariant | undefined;
+  /** Height 32 · 38 · 44 (the product control heights). @default "md" */
+  size?: 'sm' | 'md' | 'lg' | undefined;
+  /** The surface underneath; sets the primary colour and the focus ring. Unset: paper, flipping to ink in ink mode. */
+  ground?: ButtonGround | undefined;
+  iconLeft?: ReactNode;
+  iconRight?: ReactNode;
+  /** Shortcut hint at the end of the button (⇧S, Esc). */
+  shortcut?: string | undefined;
+  /** A count at the end (Comments 12). Hidden at zero, 99+ above 99. */
+  count?: number | undefined;
+  /** Async state: busy locks the width and shows a spinner; done confirms in place. See useButtonAction. */
+  state?: ButtonState | undefined;
+  /** Label shown while state="done". @default the children */
+  doneLabel?: ReactNode;
+  disabled?: boolean | undefined;
+  /** Why it is unavailable. Keeps the button focusable (aria-disabled) so the reason can be read and shown. */
+  disabledReason?: string | undefined;
+  /** Render the child (a link) with the button's look. Async state is not applied. */
+  asChild?: boolean | undefined;
+};
+
+export function formatCount(n: number): string | null {
+  if (!n || n <= 0) return null;
+  return n > 99 ? '99+' : String(n);
+}
+
+/**
+ * Button — one button for every action. Contrast is ink's job: the primary
+ * is ink on paper and on the yellow, the yellow on ink. One primary per
+ * view. Async results stay in the button: busy (width locked, repeat clicks
+ * ignored), done (confirmed in place); a failure is explained beside it.
+ * Hover deepens one step — no lift, no scale, no shadow.
+ */
+export function Button({
+  variant,
+  size,
+  ground,
+  iconLeft,
+  iconRight,
+  shortcut,
+  count,
+  state = 'idle',
+  doneLabel,
+  disabled,
+  disabledReason,
+  asChild,
+  className,
+  children,
+  onClick,
+  style,
+  ref,
+  ...rest
+}: ButtonProps) {
+  const inner = useRef<HTMLButtonElement | null>(null);
+  const [lockedWidth, setLockedWidth] = useState<number | null>(null);
+
+  // Lock the idle width so busy / done never resize the button.
+  useLayoutEffect(() => {
+    if (state === 'idle') setLockedWidth(null);
+    else if (lockedWidth === null && inner.current) setLockedWidth(inner.current.getBoundingClientRect().width);
+  }, [state, lockedWidth]);
+
+  const classes = cn(button({ variant, size, ground: ground ?? 'auto' }), className);
+  if (asChild) {
+    return (
+      <Slot className={classes} {...(rest as object)}>
+        {children}
+      </Slot>
+    );
+  }
+
+  const busy = state === 'busy';
+  const blocked = Boolean(disabledReason) && disabled;
+  const shownCount = count === undefined ? null : formatCount(count);
+  const setRefs = (el: HTMLButtonElement | null) => {
+    inner.current = el;
+    if (typeof ref === 'function') ref(el);
+    else if (ref) ref.current = el;
+  };
+
+  return (
+    <button
+      type="button"
+      {...rest}
+      ref={setRefs}
+      className={classes}
+      style={lockedWidth ? { ...style, width: lockedWidth } : style}
+      disabled={disabled && !disabledReason ? true : undefined}
+      // Busy is not disabled (spec: "busy and disabled are different states"):
+      // it keeps its look; aria-busy says so and repeat clicks are ignored below.
+      aria-disabled={blocked ? true : undefined}
+      aria-busy={busy || undefined}
+      title={blocked ? disabledReason : rest.title}
+      onClick={(e) => {
+        if (blocked || busy || state === 'done') {
+          e.preventDefault();
+          return;
+        }
+        onClick?.(e);
+      }}
+    >
+      {busy ? (
+        <Spinner />
+      ) : state === 'done' ? (
+        <>
+          <Check size={14} strokeWidth={2} aria-hidden />
+          {doneLabel ?? children}
+        </>
+      ) : (
+        <>
+          {iconLeft}
+          {children}
+          {iconRight}
+          {shownCount && <span className="font-medium tabular-nums opacity-70">{shownCount}</span>}
+          {shortcut && (
+            <kbd className="ml-0.5 font-sans text-[12px] font-medium opacity-60" aria-hidden>
+              {shortcut}
+            </kbd>
+          )}
+        </>
+      )}
+      {busy && <span className="sr-only">{children}</span>}
+    </button>
+  );
+}

package/src/components/Card.tsx

@@ -0,0 +1,42 @@
+import { Slot } from '@radix-ui/react-slot';
+import { cva } from 'class-variance-authority';
+import type { ComponentProps } from 'react';
+
+import { cn } from '../lib/cn';
+
+const card = cva('overflow-hidden transition-[background-color,border-color] duration-[120ms] ease-standard', {
+  variants: {
+    ground: {
+      page: 'bg-page text-fg',
+      sunk: 'bg-sunk text-fg',
+      field: 'bg-brand-field text-ink',
+      ink: 'bg-ink text-linen ink:bg-ink-raised',
+    },
+    radius: { panel: 'rounded-lg', section: 'rounded-xl' },
+    outline: { true: 'border border-rule', false: '' },
+    interactive: { true: 'cursor-pointer outline-none hover:border-fg focus-visible:shadow-(--focus-ring)', false: '' },
+    accent: { true: 'border-t-4 border-t-yellow-accent', false: '' },
+  },
+  compoundVariants: [{ interactive: true, ground: 'page', class: 'hover:bg-hover' }],
+  defaultVariants: { ground: 'page', radius: 'panel', interactive: false, accent: false },
+});
+
+export type CardProps = ComponentProps<'div'> & {
+  /** page (paper) · sunk (linen) · field (the brand yellow) · ink. @default "page" */
+  ground?: 'page' | 'sunk' | 'field' | 'ink' | undefined;
+  /** panel 16px · section 24px (whole page-level sections). @default "panel" */
+  radius?: 'panel' | 'section' | undefined;
+  /** Hairline edge. Defaults to on for page, off for the other grounds. */
+  outline?: boolean | undefined;
+  /** Clickable card: hover wash + ink edge. Use asChild to make it the link or button. */
+  interactive?: boolean | undefined;
+  /** A 4px accent rule along the top. */
+  accent?: boolean | undefined;
+  asChild?: boolean | undefined;
+};
+
+/** Card — a rounded region of the page. No shadow: depth is cut into the page. */
+export function Card({ ground = 'page', radius, outline, interactive, accent, asChild, className, ...rest }: CardProps) {
+  const Comp = asChild ? Slot : 'div';
+  return <Comp className={cn(card({ ground, radius, outline: outline ?? ground === 'page', interactive, accent }), className)} {...rest} />;
+}