@ai-matrx/design-system

The small, semantic UI foundation shared by AI Matrx React applications — primitives whose behavior and variants are identical across Vite and Next.js hosts.

Controls: Button, Badge, Label, Separator, the Input family, the Textarea family, Checkbox, Switch, RadioGroup, Slider, Toggle + ToggleGroup, Avatar, Progress. Content transfer: @ai-matrx/design-system/content-transfer supplies Matrx Alchemy's inlined glyph, accessible menu, projected capture workspace, optional AI capability seam, and locally scoped SurfaceHandle provider. Its source is captured on user action; preparation keeps an immutable original, preserves manual and alternate-source sessions, fences stale async results, and routes every copy/download through Transport. Import @ai-matrx/design-system/content-transfer.css with the package structural sheets.

<MatrxCopyMenu
  label="Log"
  export={{
    items: [
      {
        id: "raw",
        label: "Download raw log",
        build: () => ({
          content: rawText,
          filename: "worker.log",
          extension: "txt",
          mime: "text/plain",
        }),
      },
    ],
  }}
/>

An explicit filename is an exact safe basename captured with its bytes. Omit it to use the label-derived default; unsafe values fail the export visibly. Surfaces: Card, Table, Tabs, Accordion, Collapsible, ScrollArea, Popover, Tooltip, HoverCard, Sheet, Dialog, AlertDialog, Drawer, BottomSheet + TabbedBottomSheet, Alert, Resizable, Skeleton. Menus: DropdownMenu, ContextMenu, Command / CommandDialog, Select, CreatablePicker. Composed: EditableLabel, SegmentedControl, ArchiveFilter, ScoreRing, OverflowToolbar, ConfirmDialog + ConfirmDialogHost. Hooks + utilities: useScrollFade, useIsMobile, usePortalContainer, useDialogContainer, useDrawerDirection, cn.

The confirm dialog lives here; the imperative confirm() lives in @ai-matrx/kit. Since 0.11.0 / kit 0.9.0 the surface is one implementation, in the package that owns AlertDialog, the motion layer and the overlay scrim token. Mount the host once near your provider root and call confirm() from anywhere — they share one registry through a globalThis slot:

// app root, once
import { ConfirmDialogHost } from "@ai-matrx/design-system";
<ConfirmDialogHost />

// anywhere — a thunk, a util, a click handler
import { confirm } from "@ai-matrx/kit/confirm-opener";
if (!(await confirm({
  title: "Re-run research",
  description: "This discards the 14 pages you already have (~$50 and 10 minutes) and starts over.",
  variant: "destructive",
  confirmLabel: "Discard and re-run",
}))) return;

Use the declarative <ConfirmDialog open … busy /> inline instead when the dialog must stay open with a spinner while async work finishes. Name the consequence: a confirmation that says only "Are you sure?" does not satisfy the platform's destructive-and-expensive-actions law.

Footer actions stay touch-sized through portals. Dialog, AlertDialog, Drawer, Sheet, and BottomSheet footers apply a 44px action floor on coarse pointers or below 1024px. Import the package stylesheet; no host subtree class is required. Fine-pointer desktop keeps its declared density. State controls and prose links retain their sizing; exceptional compact actions can use data-touch-exempt with a call-site reason.

Every list over an archivable entity uses ArchiveFilter. THE ARCHIVED-ITEMS LAW (Arman, 2026-09-09 — common-docs/policies/archived-items.md): an archive filter on every list, the default hides archived rows, and seeing them is one click. ArchiveFilter is the one control — active (default) / archived / all, in the same words the Next.js app uses.

import { ArchiveFilter, DEFAULT_ARCHIVE_FILTER, type ArchiveFilterValue } from "@ai-matrx/design-system";

const [archived, setArchived] = React.useState<ArchiveFilterValue>(DEFAULT_ARCHIVE_FILTER);
const rows = useRows({ archived });   // the SERVER applies the predicate

<ArchiveFilter value={archived} onValueChange={setArchived} counts={{ active: rows.activeCount }} />

Pass the value to the reader, never filter the already-fetched page: counts, badges and pagination must describe what the list renders. toArchiveFilter() narrows an untrusted value (URL param, stored preference) back to the tri-state, defaulting to active so nothing silently widens.

The Tooltip lives here, and only here. @ai-matrx/tap-target used to ship its own copy; since design-system 0.7.0 / tap-target 0.2.0 it consumes this one and re-exports nothing.

Where hosts had forked a primitive over DENSITY, density is a prop, not a fork: Card size="sm|md|lg", Table size="sm|md", Accordion size="sm|md", Switch/Avatar/Checkbox/Slider/RadioGroup/Toggle size, ResizableHandle size="xs".."4xl". It is declared once on the root and every item reads it from context, so a card cannot mix paddings and a radio group cannot mix control sizes.

Motion ships with the component — ALL of it. Every animated surface here (Dialog, AlertDialog, Sheet, CommandDialog, Popover, DropdownMenu, ContextMenu, HoverCard, Select, Tooltip, Accordion, Collapsible, Skeleton) animates out of the box from keyframes in styles.css. You never define keyframes, add an animate-* utility, or install tailwindcss-animate / tw-animate-css for anything this package renders — that plugin is loaded from a host's CSS entry, which is why three of the four apps that already used this package had zero animation on every overlay and no error to show for it (0.10.0). prefers-reduced-motion is honoured in the sheet.

