@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/RecordKindGlyph/README.md

@@ -0,0 +1,34 @@
+# RecordKindGlyph
+
+RecordKindGlyph draws the Lucide icon assigned to each of the 26 record kinds, grouped by class.
+
+| Class      | Kind         | Lucide icon   |
+| ---------- | ------------ | ------------- |
+| Work       | Build        | Construction  |
+| Work       | Rehearsal    | Repeat        |
+| Work       | Shift        | CalendarClock |
+| Work       | Strike       | PackageX      |
+| Work       | Task         | SquareCheck   |
+| Work       | Training     | GraduationCap |
+| Artifact   | Document     | FileText      |
+| Artifact   | Supply       | Package       |
+| Commitment | Booking      | CalendarCheck |
+| Commitment | Contract     | FileSignature |
+| Commitment | Payment      | Banknote      |
+| Commitment | Recruitment  | UserPlus      |
+| Control    | Approval     | Stamp         |
+| Control    | Compliance   | ShieldCheck   |
+| Control    | Deadline     | AlarmClock    |
+| Control    | Decision     | Split         |
+| Control    | Inspection   | ScanSearch    |
+| Control    | Permit       | BadgeCheck    |
+| Time       | Distribution | Send          |
+| Time       | Event        | Ticket        |
+| Time       | Goal         | Target        |
+| Time       | Meeting      | Users         |
+| Time       | Milestone    | Milestone     |
+| Time       | Report       | ChartColumn   |
+| Time       | Risk         | TriangleAlert |
+| Time       | Timeline     | ChartGantt    |
+
+Exported as `XOS.glyphs.recordKinds`. The Build kind uses Construction so it stays distinct from the Build phase (Hammer).

package/src/RecordRow/README.md

@@ -0,0 +1,7 @@
+# RecordRow
+
+RecordRow is one list-view row that answers what now: state, key, title, phase, next date, owner and the next action.
+
+- The next action appears on hover or focus, and is always visible on touch.
+- Rows sit inside RecordList, which carries the grid role and the list's name.
+- Titles follow each kind's title grammar (Bible tab 24): Task is imperative, Supply and Inspection are noun phrases.

package/src/RefusalNotice/README.md

@@ -0,0 +1,5 @@
+# RefusalNotice
+
+RefusalNotice renders NO_ANSWER, UNRATIFIED or REFUSE with its reason and the action that resolves it.
+
+- A refusal is a first-class outcome, never a permissive default and never an error style.

package/src/ResizablePanel/README.md

@@ -0,0 +1,3 @@
+# ResizablePanel
+
+ResizablePanel lets a person resize the sidebar, side peek or split view by pointer or arrow keys within token limits.

package/src/ResourceSchedule/README.md

@@ -0,0 +1,6 @@
+# ResourceSchedule
+
+ResourceSchedule shows people against days with their shifts, and flags double bookings in place before assignment.
+
+- It is a native table, so it is its own accessible alternative.
+- Default view for shifts in Atlas (views registry).

package/src/RichTextEditor/README.md

@@ -0,0 +1,3 @@
+# RichTextEditor
+
+RichTextEditor edits documents with mentions, record links, slash commands, tables, checklists and live co-editing.

package/src/RichTextEditor/extensions.ts

