@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GHXSTSHIP Industries LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @ghxstship/xos-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+XOS web component library: React 19 components on Radix, cmdk and TanStack, styled with the token preset.
+
+This is `@xos/ui` from the Atlas repository at release v4.16.0, published under the `@ghxstship` scope.
+The archive holds the package's TypeScript source as the release tag does.
+
+## Install
+
+The source imports its sibling packages as `@xos/*`, so install it under its workspace name with an npm alias, at an exact version:
+
+```json
+{
+  "dependencies": {
+    "@xos/ui": "npm:@ghxstship/xos-ui@4.16.0",
+    "@xos/i18n": "npm:@ghxstship/xos-i18n@4.16.0",
+    "@xos/icons": "npm:@ghxstship/xos-icons@4.16.0",
+    "@xos/tokens": "npm:@ghxstship/xos-tokens@4.16.0"
+  }
+}
+```
+
+## Build
+
+The package ships TypeScript, so the consuming build transpiles it.
+
+- In Next.js, list both names of every installed package in `transpilePackages`, for example `"@xos/ui"` and `"@ghxstship/xos-ui"`. pnpm resolves an alias to the published name, so the alias alone is not enough.
+- The source imports its own files with `.ts` and `.tsx` extensions, so the consumer's `tsconfig.json` sets `allowImportingTsExtensions` (with `noEmit` and bundler module resolution).
+- Peer dependencies are exact, as in Atlas at this release: `tailwindcss` 4.3.3, `react` 19.3.0, `react-dom` 19.3.0.
+
+## License
+
+MIT. See `LICENSE`.

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@ghxstship/xos-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.16.0",
+  "description": "XOS web component library: React 19 components on Radix, cmdk and TanStack, styled with the token preset.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./legal-text": "./src/LegalText/index.ts",
+    "./consent": "./src/ConsentBanner/index.ts",
+    "./consent/static": "./src/ConsentBanner/static.ts",
+    "./static": "./src/static.ts",
+    "./marketing": "./src/marketing.ts",
+    "./preferences": "./src/lib/preferences.ts",
+    "./shortcut-targets": "./src/lib/shortcut-targets.ts",
+    "./undo": "./src/lib/undo-stack.ts",
+    "./route-transition": "./src/lib/route-transition.tsx",
+    "./quick-add": "./src/Editing/quickAddCore.ts",
+    "./pwa": "./src/pwa/index.ts",
+    "./pwa/client": "./src/pwa/client.ts",
+    "./pwa/analytics": "./src/pwa/analytics.ts",
+    "./pwa/offline-key": "./src/pwa/offline-key.ts",
+    "./pwa/browser-push": "./src/pwa/browser-push.tsx",
+    "./pwa/action-outcome": "./src/pwa/action-outcome.tsx",
+    "./styles.css": "./src/styles/index.css",
+    "./marketing.css": "./src/styles/marketing.css",
+    "./tailwind.config.cjs": "./tailwind.config.cjs",
+    "./brand/*": "./src/brand/defaults/*"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "1.8.0",
+    "@tanstack/react-table": "9.2.6",
+    "@tanstack/react-virtual": "3.14.13",
+    "@tiptap/core": "3.31.4",
+    "@tiptap/extension-collaboration": "3.31.4",
+    "@tiptap/extension-link": "3.31.4",
+    "@tiptap/extension-list": "3.31.4",
+    "@tiptap/extension-mention": "3.31.4",
+    "@tiptap/extension-table": "3.31.4",
+    "@tiptap/pm": "3.31.4",
+    "@tiptap/react": "3.31.4",
+    "@tiptap/starter-kit": "3.31.4",
+    "@tiptap/suggestion": "3.31.4",
+    "@tiptap/y-tiptap": "3.0.9",
+    "@visx/group": "4.0.0",
+    "@visx/pattern": "4.0.0",
+    "@visx/scale": "4.0.0",
+    "@visx/shape": "4.0.0",
+    "@xos/i18n": "npm:@ghxstship/xos-i18n@4.16.0",
+    "@xos/icons": "npm:@ghxstship/xos-icons@4.16.0",
+    "@xos/tokens": "npm:@ghxstship/xos-tokens@4.16.0",
+    "chrono-node": "2.10.2",
+    "cmdk": "1.1.1",
+    "lucide-react": "1.53.0",
+    "maplibre-gl": "6.13.0",
+    "qrcode-generator": "1.4.4",
+    "radix-ui": "1.7.0",
+    "y-protocols": "1.0.7",
+    "yjs": "13.6.33"
+  },
+  "peerDependencies": {
+    "tailwindcss": "4.3.3",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ghxstship/atlas.git",
+    "directory": "packages/ui"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  }
+}

