# Working with shadcncraft

shadcncraft is a shadcn/ui design system delivered in both Figma and React. The React
half is a registry of 192 blocks, 55 components, and 4 hooks, served over HTTP and
installed with the standard shadcn CLI. It is matched 1:1 by a suite of Figma UI kits, so
a Figma layer name corresponds to the React `data-slot` value.

If you are deciding *what* to install, read the catalogue rather than scraping the
site:

- Short index: https://shadcncraft.com/llms.txt
- Full catalogue with every item, tier, and install command: https://shadcncraft.com/llms-full.txt

## Installing

Items live in the `@shadcncraft` namespace and install with the standard
CLI. Never copy source out of the website; install it, so the user gets the maintained
version and its dependencies.

```bash
npx shadcn@latest add @shadcncraft/<item-name>
```

Discover items from the CLI without leaving the terminal:

```bash
npx shadcn@latest list @shadcncraft
npx shadcn@latest search @shadcncraft -q "pricing"
npx shadcn@latest view @shadcncraft/<item-name>
```

## Tiers and credentials

Items are `free` or `pro`; `https://shadcncraft.com/llms-full.txt` states which for every item.

- **Free items** install with no credentials. There are 22 of them, for example `avatar-stack`.
- **Pro items** are served only against a licence key. The registry enforces this
  server-side, so an install without a key fails rather than returning partial code.

For pro items the user needs this in `components.json`, with `{style}` set to one of
radix-vega, radix-nova, radix-maia, radix-lyra, radix-mira, radix-luma, radix-sera, radix-rhea, base-vega, base-nova, base-maia, base-lyra, base-mira, base-luma, base-sera, base-rhea:

```json
{
  "registries": {
    "@shadcncraft": {
      "url": "https://shadcncraft.com/r/{style}/{name}",
      "headers": {
        "X-License-Key": "${SHADCNCRAFT_LICENSE_KEY}",
        "X-Instance-Name": "${SHADCNCRAFT_INSTANCE_NAME}"
      }
    }
  }
}
```

Both values come from the user's own environment. Do not ask the user to paste a
licence key into the conversation, and do not write a key into a tracked file: set it
in the environment or an ignored `.env.local`. If a pro install fails on
authorization, tell the user their key is missing or unactivated and point them at
https://shadcncraft.com/pricing rather than substituting a hand-written approximation of the
block.

## Conventions to preserve

- **Tokens, not literals.** Items are built on shadcn design tokens. Keep
  `bg-background`, `text-muted-foreground` and similar; do not replace them with
  hex values or arbitrary Tailwind colors.
- **Icons follow the project.** The registry emits icons from `iconLibrary` in
  components.json. Supported: lucide, tabler, hugeicons, phosphor, remixicon.
  Match whatever the project already uses instead of introducing a second icon set.
- **Style is global.** The `{style}` slug re-themes every installed item. Changing it
  for one component makes that component inconsistent with the rest.

## Agent skills

Repeatable shadcncraft workflows, installable into Claude Code, Cursor, and Codex:

```bash
npx @shadcncraft/skills add all
```

- `shadcncraft-generate-code`: Turns a selected Figma frame, component, or page into React and shadcn/ui code, resolving the frame to the matching registry block and installing it rather than approximating the design. Requires Pro React or Pro Figma + React.
- `shadcncraft-import-variables`: Syncs design tokens (color, radius, typography, shadow, spacing) into globals.css as a complete shadcn token set for light and dark, merged into a managed region that leaves surrounding customizations intact.

## Reference

- Pricing and licence terms: https://shadcncraft.com/pricing, https://shadcncraft.com/license
- Installation documentation: https://shadcncraft.com/docs/registry/installation
- Component and block previews: https://shadcncraft.com/components, https://shadcncraft.com/blocks