@@ -0,0 +1,217 @@
+import { Extension, type Editor, type Range } from "@tiptap/core";
+import Mention from "@tiptap/extension-mention";
+import { TaskItem, TaskList } from "@tiptap/extension-list";
+import { TableKit } from "@tiptap/extension-table";
+import { PluginKey } from "@tiptap/pm/state";
+import Suggestion, {
+  type SuggestionKeyDownProps,
+  type SuggestionOptions,
+  type SuggestionProps,
+} from "@tiptap/suggestion";
+
+/**
+ * RichTextEditor extensions (RRR-75): `@` mentions, `#` record links, `/` slash commands, tables
+ * and checklists, on the Tiptap 3.31.4 pin. Suggestion menus render in React: each trigger reports
+ * its open menu through `onMenu`, and the editor component draws the listbox.
+ */
+
+export interface SuggestionItem {
+  id: string;
+  label: string;
+  meta?: string;
+}
+
+export type SuggestionSource = (query: string) => SuggestionItem[] | Promise<SuggestionItem[]>;
+
+export type MenuKind = "mention" | "record" | "slash";
+
+export interface SuggestionMenu {
+  kind: MenuKind;
+  items: SuggestionItem[];
+  active: number;
+  rect: DOMRect | null;
+  select: (index: number) => void;
+}
+
+export type MenuListener = (menu: SuggestionMenu | null) => void;
+
+export interface SlashCommand extends SuggestionItem {
+  run: (editor: Editor, range: Range) => void;
+}
+
+/** The slash menu blocks, labeled through the `rte` catalog. */
+export function slashCommands(label: (key: string) => string): SlashCommand[] {
+  return [
+    {
+      id: "heading",
+      label: label("rte.heading"),
+      run: (e, r) => e.chain().focus().deleteRange(r).toggleHeading({ level: 2 }).run(),
+    },
+    {
+      id: "bullets",
+      label: label("rte.bullets"),
+      run: (e, r) => e.chain().focus().deleteRange(r).toggleBulletList().run(),
+    },
+    {
+      id: "checklist",
+      label: label("rte.checklist"),
+      run: (e, r) => e.chain().focus().deleteRange(r).toggleTaskList().run(),
+    },
+    {
+      id: "table",
+      label: label("rte.table"),
+      run: (e, r) =>
+        e
+          .chain()
+          .focus()
+          .deleteRange(r)
+          .insertTable({ rows: 3, cols: 3, withHeaderRow: true })
+          .run(),
+    },
+    {
+      id: "quote",
+      label: label("rte.quote"),
+      run: (e, r) => e.chain().focus().deleteRange(r).toggleBlockquote().run(),
+    },
+    {
+      id: "divider",
+      label: label("rte.divider"),
+      run: (e, r) => e.chain().focus().deleteRange(r).setHorizontalRule().run(),
+    },
+  ];
+}
+
+/** Bridges Tiptap's suggestion lifecycle to a React listener, with arrow, Enter and Escape keys. */
+export function menuRenderer<T extends SuggestionItem>(
+  kind: MenuKind,
+  listen: () => MenuListener,
+): NonNullable<SuggestionOptions<T>["render"]> {
+  return () => {
+    let props: SuggestionProps<T> | null = null;
+    let active = 0;
+    const publish = () => {
+      if (!props) return listen()(null);
+      const current = props;
+      listen()({
+        kind,
+        items: current.items,
+        active,
+        rect: current.clientRect?.() ?? null,
+        select: (index) => {
+          const item = current.items[index];
+          if (item) current.command(item);
+        },
+      });
+    };
+    return {
+      onStart: (next) => {
+        props = next;
+        active = 0;
+        publish();
+      },
+      onUpdate: (next) => {
+        props = next;
+        active = Math.min(active, Math.max(0, next.items.length - 1));
+        publish();
+      },
+      onKeyDown: ({ event }: SuggestionKeyDownProps) => {
+        if (!props) return false;
+        const count = props.items.length;
+        if (event.key === "Escape") {
+          props = null;
+          publish();
+          return true;
+        }
+        if (count === 0) return false;
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+          active = (active + (event.key === "ArrowDown" ? 1 : count - 1)) % count;
+          publish();
+          return true;
+        }
+        if (event.key === "Enter" || event.key === "Tab") {
+          const item = props.items[active];
+          if (item) props.command(item);
+          return true;
+        }
+        return false;
+      },
+      onExit: () => {
+        props = null;
+        publish();
+      },
+    };
+  };
+}
+
+async function filtered(source: SuggestionSource, query: string): Promise<SuggestionItem[]> {
+  return (await source(query)).slice(0, 8);
+}
+
+/** `@` mentions of people; the node keeps the person id and renders `@Name`. */
+export function mentionExtension(source: SuggestionSource, listen: () => MenuListener) {
+  return Mention.configure({
+    HTMLAttributes: { class: "xos-mention" },
+    suggestion: {
+      char: "@",
+      pluginKey: new PluginKey("xosMention"),
+      items: ({ query }) => filtered(source, query),
+      render: menuRenderer("mention", listen),
+    },
+  });
+}
+
+/** `#` record links; the node keeps the URID and renders a link to the record. */
+export function recordLinkExtension(
+  source: SuggestionSource,
+  href: (urid: string) => string,
+  listen: () => MenuListener,
+) {
+  return Mention.extend({ name: "recordLink" }).configure({
+    HTMLAttributes: { class: "xos-record-link" },
+    renderHTML: ({ node, options }) => [
+      "a",
+      {
+        ...options.HTMLAttributes,
+        href: href(String(node.attrs["id"])),
+        "data-urid": node.attrs["id"],
+      },
+      `#${String(node.attrs["label"] ?? node.attrs["id"])}`,
+    ],
+    renderText: ({ node }) => `#${String(node.attrs["label"] ?? node.attrs["id"])}`,
+    suggestion: {
+      char: "#",
+      pluginKey: new PluginKey("xosRecordLink"),
+      items: ({ query }) => filtered(source, query),
+      render: menuRenderer("record", listen),
+    },
+  });
+}
+
+/** `/` slash commands that insert blocks. */
+export function slashExtension(commands: SlashCommand[], listen: () => MenuListener) {
+  return Extension.create({
+    name: "slashCommand",
+    addProseMirrorPlugins() {
+      return [
+        Suggestion<SlashCommand>({
+          editor: this.editor,
+          char: "/",
+          pluginKey: new PluginKey("xosSlash"),
+          items: ({ query }) =>
+            commands.filter((c) => c.label.toLowerCase().includes(query.toLowerCase())),
+          command: ({ editor, range, props }) => props.run(editor, range),
+          render: menuRenderer<SlashCommand>("slash", listen),
+        }),
+      ];
+    },
+  });
+}
+
+/** Tables (with header rows and column resizing off for touch) and nested checklists. */
+export function blockExtensions() {
+  return [
+    TableKit.configure({ table: { resizable: false, HTMLAttributes: { class: "xos-rte-table" } } }),
+    TaskList,
+    TaskItem.configure({ nested: true }),
+  ];
+}

