# Consumer extras (ships with `@exxatdesignux/ui`)

These folders are **not** application content. They are design-system reference
material that other repositories can **refresh from the npm package** without
touching product routes or pages.

| Path in this tarball | After `exxat-ui sync-extras` in your repo |
|----------------------|-------------------------------------------|
| `CHANGELOG.md` (package root) | Stays in `node_modules/…` — read for release notes; **`exxat-ui changelog`** prints it |
| `cursor-skills/exxat-*` | `.cursor/skills/exxat-*` **and** `.claude/skills/exxat-*` (replaced; same `SKILL.md` shape, two readers) |
| `cursor-skills/exxat-package-upgrade/` | Install/upgrade agent — changelog → `sync-extras` → generated-starter shell port; **never** mock data or tenant copy |
| `cursor-hooks/exxat-*.mjs` + `cursor-hooks/hooks.json` | `.cursor/hooks/exxat-*.mjs` + `.cursor/hooks.json` merge **and** `.claude/hooks/exxat-*.mjs` + `.claude/settings.json` merge (brief-gate hook wired for both clients) |
| `cursor-rules/exxat-*.mdc` | `.cursor/rules/exxat-*.mdc` **and** `.claude/rules/exxat-*.mdc` (replaced) — binding **MUST / MUST NOT** files |
| `cursor-rules/_constitution.exxat-ds.mdc` | `.cursor/rules/_constitution.exxat-ds.mdc` **and** `.claude/rules/_constitution.exxat-ds.mdc` — four-file always-on stack + ten commandments |
| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) — pattern docs, **`component-selection-guide.md`** (UX router), **`INDEX.yaml`**, **`agent-context-architecture.md`**, **`consumer-upgrade-checklist.md`** |
| `handbook/*.md` | `docs/exxat-ds/handbook/*.md` (replaced) — `HANDBOOK`, `glossary`, `voice-and-tone`, `reference-implementations` |
| `templates/handoff.md` | `docs/exxat-ds/templates/handoff.md` (replaced) — design → engineering handoff artifact (the agent fills this in at the close of every design task) |
| `scripts/dev-guard.mjs` | Runs in place via `exxat-ui dev-guard` (no copy) — wire as `predev` to abort if a sibling `vite` is already running and stacking memory |
| `scripts/agent-context-router.mjs` | Runs in place via `exxat-ui context <surface>` — prints the smallest DS context packet by surface archetype before agents open docs |

## CLI — what each subcommand does for your team

```bash
# Scaffold a new app (Vite + React + react-router-dom — fast cold start, ~250–400 MB RSS):
npx --package=@exxatdesignux/ui@latest create-exxat-app my-app

# Engineering quality-gate — read DS rules + UX principles for a file:
npx --package=@exxatdesignux/ui@latest exxat-ui audit src/views/students.tsx

# Agent token budget — choose the smallest DS packet by surface archetype:
npx --package=@exxatdesignux/ui@latest exxat-ui context hub-list

# Memory guard for designers running long dev sessions:
"scripts": { "predev": "exxat-ui dev-guard" }
```

`dev-guard` lists every running `vite` parent and refuses to start a second
one without confirmation. Per `patterns/perf-memory-pattern.md` §2, two
parallel Vite servers stabilize at ~500–800 MB combined and confuse HMR —
even though they're 8× lighter than the Next dev servers this CLI used to
guard against (May 2026 migration).

## Rule tiers (`appliesTo:` metadata)

Every shipped `.mdc` rule carries an `appliesTo:` field:

- `[universal]` — UX principles, accessibility floor, anti-patterns, decision
  frameworks. Works for any framework (HTML, React, Vue, iOS).
- `[react]` — cites React component names / hooks / JSX. Auto-attaches via
  `globs:` when the agent edits matching files; not always-on.

Today this is documentation metadata. It is positioned for a future
`exxat-ui sync-extras --stack=html` flag that filters out `[react]` rules
for non-React consumers.

The CLI is **namespaced**: it only touches files starting with `exxat-` (skills + rules)
so a consumer's own non-Exxat rules / skills are preserved. Product code under `app/`,
`pages/`, `src/`, plus the consumer's `AGENTS.md` and any of their own docs are never
modified.

**Components and hooks** still come only from `node_modules/@exxatdesignux/ui`
via normal semver installs — `sync-extras` does not copy TS source into your app.

**Maintainers** (this monorepo): when skills, rules, or web docs change, run:

```bash
pnpm --filter @exxatdesignux/ui vendor:consumer-extras
```

…then bump `packages/ui` version and publish so consumers get the new bundle.

## What lands where (full install map)

```
<consumer-repo>/
├── .cursor/
│   ├── rules/exxat-*.mdc         ← binding MUST / MUST NOT (cursor-rules/)
│   ├── skills/exxat-*/SKILL.md   ← agent workflows + checklists (cursor-skills/)
│   ├── hooks/exxat-*.mjs         ← brief-gate scripts (cursor-hooks/)
│   └── hooks.json                ← merged; preserves consumer hooks, replaces exxat hooks
├── .claude/
│   ├── rules/exxat-*.mdc         ← Claude mirror of cursor-rules (same MUST / MUST NOT)
│   ├── skills/exxat-*/SKILL.md   ← Claude mirror of the same skills (cursor-skills/)
│   ├── hooks/exxat-*.mjs         ← Claude brief-gate scripts (from cursor-hooks/)
│   └── settings.json             ← merged PreToolUse hook entry for exxat-brief-gate
└── docs/
    └── exxat-ds/
        ├── *-pattern.md          ← narrative pattern docs (patterns/)
        ├── consumer-upgrade-checklist.md
        ├── handbook/
        │   ├── HANDBOOK.md
        │   ├── glossary.md
        │   ├── voice-and-tone.md
        │   └── reference-implementations.md
        └── templates/
            └── handoff.md         ← design → engineering handoff artifact
```

## Note on handbook link rewriting

The bundled handbook files (`handbook/*.md`) are stage-rewritten copies of the
workspace source (`apps/web/docs/*.md`). Inter-doc links are normalised at
bundle time:

- Links to files we ship → relative (`./glossary.md`, `../data-views-pattern.md`)
- Links to files we don't ship (blueprints, `token-taxonomy.md`, `component-selection-guide.md`, `lib/*`, root `AGENTS.md`) → absolute GitHub URLs

This keeps every link clickable from the consumer's `docs/exxat-ds/handbook/`
directory without requiring them to clone the workspace.