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

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 1.0.0-alpha.1 (2026-09-29)
+
+All 22 COSX Design System 3.0 primitives, checked against their
+design.cosx.co pages in light / ink × English / Chinese.
+
+- Core: Button (six types, grounds, 32/38/44, shortcut and count,
+  disabled-with-reason, busy/done in place + `useButtonAction`),
+  IconButton, Badge (shape carries urgency; compact dot keeps the
+  wording), Tag, Card, Figure, Marker, MetaLabel, Logo, Icon (Lucide),
+  Spinner, ThemeProvider (system / light / ink).
+- Forms: Field (label, hint, error, prefix/suffix, read-only), Input,
+  Textarea, Select (portal, auto placement, keyboard, groups, disabled
+  rows, meta, filter above 8), Checkbox (indeterminate), RadioGroup, Switch.
+- Tabs (underline, pills), Dialog, Toast (`toast()` + `<Toaster>`),
+  Tooltip, Table (sortable, washes for attention/overdue, cards on phones).
+- `--brand-field` / `--brand-mark` for workspace brands; the 3.0 ink
+  marker rule for `data-mode="ink"`; an `ink:` Tailwind variant.
+- 65 tests (behaviour + axe). Spec/source differences and what was
+  built: docs/workdocs/2026-09-29_feature-ui-1.0.
+
 ## 1.0.0-alpha.0 (2026-09-29)
 
 **A new system — breaking for every 0.x consumer.** 0.x continues on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.1",
   "description": "COSX Design System 3.0 — tokens, Tailwind v4 theme and React components",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,7 +31,8 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "check:css": "tailwindcss -i test/fixture.css -o test/out.css"
+    "check:css": "tailwindcss -i test/fixture.css -o test/out.css",
+    "playground": "vite --config playground/vite.config.ts"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -40,12 +41,23 @@
   },
   "devDependencies": {
     "@tailwindcss/cli": "^4",
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
     "@types/node": "^26.6.3",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "axe-core": "^4.13.0",
+    "jsdom": "^30.1.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tailwindcss": "^4",
     "typescript": "^5.6.0",
-    "vitest": "^3.2.0"
+    "vite": "^6.0.0",
+    "vitest": "^3.2.0",
+    "vitest-axe": "^0.1.0"
   },
   "sideEffects": [
     "**/*.css"
@@ -53,7 +65,19 @@
   "dependencies": {
     "@fontsource-variable/geist": "^5.3.0",
     "@fontsource-variable/noto-sans-sc": "^5.3.0",
+    "@radix-ui/react-checkbox": "^1.3.11",
+    "@radix-ui/react-dialog": "^1.1.23",
+    "@radix-ui/react-label": "^2.1.15",
+    "@radix-ui/react-popover": "^1.1.23",
+    "@radix-ui/react-radio-group": "^1.4.7",
+    "@radix-ui/react-slot": "^1.3.3",
+    "@radix-ui/react-switch": "^1.3.7",
+    "@radix-ui/react-tabs": "^1.1.21",
+    "@radix-ui/react-toast": "^1.2.23",
+    "@radix-ui/react-tooltip": "^1.2.16",
+    "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "lucide-react": "^1.48.0",
     "tailwind-merge": "^3.3.1"
   },
   "peerDependenciesMeta": {

package/src/brand.css

@@ -0,0 +1,13 @@
+/* @cosxai/ui — workspace brand injection (MetaRoom spec §01).
+ *
+ * A customer's colour replaces the COSX yellow through two variables;
+ * everything else stays ink, so any colour keeps text readable:
+ *   --brand-field  large areas: selected nav and tabs, section grounds
+ *   --brand-mark   small marks: dots, progress, highlights, attention fills
+ * Ink (text, primary button, icons) and --status-error are not injectable.
+ * Default: the COSX yellow. A workspace sets both on <html>.
+ */
+:root {
+  --brand-field: var(--yellow);
+  --brand-mark: var(--yellow-accent);
+}

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/Button.tsx

@@ -0,0 +1,178 @@
+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:cursor-not-allowed disabled:opacity-40 aria-disabled:cursor-not-allowed aria-disabled:opacity-40',
+  ],
+  {
+    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)]' },
+    ],
+    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}
+      aria-disabled={blocked || busy ? 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} />;
+}