package/src/RunOfShowLive/README.md

@@ -0,0 +1,5 @@
+# RunOfShowLive
+
+RunOfShowLive steps through cues with a countdown; Space advances, and Compass mirrors it in under 500 ms.
+
+- Show mode (`showMode`) enlarges cues to arm's-length reading.

package/src/ScanSheet/README.md

@@ -0,0 +1,3 @@
+# ScanSheet
+
+ScanSheet scans barcodes, QR codes and NFC continuously for asset custody, receiving and credentials, with a running count and a haptic per scan.

package/src/ScreenshotFrame/README.md

@@ -0,0 +1,7 @@
+# ScreenshotFrame
+
+ScreenshotFrame presents a product image, or live XOS components standing in for one, inside a window frame.
+
+With `src` it draws an image at a fixed aspect ratio, lazy by default; pass `eager` for the hero image. Without `src` it frames the components passed as children: the content is inert, hidden from assistive technology and exposed as a single image, so it adds no tab stops.
+
+`alt` is required in both modes and says what the picture shows, not that it is a screenshot. Provide one image per locale so the picture matches the page language. Pictures use only the fictional Northwind Live tenant.

package/src/ScrollRegion/README.md

@@ -0,0 +1,9 @@
+# ScrollRegion
+
+ScrollRegion keeps wide data inside the page width. Content wider than its container scrolls horizontally inside a labeled region; the page itself never scrolls sideways, which satisfies WCAG 1.4.10 Reflow for two-dimensional content.
+
+- DataTable, BudgetGrid, ReconciliationTable, AccessGridMatrix, RadioChannelTable, ShortcutEditor, ResourceSchedule, DiffViewer, CoordinateMatrix, OrgChart and Timeline are wrapped automatically. Use ScrollRegion directly for any other wide content.
+- The region has `role="region"` and an accessible name taken from the wrapped component's label, caption or title (fallback: "Scrollable content").
+- It joins the tab order only while its content actually overflows, measured with a ResizeObserver, so keyboard users can scroll it with the arrow keys and nobody else pays an extra tab stop.
+- Focus shows the standard 2 px `focus-ring` outline. Scrolling is contained (`overscroll-behavior-x: contain`) so a horizontal swipe never navigates the browser back.
+- Production: keep this wrapper around TanStack Table and Glide Data Grid surfaces; Glide's own canvas scroller replaces it inside the grid.

