# @exxatdesignux/ui

The Exxat Design System — a Vite + React 19 + Tailwind v4 component
library plus the full hub-page stack (`ListPageTemplate`, `DataTable`,
`HubTable`, `TablePropertiesDrawer`, `KeyMetrics`, `PageHeader`, board
cards, charts, …) wrapped in one publishable package.

## 60-second start

Spin up a brand-new app pre-wired with the DS:

```bash
pnpm create exxat-app my-app
cd my-app
pnpm dev
```

Works with every modern package manager — the scaffolder auto-detects
the runner and uses the matching install:

```bash
npm  create exxat-app my-app
yarn create exxat-app my-app
bun  create exxat-app my-app
```

The scaffolder ships a complete Vite + react-router-dom starter: the reference
**Library** hub at `/library/all`, the `/columns` cell-catalog showcase,
typed mock data, plus the full Cursor + Claude agent bundle dropped into
the right paths **automatically**:

- `.cursor/rules/exxat-*.mdc` — 29 binding rules (Cursor reads these as
  always-on / agent-requestable).
- `.cursor/skills/exxat-*/` and `.claude/skills/exxat-*/` — 16 skill
  bundles (`SKILL.md` + references); same source written to both readers.
- `docs/exxat-ds/*.md` — 6 pattern docs (data views, command menu,
  drawer-vs-dialog, KPI flat band, …) + the consumer upgrade checklist.
- `docs/exxat-ds/handbook/*.md` — HANDBOOK · glossary · voice-and-tone ·
  reference-implementations.
- `AGENTS.md` (root) — the project's AI handbook from the reference app.

When you `cd my-app` and open Cursor for the first time, every binding
rule, skill, and pattern doc is already in place. To opt out, pass
`--no-extras` to the scaffolder; you can run it later with
`exxat-ui sync-extras` (see below).

## Adding to an existing Vite app

If you already have a Vite + React app and just want the components:

```bash
pnpm add @exxatdesignux/ui
```

Then in your global CSS (e.g. `app/globals.css`):

```css
@import "@exxatdesignux/ui/globals.css";
```

And import primitives or full patterns from the umbrella or a subpath:

```tsx
import { DataTable, HubTable, ListPageTemplate, KeyMetrics } from "@exxatdesignux/ui"
import { Button } from "@exxatdesignux/ui/components/button"
import { useTableState } from "@exxatdesignux/ui/components/data-table/use-table-state"
```

Mount `KeyMetricsProvider` near the root if you want the "Ask Leo about
these metrics" CTA wired to your AI surface (otherwise the strip just
hides that button automatically).

## Refresh Cursor / Claude agent bundle in any consumer

`pnpm create exxat-app` drops the agent bundle for you on first scaffold.
When you upgrade `@exxatdesignux/ui` later — or when you want to seed the
bundle into an **existing** Vite app that already depends on the DS —
run:

```bash
pnpm dlx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
```

The command is **namespaced**: it only writes files starting with
`exxat-` (rules + skills) and only inside `.cursor/`, `.claude/skills/`,
and `docs/exxat-ds/`. Your own rules, skills, AGENTS.md, and product
code are never touched.

## What's inside

- **Primitives** (`@exxatdesignux/ui/components/<name>`) — Button, Input,
  Select, Dialog, AlertDialog, Sheet, Popover, DropdownMenu,
  ContextMenu, Tabs, Accordion, Tooltip, Toast-free Banner, ScrollArea,
  Slider, HoverCard, Avatar, Badge, StatusBadge, Calendar, Kbd, …
- **Hub stack** — `DataTable<TRow>`, `useTableState<TRow>`,
  `TablePropertiesDrawer`, `HubTable<TRow>`, `ListPageTemplate`,
  `PageHeader`, `KeyMetrics`, `ListPageBoardCard`,
  `ListPageBoardTemplate`, `DataRowList`, `FinderPanelView`,
  `FolderGridView`, `OutlineTreeMenu`.
- **Data-list registry** — `DataListViewType`, `DATA_LIST_VIEW_TILES`,
  `dataListViewIcon`, `dataListViewAddShortcut`, `usesDataTableComponent`,
  `usesDashboardSurface`.
- **Templates** — `ListPageTemplate`, `NestedSecondaryPanelShell`,
  `DedicatedSearchLandingTemplate`, `DedicatedSearchResultsTemplate`.
- **Tokens** — `tokens/hooks-index.json` (197 tokens · 42 namespaces)
  feeds the workspace ESLint plugin's `no-deprecated-tokens` rule.
- **Tailwind v4 token bridge** — `globals.css` imports the L0
  `--exxat-color-*` / `--exxat-radius-*` / `--exxat-spacing-*` family
  and wires Tailwind shorthand (`bg-surface-1`, `text-ink-1`,
  `rounded-2`, …) via `@theme inline`.

## CLI commands

After `pnpm add @exxatdesignux/ui` (or globally `npm i -g @exxatdesignux/ui`):

```bash
# In an empty directory (or new sub-folder), scaffold an app:
npx --package=@exxatdesignux/ui create-exxat-app my-app

# Sync Cursor skills + binding rules + pattern docs into your repo:
npx --package=@exxatdesignux/ui exxat-ui sync-extras
```

The standalone [`create-exxat-app`](https://www.npmjs.com/package/create-exxat-app)
package wraps the first command so `<pm> create exxat-app …` resolves
natively.

## Docs

- Design-system **HANDBOOK** — read-this-first orientation, the 6-step
  "how to build a hub" walkthrough, the §13 PR checklist.
- **Blueprints** — framework-agnostic specs for each major composition
  (`PageHeader`, `DataTable`, `ListPageTemplate`, `BoardCard`,
  `KeyMetrics`, …).
- **Component selection guide** — top-of-funnel decision tree for
  picking the right composition.
- **Token taxonomy** — naming + deprecation policy for every CSS
  custom property the DS ships.

The full doc set is mirrored under `handbook/` and `patterns/` in this
package; `pnpm create exxat-app` drops them at `docs/exxat-ds/` on first
scaffold, and `exxat-ui sync-extras` re-syncs them in any later upgrade.

## Compatibility

| Peer | Range |
| --- | --- |
| React | `>=19.0.0` |
| Vite | `>=6.0.0` |
| react-router-dom | `>=7.0.0` |
| Tailwind CSS | `>=4.0.0` |

## License

UNLICENSED — proprietary to Exxat Design.