# Exxat DS starter app

Builder-facing Vite + React starter for products that consume `@exxatdesignux/ui`.
It opens with a working Exxat shell, product switcher, token system, sample
routes, and architecture guardrails so the first run is useful instead of blank.

## AI / Contributors

- **Handbook:** [`AGENTS.md`](./AGENTS.md) — MUST/MUST NOT rules, list pages, accessibility, checklist.
- **Cursor rules:** [`.cursor/rules/`](./.cursor/rules/) — data tables, product routing, keyboard hints, accessibility, token discipline.
- **Skills:** [`.cursor/skills/`](./.cursor/skills/) and [`.claude/skills/`](./.claude/skills/) — UX brief, DS patterns, accessibility, and React doctor workflows.

## Architecture Boundaries

Use this starter as the product shell, not as a place to fork the design system:

- **No product-specific business logic in `packages/ui`.** Product routes own domain data, API wiring, workflow copy, and mocks.
- **No reusable component invented inside a product route.** Build locally first; promote to the DS only after a repeated need is clear.
- **One token system.** Theme products through Exxat DS tokens, not app-local color scales.
- **One shell pattern.** Product switcher, sidebar, page headers, persistence, shortcuts, and Ask Leo come from the shared shell.
- **Golden-path templates.** Start new products from this scaffold and replace placeholder routes intentionally.
- **Release gates.** Before publishing DS package updates, run visual, accessibility, lint, type, and migration checks against the reference app.
- **Versioned migrations.** If consuming products upgrade from npm, document breaking changes and migration steps with each release.

## Development

Run from this app directory:

```bash
pnpm install
pnpm dev
```

Open **http://localhost:5000**. Customer apps live on the **5000-series**
so they coexist with the Exxat DS app (`apps/web` → `:4000`) on the same
machine. Alternative ports:

```bash
pnpm dev:5001   # http://localhost:5001
pnpm dev:5005   # http://localhost:5005
```

## First-Run Map

- `/prism/dashboard` — builder starter workspace and architecture guardrails.
- `/library/all` — working hub example with DS list/table patterns.
- `/tokens-themes` — token and theme inspection surface.
- `/settings/organization` — product registration and branding setup.
- Product routes without real IA show a builder-facing shell placeholder so the route does not feel broken.

## Importing from the shared UI package

```tsx
import { Button } from "@exxatdesignux/ui/components/button"
import { usePersistedState } from "@exxatdesignux/ui/lib/persisted-state"
import { defineProduct } from "@exxatdesignux/product-framework"
```

In this scaffold, local re-export files under `components/` and `lib/` mirror the
published package API. Product code should consume the local shell composition
and avoid importing package internals.

## Adding components (shadcn)

```bash
npx shadcn@latest add button
```

Only add local components when they are product-specific. Reusable primitives
belong in the DS package after reuse is proven.