package/src/SegmentedControl/README.md

@@ -0,0 +1,5 @@
+# SegmentedControl
+
+SegmentedControl switches between two to five peer options, such as the view switcher.
+
+- The view switcher offers only views that fit the data; it never shows a disabled option.

package/src/Select/README.md

@@ -0,0 +1,5 @@
+# Select
+
+Select picks one value from a short closed list; use Combobox when the list is long or searchable.
+
+- Options come from reference tables and i18n catalogs, never from code.

package/src/ShiftCard/README.md

@@ -0,0 +1,3 @@
+# ShiftCard
+
+ShiftCard leads with role, date, time and place, and offers swap and wallet actions.

package/src/ShortcutEditor/README.md

@@ -0,0 +1,3 @@
+# ShortcutEditor
+
+ShortcutEditor rebinds shortcuts and blocks conflicts and reserved browser and screen reader keys.

package/src/ShortcutSheet/README.md

@@ -0,0 +1,3 @@
+# ShortcutSheet
+
+ShortcutSheet lists every shortcut by group; `?` opens it anywhere.

package/src/SidePeek/README.md

@@ -0,0 +1,6 @@
+# SidePeek
+
+SidePeek opens a record beside the list with the one record anatomy: title, kind and state, properties, activity.
+
+- Width `layout-peek` (560 px), resizable 440 to 960; full screen below md.
+- Slides 16 px and fades over `duration-slow`.

package/src/Sidebar/README.md

@@ -0,0 +1,5 @@
+# Sidebar
+
+Sidebar is generated from the sitemap; groups other than the role's defaults start collapsed.
+
+- Width `layout-sidebar` (240 px), collapsible to 56 px, resizable 200 to 360 px.

package/src/SignaturePad/README.md

@@ -0,0 +1,3 @@
+# SignaturePad
+
+SignaturePad captures a finger, stylus or mouse signature with a clear attestation line.

package/src/Skeleton/README.md

@@ -0,0 +1,3 @@
+# Skeleton
+
+Skeleton reserves space for streamed content per page region; it stops pulsing under reduced motion.

package/src/Slider/README.md

@@ -0,0 +1,3 @@
+# Slider
+
+Slider sets a value in a bounded range and always shows the current value beside its label.

package/src/SplitView/README.md

@@ -0,0 +1,3 @@
+# SplitView
+
+SplitView keeps a list on the left and the selected record on the right; used for Inbox, Dispatch and Advancing.

package/src/SpreadsheetGrid/README.md

