Docs

CLI & registry

Ballmac UI is a standard shadcn registry. Everything the shadcn CLI can do with a registry, it can do with @ballmac.

Addresses

Every item has a permanent name and a JSON URL:

# by namespace (after "registry add", see Installation)
npx shadcn@latest add @ballmac/button

# by URL, no setup needed
npx shadcn@latest add https://ui.ballmac.com/r/button.json

Search and inspect before installing

# list or search everything in @ballmac
npx shadcn@latest search @ballmac -q "chat"

# see an item's files, dependencies and docs
npx shadcn@latest view @ballmac/prompt-input

Updating installed components

Components are your code once installed, so updates never happen silently. To see what changed in a newer version, compare before overwriting:

npx shadcn@latest add @ballmac/button --diff
npx shadcn@latest add @ballmac/button --overwrite

Where files go

Components: components/ballmac/ (respects your components alias and src/ folder)
Blocks: components/ballmac/blocks/<name>/
Hooks and helpers: hooks/ballmac/, lib/ballmac/

Ballmac UI never writes to components/ui, so it can't overwrite your shadcn/ui components.

Dependencies

Each item declares the npm packages it imports and the registry items it builds on (for example @ballmac/motion-presets or shadcn's utils). The CLI installs them for you. Every build checks that declared dependencies match the actual imports.

JSON format

Items follow the official shadcn registry schema. The full index is at https://ui.ballmac.com/r/registry.json. Each item's meta adds Ballmac fields for tools and agents: tier, tags, version, when to use it, what it composes with, and keyboard notes.