niamkvn/shadcn-svelte

O que shadcn-svelte faz?

Um framework para construir UI, componentes e sistemas de design para Svelte. Os componentes são adicionados como código-fonte ao projeto do usuário através da CLI.

IMPORTANTE: Execute todos os comandos da CLI usando o executor de pacotes do projeto: npx shadcn-svelte@latest, pnpm dlx shadcn-svelte@latest ou bunx --bun shadcn-svelte@latest — com base no gerenciador de pacotes do projeto. Os exemplos abaixo usam npx shadcn-svelte@latest, mas substitua pelo executor correto para o projeto.

Contexto Atual do Projeto

Leia components.json na raiz do projeto e, quando precisar do layout de arquivos ativo, liste o diretório fornecido pelo caminho aliases.ui (resolvido com as mesmas regras da CLI).

Importações (Svelte)

Cada componente vive em sua própria pasta com um barrel index.ts. Siga a documentação de instalação:

• Componentes multi-parte (dialog, select, card, field, tabs, …): import * as Dialog from "$lib/components/ui/dialog" então Dialog.Content, Dialog.Title, Card.Root, Card.Header, etc. — tudo o que o barrel exportar (nomes curtos e/ou aliases Root as …).
• Barrels de componente único (apenas um componente significativo na pasta): importações nomeadas — import { Button } from "$lib/components/ui/button" e <Button>, não import * as Button + Button.Root. Mesmo padrão para { Input }, { Badge }, { Spinner }, { Checkbox }, { Separator }, { Skeleton }, etc.

import * as Dialog from "$lib/components/ui/dialog";
import { Button } from "$lib/components/ui/button";
import { Separator } from "$lib/components/ui/separator";

Use os aliases reais de components.json (geralmente $lib/components/ui/...), não caminhos fixos.

Princípios

1. Use componentes existentes primeiro. Execute npx shadcn-svelte@latest add sem argumentos para navegar pelos componentes disponíveis, ou verifique Componentes antes de escrever UI personalizada.
2. Componha, não reinvente. Página de configurações = Tabs + Card + controles de formulário. Dashboard = Sidebar + Card + Chart + Table.
3. Use variantes integradas antes de estilos personalizados. variant="outline", size="sm", etc.
4. Use cores semânticas. bg-primary, text-muted-foreground — nunca valores brutos como bg-blue-500.

Regras Críticas

Estas regras são sempre aplicadas. Cada uma tem links para um arquivo com pares Incorreto/Correto.

Estilização e Tailwind → styling.md

• class para layout, não estilização. Nunca substitua cores ou tipografia de componentes.
• Sem space-x-* ou space-y-*. Use flex com gap-*. Para pilhas verticais, flex flex-col gap-*.
• Use size-* quando largura e altura são iguais. size-10 não w-10 h-10.
• Use a abreviação truncate. Não overflow-hidden text-ellipsis whitespace-nowrap.
• Sem substituições manuais de dark:. Use tokens semânticos (bg-background, text-muted-foreground).
• Use cn() para classes condicionais. Não escreva ternários manuais com template literals.
• Sem z-index manual em componentes de sobreposição. Dialog, Sheet, Popover, etc. gerenciam sua própria pilha.

Formulários e Inputs → forms.md

• Formulários usam Field.FieldGroup + Field.Field. Nunca use div bruto com space-y-* ou grid gap-* para layout de formulário.
• InputGroup usa InputGroup.Input/InputGroup.Textarea. Nunca Input/Textarea bruto dentro de InputGroup.Root.
• Botões dentro de inputs usam InputGroup.Root + InputGroup.Addon.
• Conjuntos de opções (2–7 escolhas) usam ToggleGroup. Não faça loop de Button com estado ativo manual.
• Field.FieldSet + Field.FieldLegend para agrupar checkboxes/radios relacionados. Não use uma div com um cabeçalho.
• Validação de campo usa data-invalid + aria-invalid. data-invalid no Field, aria-invalid no controle. Para desabilitado: data-disabled no Field, disabled no controle.

Estrutura de Componentes → composition.md

• Itens sempre dentro de seu Grupo. Select.Item → Select.Group. DropdownMenu.Item → DropdownMenu.Group. Command.Item → Command.Group.
• Gatilhos personalizados. Envolva controles em Dialog.Trigger / AlertDialog.Trigger, ou controle o estado aberto com bind:open na raiz — veja a documentação do componente.
• Dialog, Sheet e Drawer sempre precisam de um Title. Dialog.Title, Sheet.Title, Drawer.Title obrigatório para acessibilidade. Use class="sr-only" se oculto visualmente.
• Use a composição completa do Card. Card.Header/Card.Title/Card.Description/Card.Content/Card.Footer. Não jogue tudo em Card.Content.
• Button não tem isPending/isLoading. Componha com Spinner dentro de Button + disabled; use data-icon="inline-start" / inline-end no Spinner para espaçamento correto (import { Button }, import { Spinner }).
• Tabs.Trigger deve estar dentro de Tabs.List. Nunca renderize gatilhos diretamente em Tabs.
• Avatar sempre precisa de Avatar.Fallback. Para quando a imagem falha ao carregar.

