@govbr-ds/webcomponents 2.3.0 → 2.5.0

package/dist/types/components/table/table.d.ts

@@ -1,44 +1,37 @@
 import type { ColumnWidth, TableAlignment, TableDensity, TableDividerStyle, TableOverflow, TableTooltipMode, TableTooltipState } from './table-types';
 /**
- * O componente `br-table` é o elemento oficial do GovBR-DS para exibição e gerenciamento de dados tabulares estruturados em linhas e colunas, desenvolvido com suporte a CSS Grid, responsividade e alta flexibilidade de composição.
+ * O `br-table` estrutura e exibe conjuntos de dados organizados em linhas e colunas.
  *
- * ### Para que serve
+ * Estruture a tabela usando os subcomponentes `br-table-header`, `br-table-body`, `br-table-row` e `br-table-cell`. Para exibir um indicador de carregamento durante atualizações assíncronas, use a propriedade `loading`.
  *
- * - **Apresentação de conjuntos de dados relacionais:** Organiza registros com múltiplos atributos comparáveis (ex.: relatórios, tabelas de processos, listagens financeiras).
- * - **Recursos interativos avançados:** Suporta ordenação por coluna, seleção simples ou múltipla de linhas, densidades variadas (alta, média, baixa) e paginação integrada com `br-pagination`.
- * - **Acessibilidade WAI-ARIA:** Preserva a semântica de tabela acessível (`role="table"`, `role="columnheader"`, `role="row"`, `role="cell"`) mesmo em leiautes baseados em CSS Grid.
+ * ```html
+ * <br-table>
+ *   <br-table-header slot="header">
+ *     <br-table-row>
+ *       <br-table-header-cell>Nome</br-table-header-cell>
+ *       <br-table-header-cell>Cargo</br-table-header-cell>
+ *     </br-table-row>
+ *   </br-table-header>
+ *   <br-table-body slot="body">
+ *     <br-table-row>
+ *       <br-table-cell>Maria Silva</br-table-cell>
+ *       <br-table-cell>Analista</br-table-cell>
+ *     </br-table-row>
+ *   </br-table-body>
+ * </br-table>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - As informações compartilharem campos e atributos fixos que justifiquem a comparação lado a lado em colunas.
- *   - A pessoa usuária precisar ordenar, filtrar ou selecionar múltiplos registros da lista.
- * - **Evite e prefira outro componente quando:**
- *   - Os itens forem heterogêneos com estruturas visuais distintas (prefira `br-card`).
- *   - Houver apenas um texto linear simples por item (prefira `br-list`).
+ * - Dados bidimensionais com cabeçalhos de coluna e necessidades de ordenação ou comparação.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * O ecossistema da Tabela segue a hierarquia semântica modular:
+ * - Listas simples de itens lineares: use `br-list`.
+ * - Agrupamento de informações de um único registro: use `br-card`.
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-table` | **Orquestrador principal.** Gerencia o grid de colunas, ordenação, seleção de linhas e densidade. | Contêiner raiz da tabela. |
- * | `br-table-header` | **Seção de cabeçalho.** Agrupa as linhas de títulos das colunas. | Declarado no slot `header` da tabela. |
- * | `br-table-body` | **Corpo de dados.** Agrupa as linhas de registros de conteúdo. | Declarado no slot `body` (ou padrão) da tabela. |
- * | `br-table-row` | **Linha.** Representa uma linha de cabeçalho ou de registro de dados. | Declarado dentro de `br-table-header` ou `br-table-body`. |
- * | `br-table-header-cell` | **Célula de título.** Célula de cabeçalho com suporte a botão de ordenação. | Declarado dentro de `br-table-row` no cabeçalho. |
- * | `br-table-cell` | **Célula de dados.** Célula de conteúdo individual de uma coluna. | Declarado dentro de `br-table-row` no corpo de dados. |
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/table?tab=designer).
  *
- * ### Como os subcomponentes se relacionam
- *
- * A arquitetura de `br-table` reflete a semântica nativa de tabelas HTML de forma modular:
- * `br-table` → `br-table-header` / `br-table-body` → `br-table-row` → `br-table-header-cell` / `br-table-cell`.
- * O componente pai orquestra o alinhamento das colunas via tokens de Grid, distribuindo automaticamente os estados de seleção e foco para as linhas filhas.
- *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).
- *
-
  * @category Dados, Conteúdo
  * @status stable
  * @Slot header: Área para inclusão do subcomponente br-table-header

package/dist/types/components/tag/tag.d.ts

@@ -4,37 +4,28 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrDensity } from '../global.types';
 import type { TagShape, TagValidator, TagVariant } from './tag.types';
 /**
- * O componente `br-tag` é o elemento visual compacto do GovBR-DS utilizado para rotular, categorizar, exibir metadados ou aplicar filtros rápidos na interface.
+ * O `br-tag` categoriza, rotula ou destaca informações curtas e metadados.
  *
- * ### Para que serve
+ * Suporta modo estático informativo, modo interativo clicável com `action`, modo com botão de fechar (`closable`) e modo selecionável com `selectable`.
  *
- * - **Categorização e metadados:** Identifica o tipo, categoria ou atributos de um item (ex.: "Educação", "Tecnologia", "Urgente").
- * - **Sinalização de status:** Exibe estados operacionais de processos ou documentos através de cores semânticas e ícones (ex.: "Aprovado", "Pendente", "Cancelado").
- * - **Filtros interativos dispensáveis:** Suporta botão de fechamento (`closable`), permitindo remover filtros dinamicamente.
- * - **Tags de seleção:** Suporta modo interativo selecionável com integração nativa a formulários (`formAssociated`).
+ * ```html
+ * <br-tag>Pendente</br-tag>
+ * <br-tag status="success">Concluído</br-tag>
+ * <br-tag closable>Filtro: Brasília</br-tag>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Exibir palavras-chave associadas a um conteúdo ou cartão.
- *   - Exibir status sucinto de registros em tabelas (`br-table`) ou cabeçalhos.
- *   - Oferecer filtros aplicados que podem ser removidos com um clique.
- * - **Evite e prefira outro componente quando:**
- *   - O elemento for a ação primária ou um comando executável (prefira `br-button`).
- *   - O texto for extenso e exigir explicações detalhadas (prefira `br-message`).
+ * - Rótulos de estado, tags de categorias ou palavras-chave.
+ * - Filtros aplicados que podem ser removidos individualmente.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-tag` oferece flexibilidade estrutural:
- * - `default`: Slot principal para texto ou conteúdo livre da tag.
- * - `label`: Slot para rótulo customizado.
- * - `icon`: Slot para inserção de ícone auxiliar (`br-icon`).
- * - `close-button`: Slot para customizar o botão de remoção.
- * - `feedback`: Slot para mensagem de validação contextual.
+ * - Ações primárias ou envio de formulário: use `br-button`.
+ * - Contagem numérica pura: use `br-avatar` ou texto de badge.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tag?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/tag?tab=designer).
  *
-
  * @category Conteúdo, Dados
  * @status stable
  * @slot default - Slot para inserir o conteúdo da tag, como rótulo ou ícone.
@@ -141,7 +132,7 @@ export declare class Tag {
      */
     size: string;
     /**
-     * Variante funcional canônica. Aceita `default`, `status`, `action` ou `selectable`.
+     * Variante funcional padrão. Aceita `default`, `status`, `action` ou `selectable`.
      * Valores inválidos são ignorados; nesse caso, os aliases booleanos legados
      * continuam disponíveis para manter a compatibilidade.
      */