package/src/components/Checkbox.tsx

@@ -0,0 +1,67 @@
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+import { Check, Minus } from 'lucide-react';
+import { useId, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type CheckboxProps = Omit<ComponentProps<typeof CheckboxPrimitive.Root>, 'checked' | 'onCheckedChange' | 'onChange' | 'children'> & {
+  /** true · false · "indeterminate" (some children selected). */
+  checked?: boolean | 'indeterminate' | undefined;
+  onChange?: ((checked: boolean) => void) | undefined;
+  /** The label; clicking it toggles too. */
+  label?: ReactNode;
+  /** A line below the label — say why when disabled. */
+  description?: ReactNode;
+  /** Class for the whole row (className goes to the box). */
+  rowClassName?: string | undefined;
+};
+
+/**
+ * Checkbox — a choice in a form that applies on Save or Send (a setting
+ * that applies at once is a Switch). Sunk box, ink when checked; the mixed
+ * state means some children are selected. The whole row toggles.
+ */
+export function Checkbox({ checked, onChange, label, description, disabled, id, className, rowClassName, ...rest }: CheckboxProps) {
+  const auto = useId();
+  const boxId = id ?? `cb${auto}`;
+  const descId = description ? `${boxId}-desc` : undefined;
+  const box = (
+    <CheckboxPrimitive.Root
+      id={boxId}
+      {...(checked !== undefined && { checked })}
+      onCheckedChange={(v) => onChange?.(v === true)}
+      disabled={disabled}
+      aria-describedby={descId}
+      className={cn(
+        'peer mt-0.5 grid size-4 shrink-0 cursor-pointer place-items-center rounded-xs border border-fg-secondary bg-sunk text-page',
+        'transition-[background-color,border-color] duration-[120ms] ease-standard outline-none focus-visible:shadow-(--focus-ring)',
+        'data-[state=checked]:border-fg data-[state=checked]:bg-fg data-[state=indeterminate]:border-fg data-[state=indeterminate]:bg-fg',
+        'disabled:cursor-not-allowed',
+        className,
+      )}
+      {...rest}
+    >
+      <CheckboxPrimitive.Indicator className="grid place-items-center">
+        {checked === 'indeterminate' ? <Minus size={11} strokeWidth={2.5} aria-hidden /> : <Check size={11} strokeWidth={2.5} aria-hidden />}
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+  if (!label && !description) return box;
+  return (
+    <div className={cn('inline-flex items-start gap-2.5 font-sans', disabled && 'opacity-40', rowClassName)}>
+      {box}
+      <span className="flex flex-col gap-0.5">
+        {label && (
+          <label htmlFor={boxId} className={cn('text-small leading-[1.45] text-fg', disabled ? 'cursor-not-allowed' : 'cursor-pointer')}>
+            {label}
+          </label>
+        )}
+        {description && (
+          <span id={descId} className="text-meta leading-normal text-fg-secondary">
+            {description}
+          </span>
+        )}
+      </span>
+    </div>
+  );
+}

package/src/components/Dialog.tsx

@@ -0,0 +1,111 @@
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { X } from 'lucide-react';
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { IconButton } from './IconButton';
+
+/** Dialog root: `open` / `onOpenChange` (or uncontrolled with DialogTrigger). */
+export const Dialog = DialogPrimitive.Root;
+/** The element that opens it (asChild onto a Button). Focus returns here on close. */
+export const DialogTrigger = DialogPrimitive.Trigger;
+/** Closes the dialog (asChild onto the Cancel button). */
+export const DialogClose = DialogPrimitive.Close;
+
+const WIDTH = { sm: 'sm:max-w-[400px]', md: 'sm:max-w-[520px]', lg: 'sm:max-w-[640px]' } as const;
+
+const MOBILE = {
+  // Confirmations stay centred.
+  center: 'max-sm:left-4 max-sm:right-4 max-sm:top-1/2 max-sm:-translate-y-1/2 max-sm:rounded-lg',
+  // Long forms push in full screen.
+  page: 'max-sm:inset-0 max-sm:max-h-none max-sm:rounded-none max-sm:border-0',
+  // Light choices become a bottom sheet.
+  sheet: 'max-sm:inset-x-0 max-sm:bottom-0 max-sm:rounded-t-lg max-sm:rounded-b-none max-sm:border-b-0',
+} as const;
+
+export type DialogContentProps = Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title'> & {
+  /** A question or an action: "Revoke this share?" — the primary repeats its verb. Labels the dialog. */
+  title: ReactNode;
+  /** A line above the title. */
+  eyebrow?: ReactNode;
+  /** The consequence, read out with the title ("Anna loses access now."). */
+  description?: ReactNode;
+  /** Actions, bottom right: secondary left, primary right. A destructive primary is Button variant="danger". */
+  footer?: ReactNode;
+  /** sm 400 (confirm) · md 520 (form, up to five fields) · lg 640. @default "md" */
+  size?: keyof typeof WIDTH | undefined;
+  /** How it shows on phones: center (confirmations) · page (long forms) · sheet (light choices). @default "center" */
+  mobile?: keyof typeof MOBILE | undefined;
+  /** Accessible name of the close button. @default "Close" */
+  closeLabel?: string | undefined;
+  hideClose?: boolean | undefined;
+};
+
+/**
+ * DialogContent — something that interrupts the task and needs an answer.
+ * Page colour lifted by the scrim; 16px corners; no shadow. Focus moves in,
+ * is trapped, and returns to the trigger; Esc closes only the top layer
+ * (Radix Dialog). Otherwise prefer a side panel, an inline expansion or a
+ * toast.
+ */
+export function DialogContent({
+  title,
+  eyebrow,
+  description,
+  footer,
+  size = 'md',
+  mobile = 'center',
+  closeLabel = 'Close',
+  hideClose = false,
+  className,
+  children,
+  onOpenAutoFocus,
+  ...rest
+}: DialogContentProps) {
+  return (
+    <DialogPrimitive.Portal>
+      <DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-scrim" />
+      <DialogPrimitive.Content
+        /* Radix links the Description itself; without one, opt out so no
+           dangling reference (and no warning) remains. */
+        {...(description ? {} : { 'aria-describedby': undefined })}
+        /* Focus the dialog itself on open (read out by its title), not the
+           close button: no ring before the person has done anything. Tab
+           then reaches the controls; focus stays trapped. */
+        onOpenAutoFocus={(e) => {
+          onOpenAutoFocus?.(e);
+          if (e.defaultPrevented) return;
+          e.preventDefault();
+          (e.currentTarget as HTMLElement | null)?.focus();
+        }}
+        className={cn(
+          'fixed top-1/2 left-1/2 z-50 flex max-h-[calc(100dvh-48px)] w-[calc(100%-48px)] -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden',
+          'rounded-lg border border-rule bg-page font-sans text-fg outline-none',
+          WIDTH[size],
+          MOBILE[mobile],
+          mobile !== 'center' && 'max-sm:translate-x-0 max-sm:translate-y-0 max-sm:w-auto max-sm:top-auto max-sm:left-0',
+          mobile === 'page' && 'max-sm:top-0',
+          className,
+        )}
+        {...rest}
+      >
+        <div className="flex items-start gap-4 px-7 pt-6">
+          <div className="min-w-0 flex-1">
+            {eyebrow && <div className="mb-2.5 text-meta font-medium text-fg-secondary">{eyebrow}</div>}
+            <DialogPrimitive.Title className="m-0 text-[21px] leading-[1.2] font-medium tracking-heading">{title}</DialogPrimitive.Title>
+          </div>
+          {!hideClose && (
+            <DialogPrimitive.Close asChild>
+              <IconButton icon={X} label={closeLabel} size="sm" className="-mt-1 -mr-2" />
+            </DialogPrimitive.Close>
+          )}
+        </div>
+        <div className="min-h-0 flex-1 overflow-y-auto px-7 pt-3.5 pb-6 text-small leading-relaxed text-fg-secondary">
+          {description && <DialogPrimitive.Description className="m-0">{description}</DialogPrimitive.Description>}
+          {children && <div className={description ? 'mt-3' : undefined}>{children}</div>}
+        </div>
+        {footer && <div className="flex justify-end gap-2.5 border-t border-rule bg-sunk px-7 py-4 max-sm:flex-col-reverse">{footer}</div>}
+      </DialogPrimitive.Content>
+    </DialogPrimitive.Portal>
+  );
+}

package/src/components/Field.tsx

@@ -0,0 +1,66 @@
+import { createContext, useContext, useId, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type FieldContextValue = {
+  /** id for the control; the label points at it. */
+  id: string;
+  /** id of the visible label, when there is one. */
+  labelId: string | undefined;
+  /** id of the hint / error line, for aria-describedby. */
+  describedBy: string | undefined;
+  invalid: boolean;
+  disabled: boolean;
+};
+
+const FieldContext = createContext<FieldContextValue | null>(null);
+
+/** The surrounding Field, if any — controls take their id and aria from it. */
+export function useField(): FieldContextValue | null {
+  return useContext(FieldContext);
+}
+
+export type FieldProps = Omit<ComponentProps<'div'>, 'children'> & {
+  /** Always visible. The placeholder shows an example; it never replaces the label. */
+  label?: ReactNode;
+  /** A helper line below the control. */
+  hint?: ReactNode;
+  /** The error, in words that say how to fix it. Replaces the hint and marks the control invalid. */
+  error?: ReactNode;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Use this id for the control instead of a generated one. */
+  id?: string | undefined;
+  children: ReactNode;
+};
+
+/**
+ * Field — label, hint and error around one control. The label is tied to
+ * the control; the hint or error is its aria-describedby; an error sets
+ * aria-invalid. Error is wording in the one red, never colour alone.
+ */
+export function Field({ label, hint, error, required = false, disabled = false, id, className, children, ...rest }: FieldProps) {
+  const auto = useId();
+  const controlId = id ?? `f${auto}`;
+  const noteId = `${controlId}-note`;
+  const note = error ?? hint;
+  const value: FieldContextValue = { id: controlId, labelId: label ? `${controlId}-label` : undefined, describedBy: note ? noteId : undefined, invalid: Boolean(error), disabled };
+  return (
+    <FieldContext.Provider value={value}>
+      <div className={cn('flex flex-col gap-[7px] font-sans', className)} {...rest}>
+        {label && (
+          <label id={`${controlId}-label`} htmlFor={controlId} className={cn('text-meta font-medium text-fg-secondary', disabled && 'opacity-40')}>
+            {label}
+            {required && <span> · required</span>}
+          </label>
+        )}
+        {children}
+        {note && (
+          <span id={noteId} className={cn('text-meta leading-normal', error ? 'text-error-text ink:text-error' : 'text-fg-secondary')}>
+            {note}
+          </span>
+        )}
+      </div>
+    </FieldContext.Provider>
+  );
+}

package/src/components/Figure.tsx

@@ -0,0 +1,30 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+
+export type FigureProps = Omit<ComponentProps<'div'>, 'children'> & {
+  /** The number. */
+  value: ReactNode;
+  /** What it counts. */
+  label: ReactNode;
+  qualifier?: ReactNode;
+  /** Where it comes from — every figure is sourced or it is removed. */
+  source?: ReactNode;
+  /** px size of the number. @default 64 */
+  size?: number | undefined;
+};
+
+/** Figure — the stat treatment: a large tabular number, a short yellow rule, the label. */
+export function Figure({ value, label, qualifier, source, size = 64, className, ...rest }: FigureProps) {
+  return (
+    <div className={cn('flex flex-col items-start font-sans text-fg', className)} {...rest}>
+      <div className="leading-none font-bold tracking-figure tabular-nums" style={{ fontSize: size }}>
+        {value}
+      </div>
+      <div aria-hidden className="mt-3.5 mb-3 h-1 w-10 rounded-[2px] bg-yellow-accent" />
+      <div className="text-[12.5px] font-medium text-fg-secondary">{label}</div>
+      {qualifier && <div className="mt-1.5 max-w-[28ch] text-small leading-normal text-fg-secondary">{qualifier}</div>}
+      {source && <div className="mt-2 text-meta text-fg-secondary">{source}</div>}
+    </div>
+  );
+}