--- title: Componentes description: >- Cards, steps, tabs, accordions, badges, grupos de código, frames, árvores, tabelas de tipos, prévias ao vivo e diffs — os componentes integrados, utilizáveis em qualquer página MDX. --- O Blume vem com um conjunto de componentes acessível e personalizável, disponível em qualquer página `.mdx` **sem imports**. Cada um é mostrado abaixo com uma prévia ao vivo e seu código-fonte. Os componentes são vanilla e não usam React; o React só entra em ação se você adicionar sua própria ilha. ## Card e CardGroup [#card-and-cardgroup] Os cards apontam para um destino com um ícone, um título e um breve resumo. Agrupe-os com `CardGroup` para obter uma grade responsiva. Use-os em páginas iniciais, índices de seção e “próximos passos” — em qualquer lugar em que você esteja guiando o leitor adiante. **[Início rápido](/docs/quickstart)** Instale o Blume e publique sua primeira página. **[Componentes](/docs/content/components)** Explore a biblioteca de componentes. ```astro lineNumbers Install Blume and ship your first page. Browse the component library. ``` `Card` recebe `title`, um `href` opcional (omita-o para um card não clicável) e um `icon` do conjunto de ícones integrado do Blume. `CardGroup` recebe `cols` (padrão `2`). ## Steps Uma sequência vertical numerada para instruções ordenadas — instalações, fluxos de configuração e tutoriais em que a ordem importa. Cada `Step` recebe um `title`. 1. **Instale o Blume** Adicione o pacote ao seu projeto. 2. **Escreva uma página** Coloque um arquivo `.mdx` na sua pasta de conteúdo. 3. **Publique** Execute `blume build` e faça o deploy de `dist/`. ```astro lineNumbers Add the package to your project. Drop an `.mdx` file into your content folder. Run `blume build` and deploy `dist/`. ``` ## Tabs Alterne entre conteúdos equivalentes no mesmo lugar — variantes de linguagem, comandos específicos de sistema operacional ou abordagens alternativas — sem empilhar tudo na página. Cada `Tab` recebe um `title`. **macOS** Use o Homebrew para instalar o toolchain. **Windows** Use o winget para instalar o toolchain. ```astro lineNumbers Use Homebrew to install the toolchain. Use winget to install the toolchain. ``` Adicione `inline` para renderizar sem bordas — uma faixa de abas sobre uma linha de largura total, com o conteúdo fluindo abaixo como texto corrido — em vez da caixa com borda. Adicione `param` para sincronizar a aba ativa com um parâmetro de consulta na URL em vez do hash, o que torna a seleção compartilhável: um link terminando em `?install=windows` abre na aba Windows. Cada grupo sincroniza com seu próprio `param`, então você pode usar vários grupos independentes e endereçáveis por link em uma mesma página. Grupos com abas de mesmo título alternam juntos — escolha “macOS” em um e todos os grupos com uma aba macOS acompanham. Adicione `syncKey` para delimitar essa sincronização: apenas os grupos que compartilham a mesma chave alternam juntos, então grupos não relacionados que por acaso tenham um título de aba em comum permanecem independentes. **macOS** Use o Homebrew para instalar o toolchain. **Windows** Use o winget para instalar o toolchain. ```astro lineNumbers Use Homebrew to install the toolchain. Use winget to install the toolchain. ``` ## Badge Um pequeno rótulo em linha para status ou metadados — tags de versão, marcadores de “novo” ou “beta”, níveis de estabilidade. O `variant` ajusta a cor ao significado. ### Padrão [#default] Metadados neutros, sem ênfase específica. Estável ```astro Stable ``` ### Destaque [#accent] Chama a atenção usando a cor de destaque do seu tema — bom para marcadores de “novo” ou de destaque. Novo ```astro New ``` ### Sucesso [#success] Um estado positivo ou aprovado. Aprovado ```astro Passing ``` ### Aviso [#warning] Algo a ser usado com cautela, como um recurso experimental. Beta ```astro Beta ``` ### Perigo [#danger] Um estado negativo ou incompatível, como uma descontinuação. Descontinuado ```astro Deprecated ``` ## Icon Renderiza um ícone pelo nome — a mesma prop `icon` alimenta cards, steps, tabs e entradas da barra lateral. Os nomes vêm do [Lucide](https://lucide.dev/icons), em minúsculas e em kebab-case (`rocket`, `gauge`, `book-open`). ```astro ``` O Blume usa somente o Lucide — um nome simples é resolvido no Lucide, e você pode prefixar um nome com `lucide:` (`lucide:rocket`) por simetria com outras entradas de ícone. `size` define o tamanho em pixels (padrão `16`) e `color` o colore (qualquer cor CSS; o padrão é `currentColor`). Passe uma string ` Product screenshot