@@ -0,0 +1,9 @@
+# SpreadsheetGrid
+
+SpreadsheetGrid edits money and numbers at spreadsheet speed: arrow keys, Enter to edit, fill handle, Excel paste, NULL-aware cells.
+
+- Deleting a cell sets it to Unpriced, never 0.
+- A totals row is blank when any line is blank.
+- `type: 'multiplier'` stores a plain number and displays it with one decimal and an x (1.5 shows as 1.5x, 2 as 2.0x). Typing 1.5x commits 1.5; the stored value is never text.
+- `derive` makes a read-only column computed from the row. Use it for any value whose source of truth is another table, so the grid never holds a second copy. Derived cells use secondary text, refuse edits and explain why on hover.
+- The preview is the Playbook Labor Rate Cards (decision D12). Each row stores only its own facts: rate card ID, role code, worker classification, pay basis, arrangement, standard rate and overtime rule. Classification, pay basis and arrangement are separate facts (decision D16): W2 Daily, Contractor 1099 and Vendor Master became Employee, Independent Contractor and Vendor-Supplied. Job Title comes from the Roles Library by role code; OT and DT come from the referenced overtime rule (decision D14), so the grid shows the multipliers and the row stores only the rule; GL Account is derived from the role code's class through the GL Accounts table (decision D13), which is why 9000.50.01 Production Stage Manager posts to 5900 Expense · Technology. The same joins are the `rate_card_resolved` view in `export/canon/schema.sql`.

package/src/StalenessIndicator/README.md

@@ -0,0 +1,3 @@
+# StalenessIndicator
+
+StalenessIndicator shows a price band's age: degraded one step at 12 months, Modeled at 24, Expired at 36, computed at read time.

package/src/StatTile/README.md

@@ -0,0 +1,6 @@
+# StatTile
+
+StatTile is a single headline number for dashboards, with its change and whether that change is good.
+
+- Direction is an icon and a signed number as well as color.
+- A blank value reads No value, never 0.

package/src/StateChip/README.md

@@ -0,0 +1,6 @@
+# StateChip
+
+StateChip shows a record state as icon plus label and opens the state menu when clickable.
+
+- Labels come from the i18n catalog keyed by the stored state value.
+- Cross-fades over `duration-fast` on change.

package/src/StateIcon/README.md

@@ -0,0 +1,6 @@
+# StateIcon
+
+StateIcon draws the shape for each of the nine record states so state never relies on color alone.
+
+- Proposed dashed circle, Ready empty circle, Scheduled clock circle, Active half circle, Blocked octagon, In Review eye circle, Complete check circle, Deferred pause circle, Canceled slashed circle.
+- Color comes from the `state-*` tokens.

package/src/StateIcon/StateIcon.tsx

