import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Introduction" />

# UI Kit

This is the workbench for a component library that gets **published**, not an app.
Every component you see here ships to teammates as its own import path.

```tsx
import '@your-team/ui/styles.css';
import { Button } from '@your-team/ui/button';
```

## How it is put together

**One folder per component.** `src/components/button/` holds the implementation,
its stories, its tests and an `index.ts`. That `index.ts` is what creates the
`@your-team/ui/button` subpath — `scripts/gen-exports.mjs` reads the folder
layout and writes `package.json#exports` from it. There is no hand-maintained
list to forget to update.

**Two token layers.** `tokens.css` holds raw values (`--ui-color-brand-500`).
`theme.css` maps them onto roles (`--primary`) and exposes those to Tailwind.
Components only ever use the role names. Rebranding therefore means editing one
file — or letting the `figma-sync` skill rewrite it from your Figma Variables.

**Styles ship compiled.** The published package carries a `styles.css` built by
the Tailwind CLI, so a consuming app needs no Tailwind configuration at all.
Apps that already run Tailwind v4 can import the token layers instead and let
their own build produce the utilities.

## Using this Storybook

- The **theme toggle** in the toolbar switches the `dark` class on the preview
  root — the same mechanism a consuming app uses.
- **Design Tokens** renders the live token values. Change `tokens.css` and the
  swatches move with it; that is the check that nothing is hardcoded.
- The **Accessibility** panel runs axe on every story. Violations are treated as
  failures, not warnings.

## Adding a component

```bash
/ui-kit-component <name>     # Claude Code: folder + story + test + exports
```

By hand: `npx shadcn@latest add <name>`, move the generated file into its own
folder, add an `index.ts` starting with `'use client'`, then run
`pnpm exports:gen`.