``` ## YouTube Incorpore um vídeo do YouTube em um quadro 16:9 responsivo e respeitoso com a privacidade (`youtube-nocookie.com`) que não envia nenhum JavaScript ao cliente. Passe um `id` de vídeo ou uma `url` completa, além de um `title` opcional (para acessibilidade) e um tempo de `start` em segundos. [Big Buck Bunny](https://www.youtube.com/watch?v=aqz-KE-bpKQ) ```astro lineNumbers ``` ## Color Exiba amostras de cor com valores hexadecimais copiáveis — útil para documentar uma paleta ou as cores da marca. Use `variant="compact"` para uma lista de amostras, ou `variant="table"` com `Color.Row` para agrupá-las. Cada `Color.Item` recebe um `name` e um `value` (uma string hexadecimal, ou `{ light, dark }` para cores sensíveis ao tema). ```astro lineNumbers ``` ## Tree Renderize uma estrutura hierárquica de arquivos/pastas com pastas expansíveis. (Para uma versão rápida, baseada em listas, veja [Árvore de arquivos](#file-tree); `Tree` oferece controle por pasta.) Use `Tree.Folder` (`name`, `defaultOpen` opcional, `openable`) e `Tree.File` (`name`). ```astro lineNumbers ``` ## Panel Um contêiner com título para conteúdo complementar, colocado à parte. `title` é opcional. Os panels contêm detalhes de apoio sem interromper o fluxo principal. ```astro Panels hold supporting detail without interrupting the main flow. ``` ## Tooltip Revele uma definição ou dica ao passar o mouse sobre um termo em linha. `tip` é o texto exibido ao passar o mouse; adicione um `headline` opcional e um `cta` + `href` para um link de continuação. Passe o mouse sobre o termo API para saber mais. ```astro Hover the API term. ``` ## Tile Uma prévia clicável que começa com um elemento visual — um ícone ou imagem — acima de um título e uma descrição. Boa para galerias e vitrines. Recebe `title`, `description` e `href`; o filho é o elemento visual. ```astro ``` ## Prompt Uma única linha com um rótulo e um botão de cópia. A `description` (Markdown) é o rótulo visível; o corpo é o próprio prompt — oculto, e copiado para a área de transferência quando o botão **Copiar prompt** é pressionado. `actions` controla os botões (por exemplo, `["copy", "cursor"]`). Escreva a documentação de referência para o endpoint POST /v1/pets. ```astro Write reference docs for the POST /v1/pets endpoint. ``` ## Visibility Mostre ou oculte conteúdo de acordo com o público. `for="web"` renderiza somente no site; `for="agents"` tem como alvo o Markdown voltado a agentes que as IAs leem (`llms-full.txt` e o espelho `.md` de cada página). ```astro Shown on the site only. Shown only in the generated Markdown. ``` ## Tabelas de tipos [#type-tables] Tabelas para documentar as propriedades de um objeto — suas props, tipos e valores padrão. Escreva as linhas manualmente com `TypeTable`, ou gere-as diretamente a partir de uma interface ou alias de tipo do TypeScript com `AutoTypeTable`. ### Tabela de tipos [#type-table] Uma grade **Prop / Tipo** em que cada linha se expande para revelar sua descrição e detalhes. Passe um mapa `type` indexado pelo nome da propriedade; cada entrada recebe um `type`, além de `description`, `default`, o sinalizador `required`, `typeDescription` e `typeDescriptionLink` opcionais. Props opcionais (`required` não definido) exibem um `?` após o nome. | Prop | Type | Default | Description | | - | - | - | - | | `label` | `string` | - | O rótulo visível do botão. | | `variant?` | `"primary" \| "ghost"` | `"primary"` | Estilo visual. | | `disabled?` | `boolean` | - | | ```astro lineNumbers ``` ### Tabela de tipos automática [#auto-type-table] Gere uma tabela de tipos a partir de um tipo do TypeScript, para que a documentação permaneça em sincronia com o código-fonte. Aponte o `AutoTypeTable` para um arquivo com `path` (resolvido a partir da raiz do seu projeto) e um `name` de tipo. As descrições vêm de comentários JSDoc, os valores padrão de tags `@default`, e as propriedades opcionais (`?`) são marcadas conforme o caso. ```astro ``` Você também pode passar o tipo em linha com `type` em vez de um `path` — prático para exemplos pequenos: ```astro lineNumbers ``` ## Informações do GitHub [#github-info] Um card com link para um repositório do GitHub com suas contagens de estrelas e forks em tempo real. As contagens são buscadas no momento do build — sem JavaScript no cliente — e o card continua sendo renderizado se a API estiver inacessível. Passe `owner` e `repo`, ou omita-os para usar o repositório do seu `blume.config`. Defina uma variável de ambiente `GITHUB_TOKEN` para elevar o limite de requisições da API. O card lê a instância a partir de [`github.host`](/docs/configuration#github-enterprise), então, em um site hospedado no Enterprise, `owner`/`repo` explícitos também apontam para essa instância. Passe `host` para direcionar um card para outro lugar — um projeto público a partir de um site Enterprise, por exemplo; a base REST é derivada dele da mesma forma que a partir de `github.host`. ```astro lineNumbers ``` ## Component O `Component` renderiza um arquivo de exemplo do diretório `examples/` do seu projeto como uma prévia ao vivo ao lado do seu código-fonte destacado, em abas. Aponte-o para um arquivo com `path` — sua localização dentro de `examples/`, sem a extensão (portanto `examples/counter.tsx` fica `path="counter"`). Exemplos em React, Vue, Svelte e Astro são todos suportados; exemplos de frameworks hidratam, os de Astro renderizam estaticamente. Ele mantém a prévia e o código em sincronia a partir de um único arquivo. A prévia é renderizada em um frame isolado que os estilos da documentação nunca alcançam — nenhuma margem de texto, tipografia ou elemento visual do tema vaza para o seu componente. O frame recebe o Tailwind (preflight + utilitários varridos do seu projeto e do seu diretório de exemplos), os tokens de design do Blume, para que classes como `bg-background` sigam a paleta do site por padrão, e ele acompanha ao vivo a alternância claro/escuro do site. O painel se dimensiona conforme o exemplo renderizado — e continua acompanhando caso o exemplo cresça ou encolha após o carregamento — com as abas Prévia e Código compartilhando uma mesma altura, de modo que alterná-las nunca desloca a página. Para estilizar as prévias com seu próprio design system — digamos, com variáveis do shadcn — aponte `examples.css` para uma folha de estilos. Ela é injetada em cada frame de prévia após os padrões do Blume, então seus tokens prevalecem. Não use `@import "tailwindcss"` nela; o frame já fornece o Tailwind. Tanto `.dark` quanto `[data-theme="dark"]` funcionam para sobrescritas de modo escuro: ```ts // blume.config.ts export default defineConfig({ examples: { css: "examples/theme.css" }, }); ``` ```css /* examples/theme.css */ :root { --primary: oklch(0.6 0.2 260); } .dark { --primary: oklch(0.75 0.15 260); } @theme inline { --color-primary: var(--primary); } ``` O diretório também é configurável — defina `source` (ou use a forma abreviada em string, `examples: "..."`) quando seus exemplos estiverem em outro lugar (por exemplo, um layout de registro). O `path` é sempre relativo a ele: ```ts // blume.config.ts export default defineConfig({ examples: "registry/files-sdk", }); ``` ```astro ``` `examples` também pode ser um glob (qualquer coisa com `*`, `?`, `[]`, `{}` ou `!`). Somente os arquivos correspondentes são descobertos, e o `path` é relativo ao prefixo estático do glob (a parte anterior ao primeiro curinga). Isso serve para um registro que coloca o código-fonte de cada componente junto ao seu exemplo — aponte apenas para os exemplos, para que os códigos-fonte, que não têm export padrão para prévia, não sejam incluídos: ```ts // blume.config.ts export default defineConfig({ // registry/files-sdk/file-list/file-list.tsx — source, left out // registry/files-sdk/file-list/examples/basic.tsx — discovered examples: "registry/files-sdk/**/examples/*", }); ``` ```astro ``` Em um monorepo, os componentes que seus exemplos importam geralmente ficam em um pacote irmão do workspace. O `@source` do Tailwind varre arquivos, não imports: o Blume varre o seu projeto e o diretório `examples` (para onde quer que `source` aponte, mesmo fora do projeto), então uma classe usada apenas dentro daquele pacote irmão não é gerada até você adicionar o pacote à varredura. Faça isso com uma diretiva `@source` no `examples.css` (para os frames de prévia) ou no `theme.css` (para o site), escrita de forma relativa ao arquivo em que ela está — a regra padrão do Tailwind — e o Blume a leva para a folha de estilos gerada: ```css /* examples/theme.css */ @source "../../../packages/ui/src"; ``` ```astro ``` Um exemplo em Astro renderiza ao vivo sem nenhum JavaScript no cliente: ## CodeBlock O `CodeBlock` destaca uma string de código com o mesmo tema do Shiki e os mesmos transformadores do seu código em blocos de crase — incluindo a troca claro/escuro — para lugares aonde um bloco de crase não chega, como uma página inicial ou um componente personalizado. Passe `code` e uma `lang`: \`Hello, \${name}!\`;`} /> ```astro --- import CodeBlock from "blume/components/content/CodeBlock.astro"; --- ``` Para destacar você mesmo o código em uma string HTML (por exemplo, dentro do seu próprio componente), importe o helper subjacente de `blume/markdown`: ```ts import { highlightCode } from "blume/markdown"; const html = await highlightCode(source, "ts"); ``` ## Diff O `Diff` renderiza um diff no estilo do git, destacado com o mesmo tema do Shiki dos seus blocos de código e produzido inteiramente no momento do build — sem JavaScript no cliente. Passe a ele duas strings em linha (`old` / `new`), dois caminhos de arquivo (`before` / `after`) ou um patch unificado (uma string `patch` em linha ou um arquivo `src`). ```astro ``` Compare dois arquivos do seu projeto, relativos à sua raiz: ```astro ``` Ou renderize um patch unificado — seja de um arquivo com `src`, seja em linha com `patch`: ```astro ``` ```astro ```