Use Componentes, Não Marcação Personalizada → composition.md

• Use componentes existentes antes de marcação personalizada. Verifique se um componente existe antes de escrever uma div estilizada.
• Callouts usam Alert. Não construa divs estilizadas personalizadas.
• Estados vazios usam Empty. Não construa marcação de estado vazio personalizada.
• Toast via svelte-sonner. Use toast() de svelte-sonner com o componente Sonner da sua pasta UI.
• Use Separator em vez de <hr> ou uma div com classes apenas de borda.
• Use Skeleton para placeholders de carregamento. Sem divs animate-pulse personalizadas.
• Use Badge em vez de spans estilizados personalizados.

Ícones → icons.md

• Ícones em <Button> usam data-icon. data-icon="inline-start" ou data-icon="inline-end" no ícone.
• Sem classes de tamanho em ícones dentro de componentes. Os componentes lidam com o tamanho dos ícones via CSS. Sem size-4 ou w-4 h-4.
• Passe ícones como componentes. Importe da iconLibrary configurada (ex.: @lucide/svelte), não chaves de string.

CLI

• Presets — copie a string codificada do construtor de sistema de design em shadcn-svelte.com e passe para npx shadcn-svelte@latest init --preset <code>.

Padrões Chave

Estes são os padrões mais comuns que diferenciam o código correto de shadcn-svelte. Para casos extremos, veja os arquivos de regras vinculados acima.

<script lang="ts">
  import * as Field from "$lib/components/ui/field";
  import { Input } from "$lib/components/ui/input";
  import { Button } from "$lib/components/ui/button";
  import SearchIcon from "@lucide/svelte/icons/search";
  import { Badge } from "$lib/components/ui/badge";
  import * as Avatar from "$lib/components/ui/avatar";
</script>

<!-- Layout de formulário: Field.FieldGroup + Field.Field, não div + Label. -->
<Field.FieldGroup>
  <Field.Field>
    <Field.FieldLabel for="email">Email</Field.FieldLabel>
    <Input id="email" />
  </Field.Field>
</Field.FieldGroup>

<!-- Validação: data-invalid no Field, aria-invalid no controle. -->
<Field.Field data-invalid>
  <Field.FieldLabel for="email">Email</Field.FieldLabel>
  <Input id="email" aria-invalid />
  <Field.FieldDescription>Email inválido.</Field.FieldDescription>
</Field.Field>

<!-- Ícones em botões: data-icon, sem classes de tamanho. -->
<Button>
  <SearchIcon data-icon="inline-start" />
  Pesquisar
</Button>

<!-- Espaçamento: gap-*, não space-y-*. -->
<div class="flex flex-col gap-4"></div>

<!-- Dimensões iguais: size-*, não w-* h-*. -->
<Avatar.Root class="size-10">
  <Avatar.Image src="/u.png" alt="Usuário" />
  <Avatar.Fallback>U</Avatar.Fallback>
</Avatar.Root>

<!-- Cores de status: variantes de Badge ou tokens semânticos, não cores brutas. -->
<Badge variant="secondary">+20.1%</Badge>

Seleção de Componentes

Necessidade	Use
Botão/ação	Button com variante apropriada (import { Button })
Inputs de formulário	Input, Select, Combobox, Switch, Checkbox, RadioGroup, Textarea, InputOTP, Slider
Alternar entre 2–5 opções	ToggleGroup.Root + ToggleGroup.Item
Exibição de dados	Table, Card, Badge, Avatar
Navegação	Sidebar, NavigationMenu, Breadcrumb, Tabs, Pagination
Sobreposições	Dialog (modal), Sheet (painel lateral), Drawer (folha inferior), AlertDialog (confirmação)
Feedback	svelte-sonner (toast), Alert, Progress, Skeleton, Spinner
Paleta de comandos	Command dentro de Dialog
Gráficos	Chart (LayerChart)
Layout	Card, Separator, Resizable, ScrollArea, Accordion, Collapsible
Estados vazios	Empty
Menus	DropdownMenu, ContextMenu, Menubar
Dicas/informação	Tooltip, HoverCard, Popover

Campos Chave

Use components.json e o sistema de arquivos — não um comando info separado:

• aliases → use o prefixo de alias real da configuração (ex.: $lib/), nunca codifique projetos não relacionados.
• tailwind.css → o arquivo CSS global onde as variáveis de tema residem. Edite este arquivo para ajustes de tema; não adicione um segundo arquivo globals a menos que o usuário já use um.
• style → tratamento visual (ex.: nova, vega, …) e caminho de estilo do registro.
• iconLibrary → determina os pacotes de ícones (@lucide/svelte, @tabler/icons-svelte, etc.). Nunca presuma @lucide/svelte.
• registry → de onde a CLI busca componentes; registro oficial padrão em shadcn-svelte.com.
• resolvedPaths (conceitual) → a CLI resolve aliases para caminhos absolutos; liste aliases.ui no disco para ver os componentes instalados.

Veja cli.md para comandos e flags.

Documentação de Componentes, Exemplos e Uso

Abra https://shadcn-svelte.com/docs/components/<name>.md para documentação e exemplos. Ao criar, corrigir, depurar ou usar um componente, leia a página oficial primeiro para seguir as APIs documentadas.

Fluxo de Trabalho

1. Obter contexto do projeto — leia components.json e liste o diretório de componentes UI quando necessário.
2. Verificar componentes instalados primeiro — antes de executar add, liste os arquivos sob o caminho ui resolvido. Não importe componentes que não foram adicionados e não adicione novamente os já presentes a menos que esteja atualizando.
3. Descobrir componentes — npx shadcn-svelte@latest add sem argumentos (lista interativa), ou o site de documentação.
4. Instalar ou atualizar — npx shadcn-svelte@latest add <name> ou uma URL de registro. Para atualizar arquivos existentes do registro, use npx shadcn-svelte@latest update (veja cli.md).
5. Corrigir importações em itens de terceiros / adicionados por URL — Após adicionar de uma URL de registro personalizada, verifique se há caminhos codificados que não correspondem aos aliases do projeto. Reescreva as importações para usar os aliases ui / lib do projeto de components.json.
6. Revisar componentes adicionados — Após adicionar, leia os arquivos adicionados e verifique a composição (grupos, títulos, atributos de validação). Alinhe as importações de ícones com iconLibrary.
7. Itens de registro remoto — Adicionar por URL é explícito; se o usuário quiser um componente de uma fonte desconhecida, confirme a URL do registro ou o item antes de executar add.

Sistemas de Design a partir de DESIGN.md

Quando o usuário pedir um sistema de design a partir de um DESIGN.md (ou uma especificação de marca), com ou sem um preset, siga design-system.md de ponta a ponta:

1. Para um novo aplicativo, crie o esqueleto do SvelteKit com npx sv create <app> (ou Svelte + Vite quando solicitado), depois inicialize com npx shadcn-svelte@latest init --preset <code>. Sem um código, escolha um estilo que se encaixe no DESIGN.md e passe seu nome, ex.: init --preset luma; códigos de preset React e flags de scaffolding não se aplicam. Em um aplicativo existente, preserve personalizações locais.
2. Instale todos os componentes com add --all --yes em um novo aplicativo; adicione apenas componentes ausentes em um existente.
3. Leia o frontmatter do DESIGN.md, os Faça e Não Faça, e as Lacunas Conhecidas antes de editar.
4. Mapeie seus tokens para as variáveis em tailwind.css de components.json. Fixe a escala de raio, sombras, fontes e utilitários type-*.
5. Reestilize as variantes tailwind-variants instaladas e o CSS de estilo associado. Altere as alturas dos controles juntas.
6. Construa a página de acordo com design-system-page.md: papéis de cor verificados por contraste, espécimes de tipo, matrizes de estado fixas, casos extremos, pares faça/não faça, receitas. Verifique as importações com scripts/showcase-coverage.mjs, depois verifique se cada componente renderiza.
7. Verifique em um navegador: svelte-check, build de produção incluindo SSR, sem erros no console, carrega no topo, sem overflow horizontal, modo escuro.

Atualizando Componentes

Use o comando update para puxar as versões mais recentes do registro dos componentes já no projeto. Revise as alterações com git diff após update.

1. Faça commit ou stash do trabalho local.
2. Execute npx shadcn-svelte@latest update [component] ou --all.
3. Resolva conflitos de merge se você personalizou arquivos.
4. Nunca use --overwrite no add sem a aprovação explícita do usuário quando isso destruir edições intencionais.

Referência Rápida

# Inicializar shadcn-svelte em um novo projeto
npx shadcn-svelte@latest init

# Adicionar um componente
npx shadcn-svelte@latest add button
npx shadcn-svelte@latest add https://registry.example.com/button.json

# Adicionar todos os componentes
npx shadcn-svelte@latest add --all

# Atualizar componentes
npx shadcn-svelte@latest update button
npx shadcn-svelte@latest update --all

# Inicializar com um preset
npx shadcn-svelte@latest init --preset <codigo>