ui-kit/README.md

# @jason/ui-kit

Shared design foundation for all my apps. One brand system, reused everywhere — so
new apps start polished and existing apps have a clear upgrade path.

Built on the stack I already use (**React + Vite + Tailwind + TypeScript**) and
guarded by [Impeccable](https://impeccable.style) so nothing ships looking like a
generic AI-generated template.

## What's inside

- **Generated design tokens + Tailwind preset** — accessible dark/light palettes, semantic foregrounds, radius/shadow/motion scales, and a parity check that prevents CSS/TypeScript drift.
- **Theme runtime + optional self-hosted fonts** — persisted dark/light/system mode, a no-flash script, and Latin variable-font delivery.
- **`cn()`** helper (clsx + tailwind-merge) — the standard everywhere.
- **Primitives** — Button, Card, FormField, Input, Select, Checkbox, Switch, Tabs, Tooltip, Badge, Dialog, DropdownMenu, Table, Pagination, Skeleton, and Toaster. Radix-backed, accessible, pre-themed.
- **Motion** — `FadeIn`, `Stagger` (framer/`motion`, reduced-motion aware).
- **Animated** — `AnimatedNumber` (count-up stats), `SpotlightCard` (cursor glow).
- **Blocks** — responsive `AppShell` (desktop sidebar + mobile drawer), `CommandPalette` (⌘K), `Hero`, `FeatureGrid`, `Pricing`.
- **Living showcase** — executable coverage of themes, states, product UI, and marketing blocks.
- **Impeccable** wired in — `DESIGN.md` / `PRODUCT.md` design context, config, and a CI anti-slop detector.

## Install (in a consuming app)

This package publishes to the Gitea npm registry. Add an `.npmrc` (see `.npmrc.example`):

```
@jason:registry=https://git.alwisp.com/api/packages/jason/npm/
//git.alwisp.com/api/packages/jason/npm/:_authToken=${GITEA_NPM_TOKEN}
```

Then:

```bash
npm install @jason/ui-kit
```

### Wire up Tailwind

```js
// tailwind.config.js
module.exports = {
  presets: [require("@jason/ui-kit/preset")],
  content: [
    "./index.html",
    "./src/**/*.{ts,tsx}",
    "./node_modules/@jason/ui-kit/dist/**/*.js", // so kit classes aren't purged
  ],
};
```

```ts
// app entry (main.tsx)
import "@jason/ui-kit/styles.css";
```

Load the branded variable fonts as an opt-in asset:

```ts
import "@jason/ui-kit/fonts.css";
import "@jason/ui-kit/styles.css";
```

### Use it

```tsx
import {
  Button, FormField, Input, ThemeProvider, ThemeScript, Toaster
} from "@jason/ui-kit";

<ThemeScript />
<ThemeProvider>
  <FormField label="Workspace name" description="Shown in navigation.">
    <Input />
  </FormField>
  <Button>Save</Button>
  <Toaster />
</ThemeProvider>
```

## Develop

```bash
npm ci
npm run dev          # tsup watch build
npm run demo         # root demo.html using the real kit components
npm run showcase     # living component review surface
npm run check        # tokens, types, tests, builds, and design detector
```

The portable project entry is [`demo.html`](./demo.html). Open
`http://localhost:5173/demo.html` after running `npm run demo`.

## Publish a new version

```bash
npm version patch      # or minor / major
npm publish            # builds via prepare, pushes to Gitea registry
```

## Extending with 21st.dev

This kit is the base layer. For richer one-off blocks, pull
[21st.dev](https://21st.dev) components (shadcn-registry compatible) into an app,
then re-theme them with these tokens and, if broadly useful, promote them into
`src/blocks/` here. Run `/impeccable polish` on anything new before it ships.

See **DESIGN.md** for the full system spec and **MIGRATION.md** for adopting the
kit in apps that already exist.