# Registry

Registry items live under `registry/items/<section>/<name>/`. `<section>` is `components`, `blocks`, `utilities`, or `files`. Each item is a folder with an `_registry.svx` metadata file, a live preview, and a Storybook story. There's no scaffold CLI yet — copy an existing item folder as a starting point (`registry/items/components/button` is a good one) and adjust it.

## Item layout

```tree
registry/items/components/badge/
  _registry.svx
  _preview.svelte
  stories/badge.stories.ts

registry/items/files/styles/
  _registry.svx
  _preview.svelte
  stories/styles.stories.svelte
  globals.css
  theme.css
  theme-secondary.css
  theme-tertiary.css
```

- `_registry.svx` — YAML frontmatter (`name`, `type`, `files`, `dependencies`) plus optional Markdown usage docs, rendered on the item's docs page
- `_preview.svelte` — live demo shown in the "Preview" tab (never published in the item JSON)
- `stories/*.stories.svelte` — the matching Storybook story

## Where the source lives

**Every registry item's source lives inside its own item folder, under `registry/items/<section>/<name>/`.** `src/lib/components/**` is the documentation site's own application shell — it is never where a registry item's `.svelte`/`.ts` source lives, even for components (`button`, `badge`, `card`, `accordion`, `tabs`, `avatar`, `breadcrumb`, …) that also happen to render the docs site's own UI. The docs site consumes those the same way an external consumer would after installing them — import via the `$registry` alias (`$registry/items/components/<name>/index.js`), never by re-implementing the component under `src/lib/components/ui/`. See the `registry-source-boundary` agent skill (`.agents/skills/registry-source-boundary/SKILL.md`) for the full rationale and how to catch a drifted duplicate.

`files[].path` in `_registry.svx` points to the real on-disk source file:

- **Components, blocks, and utilities authored for this registry** (`button`, `badge`, `card`, `accordion`, `tabs`, `avatar`, `hero`, `cn`, …) keep their source directly in the item folder (or `src/lib/utils.ts` for `cn`).
- **Published CSS and other standalone files** (`styles`) keep `_registry.svx`, `_preview.svelte`, and the CSS together under `registry/items/files/<name>/`. They still appear in the Utilities catalog (for example [`/utilities/styles`](/utilities/styles)).

```yaml
files:
  - path: registry/items/components/button/button.svelte
    type: registry:ui
    target: "~/components/button/button.svelte"
```

CSS-only items are authored in that same `files/` folder:

```yaml
files:
  - path: registry/items/files/styles/globals.css
    type: registry:file
    target: "~/styles/globals.css"
```

`target` is where the file lands in a consumer's project when installed via the CLI. Prefix with `~/` for a path from the project root. Without it, `registry:ui` files resolve under the `ui` alias (`src/lib/components/ui`) and `registry:style` CSS files nest under the Tailwind CSS filename from `components.json`.

## Generating and validating

```sh
bun run registry:generate   # writes registry.generated.json from registry/items/**
bun run registry:build      # generate, then build static/r/*.json via `shadcn-svelte registry build`
bun run registry:doctor     # lint _registry.svx files: bad frontmatter, missing files[], orphan folders
```

Run `registry:doctor` after adding or editing an item — it catches the mistakes `registry:generate` doesn't, like a `files[].path` that doesn't exist or a folder placed under the wrong section (`registry/items/<section>/` must be `components`, `blocks`, `utilities`, or `files`, or the item is silently invisible to the catalog).