package/dist/types/components/textarea/textarea.d.ts

@@ -3,34 +3,26 @@ import { type FormValidationState } from '../../shared/utils/form';
 import type { InputValidationChangeDetail, InputValidator } from '../input/input.types';
 import type { TextareaResize, TextareaWrap } from './textarea.types';
 /**
- * O componente `br-textarea` é o controle oficial do GovBR-DS para entrada de dados textuais em múltiplas linhas, projetado para capturar textos longos, justificativas, descrições ou observações em formulários.
+ * O `br-textarea` captura textos longos em múltiplas linhas em formulários.
  *
- * ### Para que serve
+ * Configure `label`, `placeholder`, `maxlength` e `state` para validação. Use `show-counter` para exibir o contador de caracteres restantes.
  *
- * - **Entrada de texto extenso:** Permite que a pessoa usuária digite parágrafos de texto livre com quebra de linha e rolagem vertical.
- * - **Contador regressivo de caracteres:** Exibe a quantidade de caracteres restantes em tempo real com base no limite máximo (`maxlength`), alertando visualmente quando o limite é atingido.
- * - **Integração com formulários:** É associado nativamente a formulários HTML (`formAssociated`), sincronizando valor, estado de validação e foco acessível.
- * - **Redimensionamento controlado:** Oferece opções de redimensionamento vertical, horizontal ou fixo.
+ * ```html
+ * <br-textarea label="Observações" placeholder="Digite sua mensagem" maxlength="500" show-counter></br-textarea>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se via `ElementInternals`, participando da validação nativa com `required`.
  *
- * - **Utilize quando:**
- *   - A entrada esperada tiver mais de uma frase ou exigir formatação multilinha (comentários, manifestações, relatórios, justificativas).
- *   - Houver restrição estrita de caracteres com necessidade de feedback quantitativo dinâmico.
- * - **Evite e prefira outro componente quando:**
- *   - O dado for curto e couber em uma única linha (como nomes, e-mails, títulos, documentos): prefira `br-input`.
- *   - For necessário um editor rico WYSIWYG com formatação em negrito, tabelas e links.
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Mensagens, comentários, justificativas, descrições ou textos extensos.
  *
- * O `br-textarea` é composto pelo campo e slots de apoio:
- * - `default`: Slot para instruções adicionais ou textos de ajuda.
- * - `feedback`: Slot para mensagens de validação contextual (como `br-message`).
- * - `validation-loading`: Slot para indicador de carregamento durante validações assíncronas.
+ * ### Quando evitar
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/textarea?tab=designer).
+ * - Dados curtos de linha única (nome, CPF, e-mail): use `br-input`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/textarea?tab=designer).
  *
-
  * @category Formulários
  * @status stable
  * @slot default - Slot para texto adicional ou instruções a serem exibidos junto ao textarea.
@@ -115,7 +107,7 @@ export declare class Textarea {
      * Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'. Valores inválidos não aplicam estado.
      */
     readonly state: 'danger' | 'success' | 'warning';
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`; valores inválidos não aplicam estado. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`; valores inválidos não aplicam estado. */
     readonly feedbackState?: 'danger' | 'success' | 'warning';
     /**
      * Regra síncrona ou assíncrona executada no `change` ou por `validate()`.

package/dist/types/components/tooltip/tooltip.d.ts

@@ -1,32 +1,26 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { TooltipDensity, TooltipPosition, TooltipState, TooltipType } from './tooltip.types';
 /**
- * O componente `br-tooltip` é a sobreposição informativa flutuante do GovBR-DS, desenvolvida para fornecer dicas breves e esclarecimentos contextuais quando o usuário foca ou posiciona o cursor sobre um elemento da interface.
+ * O `br-tooltip` exibe uma dica rápida e contextual quando o usuário foca ou passa o mouse sobre um elemento.
  *
- * ### Para que serve
+ * Coloque o texto da dica em `text` ou no slot padrão, e vincule-o ao elemento acionador através de `target` ou colocando o acionador no slot `trigger`.
  *
- * - **Esclarecimento contextual imediato:** Revela descrições sucintas para botões de ícone, termos técnicos, siglas ou campos que necessitem de auxílio extra.
- * - **Posicionamento automático:** Posiciona o balão informativo em relação ao elemento de acionamento (topo, direita, baixo, esquerda) ajustando-se dinamicamente ao espaço da tela.
- * - **Acessibilidade WAI-ARIA:** Associa o acionador ao balão com `role="tooltip"` e `aria-describedby`, exibindo-se automaticamente no foco por teclado e fechando com a tecla Escape.
+ * ```html
+ * <br-button id="btn-ajuda" shape="circle" aria-label="Ajuda">?</br-button>
+ * <br-tooltip target="#btn-ajuda" text="Clique para obter informações"></br-tooltip>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Fornecer o rótulo descritivo de um botão que contenha apenas ícone.
- *   - Explicar uma sigla ou termo abreviado na interface.
- * - **Evite e prefira outro componente quando:**
- *   - O conteúdo for extenso, contiver botões interativos ou links navegáveis (prefira `br-dropdown`, `br-modal` ou texto inline fixo, pois tooltips desaparecem ao mover o ponteiro).
- *   - A informação for indispensável para a conclusão de uma tarefa crítica (ela deve estar sempre visível na tela).
+ * - Esclarecer o significado de botões que usam apenas ícones ou rótulos abreviados.
  *
- * ### Estrutura e Slots
+ * ### Quando evitar
  *
- * O `br-tooltip` é composto por acionador e conteúdo:
- * - `trigger`: Slot obrigatório onde a aplicação declara o elemento de controle gatilho (ex.: um `br-button` de ícone).
- * - `content`: Slot onde é inserido o texto ou balão de conteúdo exibido pelo tooltip.
+ * - Informações essenciais que todos os usuários precisam ler imediatamente: exiba como texto visível na página.
+ * - Conteúdos longos com links clicáveis: use `br-message` ou diálogo.
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).
  *
-
  * @category Feedback, Sobreposições
  * @status stable
  * @slot trigger - Slot para o elemento que aciona a exibição do tooltip.

package/dist/types/components/upload/upload.d.ts

@@ -5,41 +5,29 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrFeedbackState } from '../global.types';
 import type { UploadErrorDetail, UploadFileDetail, UploadHandler, UploadProgressDetail, UploadValidator } from './upload.types';
 /**
- * O componente `br-upload` é o elemento oficial do GovBR-DS para seleção, anexação e envio de arquivos em formulários, com suporte a seleção múltipla, área de arrastar-e-soltar (drag-and-drop) e acompanhamento de progresso.
+ * O `br-upload` gerencia a seleção e envio de arquivos em formulários, com suporte a arrastar e soltar (drag and drop).
  *
- * ### Para que serve
+ * Defina os tipos aceitos em `accept` e permita múltiplos arquivos com `multiple`. Use a lista de arquivos para exibir o progresso e o botão de exclusão.
  *
- * - **Seleção e anexação de arquivos:** Permite anexar documentos, planilhas, imagens ou outros formatos através do seletor nativo do sistema operacional ou por arrastar e soltar.
- * - **Validação de tipos e tamanhos:** Valida extensões permitidas (`accept`) e tamanho máximo por arquivo (`max-file-size`), informando erros de validação de forma acessível.
- * - **Listagem visual e remoção:** Exibe a lista de arquivos selecionados com nome, tamanho formatado (KB/MB), barra de progresso individual e botão de exclusão.
- * - **Integração com formulários:** Integrado nativamente via `formAssociated`, permitindo submissão tradicional de formulários ou upload assíncrono programático.
+ * ```html
+ * <br-upload label="Enviar documento" accept=".pdf,.png,.jpg" multiple></br-upload>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se via `ElementInternals`, enviando a lista de arquivos no submit nativo.
  *
- * - **Utilize quando:**
- *   - A pessoa usuária precisar enviar comprovantes, relatórios, fotografias ou documentos digitais.
- *   - For necessário limitar e validar os tipos de arquivo e o tamanho máximo antes do envio ao servidor.
- * - **Evite e prefira outro componente quando:**
- *   - A captura for exclusivamente de texto ou URLs externas (prefira `br-input`).
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Anexar comprovantes, fotos ou documentos em formulários.
  *
- * O `br-upload` possui estrutura rica com múltiplos slots:
- * - `default`: Slot para texto personalizado do botão de upload (padrão: "Selecione o arquivo").
- * - `upload-list`: Slot opcional para substituição da área padrão de listagem de arquivos.
- * - `label`: Slot para personalização do rótulo do campo.
- * - `helper`: Slot para instruções ou restrições de formato/tamanho exibidas abaixo do campo.
- * - `feedback`: Slot para mensagens de validação e erro (como `br-message`).
- * - `loading`: Slot para indicador exibido durante o envio assíncrono dos arquivos.
+ * ### Quando evitar
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/upload?tab=designer).
+ * - Campo de texto ou URL de arquivo remoto: use `br-input`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/upload?tab=designer).
  *
-
  * @category Formulários, Dados
  * @status stable
- * @slot default - Texto personalizado para o botão de upload. Se não fornecido, será exibido "Selecione o arquivo" como texto padrão.
- *                 Use este slot para personalizar o texto do botão de acordo com o contexto do upload, por exemplo: "Anexar documentos",
- *                 "Enviar imagens", etc.
+ * @slot default - Conteúdo personalizado do botão de upload, com precedência sobre `buttonLabel` (use a prop para texto simples).
  * @slot upload-list - Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.
  * @slot label - Rótulo customizado do upload. Quando utilizado, a prop `label` é ignorada.
  * @slot helper - Texto auxiliar exibido abaixo da superfície de seleção.
@@ -121,6 +109,11 @@ export declare class Upload {
      * Rótulo exibido acima do botão de upload.
      */
     label: string;