Retiming is a token change, not an override — set --matrx-motion-duration-fast / -base / -slow / -sheet, --matrx-motion-ease-out / -in, or --matrx-motion-popper-travel. For one surface that must appear instantly, pass animated={false}; CollapsibleContent's opt-out additionally stops it clipping its body, for the rare panel with a child that must overflow.

Mobile is the Drawer's job. Drawer owns the iOS rules every host was re-deriving — dvh never vh, pb-safe/pt-safe safe-area padding, a 44px grab-handle target, DrawerBody as the flex-1 min-h-0 scroll shard — and direction makes a top/side drawer a prop rather than a fork. Every touch control (Slider, RadioGroup, ResizableHandle) carries an invisible 44px target on coarse pointers, with desktop density untouched.

pnpm add @ai-matrx/design-system

import { Badge, Button } from "@ai-matrx/design-system";

<Button variant="subtle" size="sm">Add step</Button>
<Badge variant="success">Ready</Badge>

Host-shaped systems are injected, never imported: wrap subtrees in PortalContainerProvider to point nested Popover portals at a dialog or popout body, and hand OverflowToolbar your menu and tooltip systems through its renderOverflowMenu / renderTooltip props. @ai-matrx/kit is a real dependency (installed automatically).

Styling — the package ships its CSS, the host owns the values

The package is opinionated about the token contract and ships every rule its components need to work; it is not opinionated about your colours.

// app root, once
import "@ai-matrx/design-system/tokens.css"; // default token VALUES  — override these
import "@ai-matrx/design-system/styles.css"; // structural CSS        — required

/* your Tailwind/CSS entry — FIRST line, before @import "tailwindcss" */
@layer matrx-design-system-tokens, matrx-design-system;

• styles.css (required) — every rule the components need to render right: the .matrx-scroll-fade mask geometry behind useScrollFade, the .matrx-mobile-sheet density restatement TabbedBottomSheet sets, the .matrx-glass-thin-border chrome, .pb-safe, .shadow-input. It hardcodes no colour: every colour resolves from a token.
• tokens.css (default values) — a neutral, sensible default for every token the package reads, in both themes, so a fresh app renders correctly unthemed. This is not a brand.
• theme.css (Tailwind v4 hosts, optional) — @import "@ai-matrx/design-system/theme.css"; from your Tailwind entry maps the semantic colour utilities (bg-background, text-muted-foreground, …) onto those tokens and registers the package build as a scan source. A host that already maps this vocabulary (matrx-frontend does, as a branded superset) skips this file and keeps its own.

Overriding with your brand. Redeclare any token — --primary, --background, the --matrx-glass-* material, the overlay scrims — anywhere in your own CSS. The package defaults live in the matrx-design-system-tokens layer, and the one-line @layer declaration above puts that layer at the bottom of the cascade, so any host declaration wins: layered or unlayered, before or after, whatever the specificity. Declare the layer order once and the question never arises.

Tailwind CSS v4 ignores node_modules by default, so a host that does not import theme.css still registers the package build beside its Tailwind import:

@import "tailwindcss";
@source "../node_modules/@ai-matrx/design-system/dist";

Workspace consumers point @source at apps/shared/design-system/src.

Release gate

pnpm --filter @ai-matrx/design-system typecheck
pnpm --filter @ai-matrx/design-system test
pnpm --filter @ai-matrx/design-system check:package

The gate validates declarations and exports against the packed tarball, installs it into an empty project, and imports the public entry point.

Data tables

import { MatrxDataTable } from "@ai-matrx/design-system/data-table";
import { usePaginatedData } from "@ai-matrx/data/react";

// The caller owns loadPage, source identity, and query state.
const pagination = usePaginatedData({ queryKey, initialCursor: 0, loadPage, getRowId });
<MatrxDataTable data={pagination.rows} columns={columns} getRowId={getRowId}
  query={{ mode: "controlled-append", state, onStateChange, pagination,
    scroll: { mode: "scroll", thresholdPx: 96, intentTimeoutMs: 1200 } }} />;

URL/source owners can control columns without rebuilding the table: pass columnState={{ order, hidden, onChange }} and reorderableColumns. The package then commits both the Columns dialog and header drag through onChange. The dialog provides drag ordering and labelled arrow controls; columns marked hideable: false remain visible.

Use application-resolved preferences for scroll; manual always retains Load more. Numbered exact-page sources use controlled with totalItems; fully loaded client arrays use local mode or controlled-local. Partial server results must not claim client filtering searched the entire source. Query identity must cover authentication, organization, filters, sort, and page size. A page loader receives an AbortSignal and returns rows, a next cursor (null when complete), and an optional exact total. Repeated cursors fail visibly instead of looping.

Framework-specific identity ports are optional via @ai-matrx/design-system/data-table/host. Utilities and types have dedicated subpaths listed in the export map. The package retains copy/subset/export, row windows, hierarchy, selection, inline editing, and accessible manual pagination.

Editable append tables keep drafts separately for each query identity during the component lifetime. A return to that identity restores its drafts; drafts from other results offer Copy and confirmed Discard, never a save against the current rows. Applications own persistence across unmounts and must remount the table when changing authenticated users so prior-user drafts are not exposed.