@@ -0,0 +1,127 @@
+import type { ReactElement, ReactNode } from "react";
+import type { RecordState, StateIconProps as ReferenceStateIconProps } from "../types/reference";
+import { cx } from "../lib/cx.ts";
+
+export type StateIconProps = ReferenceStateIconProps;
+
+/** State hue classes. The shape carries meaning; the hue reinforces it. */
+const STATE_CLASS: Record<RecordState, string> = {
+  proposed: cx("text-state-proposed"),
+  ready: cx("text-state-ready"),
+  scheduled: cx("text-state-scheduled"),
+  active: cx("text-state-active"),
+  blocked: cx("text-state-blocked"),
+  "in-review": cx("text-state-in-review"),
+  complete: cx("text-state-complete"),
+  deferred: cx("text-state-deferred"),
+  canceled: cx("text-state-canceled"),
+};
+
+const CUT = "var(--color-bg-canvas)";
+
+function ring(extra: Record<string, string> = {}): ReactNode {
+  return (
+    <circle cx={8} cy={8} r={6} fill="none" stroke="currentColor" strokeWidth={1.5} {...extra} />
+  );
+}
+
+function shape(state: RecordState): ReactNode {
+  switch (state) {
+    case "proposed":
+      return ring({ strokeDasharray: "2.2 2.2" });
+    case "scheduled":
+      return (
+        <>
+          {ring()}
+          <path
+            d="M8 5v3.25l2 1.25"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={1.5}
+            strokeLinecap="round"
+          />
+        </>
+      );
+    case "active":
+      return (
+        <>
+          {ring()}
+          <path d="M8 4.5a3.5 3.5 0 0 1 0 7z" fill="currentColor" />
+        </>
+      );
+    case "blocked":
+      return (
+        <>
+          <path d="M5.5 2h5L14 5.5v5L10.5 14h-5L2 10.5v-5z" fill="currentColor" />
+          <path d="M5.5 8h5" stroke={CUT} strokeWidth={1.5} strokeLinecap="round" />
+        </>
+      );
+    case "in-review":
+      return (
+        <>
+          {ring()}
+          <path
+            d="M4.75 8s1.25-2 3.25-2s3.25 2 3.25 2s-1.25 2-3.25 2s-3.25-2-3.25-2z"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={1.25}
+          />
+          <circle cx={8} cy={8} r={0.9} fill="currentColor" />
+        </>
+      );
+    case "complete":
+      return (
+        <>
+          <circle cx={8} cy={8} r={6.75} fill="currentColor" />
+          <path
+            d="M5.25 8.25l1.75 1.75l3.5-4"
+            fill="none"
+            stroke={CUT}
+            strokeWidth={1.5}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </>
+      );
+    case "deferred":
+      return (
+        <>
+          {ring()}
+          <path
+            d="M6.75 5.75v4.5M9.25 5.75v4.5"
+            stroke="currentColor"
+            strokeWidth={1.5}
+            strokeLinecap="round"
+          />
+        </>
+      );
+    case "canceled":
+      return (
+        <>
+          {ring()}
+          <path d="M4 12l8-8" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" />
+        </>
+      );
+    default:
+      return ring();
+  }
+}
+
+/** One of the nine record state icons, drawn by this system (filled and half-filled shapes). Decorative: pair it with a label. */
+export function StateIcon({ state, size = 14 }: StateIconProps): ReactElement {
+  return (
+    <svg
+      className={cx(
+        "inline-block flex-none align-middle",
+        STATE_CLASS[state] ?? "text-text-secondary",
+      )}
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      aria-hidden="true"
+      data-state={state}
+    >
+      {shape(state)}
+    </svg>
+  );
+}

package/src/StatusHeatmap/README.md

@@ -0,0 +1,15 @@
+# StatusHeatmap
+
+StatusHeatmap crosses rows with columns, one state per cell: the recipients of an advance packet by its sections, the
+people on a roster by readiness category, or the parties of a project by offering (R11, Section 11.11).
+
+- Props: `label`, `corner`, `rows` (`{ id, label, sublabel }`), `cols` (`{ id, label }`), `cells` keyed
+  `<row id>:<col id>` to `{ state, href, detail, readOnly }` (`detail` shows under the state; a `readOnly` cell keeps its
+  focus but opens nothing), `legend` (`{ state, icon, label }`), optional `selection` for a
+  bulk action on rows, and `onCellSelect`.
+- An ARIA grid with `useGridFocus`, like CoordinateMatrix: arrows move between cells, Home and End go to the row's
+  ends (with Ctrl or Cmd, the grid's), and Enter or Space opens a cell (`onCellSelect`, else the cell's `href`).
+- Every state shows its `StateIcon` and its label, never color alone. A row and column with no cell reads "not asked".
+- The table is its own accessible alternative: row and column headers name every cell, and the legend lists each
+  state once. Wide grids scroll inside a `ScrollRegion`, so a 375 px page never scrolls sideways.
+- Atlas imports it directly on Advancing > Progress, the default section of a route that is not a key page: a control that renders on arrival loses its first clicks behind `next/dynamic` (ADR 0027).

package/src/Stepper/README.md

@@ -0,0 +1,3 @@
+# Stepper
+
+Stepper shows wizard progress across the top; each step saves when completed.

