UI Catalog

Instalar via CLI

Cada item é servido no formato registry-item do shadcn. Num projeto com components.json, uma linha instala o arquivo e as dependências (primitivos do shadcn e pacotes npm):

npx shadcn@latest add https://ui.codehall.io/r/<slug>.json

# vários de uma vez
npx shadcn@latest add https://ui.codehall.io/r/hero-centralizado.json https://ui.codehall.io/r/pricing-tres-planos.json

O índice completo está em /r/registry.json. Os itens foram escritos com o estilo base-nova (Base UI); em projetos no estilo Radix, os primitivos equivalentes também existem e o CLI instala os do seu estilo.

MCP no Claude Code

O catálogo expõe um servidor MCP (HTTP streamable, JSON-RPC, sem sessão). Adicione ao .mcp.json do projeto (ou ao global) e reinicie o Claude Code — servidores MCP só carregam no início da sessão:

.mcp.json

{
  "mcpServers": {
    "ui-catalog": {
      "type": "http",
      "url": "https://ui.codehall.io/api/mcp",
      "headers": { "Authorization": "Bearer ${UI_CATALOG_MCP_TOKEN}" }
    }
  }
}

Exporte UI_CATALOG_MCP_TOKEN (peça o token para o time). Sem o token o endpoint responde 401.

Tools do MCP

search_items

Busca itens do catálogo (componentes, blocos, páginas, ilustrações) por texto, tipo, categoria, coleção, tag ou status. Retorna só metadados (sem o código) para economizar tokens. Use get_item para o código completo.

get_item

Retorna um item completo (incluindo o código TSX, dependências e o comando de instalação) pelo id ou slug.

add_item

Adiciona um item ao catálogo. O código é validado (sintaxe + imports suportados + export default) antes de salvar — erros voltam na resposta. Cria categoria, coleção e tags se não existirem. Dependências (npm e registry) são derivadas dos imports quando omitidas.

update_item

Atualiza um item existente (pelo id ou slug). Só os campos enviados mudam. tags substitui o conjunto inteiro; collection/category vazios desvinculam. Se code mudar, é validado de novo.

delete_item

Remove um item do catálogo (pelo id ou slug). Ação irreversível.

check_code

Valida um TSX sem salvar: compila, lista os imports, aponta módulos não suportados no preview e confere o export default. Use antes de add_item quando estiver inseguro.

list_supported_modules

Lista o que pode ser importado num item (módulos @/components/ui/* disponíveis, bibliotecas) e as regras de autoria do catálogo. Chame antes de escrever código.

list_categories

Lista as categorias (opcionalmente de um tipo) com a contagem de itens.

upsert_category

Cria ou atualiza uma categoria (nome, descrição exibida na seção, ordem). Útil para dar descrição às seções do catálogo.

list_collections

Lista as coleções do catálogo com a contagem de itens.

list_tags

Lista as tags do catálogo com a contagem de itens.

Fluxo recomendado para criar: list_supported_modules → escrever o TSX → check_code → add_item → abrir o preview no catálogo. Para usar: search_items → get_item → instalar com o comando devolvido.

Regras de autoria

Um único arquivo .tsx auto-contido com `export default function NomeDoItem()` sem props obrigatórias.
Importe primitivos de `@/components/ui/<nome>` (lista em list_supported_modules), ícones de `lucide-react`, animação de `motion/react`, gráficos de `recharts`.
Estilize só com classes Tailwind v4 e tokens do shadcn (bg-background, text-muted-foreground, border-border, bg-primary…). Nada de cores hex hardcoded — o item precisa funcionar em claro e escuro.
Sem `process.env`, sem fetch a APIs externas, sem imagens remotas que possam sumir (prefira SVG inline, gradientes ou placeholders).
Blocos (BLOCK) ocupam a largura toda (`w-full`) com padding próprio (`py-16 px-6`); componentes e ilustrações têm tamanho natural e são centralizados pelo preview.
Ilustrações: SVG inline + motion (`motion.path`, `animate`, `transition.repeat: Infinity`) e `currentColor`/tokens para herdar o tema.
Dados de exemplo em pt-BR, realistas e curtos. Sem lorem ipsum.

O preview compila o arquivo no navegador (sucrase) e resolve os imports num mapa fixo; Tailwind v4 roda em runtime no iframe, então qualquer classe funciona. O que não está em imports suportados não renderiza.

Imports suportados

Primitivos shadcn (61)

accordionalertalert-dialogaspect-ratioattachmentavatarbadgebreadcrumbbubblebuttonbutton-groupcalendarcardcarouselchartcheckboxcollapsiblecomboboxcommandcontext-menudialogdirectiondrawerdropdown-menuemptyfieldhover-cardinputinput-groupinput-otpitemkbdlabelmarkermenubarmessagemessage-scrollernative-selectnavigation-menupaginationpopoverprogressquestionnaireradio-groupresizablescroll-areaselectseparatorsheetsidebarskeletonsliderspinnerswitchtabletabstextareatoasttoggletoggle-grouptooltip

Bibliotecas e utilitários

reactreact-domreact/jsx-runtimereact/jsx-dev-runtimelucide-reactmotionmotion/reactframer-motionrechartsclass-variance-authoritycncmdkdate-fnsreact-day-pickerembla-carousel-reactinput-otpreact-resizable-panels@base-ui/react@base-ui/react/button@base-ui/react/dialog@base-ui/react/menu@base-ui/react/merge-props@base-ui/react/use-render@/lib/utils@/hooks/use-mobilenext/linknext/imagenext/navigation

next/link, next/image e next/navigation são shims inertes no preview (viram <a>, <img> e hooks vazios).

API REST

GET  https://ui.codehall.io/api/items?q=&kind=&category=&collection=&tag=&cursor=&limit=&withTotal=1
GET  https://ui.codehall.io/api/items/<id|slug>            # item completo (com code)
GET  https://ui.codehall.io/api/items/<id|slug>/code       # TSX cru (text/plain); ?download=1
GET  https://ui.codehall.io/api/facets?kind=BLOCK          # categorias, coleções, tags
GET  https://ui.codehall.io/api/stats
POST https://ui.codehall.io/api/check          { code }     # validação estática
POST https://ui.codehall.io/api/items/zip      { ids }      # .zip com os .tsx
POST https://ui.codehall.io/api/items/bulk     { action, ids, ... }  # addTags|removeTags|setCollection|setFeatured|setStatus
GET  https://ui.codehall.io/r/registry.json  ·  GET https://ui.codehall.io/r/<slug>.json

As rotas da UI (PATCH/DELETE/bulk) não têm autenticação — o catálogo é uma ferramenta interna. Só o MCP exige token.

Skills do Claude Code

Duas skills acompanham o catálogo: ui-catalog-create (autorar e publicar via MCP, com validação) e ui-catalog-use (buscar, instalar e adaptar no projeto). No repo tasky elas já vêm em .claude/skills/; fora dele:

/plugin marketplace add hikinine/inboxzero
/plugin install ui-catalog@clickmax

Depois é só pedir: “cria um bloco de pricing com três planos pro catálogo” ou “pega um hero do UI Catalog e coloca na landing”. Veja também a página de novo item para publicar à mão.