package/scripts/generate-stories.mjs

@@ -0,0 +1,85 @@
+/**
+ * Writes one Storybook story per design preview (RRR-34, design handoff build step 7) into
+ * stories/generated/. Each preview in design/xos-design-system/components/<Name>/preview.html renders
+ * the reference component with representative props through `XOS.<Name>`; the story runs the same
+ * code against the production @xos/ui exports, which the contract test holds to the reference props.
+ * Previews without a script (Cover) and previews that draw with reference-only CSS (ControlStates)
+ * have hand-written stories in stories/.
+ *
+ * Usage: node scripts/generate-stories.mjs [--check]
+ * With --check, writes nothing and exits 1 when a generated story is missing, stale or extra.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as prettier from "prettier";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = join(here, "../../../design/xos-design-system/components");
+const target = join(here, "../stories/generated");
+const HAND_WRITTEN = new Set(["Cover", "ControlStates"]);
+
+function story(name, html) {
+  const card = /@dsCard(?:\s+group="([^"]+)")?(?:\s+height=(\d+))?/.exec(html);
+  const group = card?.[1] ?? "Foundations";
+  const height = Number(card?.[2] ?? 240);
+  const script = /<script>([\s\S]*?)<\/script>/.exec(html)?.[1];
+  if (!script) return null;
+  const body = script
+    .replace(/^\s*var X = window\.XOS, h = React\.createElement;\s*$/m, "")
+    .replace(/ReactDOM\.createRoot\(document\.getElementById\('root'\)\)\.render\(/, "return (");
+  return `/* Generated by scripts/generate-stories.mjs from design/xos-design-system/components/${name}/preview.html. Do not edit; run \`pnpm --filter @xos/ui generate:stories\`. */
+import { createElement } from "react";
+import * as X from "../../src/index.ts";
+
+const h = createElement;
+const React = { createElement };
+
+export default {
+  title: ${JSON.stringify(`${group}/${name}`)},
+  parameters: { preview: { height: ${height} } },
+};
+
+export const Preview = {
+  name: ${JSON.stringify(name)},
+  render: () => {
+    void React;
+    void X;
+    void h;
+${body}
+  },
+};
+`;
+}
+
+const outputs = new Map();
+for (const name of readdirSync(source).sort()) {
+  const file = join(source, name, "preview.html");
+  if (HAND_WRITTEN.has(name) || !existsSync(file)) continue;
+  const code = story(name, readFileSync(file, "utf8"));
+  if (!code) continue;
+  const path = join(target, `${name}.stories.js`);
+  const config = (await prettier.resolveConfig(path)) ?? {};
+  outputs.set(`${name}.stories.js`, await prettier.format(code, { ...config, filepath: path }));
+}
+
+if (process.argv.includes("--check")) {
+  const present = existsSync(target) ? readdirSync(target) : [];
+  const problems = [
+    ...[...outputs]
+      .filter(([f, c]) => !present.includes(f) || readFileSync(join(target, f), "utf8") !== c)
+      .map(([f]) => f),
+    ...present.filter((f) => !outputs.has(f)),
+  ];
+  if (problems.length) {
+    console.error(
+      `stories/generated is out of date (${problems.join(", ")}). Run pnpm --filter @xos/ui generate:stories.`,
+    );
+    process.exit(1);
+  }
+} else {
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(target, { recursive: true });
+  for (const [file, code] of outputs) writeFileSync(join(target, file), code);
+  console.log(`Wrote ${outputs.size} stories to stories/generated`);
+}

package/src/AIDisclosureBadge/README.md

@@ -0,0 +1,7 @@
+# AIDisclosureBadge
+
+AIDisclosureBadge marks a feature as AI, names the model provider and links the notice.
+
+Place it beside every mention of an AI feature on a public page, and beside any image or text an AI system generated. The label is a word, "AI feature", never an icon alone.
+
+The consumer provides the provider line and the link to the AI Features Notice.

package/src/AccessGridMatrix/README.md

@@ -0,0 +1,3 @@
+# AccessGridMatrix
+
+AccessGridMatrix sets which credential categories enter which zones; Compass validates scans against it offline.

package/src/Accordion/README.md

@@ -0,0 +1,7 @@
+# Accordion
+
+Accordion progressively discloses sections; use it for the More fields pattern past seven visible fields.
+
+Inside a form, pass `keepMounted` so collapsed fields stay in the DOM, hidden, keep their values and submit with the form. Title the section with the "More fields" label and put every field past the seventh in it.
+
+`MoreFields` is that section ready-made: an Accordion titled with the catalog's "More fields", kept mounted.

package/src/ActivityFeedItem/README.md

@@ -0,0 +1,3 @@
+# ActivityFeedItem
+
+ActivityFeedItem shows one event or comment in a feed; reactions use XOS icon glyphs, not emoji.

package/src/AgencySlate/README.md

@@ -0,0 +1,3 @@
+# AgencySlate
+
+AgencySlate lets a staffing agency pick named staff from its roster against the positions, with certification status.

package/src/AppShell/README.md

@@ -0,0 +1,5 @@
+# AppShell
+
+AppShell composes the brand slot, sidebar, header and content area for every Atlas page.
+
+- The brand slot renders BrandMark, so the tenant logo appears without layout changes.

package/src/ApplicationForm/README.md

@@ -0,0 +1,3 @@
+# ApplicationForm
+
+ApplicationForm shows exactly what the person shares before they apply, the org's questions and availability confirmation.

package/src/AssertionRankBadge/README.md

@@ -0,0 +1,5 @@
+# AssertionRankBadge
+
+AssertionRankBadge shows an assertion value with four pips for its rank from 4 down to 0.
+
+- Rank 4 pips use `success`; ranks 1 and 0 use `warning`.

package/src/AvailabilityCalendar/README.md

@@ -0,0 +1,3 @@
+# AvailabilityCalendar
+
+AvailabilityCalendar marks available and booked days; booked days use strike-through as well as color.

package/src/Avatar/Avatar.tsx

@@ -0,0 +1,56 @@
+import type { ReactElement } from "react";
+import type {
+  AvatarProps as ReferenceAvatarProps,
+  AvatarStackProps as ReferenceAvatarStackProps,
+} from "../types/reference";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { avatarClass, initials } from "./avatar-class.ts";
+
+export type AvatarProps = ReferenceAvatarProps;
+export type AvatarStackProps = ReferenceAvatarStackProps;
+
+export { avatarClass, initials };
+
+/** Initials in a circle, named for assistive technology. */
+export function Avatar({ name, size = "md" }: AvatarProps): ReactElement {
+  return (
+    <span
+      role="img"
+      aria-label={name}
+      title={name}
+      className={cx(
+        avatarClass,
+        size === "lg" ? "size-(--ui-avatar-lg) text-text-12" : "size-(--ui-avatar) text-text-11",
+      )}
+    >
+      {initials(name)}
+    </span>
+  );
+}
+
+/** Up to `max` avatars (3 by default) and a count of the rest. */
+export function AvatarStack({ names, max = 3 }: AvatarStackProps): ReactElement {
+  const t = useT();
+  const shown = names.slice(0, max);
+  const extra = names.length - shown.length;
+  return (
+    <span className="inline-flex [&>*+*]:ms-(--ui-avatar-overlap)">
+      {shown.map((name) => (
+        <Avatar key={name} name={name} />
+      ))}
+      {extra > 0 ? (
+        <span
+          role="img"
+          aria-label={t("avatar.more", { n: extra })}
+          className={cx(
+            avatarClass,
+            "size-(--ui-avatar) text-text-11 bg-bg-surface text-text-secondary tabular-nums",
+          )}
+        >
+          {t("avatar.overflow", { n: extra })}
+        </span>
+      ) : null}
+    </span>
+  );
+}

package/src/Avatar/README.md

@@ -0,0 +1,3 @@
+# Avatar
+
+Avatar shows a person's initials at 24 px or 32 px.

package/src/Avatar/avatar-class.ts

@@ -0,0 +1,19 @@
+import { cx } from "../lib/cx.ts";
+
+/**
+ * The avatar's initials and classes without the component: no hooks and no context, so a server
+ * component can draw the same circle (ADR 0027).
+ */
+export function initials(name: string): string {
+  return name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part.charAt(0).toUpperCase())
+    .join("");
+}
+
+export const avatarClass = cx(
+  "inline-grid place-items-center flex-none rounded-full bg-bg-hover text-text-primary font-semibold",
+  "ring-(length:--stroke-width-focus) ring-bg-canvas",
+);

package/src/AvatarStack/README.md

@@ -0,0 +1,3 @@
+# AvatarStack
+
+AvatarStack overlaps up to `max` avatars and counts the rest; used for presence and assignees.

package/src/Badge/README.md

@@ -0,0 +1,3 @@
+# Badge
+
+Badge counts unread or pending items beside navigation and tabs; above 99 it shows 99+.

package/src/Banner/README.md

@@ -0,0 +1,3 @@
+# Banner
+
+Banner states a page-wide condition across the top of a page; at most one per page.

package/src/BidSheet/README.md

@@ -0,0 +1,3 @@
+# BidSheet
+
+BidSheet is a sealed line-item bid grid; unpriced lines stay blank and make the total Unpriced.

package/src/Board/README.md

@@ -0,0 +1,6 @@
+# Board
+
+Board groups records into columns by state or any single-choice field; dragging a card changes that field, with a keyboard path.
+
+- A card shows its key, owner, title, an optional `meta` line in secondary text, its kind and its due date.
+- `readOnly` hides the add buttons and disables moving cards, for viewers who cannot create or change these records.

package/src/BrandMark/BrandMark.tsx

@@ -0,0 +1,95 @@
+import type { ReactElement } from "react";
+import type { BrandMarkProps as ReferenceBrandMarkProps } from "../types/reference";
+import { cx } from "../lib/cx.ts";
+
+export type BrandMarkProps = ReferenceBrandMarkProps;
+
+const TILE: Record<NonNullable<BrandMarkProps["size"]>, string> = {
+  sm: cx("size-icon-20 text-text-11 rounded-control"),
+  md: cx("h-control-md min-w-control-md text-text-11 rounded-control"),
+  lg: cx("h-(--space-40) min-w-(--space-40) text-heading-16 rounded-card"),
+};
+
+const NAME: Record<NonNullable<BrandMarkProps["size"]>, string> = {
+  sm: cx("text-text-13"),
+  md: cx("text-text-14"),
+  lg: cx("text-heading-20"),
+};
+
+const LOGO: Record<NonNullable<BrandMarkProps["size"]>, string> = {
+  sm: cx("h-(--icon-size-20)"),
+  md: cx("h-control-md"),
+  lg: cx("h-(--space-40)"),
+};
+
+export function monogram(name: string, override?: string): string {
+  return (
+    override ??
+    name
+      .replace(/[^A-Za-z0-9 ]/g, "")
+      .split(/\s+/)
+      .map((w) => w.charAt(0))
+      .join("")
+      .slice(0, 2)
+  ).toUpperCase();
+}
+
+/**
+ * The white-label mark (ADR 0011): the tenant's light or dark logo for the current theme, or a
+ * monogram tile in accent-default with the name until logos are set.
+ */
+export function BrandMark({
+  name,
+  logoLight,
+  logoDark,
+  monogram: mark,
+  size = "md",
+  iconOnly = false,
+}: BrandMarkProps): ReactElement {
+  if (logoLight || logoDark) {
+    return (
+      <span className="inline-flex items-center gap-8">
+        {logoDark ? (
+          <img
+            src={logoDark}
+            alt={name}
+            className={cx(
+              LOGO[size],
+              "w-auto in-data-[theme=light]:hidden in-data-[theme=sunlight]:hidden",
+            )}
+          />
+        ) : null}
+        {logoLight ? (
+          <img
+            src={logoLight}
+            alt={logoDark ? "" : name}
+            className={cx(
+              LOGO[size],
+              "w-auto",
+              logoDark && "hidden in-data-[theme=light]:inline in-data-[theme=sunlight]:inline",
+            )}
+          />
+        ) : null}
+      </span>
+    );
+  }
+  return (
+    <span role="img" aria-label={name} className="inline-flex items-center gap-8">
+      <span
+        aria-hidden="true"
+        className={cx(
+          "inline-grid place-items-center bg-accent text-accent-text-on font-bold leading-none tracking-wide",
+          "forced-colors:forced-color-adjust-none",
+          TILE[size],
+        )}
+      >
+        {monogram(name, mark)}
+      </span>
+      {iconOnly ? null : (
+        <span aria-hidden="true" className={cx("font-semibold text-text-primary", NAME[size])}>
+          {name}
+        </span>
+      )}
+    </span>
+  );
+}

package/src/BrandMark/README.md

@@ -0,0 +1,7 @@
+# BrandMark
+
+BrandMark renders the tenant's logo, switching light and dark files with the theme, or a token-driven monogram and name when no logo is set.
+
+- Props: `name` (required, also the alt text), `logoLight`, `logoDark`, `monogram`, `size` (`sm` 20 px, `md` 28 px, `lg` 40 px), `iconOnly`.
+- With no logo uploaded, the monogram tile uses `accent-default` and `accent-text-on`, so it follows the tenant accent automatically.
+- The platform brand marks are not set yet; until they are, the platform also renders through this fallback.

package/src/BrandSlot/README.md

@@ -0,0 +1,6 @@
+# BrandSlot
+
+BrandSlot marks where a tenant uploads a brand file in White Label settings, with its size and formats.
+
+- Slots: Logo Light, Logo Dark, Favicon, App Icon (Enterprise branded builds), Splash (Enterprise branded builds).
+- Pass the delivery size as `width` and `height` in pixels. The frame is drawn in proportion, at most 160 by 148, and the caption states the delivery size.

package/src/Breadcrumbs/README.md

@@ -0,0 +1,3 @@
+# Breadcrumbs
+
+Breadcrumbs show Org, Workspace, Project, Scope node, Module and Record, omitting levels that do not apply.

package/src/BudgetGrid/README.md

@@ -0,0 +1,10 @@
+# BudgetGrid
+
+BudgetGrid groups budget lines by GL account in numeric order, then by cost center and URID, with a grade toggle.
+
+- GL posting is derived, never stored. A line carries its URID; the URID class (first segment) selects that class's one account of the requested type from the GL Accounts table passed as `accounts` (Expense by default). 5000.01.02 posts to 5500 Expense · Production because class 5000 owns 5500. A line whose class has no account groups last under Unmapped Account with a warning icon, so a gap in the chart is visible rather than silently misposted.
+- Amount is derived as quantity times the selected grade's rate. It is never stored, and a blank input gives a blank amount.
+- Totals follow the silence rule: any unpriced line makes its subtotal and the total Unpriced.
+- Line types are Scope, Overhead, Contingency, Fee and Retainer. Fee and Contingency are line types, not accounts.
+- Grades are Base, Elevated and Premium (build prompt, decision D11). Grade labels are passed as `grades` from the enumeration table, never hard-coded.
+- The preview uses Item Catalog lines and prices verbatim. Ungraded items carry the same rate in every grade; graded touchpoint items such as Artist-Rooted Cultural Menu are unpriced in the catalog, which is why the Hospitality subtotal and the total read Unpriced.

package/src/BulkActionBar/README.md

@@ -0,0 +1,3 @@
+# BulkActionBar
+
+BulkActionBar appears with a selection and shows the count and the actions every selected item allows, at most five.

package/src/Button/Button.tsx

@@ -0,0 +1,100 @@
+import type { ReactElement } from "react";
+import type {
+  ButtonProps as ReferenceButtonProps,
+  IconButtonProps as ReferenceIconButtonProps,
+} from "../types/reference";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { buttonClass, iconButtonClass } from "./button-class.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { Keys } from "../Kbd/Kbd.tsx";
+
+export type ButtonProps = ReferenceButtonProps;
+export type IconButtonProps = ReferenceIconButtonProps;
+
+export { buttonClass, iconButtonClass };
+
+function Spinner(): ReactElement {
+  return (
+    <svg
+      className="xos-anim-spin inline-block flex-none"
+      width={14}
+      height={14}
+      viewBox="0 0 16 16"
+      aria-hidden="true"
+    >
+      <circle
+        cx={8}
+        cy={8}
+        r={6}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={1.5}
+        strokeDasharray="28 10"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
+
+/**
+ * Triggers one action. One primary per screen; `loading` sets aria-busy and blocks repeat clicks
+ * without disabling focus.
+ */
+export function Button({
+  variant = "secondary",
+  size = "md",
+  loading = false,
+  icon,
+  shortcut,
+  className,
+  children,
+  type = "button",
+  onClick,
+  ...rest
+}: ButtonProps): ReactElement {
+  return (
+    <button
+      type={type}
+      {...rest}
+      {...(loading ? { "aria-busy": true, "aria-disabled": true } : {})}
+      onClick={loading ? undefined : onClick}
+      className={cx(buttonClass(variant, size), className)}
+    >
+      {loading ? <Spinner /> : icon ? <Icon name={icon} size={14} /> : null}
+      {children}
+      {/* A touch screen has no keyboard to press it with, so the hint stays off there (A59-023). */}
+      {shortcut ? (
+        <span className="ms-4 inline-flex pointer-coarse:hidden">
+          <Keys keys={shortcut} />
+        </span>
+      ) : null}
+    </button>
+  );
+}
+
+/**
+ * A square control with one icon and a required label, used as aria-label and the tooltip text.
+ */
+export function IconButton({
+  icon,
+  label,
+  shortcut,
+  variant = "ghost",
+  className,
+  type = "button",
+  ...rest
+}: IconButtonProps): ReactElement {
+  const t = useT();
+  return (
+    <button
+      type={type}
+      aria-label={label}
+      title={shortcut ? t("tooltip.withShortcut", { label, shortcut }) : label}
+      {...rest}
+      className={cx(iconButtonClass(variant), className)}
+    >
+      <Icon name={icon} />
+    </button>
+  );
+}

package/src/Button/README.md

@@ -0,0 +1,10 @@
+# Button
+
+Button triggers one action; exactly one primary per screen, everything else secondary, ghost or in overflow.
+
+- Variants: `primary` (accent fill, the one action the screen is for), `secondary` (default), `ghost` (toolbars, dialog cancel), `danger` (destructive, always paired with Undo or a confirmation for irreversible work).
+- Sizes: `sm` 24 px, `md` 28 px (default), `lg` 32 px from `control-*` tokens, and `xl` 44 px from `target-coarse`, the call to action size on public pages.
+- Labels are Title Case and at most three words, verb first: Create Record, Approve, Export.
+- Pass `shortcut` to show the key in a Kbd; every action has one.
+- `loading` sets `aria-busy` and blocks repeat clicks without a blocking spinner elsewhere.
+- States: default, hover (`bg-hover` or brightness on primary), focus (2 px `focus-ring`), active, disabled (`opacity-disabled`), loading.