package/src/Surface/Skeleton.tsx

@@ -0,0 +1,21 @@
+import type { ReactElement } from "react";
+import type { SkeletonProps as ReferenceSkeletonProps } from "../types/reference";
+
+export type SkeletonProps = ReferenceSkeletonProps;
+
+/**
+ * Reserves space for streamed content; stops pulsing under reduced motion. A module of its own:
+ * route loading boundaries render it on every visit, so it brings nothing else along (ADR 0027).
+ */
+export function Skeleton({ width, height }: SkeletonProps): ReactElement {
+  return (
+    <span
+      aria-hidden="true"
+      className="xos-anim-pulse block rounded-chip bg-bg-hover"
+      style={{
+        inlineSize: width ?? "var(--ui-skeleton-inline)",
+        blockSize: height ?? "var(--ui-skeleton-block)",
+      }}
+    />
+  );
+}

package/src/Surface/Surface.tsx

@@ -0,0 +1,63 @@
+import type { ReactElement } from "react";
+import type {
+  CardProps as ReferenceCardProps,
+  DividerProps as ReferenceDividerProps,
+} from "../types/reference";
+import { cx } from "../lib/cx.ts";
+
+export { Skeleton, type SkeletonProps } from "./Skeleton.tsx";
+
+export type CardProps = ReferenceCardProps & { className?: string };
+export type DividerProps = ReferenceDividerProps;
+
+export const cardClass = cx(
+  "bg-bg-raised border border-border-subtle rounded-card forced-colors:border-[CanvasText]",
+  "print:bg-paper print:text-paper-ink print:shadow-none",
+);
+export const cardHeadClass = cx(
+  "flex items-center justify-between gap-8 px-16 py-12 border-b border-border-subtle",
+);
+export const cardBodyClass = cx("flex flex-col gap-12 p-16");
+export const cardFootClass = cx(
+  "flex items-center justify-end gap-8 px-16 py-12 border-t border-border-subtle",
+);
+
+/** A raised region with an optional title, meta and footer. `interactive` strengthens the border on hover. */
+export function Card({
+  title,
+  meta,
+  footer,
+  interactive = false,
+  children,
+  className,
+}: CardProps): ReactElement {
+  return (
+    <section className={cx(cardClass, interactive && "hover:border-border-strong", className)}>
+      {title ? (
+        <header className={cardHeadClass}>
+          <strong className="font-semibold">{title}</strong>
+          {meta ? <span className="text-text-secondary">{meta}</span> : null}
+        </header>
+      ) : null}
+      <div className={cardBodyClass}>{children}</div>
+      {footer ? <footer className={cardFootClass}>{footer}</footer> : null}
+    </section>
+  );
+}
+
+/** A hairline rule, or a labeled separator between groups. */
+export function Divider({ label }: DividerProps): ReactElement {
+  if (!label) return <hr className="h-(--stroke-width-hairline) my-8 border-0 bg-border-subtle" />;
+  return (
+    <div
+      role="separator"
+      aria-label={label}
+      className={cx(
+        "flex items-center gap-8 my-8 text-text-11 text-text-tertiary",
+        "before:h-(--stroke-width-hairline) before:flex-1 before:bg-border-subtle after:h-(--stroke-width-hairline) after:flex-1 after:bg-border-subtle",
+      )}
+    >
+      <span aria-hidden="true">{label}</span>
+    </div>
+  );
+}

package/src/SurfaceTriptych/README.md

@@ -0,0 +1,7 @@
+# SurfaceTriptych
+
+SurfaceTriptych presents the three XOS surfaces side by side, each with its audience and its release status.
+
+Each card names the surface, who uses it and what it does, and carries a Tag with the status. Status is always a word beside the dot, never color alone. A surface that is not released says so here; the page never implies availability the source does not support.
+
+The consumer provides name, audience, body, status and up to three points per surface.