+    /**
+     * Texto do botão de seleção. Quando omitido, usa "Selecione o arquivo" ou,
+     * com `multiple`, "Selecione o(s) arquivo(s)". O slot padrão tem precedência.
+     */
+    buttonLabel?: string;
     /**
      * Lista de arquivos já enviados (para edição ou pré-visualização).
      * Pode ser uma string JSON ou um array de objetos IUploadFile. Cada item deve ter `name` não vazio e `size` numérico não negativo opcional; itens inválidos são ignorados.
@@ -162,7 +155,7 @@ export declare class Upload {
      * Estado visual: 'info', 'warning', 'danger' ou 'success'. Valores inválidos não aplicam estado.
      */
     state: BrFeedbackState;
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`. */
     feedbackState?: BrFeedbackState;
     /**
      * Indica se o componente permite a seleção de múltiplos arquivos.
@@ -221,7 +214,7 @@ export declare class Upload {
      * @deprecated Use `brUploadRemove`.
      */
     brRemove: EventEmitter<IUploadFile>;
-    /** Evento canônico emitido quando um arquivo existente é removido. */
+    /** Evento emitido quando um arquivo existente é removido. */
     brUploadRemove: EventEmitter<IUploadFile>;
     /** Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada. */
     brUploadCancel: EventEmitter<void>;

package/dist/types/components/wizard/wizard-panel/wizard-panel.d.ts

@@ -1,18 +1,8 @@
 /**
- * Subcomponente individual de `br-wizard`, responsável por encapsular o formulário, campos de entrada ou informações pertencentes a uma etapa específica do fluxo guiado.
+ * Painel de conteúdo de uma etapa individual do `br-wizard`.
  *
- * ### Papel na composição
+ * Defina o título da etapa em `title-text`. Insira os campos e conteúdos dessa fase no slot padrão.
  *
- * - Agrupa todos os campos de formulário e conteúdos daquela etapa.
- * - Informa o título e subtítulo da etapa que serão refletidos na barra de progresso do wizard.
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser declarado no slot padrão do orquestrador `br-wizard`. O componente pai é quem decide qual painel deve estar visível com base na etapa corrente, coordenando os botões de avançar e voltar. Não deve ser instanciado de forma autônoma fora de um `br-wizard`.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
- *
-
  * @slot default - Slot para o conteúdo da etapa (formulários, campos ou informações da fase atual).
  *
  * @part panel - Wrapper do painel.

package/dist/types/components/wizard/wizard.d.ts

@@ -1,39 +1,35 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrOrientation, BrProgressionType } from '../global.types';
 /**
- * O componente `br-wizard` é o orquestrador completo de fluxos passo a passo do GovBR-DS, desenvolvido para guiar a pessoa usuária através de formulários e tarefas complexas distribuídas em etapas consecutivas.
+ * O `br-wizard` conduz fluxos passo a passo divididos em telas sequenciais com botões de navegação e barra de progresso.
  *
- * ### Para que serve
+ * Insira cada tela com `br-wizard-panel` no slot padrão. Acompanhe a mudança de etapas pelo evento `brStepChange`.
  *
- * - **Condução guiada de processos:** Apresenta um formulário longo dividido em etapas menores e focadas, reduzindo a carga cognitiva e o índice de abandono.
- * - **Barra de progresso e navegação integradas:** Combina o indicador visual de etapas (`step`), os painéis de conteúdo de cada etapa (`br-wizard-panel`) e a barra de ações com botões de "Voltar", "Avançar", "Concluir" e "Cancelar".
- * - **Validação por etapa:** Permite interceptar o avanço de cada passo para validação antes de liberar o próximo painel.
+ * ```html
+ * <br-wizard>
+ *   <br-wizard-panel title-text="Identificação">
+ *     <p>Primeira etapa do cadastro.</p>
+ *   </br-wizard-panel>
+ *   <br-wizard-panel title-text="Endereço">
+ *     <p>Segunda etapa do cadastro.</p>
+ *   </br-wizard-panel>
+ *   <br-wizard-panel title-text="Confirmação">
+ *     <p>Revise os dados antes de enviar.</p>
+ *   </br-wizard-panel>
+ * </br-wizard>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Houver um processo de cadastro, requerimento, compra ou configuração estruturado em etapas com dependência de sequência.
- *   - For essencial oferecer navegação pré-programada de retorno e avanço com controle de estado.
- * - **Evite e prefira outro componente quando:**
- *   - O objetivo for apenas mostrar o status de um pedido já concluído (use `br-step` simples).
- *   - O usuário puder navegar em qualquer ordem entre as seções da tela (use `br-tab`).
+ * - Formulários extensos com dependência lógica entre etapas.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-wizard` | **Orquestrador principal.** Gerencia a barra de progresso, ações de navegação (voltar/avançar), botões de rodapé e controle do painel ativo. | Deve ser o contêiner raiz do fluxo. |
- * | `br-wizard-panel` | **Painel de etapa individual.** Contém os campos e formulários de uma etapa específica. | Declarado dentro do slot padrão do `br-wizard`. |
+ * - Apenas indicar o status de um pedido já realizado: use `br-step`.
+ * - Conteúdos independentes onde a ordem de preenchimento é livre: use `br-tab`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
  *
- * O `br-wizard` gerencia ativamente os elementos `br-wizard-panel` declarados em seu interior:
- * 1. O pai exibe apenas o painel correspondente à etapa atual (`activeStep`), mantendo os demais ocultos.
- * 2. Ao avançar ou retroceder, o `br-wizard` dispara eventos de validação e troca de etapa (`brStepChange`), atualizando simultaneamente o cabeçalho de progresso e as ações do rodapé.
- *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
- *
-
  * @category Navegação, Formulários, Progresso
  * @status stable
  * @slot default - Slot para os painéis de etapa (br-wizard-panel) do wizard.