@govbr-ds/webcomponents 2.1.2 → 2.2.0

package/cem/webcomponents.html-custom-data.json

@@ -4,11 +4,11 @@
   "tags": [
     {
       "name": "br-avatar",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/avatar?tab=designer).\n---\n\n\n### **Methods:**\n - **handleDensityChange(newValue: _AvatarDensity_)** - Observa mudanças na propriedade density para validação e sincronização com atributo DOM.\nGarante que apenas valores válidos sejam aceitos e atualiza o atributo no elemento host.\n- **setFocus()** - Move o foco programaticamente para o avatar.\n\n### **Slots:**\n - **status** - Conteúdo customizado para o indicador de status. Quando usado, substitui a tag padrão.\n\n### **CSS Parts:**\n - **container** - Elemento externo do avatar.\n- **content** - Conteúdo interno do avatar (imagem, ícone ou texto).\n- **status** - Indicador de status posicionado sobre o avatar.",
+      "description": "O componente `br-avatar` é a representação visual compacta de um usuário, pessoa ou entidade no GovBR-DS. Ele exibe fotos de perfil, ícones institucionais ou iniciais textuais com suporte a múltiplos tamanhos, temas e indicador de status contextual.\n\n### Para que serve\n\n- **Identificação visual de perfil:** Exibe a foto do usuário logado em barras de cabeçalho, cartões de perfil, listas de contatos ou comentários.\n- **Resiliência e fallback visual:** Caso a imagem informada falhe ao carregar (`src`), o componente passa suavemente para o ícone padrão ou texto alternativo sem quebrar o leiaute.\n- **Indicador de status integrado:** Informa estados operacionais (online, offline, ocupado, ausente) através do slot dedicado `status`.\n- **Acessibilidade:** Garante descrição textual adequada através da propriedade `alt`, essencial para pessoas que utilizam leitores de tela.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - For necessário identificar a pessoa autenticada no cabeçalho ou menu da aplicação.\n  - Exibir listas de contatos, autores de publicações, membros de equipe ou participantes de um fluxo colaborativo.\n  - Indicar o status de disponibilidade de um usuário ou atendente no sistema.\n- **Evite e prefira outro componente quando:**\n  - For necessária uma exibição de imagem ilustrativa ampla ou promocional (prefira tags HTML `<img>` semânticas ou contêineres ilustrativos do design).\n  - O elemento requerer interações ricas com múltiplas ações (prefira compor com `br-card`).\n\n### Estrutura e Slots\n\nO `br-avatar` é um componente autônomo e direto:\n- `default`: Conteúdo interno livre (quando não for utilizada imagem via prop `src`), permitindo inserir ícones como `br-icon` ou texto de iniciais.\n- `status`: Slot posicionado para inserção de um indicador visual de status sobreposto ao avatar.\n\nPara 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/avatar?tab=designer).\n---\n\n\n### **Methods:**\n - **handleDensityChange(newValue: _AvatarDensity_)** - Observa mudanças na propriedade density para validação e sincronização com atributo DOM.\nGarante que apenas valores válidos sejam aceitos e atualiza o atributo no elemento host.\n- **setFocus()** - Move o foco programaticamente para o avatar.\n\n### **Slots:**\n - **status** - Conteúdo customizado para o indicador de status. Quando usado, substitui a tag padrão.\n\n### **CSS Parts:**\n - **container** - Elemento externo do avatar.\n- **content** - Conteúdo interno do avatar (imagem, ícone ou texto).\n- **status** - Indicador de status posicionado sobre o avatar.",
       "attributes": [
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "AvatarDensity" }]
         },
         {
@@ -73,7 +73,7 @@
         },
         {
           "name": "status-position",
-          "description": "Posição do indicador de status sobre o avatar.",
+          "description": "Posição do indicador de status sobre o avatar. Aceita `top-right`, `bottom-right`, `top-left` ou `bottom-left`.\nValores inválidos usam `top-right`.",
           "values": [{ "name": "AvatarStatusPosition" }]
         }
       ],
@@ -81,7 +81,7 @@
     },
     {
       "name": "br-breadcrumb",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **default** - Itens de breadcrumb declarados via elementos br-crumb.\n\n### **CSS Parts:**\n - **nav** - Elemento nav do breadcrumb.\n- **list** - Lista ordenada de itens do breadcrumb.",
+      "description": "O componente `br-breadcrumb` é o controle de navegação estrutural do GovBR-DS, desenvolvido para exibir o caminho hierárquico até a página atual e permitir que a pessoa usuária retorne facilmente a níveis anteriores da aplicação.\n\n### Para que serve\n\n- **Localização contextual:** Informa em qual nível da arquitetura de informação o usuário se encontra dentro do portal ou sistema.\n- **Navegação de retorno:** Oferece atalhos diretos para páginas ancestrais sem a necessidade de recorrer repetidamente ao botão \"Voltar\" do navegador.\n- **Acessibilidade estruturada WAI-ARIA:** Utiliza a semântica nativa de `<nav aria-label=\"Breadcrumb\">`, identifica a página atual com `aria-current=\"page\"` e gera separadores visuais acessíveis.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A aplicação possuir estrutura hierárquica com dois ou mais níveis de profundidade (ex.: Início > Serviços > Cidadão > Solicitar documento).\n- **Evite e prefira outro componente quando:**\n  - A aplicação possuir navegação plana (flat) de nível único sem hierarquia.\n  - O fluxo for linear com etapas progressivas de um formulário (prefira `br-step` ou `br-wizard`).\n\n### Composição e Subcomponentes\n\nO ecossistema do Breadcrumb é composto pelo orquestrador e seus itens:\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-breadcrumb` | **Orquestrador principal.** Gerencia a trilha de navegação, insere separadores visuais e controla acessibilidade. | Deve ser o contêiner raiz declarado no template da página. |\n| `br-breadcrumb-item` | **Item declarativo canônico.** Representa cada nível do caminho hierárquico. | Declarado dentro do slot padrão do `br-breadcrumb`. |\n| `br-crumb` | **Item legado de compatibilidade.** Equivalente ao `br-breadcrumb-item`. | Mantido para compatibilidade; prefira `br-breadcrumb-item` em novos códigos. |\n\n### Como os subcomponentes se relacionam\n\nO `br-breadcrumb` atua como container pai que monitora os itens declarados em seu slot padrão:\n1. **Identificação da página atual:** O último item da lista é automaticamente identificado como o destino atual, recebendo destaque visual e `aria-current=\"page\"` sem link ativo.\n2. **Separação visual padronizada:** O componente pai insere e padroniza os ícones separadores entre os níveis sem poluir a árvore do leitor de tela.\n\nPara 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/breadcrumb?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **default** - Itens de breadcrumb declarados via elementos br-breadcrumb-item. O elemento br-crumb é aceito apenas por compatibilidade.\n\n### **CSS Parts:**\n - **nav** - Elemento nav do breadcrumb.\n- **list** - Lista ordenada de itens do breadcrumb.",
       "attributes": [
         {
           "name": "custom-id",
@@ -98,14 +98,19 @@
           "description": "URL canônica da página inicial. Quando informada, tem precedência sobre `homeUrl`.",
           "values": []
         },
+        {
+          "name": "truncate-after",
+          "description": "Quantidade máxima de crumbs exibidos antes de ativar o modo truncado.\nQuando omitida, o truncamento continua sendo decidido apenas pelo espaço disponível.\nValores inválidos são ignorados.",
+          "values": []
+        },
         {
           "name": "crumbs",
-          "description": "Define o array de objetos que receberá os nomes e links do breadcrumb.\nDefine valor padrão do breadcrumb 'defaultCrumbs'.",
+          "description": "Fornece os nomes e links do breadcrumb.\nUse uma string JSON no atributo HTML ou um array de `BreadcrumbItem` por property binding.\nCada item deve ter `label` string e pode ter `href`, `target`, `home` e `active`.\nItens inválidos são ignorados; se nenhum item válido restar, usa `defaultCrumbs` e avisa no console.",
           "values": [{ "name": "BreadcrumbItem[]" }]
         },
         {
           "name": "navigation-mode",
-          "description": "Controla como os links do breadcrumb integram a navegação mantendo `href` real nos itens navegáveis.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.",
+          "description": "Controla como os links do breadcrumb integram a navegação mantendo `href` real nos itens navegáveis.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.\nValores inválidos usam `native`.",
           "values": [{ "name": "BrNavigationMode" }]
         }
       ],
@@ -113,7 +118,7 @@
     },
     {
       "name": "br-breadcrumb-item",
-      "description": "Item declarativo canônico de `br-breadcrumb`.\n---\n\n\n### **Events:**\n - **brCrumbPropsChange** - Protocolo compatível com o listener atual do breadcrumb.\n\n### **Slots:**\n - **default** - Conteúdo alternativo do rótulo.",
+      "description": "Subcomponente declarativo canônico de `br-breadcrumb`, utilizado para representar cada nível individual dentro da trilha hierárquica de navegação.\n\n### Papel na composição\n\n- Define o rótulo legível e o destino de navegação (`href`) de um nível hierárquico específico.\n- Suporta a propriedade `home` para renderizar o ícone institucional da página inicial no primeiro item da trilha.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado exclusivamente dentro do slot padrão do orquestrador `br-breadcrumb`. Ele não deve ser utilizado isoladamente fora da trilha de breadcrumb. O componente pai monitora os itens para aplicar automaticamente os separadores visuais e demarcar o último item como a página atual.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).\n---\n\n\n### **Events:**\n - **brCrumbPropsChange** - Protocolo compatível com o listener atual do breadcrumb.\n\n### **Slots:**\n - **default** - Conteúdo alternativo do rótulo. Quando usado, substitui o texto fornecido em `label`.",
       "attributes": [
         { "name": "label", "description": "Rótulo do item.", "values": [] },
         { "name": "href", "description": "URL do item.", "values": [] },
@@ -137,7 +142,7 @@
     },
     {
       "name": "br-crumb",
-      "description": "@deprecated Use `br-breadcrumb-item`.\n\nPara a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/breadcrumb?tab=designer).\n---\n\n\n### **Events:**\n - **brCrumbPropsChange** - Evento disparado quando as propriedades do crumb mudam.\nO componente pai (br-breadcrumb) escuta este evento para se atualizar.\n\n### **Slots:**\n - **default** - Conteúdo alternativo do rótulo do item de navegação.",
+      "description": "@deprecated Use `br-breadcrumb-item`.\n\nSubcomponente legado de `br-breadcrumb`, mantido para compatibilidade com implementações existentes que utilizavam a nomenclatura antiga.\n\n### Papel na composição\n\n- Equivalente funcional do `br-breadcrumb-item`, representando um nível na trilha de navegação.\n\n### Regra de uso e relacionamento\n\nDeclarado dentro do slot padrão do `br-breadcrumb`. Em novos desenvolvimentos e manutenções ativas, **recomenda-se utilizar a tag canônica `br-breadcrumb-item`**.\n\nPara a documentação canônica completa, consulte a página do [br-breadcrumb](/docs/components/breadcrumb).\n---\n\n\n### **Events:**\n - **brCrumbPropsChange** - Evento disparado quando as propriedades do crumb mudam.\nO componente pai (br-breadcrumb) escuta este evento para se atualizar.\n\n### **Slots:**\n - **default** - Conteúdo alternativo do rótulo do item de navegação.",
       "attributes": [
         {
           "name": "label",
@@ -169,11 +174,11 @@
     },
     {
       "name": "br-button",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/button?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para o rótulo ou conteúdo do botão.\n\n### **CSS Parts:**\n - **button** - Parte para o elemento button interno, usada para estilos customizados via ::part(button).",
+      "description": "O componente `br-button` é o controle fundamental de ação e acionamento do GovBR-DS. Desenvolvido para permitir que pessoas usuárias executem comandos, confirmem intenções e submetam ou redefinam formulários, ele oferece retorno visual imediato e conformidade com diretrizes de acessibilidade WAI-ARIA.\n\n### Para que serve\n\n- **Disparo de ações do sistema:** Executa comandos locais ou assíncronos na interface (ex.: salvar dados, abrir modais, aplicar filtros).\n- **Integração com formulários:** Suporta os tipos nativos de botão (`type=\"button\"`, `type=\"submit\"` e `type=\"reset\"`), integrando-se ao ciclo de submissão do formulário HTML.\n- **Variantes e hierarquia visual:** Oferece diferentes estilos visuais (primário, secundário), densidades e opções de exibição (com ícone, somente ícone, circular e em bloco).\n- **Feedback de carregamento e estado:** Informa estados de processamento com o modo `loading` e desativação acessível com `disabled`.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A pessoa usuária precisar executar uma ação imediata ou submeter dados dentro do fluxo atual da página.\n  - For necessário acionar componentes flutuantes (como abrir `br-modal`, alternar `br-collapse` ou expandir `br-dropdown`).\n- **Evite e prefira outro componente quando:**\n  - A ação tiver como objetivo navegar para outra página ou alterar a URL do navegador (prefira `br-link` ou um elemento `<a>` nativo).\n  - O controle representar uma escolha de valor fixo entre poucas opções mutuamente exclusivas (prefira `br-radio` ou `br-radio-group`).\n\n### Estrutura e Slots\n\nO `br-button` é um controle direto e autônomo:\n- `default`: Slot para inserção do texto do rótulo, ícones de apoio (`br-icon`) ou composições personalizadas.\n\nPara 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/button?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para o rótulo ou conteúdo do botão.\n\n### **CSS Parts:**\n - **button** - Parte para o elemento button interno, usada para estilos customizados via ::part(button).",
       "attributes": [
         {
           "name": "color-mode",
-          "description": "Define se o botão usará um esquema de cores escuro.",
+          "description": "Define se o botão usará um esquema de cores escuro. Valores inválidos são ignorados.",
           "values": [{ "name": "ButtonColorMode" }]
         },
         {
@@ -183,7 +188,7 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "ButtonDensity" }]
         },
         {
@@ -193,7 +198,7 @@
         },
         {
           "name": "emphasis",
-          "description": "Define a ênfase do botão, alterando sua aparência para criar hierarquia visual e destacar ações importantes.",
+          "description": "Define a ênfase do botão, alterando sua aparência para criar hierarquia visual e destacar ações importantes. Valores inválidos são ignorados.",
           "values": [{ "name": "ButtonEmphasis" }]
         },
         {
@@ -218,12 +223,12 @@
         },
         {
           "name": "shape",
-          "description": "Define o formato do botão.",
+          "description": "Define o formato do botão. Valores inválidos são ignorados.",
           "values": [{ "name": "ButtonShape" }]
         },
         {
           "name": "type",
-          "description": "Define o tipo de botão, especificando seu comportamento padrão.",
+          "description": "Define o tipo de botão, especificando seu comportamento padrão. Valores inválidos usam `button`.",
           "values": [{ "name": "ButtonType" }]
         },
         {
@@ -233,7 +238,7 @@
         },
         {
           "name": "custom-tab-index",
-          "description": "Define o índice de tabulação do botão.\nÚtil para remover o botão da sequência de tabulação (tabindex=\"-1\") quando ele é puramente decorativo ou o foco é gerenciado por um componente pai.",
+          "description": "Define o índice de tabulação do botão.\nÚtil para remover o botão da sequência de tabulação (tabindex=\"-1\") quando ele é puramente decorativo ou o foco é gerenciado por um componente pai.\nAceita inteiros maiores ou iguais a -1; valores inválidos são ignorados.",
           "values": []
         },
         {
@@ -258,7 +263,7 @@
         },
         {
           "name": "aria-haspopup",
-          "description": "Indica que o botão abre um menu, listbox, tree, grid ou dialog.\nOs valores permitidos são: 'true', 'menu', 'listbox', 'tree', 'grid' ou 'dialog'.",
+          "description": "Indica que o botão abre um menu, listbox, tree, grid ou dialog.\nOs valores permitidos são: 'true', 'menu', 'listbox', 'tree', 'grid' ou 'dialog'.\nValores inválidos são removidos do elemento interno.",
           "values": [{ "name": "AriaHasPopup" }]
         }
       ],
@@ -266,7 +271,7 @@
     },
     {
       "name": "br-card",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/card?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para conteúdo livre do card, quando não usar a estrutura de slots nomeados.\n- **media** - Slot para conteúdo de mídia exibido antes do cabeçalho.\n- **header** - Slot para o conteúdo do cabeçalho do card.\n- **content** - Slot para o corpo principal do card ao usar a estrutura de slots.\n- **footer** - Slot para o conteúdo do rodapé do card.\n\n### **CSS Parts:**\n - **wrapper** - Área principal do card.\n- **media** - Área de mídia do card.\n- **header** - Área do cabeçalho.\n- **content** - Área do conteúdo principal.\n- **footer** - Área do rodapé.",
+      "description": "O componente `br-card` é um contêiner estruturado e flexível do GovBR-DS, projetado para agrupar informações, mídias e ações correlacionadas em uma superfície visual coesa e destacada.\n\n### Para que serve\n\n- **Agrupamento de informações modulares:** Organiza conteúdos heterogêneos de um mesmo assunto (como resumos de serviços, cartões de notícias, painéis de métricas ou resultados de busca).\n- **Segmentação visual limpa:** Proporciona hierarquia e legibilidade através de bordas, elevações e espaçamentos padronizados pelos tokens do design system.\n- **Suporte a interação opcional:** Pode atuar como elemento estático de leitura ou como contêiner interativo/navegável.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Desejar exibir blocos independentes de conteúdo em grades (grid) ou listas de cartões.\n  - O conteúdo for composto por uma combinação de elementos (imagem/vídeo, cabeçalho, texto explicativo e botões de ação).\n- **Evite e prefira outro componente quando:**\n  - Os dados forem puramente tabulares ou comparativos entre múltiplos itens homogêneos (prefira `br-table`).\n  - Houver apenas uma sequência linear simples de textos ou links (prefira `br-list`).\n\n### Estrutura e Slots\n\nO `br-card` oferece estrutura modular com slots nomeados ou composição livre:\n- `media`: Slot superior para exibição de imagens, ilustrações ou mídia de destaque.\n- `header`: Slot para título, subtítulo ou cabeçalho informativo do card.\n- `content`: Slot principal para o corpo de texto e conteúdo descritivo.\n- `footer`: Slot inferior para botões de ação (`br-button`), links complementares ou metadados.\n- `default`: Slot livre para renderização direta quando não for necessária a divisão pré-definida em seções.\n\nPara 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/card?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para conteúdo livre do card, quando não usar a estrutura de slots nomeados.\n- **media** - Slot para conteúdo de mídia exibido antes do cabeçalho.\n- **header** - Slot para o conteúdo do cabeçalho do card.\n- **content** - Slot para o corpo principal do card ao usar a estrutura de slots.\n- **footer** - Slot para o conteúdo do rodapé do card.\n\n### **CSS Parts:**\n - **wrapper** - Área principal do card.\n- **media** - Área de mídia do card.\n- **header** - Área do cabeçalho.\n- **content** - Área do conteúdo principal.\n- **footer** - Área do rodapé.",
       "attributes": [
         {
           "name": "custom-id",
@@ -293,7 +298,7 @@
     },
     {
       "name": "br-carousel",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/carousel?tab=designer).\n---\n\n\n### **Events:**\n - **brDidPageChange** - Emitido quando o slide ativo muda.\nDisparado por clique nos botões de navegação, clique no indicador de step,\ngesto swipe (apenas em mobile, breakpoint < 576px) ou avanço automático.\n`activePage` é 1-based: o primeiro slide emite `1`, o segundo `2`, e assim por diante.\n- **brCarouselPageChange** - Evento canônico emitido quando o slide ativo muda.\n- **brDidAutoPlayStart** - Emitido quando a reprodução automática é iniciada ou retomada.\n- **brCarouselAutoplayStart** - Evento canônico emitido quando a reprodução automática começa.\n- **brDidAutoPlayPause** - Emitido quando a reprodução automática é pausada.\n- **brCarouselAutoplayPause** - Evento canônico emitido quando a reprodução automática é pausada.\n\n### **Methods:**\n - **onTablistKeydown(e: _KeyboardEvent_)** - Navegação por teclado para o modo tablist (`indicatorType=\"simple\"`).\n\nO W3C APG Carousel Pattern especifica que, quando os controles de seleção de slide\nsão implementados como tabs, a interação de teclado segue o\nhttps://www.w3.org/WAI/ARIA/apg/patterns/tabs/ Tabs Pattern (W3C APG).\nEsse padrão define o comportamento de roving tabindex com as teclas:\n- `ArrowLeft` / `ArrowRight` (ou `ArrowUp` / `ArrowDown`): move o foco entre as tabs.\n- `Home`: move o foco para a primeira tab.\n- `End`: move o foco para a última tab.\n\nO handler está no `br-carousel` (e não no `br-step`) porque a lógica de\n`effectiveCircular` é uma responsabilidade do carrossel, mantendo uma única\nfonte de verdade para a navegação circular.\n\nO evento `keydown` é composto (`composed: true`), portanto borbulha através do\nshadow DOM do `br-step-item` até o host do `br-carousel`.\n- **nextPage(): _Promise<void>_** - Avança para o próximo slide. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).\n- **previousPage(): _Promise<void>_** - Retorna ao slide anterior. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).\n- **goToPage(index: _number_): _Promise<void>_** - Navega para o slide de número `index` (1 = primeiro slide, 2 = segundo, …).\nValores fora do intervalo válido são ignorados.\n- **getActivePage(): _Promise<number>_** - Retorna o número do slide atualmente ativo (1 = primeiro slide, 2 = segundo, …).\n- **play(): _Promise<void>_** - Inicia ou retoma a reprodução automática programaticamente.\n- **pause(): _Promise<void>_** - Pausa a reprodução automática programaticamente.\n- **getIsPlaying(): _Promise<boolean>_** - Retorna `true` se a reprodução automática está ativa no momento.\n\n### **Slots:**\n - **default** - Slot para os slides do carrossel. Aceita exclusivamente elementos `br-carousel-page`.\n\n### **CSS Parts:**\n - **container** - Elemento raiz do carrossel. Recebe `role=\"region\"` e `aria-roledescription=\"carousel\"`.\n- **stage** - Área do palco que contém os slides. Recebe `aria-live` e `aria-atomic`.\n- **nav-prev** - Wrapper do botão de navegação para o slide anterior.\n- **nav-next** - Wrapper do botão de navegação para o próximo slide.\n- **indicator** - Wrapper do indicador de páginas. - Quando `indicatorType=\"simple\"`: renderiza `br-step` em `mode=\"tablist\"`. - Quando `indicatorType=\"textual\"`: renderiza um `span[aria-live]` com \"X/N\".\n- **play-button** - Wrapper do botão de play/pause. Presente apenas quando `autoPlay=true`.",
+      "description": "O componente `br-carousel` é o contêiner de apresentação rotativa e sequencial de conteúdos do GovBR-DS, desenvolvido para exibir múltiplos slides em um espaço delimitado onde apenas um item (ou grupo ativo) fica em foco por vez.\n\n### Para que serve\n\n- **Apresentação rotativa de destaque:** Ideal para galerias visuais, banners informativos, campanhas institucionais e passos ilustrativos.\n- **Navegação assistida:** Fornece controles de avanço e retrocesso (setas), barra de indicadores de página/slides (bolinhas de paginação) e suporte a gestos de toque (swipe) em dispositivos móveis.\n- **Reprodução automática controlável:** Suporta transição automática temporizada com botão obrigatório de pausa/reprodução para conformidade com diretrizes de acessibilidade (WCAG).\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Houver um conjunto de imagens, avisos ou destaques que compartilham o mesmo nível de relevância visual.\n  - O espaço vertical da página for restrito e comportar a rotação sequencial de conteúdos.\n- **Evite e prefira outro componente quando:**\n  - Todas as informações forem cruciais para a tarefa do usuário e precisarem ficar simultaneamente visíveis (prefira uma grade com `br-card`).\n  - O fluxo representar preenchimento obrigatório de formulário por etapas (prefira `br-wizard` ou `br-step`).\n\n### Composição e Subcomponentes\n\nO ecossistema do Carousel é composto por:\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-carousel` | **Orquestrador principal.** Gerencia a rotação, temporizador, botões de paginação, navegação por teclado e gestos. | Contêiner raiz obrigatório declarado na página. |\n| `br-carousel-page` | **Slide individual.** Encapsula o conteúdo visual ou textual de cada página do carrossel. | Declarado dentro do slot padrão do `br-carousel`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-carousel` projeta internamente os controles de navegação e gerencia os elementos `br-carousel-page` declarados em seu interior:\n1. O componente pai monitora os slides filhos, calcula o total de páginas e gera dinamicamente os botões indicadores.\n2. Apenas a página correspondente ao índice ativo é exibida e anunciada para leitores de tela com atributos `aria-roledescription=\"slide\"`.\n\nPara 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/carousel?tab=designer).\n---\n\n\n### **Events:**\n - **brDidPageChange** - Emitido quando o slide ativo muda.\nDisparado por clique nos botões de navegação, clique no indicador de step,\ngesto swipe (apenas em mobile, breakpoint < 576px) ou avanço automático.\n`activePage` é 1-based: o primeiro slide emite `1`, o segundo `2`, e assim por diante.\n- **brCarouselPageChange** - Evento canônico emitido quando o slide ativo muda.\n- **brDidAutoPlayStart** - Emitido quando a reprodução automática é iniciada ou retomada.\n- **brCarouselAutoplayStart** - Evento canônico emitido quando a reprodução automática começa.\n- **brDidAutoPlayPause** - Emitido quando a reprodução automática é pausada.\n- **brCarouselAutoplayPause** - Evento canônico emitido quando a reprodução automática é pausada.\n\n### **Methods:**\n - **onTablistKeydown(e: _KeyboardEvent_)** - Navegação por teclado para o modo tablist (`indicatorType=\"simple\"`).\n\nO W3C APG Carousel Pattern especifica que, quando os controles de seleção de slide\nsão implementados como tabs, a interação de teclado segue o\nhttps://www.w3.org/WAI/ARIA/apg/patterns/tabs/ Tabs Pattern (W3C APG).\nEsse padrão define o comportamento de roving tabindex com as teclas:\n- `ArrowLeft` / `ArrowRight` (ou `ArrowUp` / `ArrowDown`): move o foco entre as tabs.\n- `Home`: move o foco para a primeira tab.\n- `End`: move o foco para a última tab.\n\nO handler está no `br-carousel` (e não no `br-step`) porque a lógica de\n`effectiveCircular` é uma responsabilidade do carrossel, mantendo uma única\nfonte de verdade para a navegação circular.\n\nO evento `keydown` é composto (`composed: true`), portanto borbulha através do\nshadow DOM do `br-step-item` até o host do `br-carousel`.\n- **nextPage(): _Promise<void>_** - Avança para o próximo slide. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).\n- **previousPage(): _Promise<void>_** - Retorna ao slide anterior. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).\n- **goToPage(index: _number_): _Promise<void>_** - Navega para o slide de número `index` (1 = primeiro slide, 2 = segundo, …).\nValores fora do intervalo válido são ignorados.\n- **getActivePage(): _Promise<number>_** - Retorna o número do slide atualmente ativo (1 = primeiro slide, 2 = segundo, …).\n- **play(): _Promise<void>_** - Inicia ou retoma a reprodução automática programaticamente.\n- **pause(): _Promise<void>_** - Pausa a reprodução automática programaticamente.\n- **getIsPlaying(): _Promise<boolean>_** - Retorna `true` se a reprodução automática está ativa no momento.\n\n### **Slots:**\n - **default** - Slot para os slides do carrossel. Aceita exclusivamente elementos `br-carousel-page`.\n\n### **CSS Parts:**\n - **container** - Elemento raiz do carrossel. Recebe `role=\"region\"` e `aria-roledescription=\"carousel\"`.\n- **stage** - Área do palco que contém os slides. Recebe `aria-live` e `aria-atomic`.\n- **nav-prev** - Wrapper do botão de navegação para o slide anterior.\n- **nav-next** - Wrapper do botão de navegação para o próximo slide.\n- **indicator** - Wrapper do indicador de páginas. - Quando `indicatorType=\"simple\"`: renderiza `br-step` em `mode=\"tablist\"`. - Quando `indicatorType=\"textual\"`: renderiza um `span[aria-live]` com \"X/N\".\n- **play-button** - Wrapper do botão de play/pause. Presente apenas quando `autoPlay=true`.",
       "attributes": [
         {
           "name": "custom-id",
@@ -342,7 +347,7 @@
         },
         {
           "name": "interval",
-          "description": "Intervalo em milissegundos entre cada avanço automático.\nSó tem efeito quando `autoPlay=true`.",
+          "description": "Intervalo em milissegundos entre cada avanço automático.\nDeve ser um inteiro maior que 0; valores inválidos usam `5000`.\nSó tem efeito quando `autoPlay=true`.",
           "values": []
         },
         {
@@ -385,7 +390,7 @@
     },
     {
       "name": "br-carousel-page",
-      "description": "## Design System\n\nSubcomponente do `br-carousel`. Representa um slide individual dentro do carrossel.\nDeve ser usado exclusivamente como filho direto de `br-carousel`.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/carousel?tab=designer).\n---\n\n\n### **Methods:**\n - **setLabel(defaultLabel: _string_): _Promise<void>_** - Define o label acessível (`aria-label`) do slide.\n\nChamado pelo `br-carousel` pai para aplicar o label gerado automaticamente\ncom base na posição do slide (ex: `\"Slide 1 de 3\"`).\n\nO `aria-label` declarado diretamente no elemento tem prioridade:\nse o consumidor definir `aria-label` no HTML ou via `setAttribute`,\nesse valor será mantido e o parâmetro `defaultLabel` será ignorado.\n- **setActive(active: _boolean_): _Promise<void>_** - Ativa ou desativa o slide.\n\n### **Slots:**\n - **default** - Qualquer conteúdo: imagens, textos, cards, vídeos, outros componentes do Design System.\n\n### **CSS Parts:**\n - **content** - Wrapper interno do conteúdo do slide.",
+      "description": "Subcomponente especializado de `br-carousel`, responsável por encapsular exatamente um slide ou página individual dentro da sequência de apresentação.\n\n### Papel na composição\n\n- Contém a mídia visual (imagem, ilustração ou vídeo), textos informativos e botões de ação associados àquele slide específico.\n- Recebe as classes e propriedades de visibilidade ativa gerenciadas pelo carrossel pai.\n\n### Regra de uso e relacionamento\n\nDeve ser instanciado exclusivamente dentro do slot padrão do orquestrador `br-carousel`. O componente pai coordena as transições de deslize, calcula o índice do slide e gerencia a acessibilidade. Não deve ser usado como elemento autônomo fora de um carrossel.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/carousel?tab=designer).\n---\n\n\n### **Methods:**\n - **setLabel(defaultLabel: _string_): _Promise<void>_** - Define o label acessível (`aria-label`) do slide.\n\nChamado pelo `br-carousel` pai para aplicar o label gerado automaticamente\ncom base na posição do slide (ex: `\"Slide 1 de 3\"`).\n\nO `aria-label` declarado diretamente no elemento tem prioridade:\nse o consumidor definir `aria-label` no HTML ou via `setAttribute`,\nesse valor será mantido e o parâmetro `defaultLabel` será ignorado.\n- **setActive(active: _boolean_): _Promise<void>_** - Ativa ou desativa o slide.\n\n### **Slots:**\n - **default** - Qualquer conteúdo: imagens, textos, cards, vídeos, outros componentes do Design System.\n\n### **CSS Parts:**\n - **content** - Wrapper interno do conteúdo do slide.",
       "attributes": [
         {
           "name": "custom-id",
@@ -402,7 +407,7 @@
     },
     {
       "name": "br-checkbox",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/checkbox?tab=designer).\n---\n\n\n### **Events:**\n - **checkedChange** - Disparado depois que o valor do `checked` foi alterado.\n- **indeterminateChange** - Disparado depois que o valor do `indeterminate` foi alterado.\n- **brCheckboxValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do checkbox for válido, caso contrário `false`.\nSe o checkbox for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do checkbox for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o checkbox.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do checkbox e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **setIndeterminate(value: _boolean_)** - Define o estado indeterminado do checkbox.\n- **toggleChecked()** - @deprecated Atualize a propriedade `checked` diretamente. - Inverte o valor da prop `checked`\n- **setNumberOfChildren(value: _number_)** - Define o número de checkboxes filhos em um grupo de checkboxes.\n\n### **Slots:**\n - **default** - Slot para o rótulo do checkbox, como alternativa à propriedade label.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do checkbox.\n- **input** - Elemento input nativo do checkbox.\n- **label** - Rótulo do checkbox.\n- **feedback** - Contêiner da mensagem de validação.",
+      "description": "O componente `br-checkbox` é o controle de formulário oficial do GovBR-DS para seleção binária independente (marcado ou desmarcado) ou intermediária (indeterminada). Compatível com as diretrizes WAI-ARIA para checkboxes, ele integra-se nativamente a formulários HTML via `formAssociated`.\n\n### Para que serve\n\n- **Seleção independente múltipla:** Permite que a pessoa usuária escolha qualquer quantidade de opções (zero, uma ou várias) de uma lista de alternativas independentes.\n- **Confirmação e aceite binário:** Utilizado para termos de uso, declarações de concordância e confirmações obrigatórias.\n- **Estado indeterminado:** Suporta a propriedade `indeterminate`, essencial para checkboxes mestres em listas hierárquicas (indicando que parte dos itens filhos está marcada).\n- **Validação e formulários:** Comunica valor, estado de validação e mensagens contextuais de erro (`feedback`) diretamente com a API nativa de formulários HTML (`ElementInternals`).\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Houver uma lista de opções onde a seleção de uma alternativa não anula nem depende das demais.\n  - O usuário precisar confirmar explicitamente uma condição única (ex.: \"Li e concordo com os termos\").\n  - For necessário criar controle de seleção em lote (\"Selecionar todos\").\n- **Evite e prefira outro componente quando:**\n  - As opções forem mutuamente exclusivas (apenas uma pode ser escolhida): prefira `br-radio` ou `br-radio-group`.\n  - A ação ativar ou desativar instantaneamente um recurso sem exigir submissão de formulário: prefira `br-switch`.\n  - Houver muitas opções (mais de 7) em espaço reduzido: prefira `br-select` múltiplo.\n\n### Estrutura e Slots\n\nO `br-checkbox` é um controle autônomo com slots de suporte:\n- `default`: Slot para o texto do rótulo associado ao checkbox (alternativa à propriedade `label`).\n- `feedback`: Slot para exibição de mensagens de validação e alertas contextuais (como `br-message`).\n\nPara 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/checkbox?tab=designer).\n---\n\n\n### **Events:**\n - **checkedChange** - Disparado depois que o valor do `checked` foi alterado.\n- **indeterminateChange** - Disparado depois que o valor do `indeterminate` foi alterado.\n- **brCheckboxValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do checkbox for válido, caso contrário `false`.\nSe o checkbox for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do checkbox for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o checkbox.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do checkbox e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **setIndeterminate(value: _boolean_)** - Define o estado indeterminado do checkbox.\n- **toggleChecked()** - @deprecated Atualize a propriedade `checked` diretamente. - Inverte o valor da prop `checked`\n- **setNumberOfChildren(value: _number_)** - Define o número de checkboxes filhos em um grupo de checkboxes.\n\n### **Slots:**\n - **default** - Slot para o rótulo do checkbox, como alternativa à propriedade label.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do checkbox.\n- **input** - Elemento input nativo do checkbox.\n- **label** - Rótulo do checkbox.\n- **feedback** - Contêiner da mensagem de validação.",
       "attributes": [
         {
           "name": "indeterminate",
@@ -431,7 +436,7 @@
         },
         {
           "name": "validator",
-          "description": "Regra síncrona ou assíncrona aplicada ao estado booleano do checkbox.",
+          "description": "Regra síncrona ou assíncrona aplicada ao estado booleano do checkbox.\nRetorne uma mensagem para invalidar ou `null` para aceitar o valor.",
           "values": [{ "name": "CheckboxValidator" }]
         },
         {
@@ -479,8 +484,13 @@
     },
     {
       "name": "br-checkbox-group",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/checkgroup?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para adicionar os checkboxes controlados pelo grupo.",
+      "description": "O componente `br-checkbox-group` é o contêiner semântico e orquestrador de múltiplos controles `br-checkbox` que pertencem a um mesmo contexto ou pergunta em formulários do GovBR-DS.\n\n### Para que serve\n\n- **Agrupamento semântico e acessibilidade:** Cria a estrutura recomendada de `fieldset` e `legend` para leitores de tela, garantindo que o contexto da pergunta seja anunciado antes de cada opção individual.\n- **Validação conjunta:** Permite coordenar regras de validação em grupo (como exigir uma quantidade mínima ou máxima de checkboxes selecionados).\n- **Alinhamento e padronização visual:** Organiza os checkboxes vertical ou horizontalmente conforme o leiaute da interface.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Existirem duas ou mais opções em checkbox que respondem à mesma pergunta ou pertencem ao mesmo conjunto lógico de preferências.\n  - For necessário aplicar rótulo geral e mensagens de validação ao grupo completo de escolhas.\n- **Evite e prefira outro componente quando:**\n  - Houver apenas um único checkbox independente (ex.: aceite de termos): use `br-checkbox` isoladamente.\n  - A seleção for de escolha única (mutuamente exclusiva): use `br-radio-group`.\n\n### Estrutura e Slots\n\nO `br-checkbox-group` atua como container orquestrador:\n- `default`: Slot onde devem ser inseridos os elementos `br-checkbox` que compõem o grupo.\n- `feedback`: Slot opcional para mensagem de erro ou orientação de validação associada ao grupo todo.\n\nPara 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/checkgroup?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para adicionar os checkboxes controlados pelo grupo.",
       "attributes": [
+        {
+          "name": "disabled",
+          "description": "Desabilita o controlador e os checkboxes contidos no grupo.",
+          "values": []
+        },
         {
           "name": "label",
           "description": "Texto descritivo do grupo.",
@@ -503,7 +513,7 @@
         },
         {
           "name": "orientation",
-          "description": "Orientação visual das opções.",
+          "description": "Orientação visual das opções. Valores inválidos usam `vertical`.",
           "values": [{ "name": "horizontal" }, { "name": "vertical" }]
         },
         {
@@ -516,7 +526,7 @@
     },
     {
       "name": "br-checkgroup",
-      "description": "@deprecated Use `br-checkbox-group`.\n\n\n---\n\n\n### **Slots:**\n - **default** - Slot para adicionar os checkboxes controlados pelo grupo.",
+      "description": "@deprecated Use `br-checkbox-group`.\n\nO componente `br-checkgroup` é o alias legado mantido para compatibilidade com versões anteriores da biblioteca.\n\n### Papel na biblioteca\n\n- Atua como um redirecionador direto para a implementação do `br-checkbox-group`.\n- Permite que aplicações já existentes mantenham o funcionamento sem interrupções enquanto realizam a transição gradativa.\n\n### Regra de uso e migração\n\nEm novos projetos e manutenções ativas, **utilize sempre a tag canônica `br-checkbox-group`**. O uso de `br-checkgroup` está depreciado e deve ser substituído pela tag oficial.\n\nPara a documentação canônica completa, consulte a página do [br-checkbox-group](/docs/components/checkbox-group).\n---\n\n\n### **Slots:**\n - **default** - Slot para adicionar os checkboxes controlados pelo grupo.",
       "attributes": [
         {
           "name": "label",
@@ -552,13 +562,18 @@
           "name": "custom-id",
           "description": "Identificador legado do controlador.",
           "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Desabilita o controlador e os checkboxes contidos no grupo.",
+          "values": []
         }
       ],
       "references": []
     },
     {
       "name": "br-collapse",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/collapse?tab=designer).\n---\n\n\n### **Events:**\n - **brDidOpen** - Emitido ao expandir, com o identificador e o grupo de accordion.\n- **brCollapseOpen** - Evento canônico emitido ao expandir.\n- **brDidClose** - Emitido ao recolher, com o identificador e o grupo de accordion.\n- **brCollapseClose** - Evento canônico emitido ao recolher.\n\n### **Methods:**\n - **openCollapse()** - @deprecated Atualize a propriedade `open`. - Abre o collapse programaticamente.\n- **closeCollapse()** - @deprecated Atualize a propriedade `open`. - Fecha o collapse programaticamente.\n- **toggle(): _Promise<void>_** - Alterna o estado aberto.\nO elemento também redispara o evento nativo `toggle` no host; essa ocorrência é sintética (`isTrusted === false`).\n- **render()** - Renderiza o <details> com acionador e conteúdo expansível.\n\n### **Slots:**\n - **default** - Slot para o conteúdo expansível exibido ao abrir o collapse.\n- **trigger** - Slot para personalizar o acionador (texto, ícones, imagens, etc.).\n\n### **CSS Parts:**\n - **details** - Elemento details nativo do collapse.\n- **trigger** - Acionador (summary) do collapse.\n- **content** - Área de conteúdo expansível.",
+      "description": "O componente `br-collapse` é o controle retrátil do GovBR-DS baseado no elemento semântico HTML5 `<details>`, desenvolvido para permitir que a pessoa usuária expanda ou recolha seções de conteúdo sob demanda.\n\n### Para que serve\n\n- **Otimização de espaço e hierarquia:** Reduz a sobrecarga de informação inicial na tela, ocultando blocos secundários até que o usuário decida visualizá-los.\n- **Estruturação de perguntas e respostas:** Padrão oficial para construção de seções de FAQ (perguntas frequentes) e listas explicativas sanfonadas (accordion).\n- **Acessibilidade nativa:** Por utilizar internamente os elementos `<details>` e `<summary>`, possui controle total de teclado, estado acessível (`open`) e anúncios para tecnologias assistivas sem exigir scripts adicionais complexos.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O conteúdo for extenso, dividido em tópicos independentes e a maioria dos usuários só precisa consultar itens específicos.\n  - Houver seções complementares opcionais em um formulário longo.\n- **Evite e prefira outro componente quando:**\n  - A informação contida for crítica para a tomada de decisão imediata ou segurança da pessoa usuária (ela deve ficar permanentemente visível).\n  - A intenção for alternar entre diferentes visões de uma mesma tela completa (prefira `br-tab`).\n\n### Estrutura e Slots\n\nO `br-collapse` organiza o acionamento e a área expansível:\n- `trigger`: Slot para personalizar o botão/gatilho de expansão (texto, ícones ou componentes de apoio dentro do summary).\n- `default`: Slot para inserção do conteúdo que é revelado quando o componente é expandido.\n\nPara 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/collapse?tab=designer).\n---\n\n\n### **Events:**\n - **brDidOpen** - Emitido ao expandir, com o identificador e o grupo de accordion.\n- **brCollapseOpen** - Evento canônico emitido ao expandir.\n- **brDidClose** - Emitido ao recolher, com o identificador e o grupo de accordion.\n- **brCollapseClose** - Evento canônico emitido ao recolher.\n\n### **Methods:**\n - **openCollapse()** - @deprecated Atualize a propriedade `open`. - Abre o collapse programaticamente.\n- **closeCollapse()** - @deprecated Atualize a propriedade `open`. - Fecha o collapse programaticamente.\n- **toggle(): _Promise<void>_** - Alterna o estado aberto.\nO elemento também redispara o evento nativo `toggle` no host; essa ocorrência é sintética (`isTrusted === false`).\n- **render()** - Renderiza o <details> com acionador e conteúdo expansível.\n\n### **Slots:**\n - **default** - Slot para o conteúdo expansível exibido ao abrir o collapse.\n- **trigger** - Slot para personalizar o acionador (texto, ícones, imagens, etc.).\n\n### **CSS Parts:**\n - **details** - Elemento details nativo do collapse.\n- **trigger** - Acionador (summary) do collapse.\n- **content** - Área de conteúdo expansível.",
       "attributes": [
         {
           "name": "custom-id",
@@ -582,12 +597,12 @@
         },
         {
           "name": "icon-to-show",
-          "description": "Classe CSS do ícone exibido quando o conteúdo está oculto.",
+          "description": "Identificador do ícone exibido quando o conteúdo está oculto. O valor padrão usa o registro SVG local.",
           "values": []
         },
         {
           "name": "icon-to-hide",
-          "description": "Classe CSS do ícone exibido quando o conteúdo está visível.",
+          "description": "Identificador do ícone exibido quando o conteúdo está visível. O valor padrão usa o registro SVG local.",
           "values": []
         },
         {
@@ -620,7 +635,7 @@
     },
     {
       "name": "br-cookiebar",
-      "description": "Componente de gestão de consentimento de cookies (LGPD), obrigatório em sites e aplicativos do\nGoverno Federal que coletam dados de usuários.\n\nApresenta duas etapas visuais:\n- **default** – barra inferior com texto informativo e botões de ação;\n- **open** – painel de tela cheia com lista de classes de cookies configuráveis.\n\nA persistência do consentimento é responsabilidade do consumidor: ouça o evento\n`brCookiebarAccept` e armazene o payload onde desejar (localStorage, cookie HTTP, API etc.).\n\nPara a documentação completa, consulte o [Design System do GovBR](https://www.gov.br/ds/components/cookiebar?tab=designer).\n---\n\n\n### **Events:**\n - **brCookiebarShow** - Emitido quando o componente se torna visível (`show` → true).\n- **brCookiebarHide** - Emitido quando o componente é ocultado (`show` → false).\n- **brCookiebarOpen** - Emitido quando o painel expande para modo open.\n- **brCookiebarClose** - Emitido quando o painel recolhe para modo default.\n- **brCookiebarAccept** - Sinal emitido quando o usuário clica em Aceitar.\nNão carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.\n- **brCookiebarReject** - Sinal emitido quando o usuário clica em \"Rejeitar não obrigatórios\".\nNão carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.\n- **brCookiebarResponse** - Emitido após `brCookiebarAccept` ou `brCookiebarReject`, com o estado final de consentimento.\nÉ o único evento que carrega `CookiebarOutputData` — use-o para persistir o consentimento\n(localStorage, cookie HTTP, API etc.).\nNão é disparado durante interações com checkboxes e switches internos.\n- **brCookiebarPolicyClick** - Emitido quando o usuário clica no botão secundário no modo opt-in (`allOptOut=false`).\nO consumidor é responsável por navegar para a página de Política de Cookies.\n\n### **Methods:**\n - **handleShowChange(newValue: _boolean_)** - Observa mudanças em `show`.\nAo exibir o componente, garante que o modo inicial seja sempre `default` e emite `brCookiebarShow`.\nCom `scrim=true`, aplica `inert` nos irmãos e registra o trap de foco.\nCom `scrim=false`, o usuário pode navegar livremente pela página (WCAG 2.1.2).\nAo ocultar, emite `brCookiebarHide`.\n- **handleModeChange(newValue: _CookiebarMode_)** - Observa mudanças em `mode`.\nAo entrar em modo `open`, emite `brCookiebarOpen`, aplica `inert` nos irmãos e move o foco\npara o botão fechar (trap focus modal).\nAo sair do modo `open`, emite `brCookiebarClose` e — se `scrim=true` — reaplica `inert`\ne o listener de trap para o painel default. Sem scrim, nenhum trap é ativado.\n- **handleSelectAllPropChange(newValue: _boolean_)** - Observa mudanças externas na prop `selectAll`.\nSincroniza o estado interno do checkbox e propaga o valor para todos os grupos opt-out.\n- **handleGroupChange()** - Escuta o evento `brCookiebarGroupChange` emitido por qualquer `br-cookiebar-group` filho.\nApenas recalcula o estado visual do checkbox \"Selecionar tudo\" — não emite `brCookiebarResponse`.\nO evento de resposta completo é emitido somente ao clicar em Aceitar ou Rejeitar.\n- **openDefault(): _Promise<void>_** - Exibe o cookiebar no modo `default` (barra inferior).\n- **openPanel(): _Promise<void>_** - Exibe o cookiebar diretamente no modo `open` (painel de tela cheia).\n- **close(): _Promise<void>_** - Oculta o cookiebar.\n- **getSelectedCookies(): _Promise<CookiebarOutputData>_** - Retorna o JSON com o estado atual de seleção de todos os grupos e cookies.\n\n### **Slots:**\n - **default** - Recebe os subcomponentes `br-cookiebar-group`, `br-cookiebar-note-group` e `br-cookiebar-note`.\n- **header** - Recebe `br-cookiebar-header` ou HTML livre.\n- **links** - Recebe links complementares (`br-cookiebar-link` ou elementos `<a>` livres).\n- **actions** - Recebe botões de ação. Se vazio, o componente renderiza os botões padrão.\n\n### **CSS Parts:**\n - **container** - Container raiz do componente.\n- **default-panel** - Painel fechado (modo default).\n- **open-panel** - Painel expandido (modo open).\n- **header** - Cabeçalho do painel aberto.\n- **body** - Corpo do painel aberto (com rolagem).\n- **footer** - Rodapé com botões de ação.\n- **scrim** - Camada de sobreposição opcional.",
+      "description": "O componente `br-cookiebar` é o orquestrador completo do GovBR-DS para aviso e gestão de consentimento de cookies, atendendo às exigências da LGPD (Lei Geral de Proteção de Dados).\n\n### Para que serve\n\n- **Aviso de privacidade e cookies:** Informa com clareza à pessoa usuária sobre a coleta e finalidade de cookies no sistema.\n- **Gestão de consentimento:** Permite aceitar todos os cookies, rejeitar os não essenciais ou gerenciar categorias de forma granular.\n- **Detalhamento transparente:** Exibe a relação técnica de cookies utilizados por categoria com nome, validade e finalidade.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A aplicação ou portal público utilizar cookies de sessão, rastreamento ou preferências que demandem consentimento explícito.\n  - For necessário dar cumprimento às diretrizes de privacidade e proteção de dados pessoais (LGPD).\n- **Evite e prefira outro componente quando:**\n  - A notificação for apenas um alerta contextual ou mensagem simples de status sem relação com consentimento (prefira `br-message` ou `br-notification`).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-cookiebar` | **Orquestrador principal.** Gerencia abertura, fechamento, persistência e emissão dos eventos de consentimento. | Declarado como contêiner do aviso de cookies na aplicação. |\n| `br-cookiebar-header` | **Cabeçalho informativo.** Exibe título e mensagem inicial de contexto. | Inserido no slot de topo do `br-cookiebar`. |\n| `br-cookiebar-group` | **Categoria de cookies.** Agrupa cookies por finalidade com controle de seleção. | Inserido no corpo de opções do `br-cookiebar`. |\n| `br-cookiebar-cookie` | **Item de cookie.** Descreve detalhadamente um cookie específico. | Inserido dentro de um `br-cookiebar-group`. |\n| `br-cookiebar-link` | **Link informativo.** Atalho para a Política de Privacidade e termos. | Usado no cabeçalho ou notas do `br-cookiebar`. |\n| `br-cookiebar-note` | **Nota complementar.** Mensagem ou aviso jurídico adicional. | Inserido individualmente ou em `br-cookiebar-note-group`. |\n| `br-cookiebar-note-group` | **Agrupador de notas.** Organiza múltiplas notas informativas. | Posicionado na área de notas do `br-cookiebar`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-cookiebar` atua como orquestrador central. Ele controla a visualização do painel (modo compacto ou expandido), agrupa as categorias (`br-cookiebar-group`) com seus respectivos cookies (`br-cookiebar-cookie`) e disponibiliza os botões de ação para aceitar todos, rejeitar ou salvar preferências. A aplicação consome eventos unificados de consentimento disparados pelo componente pai.\n\nPara 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/cookiebar?tab=designer).\n---\n\n\n### **Events:**\n - **brCookiebarShow** - Emitido quando o componente se torna visível (`show` → true).\n- **brCookiebarHide** - Emitido quando o componente é ocultado (`show` → false).\n- **brCookiebarOpen** - Emitido quando o painel expande para modo open.\n- **brCookiebarClose** - Emitido quando o painel recolhe para modo default.\n- **brCookiebarAccept** - Sinal emitido quando o usuário clica em Aceitar.\nNão carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.\n- **brCookiebarReject** - Sinal emitido quando o usuário clica em \"Rejeitar não obrigatórios\".\nNão carrega payload — ouça `brCookiebarResponse` para obter o estado completo de consentimento.\n- **brCookiebarResponse** - Emitido após `brCookiebarAccept` ou `brCookiebarReject`, com o estado final de consentimento.\nÉ o único evento que carrega `CookiebarOutputData` — use-o para persistir o consentimento\n(localStorage, cookie HTTP, API etc.).\nNão é disparado durante interações com checkboxes e switches internos.\n- **brCookiebarPolicyClick** - Emitido quando o usuário clica no botão secundário no modo opt-in (`allOptOut=false`).\nO consumidor é responsável por navegar para a página de Política de Cookies.\n\n### **Methods:**\n - **handleShowChange(newValue: _boolean_)** - Observa mudanças em `show`.\nAo exibir o componente, garante que o modo inicial seja sempre `default` e emite `brCookiebarShow`.\nCom `scrim=true`, aplica `inert` nos irmãos e registra o trap de foco.\nCom `scrim=false`, o usuário pode navegar livremente pela página (WCAG 2.1.2).\nAo ocultar, emite `brCookiebarHide`.\n- **handleModeChange(newValue: _CookiebarMode_)** - Observa mudanças em `mode`.\nAo entrar em modo `open`, emite `brCookiebarOpen`, aplica `inert` nos irmãos e move o foco\npara o botão fechar (trap focus modal).\nAo sair do modo `open`, emite `brCookiebarClose` e — se `scrim=true` — reaplica `inert`\ne o listener de trap para o painel default. Sem scrim, nenhum trap é ativado.\n- **handleSelectAllPropChange(newValue: _boolean_)** - Observa mudanças externas na prop `selectAll`.\nSincroniza o estado interno do checkbox e propaga o valor para todos os grupos opt-out.\n- **handleGroupChange()** - Escuta o evento `brCookiebarGroupChange` emitido por qualquer `br-cookiebar-group` filho.\nApenas recalcula o estado visual do checkbox \"Selecionar tudo\" — não emite `brCookiebarResponse`.\nO evento de resposta completo é emitido somente ao clicar em Aceitar ou Rejeitar.\n- **openDefault(): _Promise<void>_** - Exibe o cookiebar no modo `default` (barra inferior).\n- **openPanel(): _Promise<void>_** - Exibe o cookiebar diretamente no modo `open` (painel de tela cheia).\n- **close(): _Promise<void>_** - Oculta o cookiebar.\n- **getSelectedCookies(): _Promise<CookiebarOutputData>_** - Retorna o JSON com o estado atual de seleção de todos os grupos e cookies.\n\n### **Slots:**\n - **default** - Recebe os subcomponentes `br-cookiebar-group`, `br-cookiebar-note-group` e `br-cookiebar-note`.\n- **header** - Recebe `br-cookiebar-header` ou HTML livre.\n- **links** - Recebe links complementares (`br-cookiebar-link` ou elementos `<a>` livres).\n- **actions** - Recebe botões de ação. Se vazio, o componente renderiza os botões padrão.\n\n### **CSS Parts:**\n - **container** - Container raiz do componente.\n- **default-panel** - Painel fechado (modo default).\n- **open-panel** - Painel expandido (modo open).\n- **header** - Cabeçalho do painel aberto.\n- **body** - Corpo do painel aberto (com rolagem).\n- **footer** - Rodapé com botões de ação.\n- **scrim** - Camada de sobreposição opcional.",
       "attributes": [
         {
           "name": "custom-id",
@@ -634,7 +649,7 @@
         },
         {
           "name": "mode",
-          "description": "Estado visual atual do painel.\n- `default`: barra inferior com texto e botões.\n- `open`: painel de tela cheia com grupos de cookies configuráveis.",
+          "description": "Estado visual atual do painel. Valores inválidos usam `default`.\n- `default`: barra inferior com texto e botões.\n- `open`: painel de tela cheia com grupos de cookies configuráveis.",
           "values": [{ "name": "CookiebarMode" }]
         },
         {
@@ -727,7 +742,7 @@
     },
     {
       "name": "br-cookiebar-cookie",
-      "description": "Representa um cookie individual dentro de um `br-cookiebar-group`.\nExibe os detalhes do cookie (nome, vencimento, domínio etc.) e,\nquando o cookie pode ser desativado, um switch de ativação.\n---\n\n\n### **Events:**\n - **brCookiebarCookieChange** - Emitido ao ligar/desligar o switch.\nBorbulha até o `br-cookiebar-group` pai para recalcular o estado do grupo.\n\n### **Slots:**\n - **default** - Área livre para inserir conteúdo personalizado abaixo dos itens do cookie.\n\n### **CSS Parts:**\n - **card** - Container principal do cookie.\n- **switch** - Área que contém o switch de ativação.\n- **details** - Wrapper interno com o switch, alerta e lista de itens.",
+      "description": "O componente `br-cookiebar-cookie` é o subcomponente do GovBR-DS que descreve as especificações técnicas de um cookie individual.\n\n### Para que serve\n\n- **Transparência técnica:** Detalha nome, validade, finalidade e fornecedor do cookie.\n- **Esclarecimento ao cidadão:** Oferece visibilidade granular sobre cada elemento de persistência.\n\n### Papel na composição\n\nAtua como item folha descritivo na listagem de cookies.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado exclusivamente dentro de um `br-cookiebar-group`.\n- Não deve ser utilizado fora do ecossistema de gestão de cookies.\n---\n\n\n### **Events:**\n - **brCookiebarCookieChange** - Emitido ao ligar/desligar o switch.\nBorbulha até o `br-cookiebar-group` pai para recalcular o estado do grupo.\n\n### **Slots:**\n - **default** - Área livre para inserir conteúdo personalizado abaixo dos itens do cookie.\n\n### **CSS Parts:**\n - **card** - Container principal do cookie.\n- **switch** - Área que contém o switch de ativação.\n- **details** - Wrapper interno com o switch, alerta e lista de itens.",
       "attributes": [
         {
           "name": "custom-id",
@@ -839,7 +854,7 @@
     },
     {
       "name": "br-cookiebar-group",
-      "description": "Representa um grupo (classe) de cookies dentro do `br-cookiebar`.\nAgrupa cookies relacionados, exibe um checkbox para seleção coletiva\ne permite expandir a lista de `br-cookiebar-cookie` filhos.\n\nSuporta dois modos:\n- **Opt-out** (`group-opt-out=\"true\"`, padrão): o usuário pode desativar o grupo.\n- **Sempre ativo** (`group-opt-out=\"false\"`): exibe badge fixo, sem checkbox.\n---\n\n\n### **Events:**\n - **brCookiebarGroupChange** - Emitido quando o estado de seleção do grupo muda (por interação do usuário ou propagação).\nO `br-cookiebar` pai escuta este evento para recalcular o checkbox \"Selecionar todos\".\n- **brCookiebarGroupToggle** - Emitido ao expandir ou recolher a lista de cookies do grupo.\n\n### **Methods:**\n - **handleGroupSelectedChange(newValue: _boolean_)** - Observa mudanças externas em `groupSelected` (propagação top-down do `br-cookiebar`).\nPropaga o novo valor para todos os cookies opt-out filhos e atualiza os contadores.\nIgnorado quando a mudança é originada internamente pelo recálculo bottom-up.\n- **handleCookieChange()** - Escuta o evento `brCookiebarCookieChange` emitido por qualquer `br-cookiebar-cookie` filho.\nRecalcula o estado do grupo (marcado / desmarcado / indeterminado) com base\nno estado atual de todos os cookies opt-out. Ignorado durante propagações top-down.\n- **getState(): _Promise<CookiebarSelectionState>_** - Retorna o estado atual de seleção do grupo:\n- `true`: todos os cookies opt-out estão selecionados.\n- `false`: nenhum cookie opt-out está selecionado.\n- `'indeterminate'`: seleção parcial.\n\n### **Slots:**\n - **default** - Recebe os subcomponentes `br-cookiebar-cookie` do grupo.\n\n### **CSS Parts:**\n - **container** - Div raiz do grupo.\n- **header** - Linha de cabeçalho com nome, contadores e controles.\n- **body** - Área expansível que contém os cookies.",
+      "description": "O componente `br-cookiebar-group` é o subcomponente do GovBR-DS que representa uma categoria de cookies (ex.: necessários, desempenho, marketing) acompanhada de um controle de seleção (switch ou checkbox).\n\n### Para que serve\n\n- **Segmentação por finalidade:** Organiza os cookies conforme o tipo e necessidade técnica.\n- **Controle de consentimento:** Permite habilitar ou desabilitar categorias não obrigatórias.\n\n### Papel na composição\n\nAtua como contêiner de agrupamento intermediário dentro do `br-cookiebar`, contendo instâncias de `br-cookiebar-cookie`.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado dentro do corpo de configuração do `br-cookiebar`.\n- Recebe elementos filhos do tipo `br-cookiebar-cookie`.\n---\n\n\n### **Events:**\n - **brCookiebarGroupChange** - Emitido quando o estado de seleção do grupo muda (por interação do usuário ou propagação).\nO `br-cookiebar` pai escuta este evento para recalcular o checkbox \"Selecionar todos\".\n- **brCookiebarGroupToggle** - Emitido ao expandir ou recolher a lista de cookies do grupo.\n\n### **Methods:**\n - **handleGroupSelectedChange(newValue: _boolean_)** - Observa mudanças externas em `groupSelected` (propagação top-down do `br-cookiebar`).\nPropaga o novo valor para todos os cookies opt-out filhos e atualiza os contadores.\nIgnorado quando a mudança é originada internamente pelo recálculo bottom-up.\n- **handleCookieChange()** - Escuta o evento `brCookiebarCookieChange` emitido por qualquer `br-cookiebar-cookie` filho.\nRecalcula o estado do grupo (marcado / desmarcado / indeterminado) com base\nno estado atual de todos os cookies opt-out. Ignorado durante propagações top-down.\n- **getState(): _Promise<CookiebarSelectionState>_** - Retorna o estado atual de seleção do grupo:\n- `true`: todos os cookies opt-out estão selecionados.\n- `false`: nenhum cookie opt-out está selecionado.\n- `'indeterminate'`: seleção parcial.\n\n### **Slots:**\n - **default** - Recebe os subcomponentes `br-cookiebar-cookie` do grupo.\n\n### **CSS Parts:**\n - **container** - Div raiz do grupo.\n- **header** - Linha de cabeçalho com nome, contadores e controles.\n- **body** - Área expansível que contém os cookies.",
       "attributes": [
         {
           "name": "custom-id",
@@ -901,7 +916,7 @@
     },
     {
       "name": "br-cookiebar-header",
-      "description": "Cabeçalho introdutório do painel aberto do `br-cookiebar`.\nExibe o título da política de cookies, a data da última atualização e um texto de introdução.\n\nPode ser usado de duas formas:\n- **Estruturada** (padrão): informe `main-title`, `entry-text` e opcionalmente `last-update`\n  para renderizar o cabeçalho com o layout oficial do Design System.\n- **Livre**: insira conteúdo HTML no slot default e ele substituirá completamente o layout\n  interno, mantendo apenas o container estilizado.\n\nDeve ser inserido no slot `header` do `br-cookiebar`.\n---\n\n\n### **Slots:**\n - **default** - Conteúdo HTML personalizado que substitui o layout estruturado. Quando preenchido, as props `main-title`, `entry-text` e `last-update` são ignoradas.\n\n### **CSS Parts:**\n - **container** - Div raiz do cabeçalho.",
+      "description": "O componente `br-cookiebar-header` é o subcomponente de topo do GovBR-DS que apresenta o título e o texto introdutório do aviso de cookies.\n\n### Para que serve\n\n- **Apresentação do contexto:** Explica resumidamente a finalidade do aviso de privacidade.\n- **Identificação visual:** Fornece o cabeçalho padronizado da barra de cookies.\n\n### Papel na composição\n\nAtua como elemento introdutório estrutural do `br-cookiebar`.\n\n### Regra de uso e relacionamento\n\n- Deve ser posicionado no slot de cabeçalho do `br-cookiebar`.\n- Não deve ser utilizado de forma independente fora do aviso de cookies.\n---\n\n\n### **Slots:**\n - **default** - Conteúdo HTML personalizado que substitui o layout estruturado. Quando preenchido, as props `main-title`, `entry-text` e `last-update` são ignoradas.\n\n### **CSS Parts:**\n - **container** - Div raiz do cabeçalho.",
       "attributes": [
         {
           "name": "custom-id",
@@ -933,7 +948,7 @@
     },
     {
       "name": "br-cookiebar-link",
-      "description": "Link complementar exibido na área de rodapé do `br-cookiebar`.\nUse dentro do slot `links` do `br-cookiebar` para adicionar links externos estruturados,\ncomo \"Política de Privacidade\" ou \"Termos de Uso\".\n\nQuando `target=\"_blank\"`, exibe automaticamente um ícone de link externo\ne adiciona `rel=\"noopener noreferrer\"` por segurança.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **CSS Parts:**\n - **link** - Elemento âncora (`<a>`) do link.",
+      "description": "O componente `br-cookiebar-link` é o subcomponente de hiperlink do GovBR-DS destinado a apontar para Políticas de Privacidade, Termos de Uso e orientações legais.\n\n### Para que serve\n\n- **Acesso a termos legais:** Encaminha a pessoa usuária para a documentação completa de proteção de dados.\n- **Estilo consistente:** Garante conformidade visual e acessibilidade no contexto do aviso de cookies.\n\n### Papel na composição\n\nAtua como item de navegação auxiliar no aviso de cookies.\n\n### Regra de uso e relacionamento\n\n- Pode ser utilizado dentro do cabeçalho, notas ou corpo do componente `br-cookiebar`.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **CSS Parts:**\n - **link** - Elemento âncora (`<a>`) do link.",
       "attributes": [
         {
           "name": "custom-id",
@@ -965,7 +980,7 @@
     },
     {
       "name": "br-cookiebar-note",
-      "description": "Subcomponente de `br-cookiebar-note-group` que representa um par pergunta/resposta\ndentro da seção de avisos de cookies.\n\nDeve ser inserido dentro de um `br-cookiebar-note-group`.\n---\n\n\n### **CSS Parts:**\n - **container** - Div raiz do item.\n- **question** - Parágrafo da pergunta.\n- **answer** - Parágrafo da resposta.",
+      "description": "O componente `br-cookiebar-note` é o subcomponente textual do GovBR-DS que exibe notas explicativas, orientações complementares ou avisos jurídicos adicionais.\n\n### Para que serve\n\n- **Notas de rodapé do aviso:** Apresenta esclarecimentos sobre retenção de dados, atualizações de termos ou exceções regulatórias.\n\n### Papel na composição\n\nAtua como bloco textual informativo complementar.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado diretamente no `br-cookiebar` ou dentro de um `br-cookiebar-note-group`.\n---\n\n\n### **CSS Parts:**\n - **container** - Div raiz do item.\n- **question** - Parágrafo da pergunta.\n- **answer** - Parágrafo da resposta.",
       "attributes": [
         {
           "name": "custom-id",
@@ -983,7 +998,7 @@
     },
     {
       "name": "br-cookiebar-note-group",
-      "description": "Seção retrátil de avisos e notas sobre cookies, exibida na área complementar do `br-cookiebar`.\nAgrupa um ou mais `br-cookiebar-note` sob um título clicável que expande ou recolhe o conteúdo.\n\nSe o slot estiver vazio, o componente não renderiza nada.\n---\n\n\n### **Events:**\n - **brCookiebarNoteGroupToggle** - Emitido ao expandir ou recolher a seção.\n\n### **Slots:**\n - **default** - Recebe `br-cookiebar-note` ou qualquer conteúdo HTML livre.\n\n### **CSS Parts:**\n - **container** - Div raiz do grupo.\n- **header** - Cabeçalho acessível que expande ou recolhe o conteúdo.\n- **content** - Área de conteúdo exibida quando o grupo está expandido.",
+      "description": "O componente `br-cookiebar-note-group` é o subcomponente contêiner do GovBR-DS que agrupa uma ou mais notas informativas `br-cookiebar-note`.\n\n### Para que serve\n\n- **Estruturação de notas:** Agrupa avisos jurídicos e observações complementares em uma seção visualmente delimitada.\n\n### Papel na composição\n\nAtua como contêiner estrutural para instâncias de `br-cookiebar-note`.\n\n### Regra de uso e relacionamento\n\n- Deve ser inserido na seção de notas informativas do `br-cookiebar`.\n---\n\n\n### **Events:**\n - **brCookiebarNoteGroupToggle** - Emitido ao expandir ou recolher a seção.\n\n### **Slots:**\n - **default** - Recebe `br-cookiebar-note` ou qualquer conteúdo HTML livre.\n\n### **CSS Parts:**\n - **container** - Div raiz do grupo.\n- **header** - Cabeçalho acessível que expande ou recolhe o conteúdo.\n- **content** - Área de conteúdo exibida quando o grupo está expandido.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1005,7 +1020,7 @@
     },
     {
       "name": "br-datetime-picker",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetimepicker?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Evento público emitido quando a data de referência ou a seleção mudam.\n- **valueChange** - Evento emitido quando o valor selecionado muda.\n- **brDatetimePickerValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **formResetCallback()** - API nativa de reset de form-associated custom elements.\n- **formStateRestoreCallback(state: _string | File | FormData | null_)** - API nativa de restauração de estado (histórico/autofill) do formulário.\n- **handleModeChange(newValue: _string_)** - Revalida o modo sempre que a prop mudar.\n- **handleRequiredChange()** - Revalida o estado do formulário quando required mudar.\n- **handleDisabledChange()** - Exclui o valor do FormData enquanto o componente estiver desabilitado.\n- **handleSelectionModeChange(newValue: _DatetimePickerSelectionMode_)** - Reage a mudanças no modo de seleção e limpa intervalo quando necessário.\n- **handleWeekStartsOnChange(newValue: _DatetimePickerWeekDayIndex_)** - Revalida o dia inicial da semana sempre que a prop mudar.\n- **handleInitialMomentChange(newValue: _DatetimePickerInitialMoment_)** - Aplica ou limpa a seleção da data atual conforme o novo valor da prop.\n- **handleValueChange(newValue: _Date | null_)** - Sincroniza alterações externas do valor com o estado visual e o formulário nativo.\n- **handleSerializedValueChange(newValue: _string_)** - Converte alterações externas no valor serializado sem mudar o tipo da prop legada `value`.\n- **handleValueAsDateChange(newValue: _Date | null_)** - Mantém `valueAsDate` e a prop legada `value` apontando para o mesmo estado observável.\n- **handleDisabledDatesChange(newValue: _DatetimePickerDisabledDates_)** - Recalcula a lista de datas desabilitadas quando a prop mudar.\n- **setDisabledDates(dates: _DatetimePickerDisabledDate[] | null_): _Promise<void>_** - Define programaticamente as datas desabilitadas por meio de array.\n\nÚtil quando o componente é usado via HTML e o consumidor precisa enviar\numa lista tipada em runtime.\n- **setValue(value: _Date | string | null_): _Promise<void>_** - Define o valor atual de forma imperativa aceitando Date, string serializada ou null.\n- **getValue(): _Promise<Date | null>_** - Retorna uma cópia do valor selecionado atualmente.\n- **clear(): _Promise<void>_** - Limpa valor e intervalo selecionados.\n- **open(): _Promise<void>_** - Abre o picker quando o componente estiver habilitado.\n- **close(): _Promise<void>_** - Fecha o picker.\n- **toggle(): _Promise<void>_** - Alterna o estado de abertura do picker.\n- **focusInput(): _Promise<void>_** - Move o foco para o input nativo interno.\n- **setRange(start: _Date | string | null_, end: _Date | string | null_): _Promise<void>_** - Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range.\n- **getRange(): __** - Retorna o intervalo de datas selecionado quando em modo `selectionMode=\"range\"`.\n- **isOpen(): __** - Consulta se o picker está atualmente aberto.\n- **resetToInitial(): _Promise<void>_** - Restaura o estado inicial atualmente registrado para reset.\n- **checkValidity(): _Promise<boolean>_** - Permite que consumidores acionem validação nativa do formulário via host.\n- **reportValidity(): _Promise<boolean>_** - Permite exibir mensagens nativas de validação no host.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define ou limpa uma mensagem de validade customizada.\n- **validate(): _Promise<boolean>_** - Executa o validator do picker e retorna se a seleção atual é válida.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **render()** - Renderização principal do componente.\n\n### **Slots:**\n - **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do seletor.\n- **panel** - Parte para o painel em forma de card que engloba o seletor.\n- **input-container** - Container base do campo de entrada interno.\n- **input-field** - Campo textual interno.\n- **input-icon** - Ícone de ação (calendário/relógio).\n- **feedback** - Contêiner da mensagem de validação.",
+      "description": "O componente `br-datetime-picker` é o orquestrador completo do GovBR-DS para seleção e digitação de datas, horários ou intervalos combinados. Ele integra-se nativamente a formulários HTML via `formAssociated` e oferece suporte WAI-ARIA para diálogos e calendários.\n\n### Para que serve\n\n- **Seleção completa de data e horário:** Reúne em um único controle o campo de entrada com máscara formatada (`br-datetime-input`), o calendário de seleção de datas (`br-date-picker`) e o seletor de horários (`br-time-picker`).\n- **Múltiplos modos operacionais:** Suporta data simples, intervalo de datas (`range`), apenas hora (`time`), data e hora combinadas (`datetime`) e datas múltiplas.\n- **Validação e formulários nativos:** Valida datas mínimas (`min`), máximas (`max`), formatos permitidos e comunica valores estruturados diretamente ao formulário pai.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O formulário exigir preenchimento de datas ou horários onde tanto a digitação manual rápida quanto a exploração visual no calendário agreguem valor à experiência.\n  - For necessário selecionar um período com data de início e fim.\n- **Evite e prefira outro componente quando:**\n  - A data for estritamente de nascimento ou emissão de documento onde a pessoa usuária sabe os dígitos de cor e prefere digitar apenas números (prefira `br-input` com máscara numérica).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-datetime-picker` | **Orquestrador principal.** Gerencia valor consolidado, validação, abertura do popup e sincronização entre input e calendário. | Deve ser o único controle declarado no template da aplicação na quase totalidade dos casos. |\n| `br-datetime-input` | **Campo com máscara.** Exibe o valor formatado e permite digitação manual. | Coordenado automaticamente pelo pai; use avulso apenas em composições customizadas. |\n| `br-date-picker` | **Calendário de datas.** Painel visual com grade de dias, meses e anos. | Coordenado pelo pai; use avulso se precisar de calendário estático embutido. |\n| `br-time-picker` | **Seletor de horário.** Controle de escolha de horas e minutos. | Coordenado pelo pai; use avulso se precisar apenas de seletor de hora sem data. |\n\n### Como os subcomponentes se relacionam\n\nO `br-datetime-picker` funciona como o modelo pronto: ele instancia e sincroniza internamente o campo textual (`br-datetime-input`) e os seletores visuais suspensos (`br-date-picker` e/ou `br-time-picker`). A aplicação consome os eventos unificados emitidos diretamente pelo orquestrador pai (`change`, `input`).\n\nPara 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/datetime-picker?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Evento público emitido quando a data de referência ou a seleção mudam.\n- **valueChange** - Evento emitido quando o valor selecionado muda.\n- **brDatetimePickerValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **formResetCallback()** - API nativa de reset de form-associated custom elements.\n- **formStateRestoreCallback(state: _string | File | FormData | null_)** - API nativa de restauração de estado (histórico/autofill) do formulário.\n- **handleModeChange(newValue: _string_)** - Revalida o modo sempre que a prop mudar.\n- **handleRequiredChange()** - Revalida o estado do formulário quando required mudar.\n- **handleDisabledChange()** - Exclui o valor do FormData enquanto o componente estiver desabilitado.\n- **handleSelectionModeChange(newValue: _DatetimePickerSelectionMode_)** - Reage a mudanças no modo de seleção e limpa intervalo quando necessário.\n- **handleWeekStartsOnChange(newValue: _DatetimePickerWeekDayIndex_)** - Revalida o dia inicial da semana sempre que a prop mudar.\n- **handleInitialMomentChange(newValue: _DatetimePickerInitialMoment_)** - Aplica ou limpa a seleção da data atual conforme o novo valor da prop.\n- **handleValueChange(newValue: _Date | null_)** - Sincroniza alterações externas do valor com o estado visual e o formulário nativo.\n- **handleSerializedValueChange(newValue: _string_)** - Converte alterações externas no valor serializado sem mudar o tipo da prop legada `value`.\n- **handleValueAsDateChange(newValue: _Date | null_)** - Mantém `valueAsDate` e a prop legada `value` apontando para o mesmo estado observável.\n- **handleDisabledDatesChange(newValue: _DatetimePickerDisabledDates_)** - Recalcula a lista de datas desabilitadas quando a prop mudar.\n- **setDisabledDates(dates: _DatetimePickerDisabledDate[] | null_): _Promise<void>_** - Define programaticamente as datas desabilitadas por meio de array.\n\nÚtil quando o componente é usado via HTML e o consumidor precisa enviar\numa lista tipada em runtime.\n- **setValue(value: _Date | string | null_): _Promise<void>_** - Define o valor atual de forma imperativa aceitando Date, string serializada ou null.\n- **getValue(): _Promise<Date | null>_** - Retorna uma cópia do valor selecionado atualmente.\n- **clear(): _Promise<void>_** - Limpa valor e intervalo selecionados.\n- **open(): _Promise<void>_** - Abre o picker quando o componente estiver habilitado.\n- **close(): _Promise<void>_** - Fecha o picker.\n- **toggle(): _Promise<void>_** - Alterna o estado de abertura do picker.\n- **focusInput(): _Promise<void>_** - Move o foco para o input nativo interno.\n- **setRange(start: _Date | string | null_, end: _Date | string | null_): _Promise<void>_** - Define intervalo de datas de forma imperativa, forçando modo date e selectionMode range.\n- **getRange(): __** - Retorna o intervalo de datas selecionado quando em modo `selectionMode=\"range\"`.\n- **isOpen(): __** - Consulta se o picker está atualmente aberto.\n- **resetToInitial(): _Promise<void>_** - Restaura o estado inicial atualmente registrado para reset.\n- **checkValidity(): _Promise<boolean>_** - Permite que consumidores acionem validação nativa do formulário via host.\n- **reportValidity(): _Promise<boolean>_** - Permite exibir mensagens nativas de validação no host.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define ou limpa uma mensagem de validade customizada.\n- **validate(): _Promise<boolean>_** - Executa o validator do picker e retorna se a seleção atual é válida.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **render()** - Renderização principal do componente.\n\n### **Slots:**\n - **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do seletor.\n- **panel** - Parte para o painel em forma de card que engloba o seletor.\n- **input-container** - Container base do campo de entrada interno.\n- **input-field** - Campo textual interno.\n- **input-icon** - Ícone de ação (calendário/relógio).\n- **feedback** - Contêiner da mensagem de validação.",
       "attributes": [
         {
           "name": "mode",
@@ -1034,22 +1049,22 @@
         },
         {
           "name": "min",
-          "description": "Menor data/horário aceito, interpretado conforme `mode`.",
+          "description": "Menor data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados.\nAceita texto no atributo HTML ou uma instância de `Date` por property binding.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "max",
-          "description": "Maior data/horário aceito, interpretado conforme `mode`.",
+          "description": "Maior data/horário aceito, interpretado conforme `mode`. Valores inválidos são ignorados.\nAceita texto no atributo HTML ou uma instância de `Date` por property binding.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "validator",
-          "description": "Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado.",
+          "description": "Regra síncrona ou assíncrona aplicada à data ou intervalo selecionado.\nRetorne uma mensagem para invalidar ou `null` para aceitar o valor.",
           "values": [{ "name": "DatetimePickerValidator" }]
         },
         {
           "name": "selection-mode",
-          "description": "Define o tipo de seleção de datas para o calendário: única ou intervalo.\n\n`range` só funciona em conjunto com `mode=\"date\"`.\nSe `selectionMode=\"range\"` for informado, o componente ajusta automaticamente\n`mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente\nnormaliza `selectionMode` para `single` quando necessário.",
+          "description": "Define o tipo de seleção de datas para o calendário: única ou intervalo.\n\n`range` só funciona em conjunto com `mode=\"date\"`.\nSe `selectionMode=\"range\"` for informado, o componente ajusta automaticamente\n`mode` para `date`. Se `mode` mudar para `time` ou `datetime`, o componente\nnormaliza `selectionMode` para `single` quando necessário.\nValores inválidos usam `single`.",
           "values": [{ "name": "DatetimePickerSelectionMode" }]
         },
         {
@@ -1064,22 +1079,22 @@
         },
         {
           "name": "value",
-          "description": "Valor selecionado pelo usuário. Pode ser controlado externamente e é atualizado\npelo evento `valueChange`.",
+          "description": "Instância de `Date` selecionada pelo usuário no modo simples.\nPode ser controlada por property binding e é atualizada pelo evento `valueChange`.\nPara formulários e atributos textuais, use `serializedValue`.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "serialized-value",
-          "description": "Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`\nou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.\n\nQuando informada, tem precedência sobre o valor legado `value` durante a inicialização.",
+          "description": "Representação serializada compatível com os formatos de controles HTML (`YYYY-MM-DD`, `HH:mm`\nou ISO local, conforme `mode`). Em intervalos, usa `início/fim`.\n\nNa inicialização, tem precedência sobre `valueAsDate`, `value` e `initialMoment`.\nUma string vazia inicia sem seleção, mesmo quando outra prop fornece uma data.",
           "values": []
         },
         {
           "name": "value-as-date",
-          "description": "Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML.",
+          "description": "Espelho tipado da seleção atual, equivalente ao padrão `valueAsDate` dos controles HTML.\nDiferentemente de `serializedValue`, recebe e retorna uma instância de `Date`.\nNa inicialização, tem precedência sobre `value` e `initialMoment` quando `serializedValue`\nnão é informado. `null` inicia sem seleção; `undefined` permite usar as outras props.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "range-value",
-          "description": "Intervalo controlado quando `selectionMode=\"range\"`.",
+          "description": "Intervalo controlado quando `selectionMode=\"range\"`.\nDeve conter datas válidas ou `null` em `start` e `end`; valores inválidos mantêm o último intervalo efetivo.\nPasse o objeto por property binding; atributos HTML não representam objetos com `Date`.",
           "values": [{ "name": "DatetimePickerDateRange" }]
         },
         {
@@ -1102,7 +1117,7 @@
     },
     {
       "name": "br-date-picker",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/date-picker?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Evento emitido quando a data de referência ou a seleção mudam.\n\n### **Methods:**\n - **handleValueChange(newValue: _Date | null_)** - Sincroniza `focusedDate` quando o valor selecionado muda externamente.\n- **handleWeekStartsOnChange(newValue: _number_)** - Revalida a configuração quando o início da semana muda.\n- **handleLocaleChange(newValue: _string_)** - Revalida o locale quando a prop muda.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do calendário.\n- **header** - Cabeçalho do calendário (contendo navegação e seleção de mês/ano).\n- **month-select** - Elemento de seleção do mês.\n- **year-input** - Elemento de entrada do ano.\n- **calendar** - Grade geral do calendário.\n- **weekdays** - Container para os rótulos dos dias da semana.\n- **weekday** - Rótulo individual do dia da semana.\n- **grid** - Grade de dias do mês.\n- **day** - Célula individual do dia no calendário.",
+      "description": "Subcomponente de calendário visual do GovBR-DS, projetado para seleção interativa de datas individuais ou intervalos.\n\n### Papel na composição\n\n- Exibe a grade mensal navegável com suporte a seleção de dia, navegação entre meses e anos, e destaque para a data atual e intervalos.\n- Implementa navegação acessível por teclado WAI-ARIA Grid (setas direcionais para dias e semanas).\n\n### Regra de uso e relacionamento\n\nGeralmente exibido dentro da superfície suspensa coordenada pelo `br-datetime-picker`. Pode ser declarado isoladamente quando a interface demandar um calendário estático permanentemente embutido na página (inline calendar).\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Evento emitido quando a data de referência ou a seleção mudam.\n\n### **Methods:**\n - **handleValueChange(newValue: _Date | null_)** - Sincroniza `focusedDate` quando o valor selecionado muda externamente.\n- **handleWeekStartsOnChange(newValue: _number_)** - Revalida a configuração quando o início da semana muda.\n- **handleLocaleChange(newValue: _string_)** - Revalida o locale quando a prop muda.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do calendário.\n- **header** - Cabeçalho do calendário (contendo navegação e seleção de mês/ano).\n- **month-select** - Elemento de seleção do mês.\n- **year-input** - Elemento de entrada do ano.\n- **calendar** - Grade geral do calendário.\n- **weekdays** - Container para os rótulos dos dias da semana.\n- **weekday** - Rótulo individual do dia da semana.\n- **grid** - Grade de dias do mês.\n- **day** - Célula individual do dia no calendário.",
       "attributes": [
         {
           "name": "week-starts-on",
@@ -1111,17 +1126,17 @@
         },
         {
           "name": "reference-date",
-          "description": "Data usada como base visual para o mês atualmente exibido.",
+          "description": "Data usada como base visual para o mês atualmente exibido, sem alterar a seleção.\nRecebe uma instância de `Date` por property binding; valores inválidos usam a data atual.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "value",
-          "description": "Data atualmente selecionada pelo usuário, ou `null` quando não há seleção.",
+          "description": "Data efetivamente selecionada, ou `null` quando não há seleção; é diferente de `referenceDate`, que controla apenas o mês visível.\nRecebe uma instância de `Date` por property binding; datas inválidas usam `null`.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "selection-mode",
-          "description": "Define se a seleção ocorre por data única ou por intervalo.",
+          "description": "Define se a seleção ocorre por data única ou por intervalo. Valores inválidos usam `single`.",
           "values": [{ "name": "DatetimePickerSelectionMode" }]
         },
         {
@@ -1136,7 +1151,7 @@
         },
         {
           "name": "range-value",
-          "description": "Intervalo controlado no modo `range`.",
+          "description": "Intervalo controlado no modo `range`, reunindo `rangeStart` e `rangeEnd` em uma atualização.\nDeve conter datas válidas ou `null`; valores inválidos são ignorados. Passe o objeto por property binding.",
           "values": [{ "name": "DatetimePickerDateRange" }]
         },
         {
@@ -1146,7 +1161,7 @@
         },
         {
           "name": "disabled-dates",
-          "description": "Lista de datas indisponíveis para seleção no calendário.",
+          "description": "Lista de datas indisponíveis para seleção no calendário.\nRecebe instâncias de `Date` por property binding; datas inválidas são ignoradas.",
           "values": [{ "name": "Date[]" }]
         },
         {
@@ -1164,7 +1179,7 @@
     },
     {
       "name": "br-datetime-input",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-input?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Emite quando o valor é alterado via input ou parsing.\n- **togglePicker** - Solicita ao componente pai a alternância da abertura do picker.\n\n### **Methods:**\n - **handleValueChange(newValue: _Date | null_)** - Revalida e reflete no input mudanças externas em `value`.\n- **handleModeChange(newValue: _string_)** - Garante modo suportado e ajusta máscara/valor textual exibido.\n- **handleReferenceDateChange(newValue: _Date_)** - Valida a data de referência e sincroniza o campo quando não há seleção.\n- **handleRangeStartChange(newValue)** - Sincroniza o input quando o início do range muda.\n- **handleRangeEndChange(newValue)** - Sincroniza o input quando o fim do range muda.\n- **render()** - Renderização principal do componente.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do campo.\n- **input** - Parte para o campo textual interno.\n- **icon** - Parte para o ícone de ação (calendário/relógio).",
+      "description": "Subcomponente especializado do ecossistema de datas do GovBR-DS, responsável pela digitação e formatação de datas e horários via teclado.\n\n### Papel na composição\n\n- Aplica máscaras automáticas de digitação conforme o formato configurado (ex.: `DD/MM/AAAA`, `HH:mm`, `DD/MM/AAAA HH:mm`).\n- Contém o botão de acionamento para expandir ou recolher o popup do calendário.\n\n### Regra de uso e relacionamento\n\nNo fluxo usual da aplicação, é instanciado e coordenado automaticamente pelo orquestrador `br-datetime-picker`. Pode ser utilizado de forma autônoma apenas quando o leiaute exigir somente o campo de digitação textual sem o painel flutuante de calendário.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Emite quando o valor é alterado via input ou parsing.\n- **togglePicker** - Solicita ao componente pai a alternância da abertura do picker.\n\n### **Methods:**\n - **handleValueChange(newValue: _Date | null_)** - Revalida e reflete no input mudanças externas em `value`.\n- **handleModeChange(newValue: _string_)** - Garante modo suportado e ajusta máscara/valor textual exibido.\n- **handleReferenceDateChange(newValue: _Date_)** - Valida a data de referência e sincroniza o campo quando não há seleção.\n- **handleRangeStartChange(newValue)** - Sincroniza o input quando o início do range muda.\n- **handleRangeEndChange(newValue)** - Sincroniza o input quando o fim do range muda.\n- **render()** - Renderização principal do componente.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do campo.\n- **input** - Parte para o campo textual interno.\n- **icon** - Parte para o ícone de ação (calendário/relógio).",
       "attributes": [
         {
           "name": "placeholder",
@@ -1178,12 +1193,12 @@
         },
         {
           "name": "reference-date",
-          "description": "Data de referência que orienta a navegação visual do calendário.",
+          "description": "Data de referência que orienta a navegação visual do calendário sem alterar a seleção.\nRecebe uma instância de `Date` por property binding.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "value",
-          "description": "Valor selecionado pelo usuário, ou `null` quando nada foi escolhido.",
+          "description": "Data efetivamente selecionada, ou `null` quando nada foi escolhido; é diferente\nde `referenceDate`, que controla apenas a referência visual.\nRecebe uma instância de `Date` por property binding.",
           "values": [{ "name": "Date" }]
         },
         {
@@ -1193,7 +1208,7 @@
         },
         {
           "name": "selection-mode",
-          "description": "Define se a seleção ocorre por data única ou por intervalo.",
+          "description": "Define se a seleção ocorre por data única ou por intervalo.\nAceita `single` ou `range`; valores inválidos usam `single`.",
           "values": [{ "name": "DatetimePickerSelectionMode" }]
         },
         {
@@ -1208,7 +1223,7 @@
         },
         {
           "name": "range-value",
-          "description": "Intervalo controlado no modo `range`.",
+          "description": "Intervalo controlado no modo `range`, reunindo `rangeStart` e `rangeEnd` em uma atualização.\nDeve conter datas válidas ou `null`; valores inválidos são ignorados. Passe o objeto por property binding.",
           "values": [{ "name": "DatetimePickerDateRange" }]
         }
       ],
@@ -1216,16 +1231,16 @@
     },
     {
       "name": "br-time-picker",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/time-picker?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Evento emitido quando a data de referência ou o valor selecionado mudam.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do seletor de horários.\n- **timer** - Container para o grupo de hora e minuto.\n- **field** - Campo individual de entrada de tempo (com botões de ajuste).\n- **separator** - Separador visual de hora e minuto.\n- **input** - Campo de entrada textual interno do tempo.",
+      "description": "Subcomponente de seleção de horários do GovBR-DS, desenvolvido para permitir a escolha intuitiva de horas e minutos.\n\n### Papel na composição\n\n- Apresenta colunas ou controles de incremento/decremento para seleção de horas e minutos com validação de limites.\n- Sincroniza o horário escolhido com o campo textual associado.\n\n### Regra de uso e relacionamento\n\nCoordenado pelo componente pai `br-datetime-picker` no modo de horário ou composto. Pode ser utilizado avulso quando a aplicação demandar exclusivamente a captura de hora sem necessidade de calendário de datas.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/datetime-picker?tab=designer).\n---\n\n\n### **Events:**\n - **dateStateChange** - Evento emitido quando a data de referência ou o valor selecionado mudam.\n\n### **CSS Parts:**\n - **container** - Parte para o container base do seletor de horários.\n- **timer** - Container para o grupo de hora e minuto.\n- **field** - Campo individual de entrada de tempo (com botões de ajuste).\n- **separator** - Separador visual de hora e minuto.\n- **input** - Campo de entrada textual interno do tempo.",
       "attributes": [
         {
           "name": "reference-date",
-          "description": "Data de referência usada para exibir e ajustar hora e minuto.",
+          "description": "Data usada como referência para a navegação de hora e minuto, sem representar necessariamente a seleção.\nRecebe uma instância de `Date` por property binding; valores inválidos usam a data atual.",
           "values": [{ "name": "Date" }]
         },
         {
           "name": "value",
-          "description": "Valor atualmente selecionado pelo usuário, ou `null` quando vazio.",
+          "description": "Data que contém a hora e o minuto efetivamente selecionados, ou `null` quando vazio.\nRecebe uma instância de `Date` por property binding; datas inválidas usam `null`.",
           "values": [{ "name": "Date" }]
         },
         {
@@ -1238,7 +1253,7 @@
     },
     {
       "name": "br-divider",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/divider?tab=designer).\n---\n\n\n### **Methods:**\n - **updateColor()** - Watcher para a cor do divisor.\nAtualiza a propriedade CSS '--border-color' do elemento para refletir a cor definida.\nIsso permite que o divisor use cores personalizadas sem precisar de estilos adicionais.\n- **updateMargins()** - Watcher para as propriedades de margin.\nAtualiza as propriedades CSS customizáveis do elemento para refletir os margins definidos.\n\n### **Slots:**\n - **default** - Slot opcional para conteúdo dentro do divisor (texto, ícones ou elementos personalizados).\n\n### **CSS Parts:**\n - **divider** - Elemento principal do divisor.\n- **content** - Conteúdo do divisor (quando há slot).",
+      "description": "O componente `br-divider` é o elemento separador visual e semântico do GovBR-DS, utilizado para demarcar limites claros entre seções, listas de conteúdos ou áreas temáticas da página.\n\n### Para que serve\n\n- **Separação visual estruturada:** Cria linhas divisórias sutis horizontais ou verticais para organizar blocos de informação com espaçamentos padronizados.\n- **Rotulação intermediária:** Permite incluir texto (ex.: \"ou\"), ícones ou outros elementos centralizados ao longo da linha divisória através do slot padrão.\n- **Variações visuais:** Suporta estilos contínuos, tracejados (`dashed`) e diferentes densidades para se adequar ao leiaute.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Houver necessidade de indicar explicitamente o término de um bloco temático e o início de outro.\n  - Separar alternativas com um divisor textual (ex.: \"Entrar com conta Gov.BR\" --- ou --- \"Entrar com certificado digital\").\n  - Dividir colunas de rodapés, menus laterais ou cabeçalhos.\n- **Evite e prefira outro componente quando:**\n  - Os espaçamentos em branco (margens e paddings) já forem suficientes para garantir a percepção de separação sem sobrecarregar visualmente a tela.\n\n### Estrutura e Slots\n\nO `br-divider` é um componente autônomo e de apresentação:\n- `default`: Slot opcional para texto ou elemento centralizado intercalado na linha do divisor.\n\nPara 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/divider?tab=designer).\n---\n\n\n### **Methods:**\n - **updateColor()** - Watcher para a cor do divisor.\nAtualiza a propriedade CSS '--border-color' do elemento para refletir a cor definida.\nIsso permite que o divisor use cores personalizadas sem precisar de estilos adicionais.\n- **updateMargins()** - Watcher para as propriedades de margin.\nAtualiza as propriedades CSS customizáveis do elemento para refletir os margins definidos.\n\n### **Slots:**\n - **default** - Slot opcional para conteúdo dentro do divisor (texto, ícones ou elementos personalizados).\n\n### **CSS Parts:**\n - **divider** - Elemento principal do divisor.\n- **content** - Conteúdo do divisor (quando há slot).",
       "attributes": [
         {
           "name": "custom-id",
@@ -1247,17 +1262,17 @@
         },
         {
           "name": "orientation",
-          "description": "Orientação do divisor.Em modo vertical, posicione dentro de um container com `display: flex`.",
+          "description": "Orientação do divisor. Em modo vertical, posicione dentro de um container com `display: flex`. Valores inválidos usam `horizontal`.",
           "values": [{ "name": "DividerOrientation" }]
         },
         {
           "name": "thickness",
-          "description": "Espessura visual do divisor.",
+          "description": "Espessura visual do divisor. Valores inválidos usam `small`.",
           "values": [{ "name": "DividerThickness" }]
         },
         {
           "name": "border-style",
-          "description": "Estilo de borda do divisor.",
+          "description": "Estilo de borda do divisor. Valores inválidos usam `solid`.",
           "values": [{ "name": "DividerBorderStyle" }]
         },
         {
@@ -1267,7 +1282,7 @@
         },
         {
           "name": "color-mode",
-          "description": "Esquema de cor canônico. Quando informado, tem precedência sobre `isDarkMode`.",
+          "description": "Esquema de cor canônico. Quando informado, tem precedência sobre `isDarkMode`; valores inválidos usam `light`.",
           "values": [{ "name": "light" }, { "name": "dark" }]
         },
         {
@@ -1277,7 +1292,7 @@
         },
         {
           "name": "align",
-          "description": "Alinhamento do conteúdo quando há slot interno.",
+          "description": "Alinhamento do conteúdo quando há slot interno. Valores inválidos são ignorados.",
           "values": [{ "name": "DividerAlign" }]
         },
         {
@@ -1287,22 +1302,22 @@
         },
         {
           "name": "margin-top",
-          "description": "Margin top em pixels; se omitido, aplica padrão interno.",
+          "description": "Margin top em pixels; se omitido, aplica padrão interno.\nDeve ser um número finito; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "margin-bottom",
-          "description": "Margin bottom em pixels; se omitido, aplica padrão interno.",
+          "description": "Margin bottom em pixels; se omitido, aplica padrão interno.\nDeve ser um número finito; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "margin-left",
-          "description": "Margin left em pixels; se omitido, aplica padrão interno.",
+          "description": "Margin left em pixels; se omitido, aplica padrão interno.\nDeve ser um número finito; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "margin-right",
-          "description": "Margin right em pixels; se omitido, aplica padrão interno.",
+          "description": "Margin right em pixels; se omitido, aplica padrão interno.\nDeve ser um número finito; valores inválidos usam 0.",
           "values": []
         }
       ],
@@ -1310,7 +1325,7 @@
     },
     {
       "name": "br-dropdown",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/dropdown?tab=designer).\n---\n\n\n### **Events:**\n - **brDidOpen** - Emitido quando o dropdown abre.\n- **brDidClose** - Emitido quando o dropdown fecha.\n- **brDropdownChange**\n- **brDropdownOpenChange** - Evento canônico emitido quando o estado aberto muda.\n\n### **Methods:**\n - **targetZIndexChanged()** - Aplica o novo valor de z-index ao elemento target.\n- **disabledChanged(newValue: _boolean_)** - Fecha o dropdown se for desabilitado enquanto estiver aberto.\n- **hide(): _Promise<{ isOpen: boolean }>_** - @deprecated Use `close`. - Esconde o dropdown.\nDefine a propriedade `isOpen` como falsa e retorna o novo estado.\nEste método pode ser chamado externamente.\n- **close(): _Promise<{ isOpen: boolean }>_** - Fecha o dropdown e mantém o formato de retorno legado.\n- **open(): _Promise<{ isOpen: boolean }>_** - Abre o dropdown.\nDefine a propriedade `isOpen` como verdadeira e retorna o novo estado.\nEste método pode ser chamado externamente.\n- **setFocus()** - Define o foco no elemento interno do componente.\nEste método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto.\n\n### **Slots:**\n - **trigger** - Slot para o elemento que aciona a abertura do dropdown.\n- **target** - Slot para o conteúdo exibido pelo dropdown.\n\n### **CSS Parts:**\n - **trigger** - Área do acionador do dropdown.\n- **target** - Área de conteúdo exibida pelo dropdown.\n- **trigger-arrow** - Indicador visual opcional do acionador do dropdown.",
+      "description": "O componente `br-dropdown` é o painel flutuante de sobreposição do GovBR-DS, ativado por um controle gatilho para apresentar listas contextuais de comandos, opções ou conteúdos complementares.\n\n### Para que serve\n\n- **Menus de contexto e ações:** Agrupa múltiplas ações secundárias ou suplementares que não precisam ficar expostas permanentemente na interface (ex.: menu \"Mais opções\", \"Exportar\", \"Filtrar por\").\n- **Posicionamento flutuante inteligente:** Gerencia a exibição da superfície suspensa sobre o conteúdo da página, garantindo contraste, elevação e fechamento ao clicar fora (`click outside`) ou pressionar a tecla Escape.\n- **Comportamento acessível:** Associa o elemento acionador ao painel de destino via atributos WAI-ARIA (`aria-expanded`, `aria-haspopup`).\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O espaço na barra de ferramentas ou cabeçalho for limitado e houver várias ações pontuais a serem oferecidas.\n  - For necessário apresentar uma lista suspensa de comandos acionáveis.\n- **Evite e prefira outro componente quando:**\n  - O objetivo for permitir a seleção de valor para submissão em formulário (prefira `br-select`).\n  - O conteúdo for a estrutura principal de navegação do site (prefira `br-menu`).\n  - A mensagem for uma notificação assíncrona ou alerta (prefira `br-message` ou `br-notification`).\n\n### Estrutura e Slots\n\nO `br-dropdown` é composto por duas regiões fundamentais:\n- `trigger`: Slot obrigatório onde a aplicação declara o botão ou link de acionamento (como um `br-button`).\n- `target`: Slot onde a aplicação declara o painel, lista de itens ou conteúdo flutuante exibido ao abrir o dropdown.\n\nPara 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/dropdown?tab=designer).\n---\n\n\n### **Events:**\n - **brDidOpen** - Emitido quando o dropdown abre.\n- **brDidClose** - Emitido quando o dropdown fecha.\n- **brDropdownChange**\n- **brDropdownOpenChange** - Evento canônico emitido quando o estado aberto muda.\n\n### **Methods:**\n - **targetZIndexChanged()** - Aplica o novo valor de z-index ao elemento target.\n- **matchTriggerWidthChanged()** - Recalcula a superfície aberta quando a política de largura muda.\n- **disabledChanged(newValue: _boolean_)** - Fecha o dropdown se for desabilitado enquanto estiver aberto.\n- **hide(): _Promise<{ isOpen: boolean }>_** - @deprecated Use `close`. - Esconde o dropdown.\nDefine a propriedade `isOpen` como falsa e retorna o novo estado.\nEste método pode ser chamado externamente.\n- **close(): _Promise<{ isOpen: boolean }>_** - Fecha o dropdown e mantém o formato de retorno legado.\n- **open(): _Promise<{ isOpen: boolean }>_** - Abre o dropdown.\nDefine a propriedade `isOpen` como verdadeira e retorna o novo estado.\nEste método pode ser chamado externamente.\n- **setFocus()** - Define o foco no elemento interno do componente.\nEste método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto.\n\n### **Slots:**\n - **trigger** - Slot para o elemento que aciona a abertura do dropdown.\n- **target** - Slot para o conteúdo exibido pelo dropdown.\n\n### **CSS Parts:**\n - **trigger** - Área do acionador do dropdown.\n- **target** - Área de conteúdo exibida pelo dropdown.\n- **trigger-arrow** - Indicador visual opcional do acionador do dropdown.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1342,6 +1357,11 @@
           "description": "Define se o dropdown deve permanecer aberto quando outro dropdown é aberto.\nQuando definido como false (padrão), o dropdown será fechado automaticamente quando outro dropdown for aberto.\nQuando definido como true, o dropdown permanecerá aberto mesmo quando outro dropdown for aberto.",
           "values": []
         },
+        {
+          "name": "match-trigger-width",
+          "description": "Faz o painel acompanhar a largura do acionador enquanto estiver aberto.\nO valor padrão `false` preserva a largura determinada pelo conteúdo.",
+          "values": []
+        },
         {
           "name": "target-z-index",
           "description": "Define o z-index do elemento target (alvo) do dropdown.\nPermite customizar a ordem de sobreposição do painel dropdown em relação aos demais elementos da página.\nO valor padrão utiliza a variável CSS do design system: var(--z-index-layer-1).",
@@ -1362,7 +1382,7 @@
     },
     {
       "name": "br-footer",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **logo** - Slot para o logo do rodapé, utilizando o componente br-logo.\n- **default** - Slot para o mapa do site, utilizando br-footer-category e br-footer-item.\n- **social-network** - Slot para as redes sociais, utilizando br-footer-social.\n- **partner-logo** - Slot para logos de parceiros, utilizando br-logo.\n- **legal** - Slot para informações legais, utilizando br-footer-legal.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do footer.\n- **site-map** - Área do mapa do site.\n- **social** - Área de redes sociais.\n- **partners** - Área de logos de parceiros.",
+      "description": "O componente `br-footer` é o orquestrador completo de rodapé institucional do GovBR-DS. Fornece o fechamento estrutural da página, centralizando links de navegação categorizados, canais de redes sociais, menção legal de licenciamento aberto e a marca do Governo Federal.\n\n### Para que serve\n\n- **Fechamento e navegação secundária:** Agrupa em categorias os links úteis de apoio, mapas do site e serviços da entidade pública.\n- **Conformidade legal e transparência:** Apresenta a nota de licenciamento de conteúdo (ex.: Creative Commons) e termos legais obrigatórios.\n- **Redes sociais institucionais:** Exibe links oficiais de comunicação pública com a sociedade.\n- **Responsividade integrada:** Converte categorias de links em painéis expansíveis (sanfona) automaticamente no modo mobile.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Finalizar a estrutura da página em portais e sistemas governamentais alinhados ao padrão GovBR-DS.\n  - Oferecer navegação complementar, canais sociais e declarações de direitos autorais.\n- **Evite e prefira outro componente quando:**\n  - A interface for um diálogo modal ou painel isolado que não representa uma página completa do portal.\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-footer` | **Orquestrador principal.** Gerencia a distribuição visual em colunas/linhas e o comportamento sanfona em telas menores. | Deve ser declarado como elemento de rodapé ao final da página. |\n| `br-footer-category` | **Categoria de links.** Agrupa links temáticos sob um título expansível. | Deve ser inserido no contêiner de categorias do `br-footer`. |\n| `br-footer-item` | **Item de link.** Link individual dentro de uma categoria de rodapé. | Deve ser utilizado dentro de um `br-footer-category`. |\n| `br-footer-logo` | **Logotipo.** Exibe a logomarca do órgão ou do Governo Federal. | Posicionado na área designada de logotipo do `br-footer`. |\n| `br-footer-social` | **Redes sociais.** Reúne links e ícones para canais sociais oficiais. | Posicionado no slot ou área de mídias sociais do `br-footer`. |\n| `br-footer-legal` | **Texto legal.** Exibe termos de licenciamento aberto e direitos autorais. | Posicionado na base legal do `br-footer`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-footer` atua como contêiner estrutural orquestrador. Ele organiza as categorias (`br-footer-category`) em colunas no desktop e alterna para comportamento de acordeão no mobile. Os itens (`br-footer-item`) herdam o contexto da categoria correspondente, enquanto as áreas de logotipo, redes sociais e notas legais completam o fechamento padronizado.\n\nPara 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/footer?tab=designer).\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **logo** - Slot para o logo do rodapé, utilizando o componente br-logo.\n- **default** - Slot para o mapa do site, utilizando br-footer-category e br-footer-item.\n- **social-network** - Slot para as redes sociais, utilizando br-footer-social.\n- **partner-logo** - Slot para logos de parceiros, utilizando br-logo.\n- **legal** - Slot para informações legais, utilizando br-footer-legal.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do footer.\n- **site-map** - Área do mapa do site.\n- **social** - Área de redes sociais.\n- **partners** - Área de logos de parceiros.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1394,7 +1414,7 @@
     },
     {
       "name": "br-footer-category",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para os itens da categoria no rodapé, utilizando br-footer-item.",
+      "description": "O componente `br-footer-category` é o subcomponente do GovBR-DS que agrupa links de rodapé por tema sob um título estruturado.\n\n### Para que serve\n\n- **Organização temática:** Divide os links de apoio em blocos temáticos claros.\n- **Colapso responsivo:** Funciona como seção que pode ser expandida ou recolhida no layout mobile, otimizando o espaço da tela.\n\n### Papel na composição\n\nAtua como agrupador intermediário entre o `br-footer` e os itens filhos individuais `br-footer-item`.\n\n### Regra de uso e relacionamento\n\n- Deve ser inserido dentro do `br-footer`.\n- Acomoda instâncias de `br-footer-item` representando cada link pertencente àquela categoria.\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para os itens da categoria no rodapé, utilizando br-footer-item.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1411,7 +1431,7 @@
     },
     {
       "name": "br-footer-item",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Renderiza o componente\n\n### **Slots:**\n - **default** - Slot para o conteúdo do item no rodapé, incluindo texto ou componentes de roteamento para SPAs.",
+      "description": "O componente `br-footer-item` é o subcomponente folha do GovBR-DS que renderiza um link de navegação individual dentro de uma categoria do rodapé.\n\n### Para que serve\n\n- **Acesso direto a links:** Conduz a pessoa usuária a páginas de serviços, transparência ou seções institucionais.\n- **Estilo padronizado:** Garante tipografia, espaçamento e estados acessíveis no rodapé.\n\n### Papel na composição\n\nAtua como item de link final na hierarquia de rodapé.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado exclusivamente dentro de um componente `br-footer-category`.\n- Não deve ser declarado de forma isolada fora de uma categoria de rodapé.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Renderiza o componente\n\n### **Slots:**\n - **default** - Slot para o conteúdo do item no rodapé, incluindo texto ou componentes de roteamento para SPAs.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1433,7 +1453,7 @@
     },
     {
       "name": "br-footer-legal",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para informações legais no rodapé, como direitos autorais ou termos de uso.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do footer-legal.",
+      "description": "O componente `br-footer-legal` é o subcomponente do GovBR-DS que apresenta as informações de licenciamento aberto de conteúdo (como Creative Commons) e termos legais obrigatórios.\n\n### Para que serve\n\n- **Transparência jurídica:** Comunica a licença de uso dos dados e conteúdos do portal público.\n- **Fechamento de conformidade:** Atende às normas governamentais de publicação de páginas federais.\n\n### Papel na composição\n\nAtua como elemento informativo legal no rodapé.\n\n### Regra de uso e relacionamento\n\n- Deve ser posicionado na área base de menções legais do `br-footer`.\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para informações legais no rodapé, como direitos autorais ou termos de uso.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do footer-legal.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1445,7 +1465,7 @@
     },
     {
       "name": "br-footer-logo",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/footer?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Monta o JSX que representa o componente.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do footer-logo.",
+      "description": "O componente `br-footer-logo` é o subcomponente do GovBR-DS responsável por renderizar a marca oficial do órgão ou a marca unificada do Governo Federal no rodapé.\n\n### Para que serve\n\n- **Assinatura institucional:** Reforça a autenticidade governamental no fechamento da página.\n- **Link oficial:** Permite redirecionar a pessoa usuária para o portal principal do Governo Federal ou do órgão.\n\n### Papel na composição\n\nAtua como elemento de identidade institucional no rodapé.\n\n### Regra de uso e relacionamento\n\n- Deve ser inserido na área ou slot de logotipo do `br-footer`.\n- Não deve ser utilizado fora do ecossistema de rodapé.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Monta o JSX que representa o componente.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do footer-logo.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1493,14 +1513,18 @@
     },
     {
       "name": "br-footer-social",
-      "description": "O subcomponente `br-footer-social` representa os ícones de redes sociais no rodapé do site, de acordo com a documentação de design do GovBR.\nEle deve ser utilizado como filho direto do componente [`br-footer`](/docs/components/footer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **icon** - Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`.",
+      "description": "O componente `br-footer-social` é o subcomponente do GovBR-DS que agrupa e renderiza atalhos e ícones para os canais oficiais de redes sociais da organização pública.\n\n### Para que serve\n\n- **Canais oficiais:** Facilita o acesso do cidadão às mídias sociais e de comunicação do órgão.\n- **Acessibilidade nos atalhos:** Fornece rótulos acessíveis e abertura segura de links externos.\n\n### Papel na composição\n\nAtua como bloco de engajamento social no rodapé.\n\n### Regra de uso e relacionamento\n\n- Deve ser inserido na área ou slot destinado a redes sociais do `br-footer`.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **icon** - Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`.",
       "attributes": [
         {
           "name": "custom-id",
           "description": "Identificador único do componente.\nQuando omitido, um valor é gerado automaticamente.\n\n> **Padrão:** valor único gerado por generateUniqueId().",
           "values": []
         },
-        { "name": "icon", "description": "Ícone da rede social", "values": [] },
+        {
+          "name": "icon",
+          "description": "Identificador da rede social. Os ícones oficiais mais comuns são\nrenderizados pelo registro SVG local; use o slot `icon` para uma fonte\ndiferente ou uma classe Font Awesome personalizada.",
+          "values": []
+        },
         {
           "name": "description",
           "description": "Descrição do ícone da rede social",
@@ -1522,7 +1546,7 @@
     },
     {
       "name": "br-header",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).\n\n### Acionamento de Menu Associado\nPara integrar o cabeçalho com um menu (`br-menu`), passe um botão no slot `menu-trigger` com os seguintes atributos:\n- `data-toggle=\"menu\"`\n- `data-target=\"#id-do-menu\"` (substitua pelo ID ou `customId` do seu `br-menu`)\n\nO componente `br-menu` escuta a esses atributos no escopo do documento e controlará automaticamente sua visibilidade.\n---\n\n\n### **Events:**\n - **headerCompactChange** - Evento disparado quando o cabeçalho entra ou sai do modo compacto.\nO evento contém os detalhes do estado compacto e o ID do componente pai.\n- **brHeaderCompactChange** - Evento canônico emitido quando o modo compacto muda.\n- **headerWidthChange** - Evento disparado para indicar qual lista deve encolher primeiro.\nO evento contém os detalhes do ID do componente pai e o nome da lista.\n- **brMenuToggle** - Evento disparado para alternar o estado de um menu associado.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **watchIsCompact(newValue: _boolean_)** - Observa mudanças na propriedade isCompact.\n- **resetHeaderList()** - Reinicializa o estado das listas do cabeçalho, disparando o evento de redimensionamento.\nPode ser chamado externamente para forçar a atualização das listas.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **logo** - Slot para a logo do cabeçalho.\n- **signature** - Slot para a assinatura visual da organização.\n- **links** - Slot para links de navegação principais.\n- **functions** - Slot para botões de ação no cabeçalho.\n- **search** - Slot para o campo de busca.\n- **access** - Slot para o botão de acesso ou autenticação.\n- **menu-trigger** - Slot para o botão que abre o menu.\n- **caption** - Slot para o título do cabeçalho.\n- **subcaption** - Slot para o subtítulo do cabeçalho.\n\n### **CSS Parts:**\n - **header** - Elemento header principal.\n- **top** - Área superior do header.\n- **top-left** - Área superior esquerda (logo + assinatura).\n- **top-right** - Área superior direita (links + funções + busca + acesso).\n- **bottom** - Área inferior do header.\n- **bottom-left** - Área inferior esquerda (menu + título).\n- **bottom-right** - Área inferior direita (busca expandida).",
+      "description": "O componente `br-header` é o orquestrador principal de cabeçalho do GovBR-DS. Centraliza a identidade visual do órgão ou sistema público, links de navegação hierárquica, atalhos de funcionalidades, mecanismo de busca e botão de acesso ou autenticação.\n\n### Para que serve\n\n- **Identidade institucional unificada:** Apresenta a marca e assinatura visual oficial do Governo Federal e da entidade pública.\n- **Navegação e atalhos rápidos:** Reúne links para áreas centrais e botões funcionais (como contraste, acessibilidade e suporte).\n- **Busca e autenticação integradas:** Fornece áreas reservadas e slots para barra de busca rápida e gatilho de login/acesso.\n- **Comportamento responsivo e densidades:** Adapta-se automaticamente a diferentes telas com suporte a densidades padrão, compacta, pequena e grande.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Desenvolver páginas, portais e sistemas públicos federais que requerem a barra superior padronizada do GovBR-DS.\n  - For necessário integrar identidade visual, navegação rápida, busca e acesso em uma estrutura consistente.\n- **Evite e prefira outro componente quando:**\n  - A navegação for exclusivamente lateral ou contextual interna de uma ferramenta gráfica (prefira `br-menu` ou barras de ferramentas específicas).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-header` | **Orquestrador principal.** Estrutura as áreas superior e inferior, gerencia responsividade e densidade. | Deve ser declarado como elemento raiz do topo da página. |\n| `br-header-logo` | **Identidade visual.** Exibe o logotipo ou brasão institucional. | Posicionado nos slots `logo` ou `signature` do `br-header`. |\n| `br-header-list` | **Agrupador de lista.** Contêiner semântico horizontal para links ou funções. | Encaixa-se nos slots `links` ou `functions` do `br-header`. |\n| `br-header-link` | **Item de link.** Atalho ou hiperlink de navegação institucional. | Deve ser inserido dentro de um `br-header-list` no slot `links`. |\n| `br-header-function` | **Ação funcional.** Botão de utilidade rápida (contraste, ajuda, etc.). | Deve ser inserido dentro de um `br-header-list` no slot `functions`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-header` orquestra as áreas da barra através de slots nomeados (`logo`, `signature`, `links`, `functions`, `search`, `access`, `menu-trigger`, `caption`, `subcaption`). Ele observa o tamanho de tela e a densidade configurada, reorganizando os blocos e delegando a exibição correta aos subcomponentes filhos.\n\nPara 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/header?tab=designer).\n---\n\n\n### **Events:**\n - **headerCompactChange** - Evento disparado quando o cabeçalho entra ou sai do modo compacto.\nO evento contém os detalhes do estado compacto e o ID do componente pai.\n- **brHeaderCompactChange** - Evento canônico emitido quando o modo compacto muda.\n- **headerWidthChange** - Evento disparado para indicar qual lista deve encolher primeiro.\nO evento contém os detalhes do ID do componente pai e o nome da lista.\n- **brMenuToggle** - Evento disparado para alternar o estado de um menu associado.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **watchIsCompact(newValue: _boolean_)** - Observa mudanças na propriedade isCompact.\n- **resetHeaderList()** - Reinicializa o estado das listas do cabeçalho, disparando o evento de redimensionamento.\nPode ser chamado externamente para forçar a atualização das listas.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **logo** - Slot para a logo do cabeçalho.\n- **signature** - Slot para a assinatura visual da organização.\n- **links** - Slot para links de navegação principais.\n- **functions** - Slot para botões de ação no cabeçalho.\n- **search** - Slot para o campo de busca.\n- **access** - Slot para o botão de acesso ou autenticação.\n- **menu-trigger** - Slot para o botão que abre o menu.\n- **caption** - Slot para o título do cabeçalho.\n- **subcaption** - Slot para o subtítulo do cabeçalho.\n\n### **CSS Parts:**\n - **header** - Elemento header principal.\n- **top** - Área superior do header.\n- **top-left** - Área superior esquerda (logo + assinatura).\n- **top-right** - Área superior direita (links + funções + busca + acesso).\n- **bottom** - Área inferior do header.\n- **bottom-left** - Área inferior esquerda (menu + título).\n- **bottom-right** - Área inferior direita (busca expandida).",
       "attributes": [
         {
           "name": "caption",
@@ -1541,7 +1565,7 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "HeaderDensity" }]
         },
         {
@@ -1556,7 +1580,7 @@
         },
         {
           "name": "is-sticky",
-          "description": "Fixa o cabeçalho no topo durante a rolagem.",
+          "description": "Fixa o cabeçalho no topo durante a rolagem.\nQuando `compact` ou `is-compact` é definido explicitamente, o modo visual\npermanece fixo durante a rolagem. Sem essa configuração, o header sticky\nalterna automaticamente entre os modos compacto e expandido.",
           "values": []
         },
         {
@@ -1599,7 +1623,7 @@
     },
     {
       "name": "br-header-function",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **handleHeaderWidthChange(event: _CustomEvent<{ id: string; listNames: string[]; shrink: boolean }>_)** - Listener para o evento 'headerWidthChange', disparado pelo componente pai 'br-header'.\nO evento contém o ID do pai e o nome da lista.\nSe o ID do pai corresponder ao ID do cabeçalho atual, o evento será tratado.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para o nome ou rótulo da funcionalidade.\n- **icon** - Slot para ícone que representa a funcionalidade.",
+      "description": "O componente `br-header-function` é o subcomponente do GovBR-DS que representa uma ação funcional ou utilitária rápida no cabeçalho (como alto contraste, atalhos de acessibilidade, suporte ou configurações).\n\n### Para que serve\n\n- **Ações utilitárias rápidas:** Permite disparar funcionalidades auxiliares com ícone e rótulo sem sair do fluxo da página.\n- **Feedback interativo:** Oferece estados visuais consistentes de foco, hover e ativação.\n\n### Papel na composição\n\nAtua como controle interativo de utilidade dentro do cabeçalho.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado dentro de um `br-header-list` posicionado no slot `functions` do `br-header`.\n- Não deve ser utilizado como botão genérico de formulário ou ação primária de conteúdo (para esses casos, utilize `br-button`).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **handleHeaderWidthChange(event: _CustomEvent<{ id: string; listNames: string[]; shrink: boolean }>_)** - Listener para o evento 'headerWidthChange', disparado pelo componente pai 'br-header'.\nO evento contém o ID do pai e o nome da lista.\nSe o ID do pai corresponder ao ID do cabeçalho atual, o evento será tratado.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para o nome ou rótulo da funcionalidade.\n- **icon** - Slot para ícone que representa a funcionalidade.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1613,7 +1637,7 @@
         },
         {
           "name": "icon-name",
-          "description": "Nome Iconify do ícone exibido.",
+          "description": "Identificador legado do ícone exibido. Nomes conhecidos são resolvidos pelo\nregistro SVG local; para novos usos, prefira o slot `icon` com um SVG, asset\nlocal ou elemento de ícone controlado pela aplicação.",
           "values": []
         },
         {
@@ -1631,7 +1655,7 @@
     },
     {
       "name": "br-header-link",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para o conteúdo do link exibido no cabeçalho.",
+      "description": "O componente `br-header-link` é o subcomponente de navegação do GovBR-DS que representa um atalho ou hiperlink de navegação institucional no cabeçalho.\n\n### Para que serve\n\n- **Navegação institucional:** Oferece acesso direto a páginas de serviços, portais correlatos ou áreas centrais do órgão.\n- **Integração SPA:** Suporta navegação web padrão via atributo `href` ou integração com roteadores SPA via eventos de navegação.\n\n### Papel na composição\n\nAtua como item folha de navegação dentro do cabeçalho.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado dentro de um `br-header-list` posicionado no slot `links` do `br-header`.\n- Não deve ser utilizado de forma avulsa fora do ecossistema de cabeçalho.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para o conteúdo do link exibido no cabeçalho.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1654,7 +1678,7 @@
     },
     {
       "name": "br-header-list",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).\n---\n\n\n### **Events:**\n - **headerListUpdate** - Evento disparado para indicar qual lista deve encolher primeiro.\nO evento envia o ID do componente pai e o nome da lista.\n- **headerListFocused** - Evento disparado quando a lista recebe foco.\nO evento envia o ID do componente.\n\n### **Methods:**\n - **closeList()** - Fecha a lista.\n- **isListOpen(): __** - Verifica se a lista está aberta.\n- **openList(): _Promise<void>_** - Abre a lista.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para o conteúdo da lista de navegação no cabeçalho.",
+      "description": "O componente `br-header-list` é o subcomponente contêiner do GovBR-DS que organiza links de navegação ou botões funcionais em uma estrutura de lista horizontal acessível.\n\n### Para que serve\n\n- **Agrupamento semântico:** Estrutura itens navegáveis ou funcionais em elementos de lista semânticos.\n- **Distribuição e espaçamento:** Garante o alinhamento horizontal padronizado de itens no cabeçalho.\n\n### Papel na composição\n\nAtua como elo intermediário entre o orquestrador `br-header` e os itens filhos individuais (`br-header-link` ou `br-header-function`).\n\n### Regra de uso e relacionamento\n\n- Deve ser inserido nos slots `links` ou `functions` do orquestrador `br-header`.\n- Serve de contêiner direto para subcomponentes `br-header-link` ou `br-header-function`.\n---\n\n\n### **Events:**\n - **headerListUpdate** - Evento disparado para indicar qual lista deve encolher primeiro.\nO evento envia o ID do componente pai e o nome da lista.\n- **headerListFocused** - Evento disparado quando a lista recebe foco.\nO evento envia o ID do componente.\n\n### **Methods:**\n - **closeList()** - Fecha a lista.\n- **isListOpen(): __** - Verifica se a lista está aberta.\n- **openList(): _Promise<void>_** - Abre a lista.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para o conteúdo da lista de navegação no cabeçalho.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1671,7 +1695,7 @@
     },
     {
       "name": "br-header-logo",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/header?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **handleIsCompactChange()** - Observa mudanças na propriedade `isCompact` e ajusta a altura da logo se `hasDefaultHeight` for verdadeiro.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para a logo personalizada exibida no cabeçalho.\n\n### **CSS Parts:**\n - **container** - Wrapper da logo do header.",
+      "description": "O componente `br-header-logo` é o subcomponente do GovBR-DS responsável por renderizar a marca visual oficial ou a assinatura do órgão dentro do cabeçalho.\n\n### Para que serve\n\n- **Exibição de marca:** Apresenta a imagem ou logotipo institucional no topo da página.\n- **Link de retorno:** Permite associar um link à marca, direcionando a pessoa usuária à página inicial do portal ou sistema.\n\n### Papel na composição\n\nAtua como elemento de identidade visual no cabeçalho. Não gerencia a estrutura do topo nem as ações utilitárias, papel reservado ao orquestrador `br-header`.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado posicionado preferencialmente no slot `logo` ou `signature` do componente orquestrador `br-header`.\n- Não deve ser utilizado isoladamente fora do contexto de cabeçalho institucional.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **handleIsCompactChange()** - Observa mudanças na propriedade `isCompact` e ajusta a altura da logo se `hasDefaultHeight` for verdadeiro.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para a logo personalizada exibida no cabeçalho.\n\n### **CSS Parts:**\n - **container** - Wrapper da logo do header.",
       "attributes": [
         {
           "name": "custom-id",
@@ -1695,12 +1719,12 @@
         },
         {
           "name": "target",
-          "description": "Target do link quando href é fornecido.",
+          "description": "Target do link quando href é fornecido.\nAceita `_self`, `_blank`, `_parent` ou `_top`. Valores inválidos usam `_self`.",
           "values": [{ "name": "BrLinkTarget" }]
         },
         {
           "name": "navigation-mode",
-          "description": "Controla como o componente integra a navegação mantendo `href` real no elemento navegável.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.",
+          "description": "Controla como o componente integra a navegação mantendo `href` real no elemento navegável.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.\nValores inválidos usam `native`.",
           "values": [{ "name": "BrNavigationMode" }]
         },
         { "name": "src", "description": "Url da logo padrão.", "values": [] },
@@ -1711,7 +1735,7 @@
     },
     {
       "name": "br-icon",
-      "description": "O componente `br-icon` fornece uma maneira flexível e dinâmica de incorporar ícones nas aplicações.\nEle aceita arquivos de imagem da aplicação por URL, SVG inline e conteúdo via slot.\nNomes Iconify por `iconName` continuam disponíveis somente para compatibilidade legada.\n\nCom opções para especificar a altura e largura, adicionar classes CSS personalizadas, e definir como o ícone\ndeve ser rotacionado ou espelhado, o `br-icon` oferece aos desenvolvedores as ferramentas necessárias para\nintegrar ícones de forma consistente com o estilo e design de suas aplicações, melhorando a experiência do usuário\ne a clareza das interfaces.\n---\n\n\n### **Slots:**\n - _default_ - Conteúdo customizado do ícone. Pode receber elementos como `<i>`, `<svg>` ou componentes de outras bibliotecas.\n\n### **CSS Parts:**\n - **icon** - Elemento interno que representa o ícone renderizado.\n- **image** - Elemento img interno quando `src` é usado.\n- **svg** - Elemento interno que recebe SVG inline quando `svg` é usado.\n- **slot** - Elemento interno que recebe conteúdo via slot.",
+      "description": "O componente `br-icon` é o elemento oficial do GovBR-DS para renderização dinâmica e padronizada de ícones vetoriais. Ele suporta a família tipográfica Font Awesome e ícones utilitários do governo, garantindo contraste, escalabilidade e acessibilidade visual.\n\n### Para que serve\n\n- **Comunicação visual imediata:** Fornece apoio gráfico rápido para ações em botões, links, cartões, menus e alertas contextuais.\n- **Acessibilidade nativa:** Gerencia automaticamente a visibilidade para leitores de tela: ícones decorativos recebem `aria-hidden=\"true\"`, enquanto ícones informativos recebem nome acessível via `aria-label`.\n- **Flexibilidade dimensional e cromática:** Permite personalizar tamanho, cor através de tokens CSS do GovBR-DS, rotação e efeitos de espelhamento.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - For necessário reforçar o significado de um texto ou ação com uma representação gráfica familiar.\n  - Criar controles compactos com ícone acompanhado de descrição acessível.\n- **Evite e prefira outro componente quando:**\n  - For necessária uma imagem fotográfica ou ilustração visual ampla com detalhes cromáticos complexos (prefira tags HTML `<img>` ou SVG ilustrativo).\n\n### Estrutura e Slots\n\nO `br-icon` renderiza um elemento vetorial direto com base no atributo `name` informado ou através de classes utilitárias.\n\nPara 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/icon?tab=designer).\n---\n\n\n### **Slots:**\n - _default_ - Conteúdo customizado do ícone. Pode receber elementos como `<i>`, `<svg>` ou componentes de outras bibliotecas.\n\n### **CSS Parts:**\n - **icon** - Elemento interno que representa o ícone renderizado.\n- **image** - Elemento img interno quando `src` é usado.\n- **svg** - Elemento interno que recebe SVG inline quando `svg` é usado.\n- **slot** - Elemento interno que recebe conteúdo via slot.",
       "attributes": [
         {
           "name": "label",
@@ -1720,7 +1744,7 @@
         },
         {
           "name": "icon-name",
-          "description": "Nome do ícone a ser exibido utilizando a biblioteca Iconify.",
+          "description": "Identificador legado do ícone. Identificadores que pertencem ao registro local são\nrenderizados como SVG empacotado; nomes desconhecidos continuam disponíveis via Iconify\nsomente para compatibilidade.",
           "values": []
         },
         {
@@ -1730,12 +1754,12 @@
         },
         {
           "name": "svg",
-          "description": "Conteúdo SVG inline a ser renderizado como ícone.\n\nUse apenas SVGs confiáveis e sanitizados pela aplicação.",
+          "description": "Conteúdo SVG inline a ser renderizado como ícone.\n\nUse apenas SVGs confiáveis e sanitizados pela aplicação.\nPasse o conteúdo por property binding para evitar serialização no atributo.",
           "values": []
         },
         {
           "name": "source",
-          "description": "Define explicitamente a origem do ícone.\nQuando `auto`, o componente prioriza slot, SVG inline e imagem por URL.\nIconify fica apenas como fallback de compatibilidade quando nenhuma fonte própria foi informada.",
+          "description": "Define explicitamente a origem do ícone.\nQuando `auto`, o componente prioriza slot, SVG inline e imagem por URL.\nIconify fica apenas como fallback de compatibilidade quando nenhuma fonte própria foi informada.\nAceita `auto`, `iconify`, `image`, `svg` ou `slot`; valores inválidos usam `auto`.",
           "values": [{ "name": "IconSource" }]
         },
         {
@@ -1770,12 +1794,12 @@
         },
         {
           "name": "rotate",
-          "description": "Define o ângulo de rotação do ícone.",
+          "description": "Define o ângulo de rotação do ícone.\nAceita `90deg`, `180deg` ou `270deg`; valores inválidos são ignorados.",
           "values": [{ "name": "IconRotate" }]
         },
         {
           "name": "flip",
-          "description": "Define o tipo de espelhamento do ícone.",
+          "description": "Define o tipo de espelhamento do ícone.\nAceita `horizontal` ou `vertical`; valores inválidos são ignorados.",
           "values": [{ "name": "IconFlip" }]
         },
         {
@@ -1798,7 +1822,7 @@
     },
     {
       "name": "br-input",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/input?tab=designer).\n\n### Validação e Acessibilidade\n- **Validação:** Utilize a propriedade `state=\"danger\"` para indicar um campo inválido e forneça o motivo no slot `feedback` utilizando o `<br-message>`. O gerenciamento da regra de validação é de responsabilidade da aplicação ou framework consumidor.\n- **Acessibilidade:** Este componente respeita a navegação por teclado e automaticamente sinaliza erros para leitores de tela quando `state=\"danger\"` é ativado. Se o campo não possuir rótulo visual (label), use a propriedade `aria-label`.\n---\n\n\n### **Events:**\n - **valueChange** - Valor atualizado do input\n- **brClear** - Emitted when the input clear button action is triggered.\n- **brInputValidationChange** - Informa o início e o resultado do validator, inclusive quando ele consulta\num serviço remoto. O `detail` contém `validating`, `valid` e `message`;\nescrita programática e reset não representam interação do usuário.\n\n### **Methods:**\n - **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do input for válido, caso contrário `false`.\nSe o input for inválido, exibe uma mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o input.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n\n### Examples\n- **validate(): _Promise<boolean>_** - Executa a regra customizada e retorna se o campo está válido.\nSe o validator for assíncrono, aguarda a resposta e ignora resultados\nantigos quando uma execução posterior já começou.\n- **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do input for válido, caso contrário `false`.\nSe o input for inválido, dispara um evento 'invalid'.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **select(): _Promise<void>_** - Seleciona todo o texto do controle nativo, conforme HTMLInputElement.select().\n- **setRangeText(replacement: _string_, start: _number_, end: _number_, selectionMode: _SelectionMode_): _Promise<void>_** - Substitui um intervalo de texto usando a API nativa do input.\n- **setSelectionRange(start: _number_, end: _number_, direction: _'forward' | 'backward' | 'none'_): _Promise<void>_** - Define o intervalo selecionado no controle nativo.\n- **stepUp(n: _number_): _Promise<void>_** - Incrementa o valor numérico pelo step nativo.\n- **stepDown(n: _number_): _Promise<void>_** - Decrementa o valor numérico pelo step nativo.\n- **showPicker(): _Promise<void>_** - Abre o picker nativo quando o navegador e o tipo do input oferecem essa API.\n- **render(): __** - Renderiza o componente de input.\n\n### **Slots:**\n - **action** - Botão à direita do input.\n- **icon** - Ícone à esquerda do input.\n- **help-text** - Personalização do texto de ajuda.\n- **feedback** - Mensagem de feedback como resposta específica a uma interação do usuário com o input. Pode ser feedback de erro, aviso, sucesso ou informação.\n- **validation-loading** - Indicador exibido enquanto o validator assíncrono está pendente.\n\n### **CSS Parts:**\n - **container** - Contêiner visual principal do input.\n- **label** - Rótulo do input.\n- **input** - Elemento input nativo.\n- **group** - Grupo que contém ícone, input, botão e ajuda.\n- **icon** - Contêiner do slot de ícone.\n- **action** - Botão de ação lateral.\n- **action-button** - Botão interno reexportado do br-button da ação.\n- **help-text** - Texto de ajuda ou slot de ajuda.\n- **feedback** - Slot de feedback.",
+      "description": "O componente `br-input` é o controle padrão do GovBR-DS para entrada de dados textuais em linha única. Totalmente integrado à validação nativa de formulários HTML via `ElementInternals` (`formAssociated`), ele suporta múltiplos tipos de entrada, máscaras e formatação.\n\n### Para que serve\n\n- **Captura de dados curtos em formulários:** Entrada de textos, senhas, endereços de e-mail, números, telefones, documentos e termos de busca.\n- **Alternância de visualização de senha:** No tipo `type=\"password\"`, oferece botão embutido para alternar entre texto visível e caracteres mascarados com feedback acessível.\n- **Validação e mensagens contextuais:** Comunica valor, validade e mensagens de erro ou orientação diretamente ao formulário HTML e leitores de tela.\n- **Densidade e ícones de apoio:** Suporta diferentes densidades visuais (alta, média e baixa) e ícones prefixados ou sufixados para enriquecer a experiência.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A informação digitada couber em uma única linha (ex.: nome, CPF, e-mail, valor monetário, busca).\n- **Evite e prefira outro componente quando:**\n  - O texto for extenso ou exigir múltiplas linhas (prefira `br-textarea`).\n  - A escolha for feita a partir de uma lista pré-determinada de opções (prefira `br-select`, `br-radio` ou `br-checkbox`).\n  - O valor for uma data ou hora estruturada (prefira `br-datetime-picker`).\n\n### Estrutura e Slots\n\nO `br-input` é composto pelo campo de entrada e slots de apoio:\n- `icon`: Slot para ícone de apoio visual (prefixado ou sufixado ao campo de digitação).\n- `feedback`: Slot para exibição de mensagens de validação contextual (como `br-message`).\n\nPara 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/input?tab=designer).\n---\n\n\n### **Events:**\n - **valueChange** - Valor atualizado do input\n- **brClear** - Emitted when the input clear button action is triggered.\n- **brInputValidationChange** - Informa o início e o resultado do validator, inclusive quando ele consulta\num serviço remoto. O `detail` contém `validating`, `valid` e `message`;\nescrita programática e reset não representam interação do usuário.\n\n### **Methods:**\n - **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do input for válido, caso contrário `false`.\nSe o input for inválido, exibe uma mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o input.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa a regra customizada e retorna se o campo está válido.\nSe o validator for assíncrono, aguarda a resposta e ignora resultados\nantigos quando uma execução posterior já começou.\n- **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do input for válido, caso contrário `false`.\nSe o input for inválido, dispara um evento 'invalid'.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **select(): _Promise<void>_** - Seleciona todo o texto do controle nativo, conforme HTMLInputElement.select().\n- **setRangeText(replacement: _string_, start: _number_, end: _number_, selectionMode: _SelectionMode_): _Promise<void>_** - Substitui um intervalo de texto usando a API nativa do input.\n- **setSelectionRange(start: _number_, end: _number_, direction: _'forward' | 'backward' | 'none'_): _Promise<void>_** - Define o intervalo selecionado no controle nativo.\n- **stepUp(n: _number_): _Promise<void>_** - Incrementa o valor numérico pelo step nativo.\n- **stepDown(n: _number_): _Promise<void>_** - Decrementa o valor numérico pelo step nativo.\n- **showPicker(): _Promise<void>_** - Abre o picker nativo quando o navegador e o tipo do input oferecem essa API.\n- **render(): __** - Renderiza o componente de input.\n\n### **Slots:**\n - **action** - Botão à direita do input.\n- **icon** - Ícone à esquerda do input.\n- **help-text** - Personalização do texto de ajuda.\n- **feedback** - Mensagem de feedback como resposta específica a uma interação do usuário com o input. Pode ser feedback de erro, aviso, sucesso ou informação.\n- **validation-loading** - Indicador exibido enquanto o validator assíncrono está pendente.\n\n### **CSS Parts:**\n - **container** - Contêiner visual principal do input.\n- **label** - Rótulo do input.\n- **input** - Elemento input nativo.\n- **group** - Grupo que contém ícone, input, botão e ajuda.\n- **icon** - Contêiner do slot de ícone.\n- **action** - Botão de ação lateral.\n- **action-button** - Botão interno reexportado do br-button da ação.\n- **help-text** - Texto de ajuda ou slot de ajuda.\n- **feedback** - Slot de feedback.",
       "attributes": [
         {
           "name": "type",
@@ -1812,7 +1836,7 @@
         },
         {
           "name": "density",
-          "description": "Ajusta a densidade, alterando o espaçamento interno para um visual mais compacto ou mais expandido.",
+          "description": "Ajusta a densidade, alterando o espaçamento interno para um visual mais compacto ou mais expandido.\nAceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.",
           "values": [{ "name": "InputDensity" }]
         },
         {
@@ -1912,22 +1936,22 @@
         },
         {
           "name": "min",
-          "description": "Define o valor mínimo para campos de entrada numéricos.",
+          "description": "Define o valor mínimo para campos de entrada numéricos. Deve ser um número finito;\nvalores inválidos são ignorados.",
           "values": []
         },
         {
           "name": "max",
-          "description": "Define o valor máximo para campos de entrada numéricos.",
+          "description": "Define o valor máximo para campos de entrada numéricos. Deve ser um número finito;\nvalores inválidos são ignorados.",
           "values": []
         },
         {
           "name": "minlength",
-          "description": "Define o comprimento mínimo do valor do campo de entrada.",
+          "description": "Define o comprimento mínimo do valor do campo de entrada. Deve ser um inteiro não negativo;\nvalores inválidos são ignorados.",
           "values": []
         },
         {
           "name": "maxlength",
-          "description": "Define o comprimento máximo do valor do campo de entrada.",
+          "description": "Define o comprimento máximo do valor do campo de entrada. Deve ser um inteiro não negativo;\nvalores inválidos são ignorados.",
           "values": []
         },
         {
@@ -1937,12 +1961,12 @@
         },
         {
           "name": "pattern",
-          "description": "Define o padrão de entrada para validação.",
+          "description": "Expressão regular usada para validar o valor final, sem alterar o texto digitado.\nDiferentemente de `mask`, esta prop valida, mas não formata a entrada.",
           "values": []
         },
         {
           "name": "mask",
-          "description": "Máscara aplicada ao valor digitado (use `#` para marcar posições numéricas).",
+          "description": "Formata o valor durante a digitação; use `#` para marcar posições numéricas.\nDiferentemente de `pattern`, esta prop não substitui uma regra de validação.",
           "values": []
         },
         {
@@ -1952,7 +1976,7 @@
         },
         {
           "name": "step",
-          "description": "Define o valor do passo para campos de entrada numéricos.",
+          "description": "Define o valor do passo para campos de entrada numéricos. Deve ser um número finito maior que 0;\nvalores inválidos são ignorados.",
           "values": []
         },
         {
@@ -1962,7 +1986,7 @@
         },
         {
           "name": "action-tab-index",
-          "description": "Define o tabindex do botão de ação.\nÚtil para remover o botão da sequência de tabulação quando o foco é gerenciado externamente (ex.: br-select).",
+          "description": "Define o tabindex do botão de ação.\nÚtil para remover o botão da sequência de tabulação quando o foco é gerenciado externamente (ex.: br-select).\nAceita inteiros maiores ou iguais a -1; valores inválidos são ignorados.",
           "values": []
         }
       ],
@@ -1970,7 +1994,7 @@
     },
     {
       "name": "br-item",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/item?tab=designer).\n---\n\n\n### **Events:**\n - **brDidClick** - Evento customizado emitido quando o item é clicado, aplicável apenas se o item for um botão (`<button>`).\nPode ser utilizado para ações personalizadas, exceto quando o item está desativado.\n- **brItemClick** - Evento canônico emitido quando o item com comportamento de botão é acionado.\n- **brDidSelect** - Evento customizado aplicável para todos os tipos de elementos (`div`, `button`, `a`), emitido quando o item é selecionado e desde que a propriedade `isInteractive` esteja presente.\nO `detail` expõe `{ selected: boolean }` indicando o novo estado.\nNão é emitido quando `disabled` está ativo.\n- **brItemSelect** - Evento canônico emitido quando a seleção muda.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **activate()** - Ativa o item programaticamente, simulando um clique na superfície.\nUtilizado pelo br-list para tratar Enter e Espaço via teclado, e\ninternamente pelo próprio item quando standalone (fora de br-list).\n- **setFocus()** - Define o foco no elemento interno do componente.\nEste método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto.\n- **setTabIndex(value: _number_)** - Define o tabIndex do elemento interno.\nUtilizado pelo br-list para implementar o padrão roving tabindex,\ngarantindo que apenas um item por vez seja alcançável via Tab.\n\n### **Slots:**\n - **default** - Área de conteúdo, podendo conter qualquer componente, exceto botões primários e componentes relacionados à navegação (como carrosséis, paginações, abas, menus, etc.).\n- **start** - Área de recursos visuais, podendo conter elementos como ícones, avatares e mídias.\n- **end** - Área de recursos complementares, podendo conter componentes interativos, metadados e informações adicionais.\n\n### **CSS Parts:**\n - **item** - Elemento principal do item (botão, link ou div).",
+      "description": "O componente `br-item` é o elemento flexível e padronizado do GovBR-DS para construção de linhas navegáveis, selecionáveis ou de exibição em listas, menus contextuais e painéis suspensos.\n\n### Para que serve\n\n- **Padronização de linhas interativas:** Garante espaçamento, tipografia, contraste e efeitos de estado (hover, foco visível, seleção e desativação) em conformidade com os tokens do design system.\n- **Polimorfismo semântico:** Pode renderizar internamente um botão interativo (`<button>`), um hiperlink navegável (`<a>`) ou uma divisão semântica (`<div>`) dependendo dos atributos fornecidos (`href`, `clickable`).\n- **Suporte a seleção visual:** Oferece suporte a estados de seleção (`selected`), marcas de verificação e densidades ajustáveis.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Estiver montando linhas de conteúdo em listas (`br-list`), painéis flutuantes (`br-dropdown`) ou agrupamentos verticais.\n  - Cada entrada representar um item de dado ou uma ação com estilo homogêneo.\n- **Evite e prefira outro componente quando:**\n  - O item pertencer especificamente à navegação de abas (use `br-tab-item`), etapas de fluxo (use `br-step-item`) ou seleção em formulário (use `br-select-option`).\n\n### Estrutura e Slots\n\nO `br-item` é um componente estrutural direto:\n- `default`: Slot para inserção do conteúdo livre da linha (textos, ícones, badges ou metadados).\n\nPara 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/item?tab=designer).\n---\n\n\n### **Events:**\n - **brDidClick** - Evento customizado emitido quando o item é clicado, aplicável apenas se o item for um botão (`<button>`).\nPode ser utilizado para ações personalizadas, exceto quando o item está desativado.\n- **brItemClick** - Evento canônico emitido quando o item com comportamento de botão é acionado.\n- **brDidSelect** - Evento customizado aplicável para todos os tipos de elementos (`div`, `button`, `a`), emitido quando a seleção do item interativo ou botão muda.\nO `detail` expõe `{ selected: boolean }` indicando o novo estado.\nNão é emitido quando `disabled` está ativo.\n- **brItemSelect** - Evento canônico emitido quando a seleção muda.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Methods:**\n - **activate()** - Ativa o item programaticamente, simulando um clique na superfície.\nUtilizado pelo br-list para tratar Enter e Espaço via teclado, e\ninternamente pelo próprio item quando standalone (fora de br-list).\n- **setFocus()** - Define o foco no elemento interno do componente.\nEste método pode ser chamado externamente para garantir que o foco seja aplicado ao elemento correto.\n- **setTabIndex(value: _number_)** - Define o tabIndex do elemento interno.\nUtilizado pelo br-list para implementar o padrão roving tabindex,\ngarantindo que apenas um item por vez seja alcançável via Tab.\n\n### **Slots:**\n - **default** - Área de conteúdo, podendo conter qualquer componente, exceto botões primários e componentes relacionados à navegação (como carrosséis, paginações, abas, menus, etc.).\n- **start** - Área de recursos visuais, podendo conter elementos como ícones, avatares e mídias.\n- **end** - Área de recursos complementares, podendo conter componentes interativos, metadados e informações adicionais.\n\n### **CSS Parts:**\n - **item** - Elemento principal do item (botão, link ou div).",
       "attributes": [
         {
           "name": "disabled",
@@ -1999,7 +2023,7 @@
         },
         {
           "name": "selected",
-          "description": "Estado selecionado canônico. Quando informado, tem precedência sobre `isSelected`.",
+          "description": "Estado selecionado canônico. Em itens interativos, também é atualizado pelo acionamento.",
           "values": []
         },
         {
@@ -2049,7 +2073,7 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "BrDensity" }]
         }
       ],
@@ -2057,7 +2081,7 @@
     },
     {
       "name": "br-link",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/link?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n- **brSpaNavigate**\n\n### **Slots:**\n - **default** - Conteúdo do link (texto, ícones ou outros elementos).\n\n### **CSS Parts:**\n - **anchor** - Parte exposta para o elemento âncora interno, usada para estilos customizados via `::part(anchor)`.",
+      "description": "O componente `br-link` é o controle oficial de hiperlink do GovBR-DS, projetado para orientar e conduzir a pessoa usuária em navegações internas entre páginas ou encaminhamentos para destinos externos.\n\n### Para que serve\n\n- **Navegação estruturada:** Conduz o usuário para novas URLs, rotas de aplicação, âncoras dentro da mesma página ou arquivos para download.\n- **Identificação de links externos:** Permite sinalizar visualmente que o link aponta para um domínio externo ou abre em nova aba/janela, adicionando os atributos de segurança e acessibilidade necessários (`target=\"_blank\"`, `rel=\"noopener noreferrer\"`).\n- **Estilos inline e de bloco:** Adapta-se ao fluxo de leitura textual em parágrafos ou como elemento de navegação isolado com suporte a ícones.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A ação resultar na alteração da URL do navegador, navegação para outra página ou download de arquivo.\n- **Evite e prefira outro componente quando:**\n  - A ação disparar um comportamento na interface sem alterar a URL (como abrir modal, submeter formulário ou acionar filtro): prefira `br-button`.\n\n### Estrutura e Slots\n\nO `br-link` é um componente autônomo:\n- `default`: Slot para o texto do link, ícones auxiliares ou elementos combinados.\n\nPara 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/link?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n- **brSpaNavigate**\n\n### **Slots:**\n - **default** - Conteúdo do link (texto, ícones ou outros elementos).\n\n### **CSS Parts:**\n - **anchor** - Parte exposta para o elemento âncora interno, usada para estilos customizados via `::part(anchor)`.",
       "attributes": [
         {
           "name": "href",
@@ -2104,7 +2128,11 @@
           "description": "Controla como o componente integra a navegação mantendo `href` real no elemento navegável.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.",
           "values": [{ "name": "BrNavigationMode" }]
         },
-        { "name": "is-spa-link-behavior", "values": [] },
+        {
+          "name": "is-spa-link-behavior",
+          "description": "Ativa o comportamento legado de navegação SPA, interceptando cliques simples\npara atualizar o histórico e emitir `brSpaNavigate`.",
+          "values": []
+        },
         {
           "name": "disabled",
           "description": "Desativa o link, tornando-o não interativo.\nQuando `true`: remove o `href` (um `<a>` sem `href` sai da ordem de\ntabulação e não recebe foco, nem por clique), marca `aria-disabled=\"true\"`\ne bloqueia o clique (sem navegação nem emissão de `brNavigate`).\nSe o link estiver focado no momento da desativação, o foco é removido.\nÚtil para componentes como `br-pagination` e `br-wizard`.",
@@ -2185,7 +2213,7 @@
     },
     {
       "name": "br-list",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/list?tab=designer).\n---\n\n\n### **Methods:**\n - **focusFirstItem()** - Move o foco para o primeiro item navegável da lista.\nAPI pública para componentes que abrem a lista programaticamente\n(ex.: `br-dropdown`), evitando acesso direto ao `br-item`.\n\n### **Slots:**\n - **default** - Slot para os itens da lista.\n- **header** - Slot para ações ou conteúdo do cabeçalho da lista.\n\n### **CSS Parts:**\n - **container** - Wrapper principal da lista.",
+      "description": "O componente `br-list` é o contêiner estrutural do GovBR-DS desenvolvido para apresentar coleções verticais de itens homogêneos ou relacionados de forma organizada, fácil de percorrer visualmente e acessível.\n\n### Para que serve\n\n- **Apresentação sequencial de informações:** Organiza listagens de dados, tarefas, configurações, opções de navegação ou mensagens.\n- **Cabeçalho e ações integradas:** Suporta cabeçalho contextual (`header`) para exibição de título da lista, contadores de itens ou botões de ação em lote.\n- **Composição com itens padronizados:** Integra-se perfeitamente com elementos `br-item` e divisores `br-divider`, mantendo ritmo visual e alinhamento consistentes.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Desejar exibir uma sequência vertical de itens que compartilham a mesma estrutura ou propósito.\n  - O conteúdo favorecer leitura linear ou seleção de uma linha e precisar ser percorrido visualmente com rapidez.\n- **Evite e prefira outro componente quando:**\n  - As informações forem tabulares com múltiplas colunas e necessidade de ordenação por coluna (prefira `br-table`).\n  - A lista representar o menu principal de navegação do sistema (prefira `br-menu`).\n\n### Estrutura e Slots\n\nO `br-list` atua como contêiner de itens:\n- `header`: Slot opcional para cabeçalho da lista (título, filtros ou ações globais).\n- `default`: Slot principal onde são inseridos os elementos filhos (como `br-item` ou divs semânticas).\n\nPara 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/list?tab=designer).\n---\n\n\n### **Methods:**\n - **handleAccordionExclusivity(event: _CustomEvent<{ accordionGroup?: string }>_)** - Coordena o accordion entre listas irmãs. Quando o `br-collapse` interno\ndesta lista abre, fecha o `br-collapse` das demais `br-list` irmãs que\ncompartilham o mesmo valor de `accordion`. Só reage ao evento da própria\nlista — `brCollapseOpen` de outras listas não passa por este host.\n- **focusFirstItem()** - Move o foco para o primeiro item navegável da lista.\nAPI pública para componentes que abrem a lista programaticamente\n(ex.: `br-dropdown`), evitando acesso direto ao `br-item`.\n\n### **Slots:**\n - **default** - Slot para os itens da lista.\n- **header** - Slot para ações ou conteúdo do cabeçalho da lista.\n\n### **CSS Parts:**\n - **container** - Wrapper principal da lista.",
       "attributes": [
         {
           "name": "header",
@@ -2199,7 +2227,7 @@
         },
         {
           "name": "orientation",
-          "description": "Orientação canônica. Quando informada, tem precedência sobre `isHorizontal`.",
+          "description": "Orientação canônica. Quando informada, tem precedência sobre `isHorizontal`; valores inválidos usam `vertical`.",
           "values": [{ "name": "horizontal" }, { "name": "vertical" }]
         },
         {
@@ -2219,22 +2247,22 @@
         },
         {
           "name": "collapse",
-          "description": "Indica se a lista possui o comportamento de collapse.",
+          "description": "Torna a lista recolhível: o corpo é envolvido por um `br-collapse` interno\nque abre e fecha ao acionar o cabeçalho. Começa recolhida.\n\nRequer um cabeçalho (atributo `header` ou slot `header`) — ele é o acionador.\nSem cabeçalho não há como recolher.\n\nPara \"apenas uma aberta por vez\" entre listas, use `accordion`.",
           "values": []
         },
         {
           "name": "accordion",
-          "description": "Indica se a lista possui o comportamento de accordion.\nO valor da propriedade define o grupo, ou seja, o accordion é aplicado a todas as listas que possuem o mesmo valor para esta propriedade.",
+          "description": "Título do grupo de accordion. `br-list` irmãs (mesmo elemento-pai) com o\nmesmo valor formam um grupo e mantêm apenas uma aberta por vez — abrir uma\nfecha as demais do grupo.\n\nSozinha já torna a lista recolhível (não precisa de `collapse`) e, como o\n`collapse`, exige um cabeçalho (`header` ou slot `header`) como acionador.\nComeça recolhida.",
           "values": []
         },
         {
           "name": "list-role",
-          "description": "Semântica do host quando o conteúdo não representa itens de lista.",
+          "description": "Semântica do host quando o conteúdo não representa itens de lista. Valores inválidos usam `list`.",
           "values": [{ "name": "list" }, { "name": "group" }]
         },
         {
           "name": "density",
-          "description": "Modificador de densidade da lista.",
+          "description": "Modificador de densidade da lista. Aceita `small`, `medium` ou `large`.\nValores inválidos usam `medium`. Quando omitida ou `null`, nenhuma densidade é aplicada.",
           "values": [
             { "name": "small" },
             { "name": "medium" },
@@ -2246,11 +2274,11 @@
     },
     {
       "name": "br-loading",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/loading?tab=designer).\n---\n\n\n### **Events:**\n - **brLoadingChange** - Notifica mudança de progresso no modo `progress`.\n- **brLoadingComplete** - Notifica conclusão do progresso no modo `progress`.\n- **brLoadingReset** - Notifica reinício do progresso no modo `progress`.\n- **brLoadingCancel** - Notifica clique no botão de cancelamento no modo `progress`.\nEste evento não altera o progresso automaticamente.\nA aplicação consumidora define a ação após o cancelamento (ex.: limpar ou ocultar).\n- **brIndeterminateStateChange** - Notifica mudança do estado lógico no modo `spinner`.\n- **brDidShow** - Notifica que o componente foi exibido.\n- **brLoadingShow** - Evento canônico emitido quando o loading é exibido.\n- **brDidHide** - Notifica que o componente foi ocultado.\n- **brLoadingHide** - Evento canônico emitido quando o loading é ocultado.\n\n### **Methods:**\n - **handleCompletion(newValue: _number_)** - Reage a mudanças em `value` no modo `progress`.\n- **handleModeChange()** - Reage a mudanças em `mode` e atualiza o estado lógico de atividade.\n- **setValue(value: _number_): __** - Define o valor do progresso.\n- **incrementValue(step): __** - Soma um valor ao progresso atual.\n- **complete(): __** - Define o progresso como concluído.\n- **reset(): __** - Reinicia o progresso e exibe o componente.\n- **show(): __** - Exibe o componente.\n- **hide(): __** - Oculta o componente.\n- **render(): __** - Renderiza o componente conforme o modo atual.\n\n### **Slots:**\n - **label** - Rótulo customizado do loading. Quando utilizado, a prop `label` é ignorada.\n- **cancel-button** - Conteúdo customizado do botão de cancelar. Quando utilizado, a prop `cancelLabel` é ignorada.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do loading.\n- **wrapper** - Wrapper do conteúdo do spinner/progress.\n- **svg** - Elemento SVG principal do loading.\n- **percentage** - Texto de percentual no modo `progress`.\n- **label-wrapper** - Wrapper do rótulo no modo `spinner`.\n- **cancel-button** - Botão de cancelamento no modo `progress` cancelável.",
+      "description": "O componente `br-loading` é o indicador de carregamento e progresso do GovBR-DS, utilizado para informar visualmente e de forma acessível que uma operação assíncrona está em execução no sistema.\n\n### Para que serve\n\n- **Feedback de processamento:** Alerta a pessoa usuária de que uma requisição, cálculo ou carregamento de dados está ocorrendo, evitando múltiplos cliques acidentais.\n- **Modo spinner (indeterminado):** Indicador circular contínuo para operações de duração imprevisível.\n- **Modo progress (determinado):** Indicador com percentual explícito (0 a 100%) para downloads, uploads ou tarefas com progresso mensurável, suportando ação de cancelamento.\n- **Acessibilidade para tecnologias assistivas:** Comunica o estado de carregamento através de regiões acessíveis (`aria-live=\"polite\"` e papéis `progressbar` ou `status`).\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Uma operação assíncrona demorar mais de 300 a 500 milissegundos para responder.\n  - Durante o envio de formulários volumosos, processamento de arquivos ou transição de telas pesadas.\n- **Evite e prefira outro componente quando:**\n  - A resposta for quase instantânea (menos de 300ms), para evitar piscamento rápido de tela que cause desconforto visual.\n  - A espera ocorrer dentro de um botão durante o clique (use a prop `loading` do próprio `br-button`).\n\n### Estrutura e Slots\n\nO `br-loading` oferece slots para personalização:\n- `label`: Slot para rótulo ou mensagem descritiva do carregamento (substitui a prop `label`).\n- `cancel-button`: Slot para botão customizado de cancelamento no modo `progress`.\n\nPara 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/loading?tab=designer).\n---\n\n\n### **Events:**\n - **brLoadingChange** - Notifica mudança de progresso no modo `progress`.\n- **brLoadingComplete** - Notifica conclusão do progresso no modo `progress`.\n- **brLoadingReset** - Notifica reinício do progresso no modo `progress`.\n- **brLoadingCancel** - Notifica clique no botão de cancelamento no modo `progress`.\nEste evento não altera o progresso automaticamente.\nA aplicação consumidora define a ação após o cancelamento (ex.: limpar ou ocultar).\n- **brIndeterminateStateChange** - Notifica mudança do estado lógico no modo `spinner`.\n- **brDidShow** - Notifica que o componente foi exibido.\n- **brLoadingShow** - Evento canônico emitido quando o loading é exibido.\n- **brDidHide** - Notifica que o componente foi ocultado.\n- **brLoadingHide** - Evento canônico emitido quando o loading é ocultado.\n\n### **Methods:**\n - **handleCompletion(newValue: _number_)** - Reage a mudanças em `value` no modo `progress`.\n- **handleModeChange()** - Reage a mudanças em `mode` e atualiza o estado lógico de atividade.\n- **setValue(value: _number_): __** - Define o valor do progresso.\n- **incrementValue(step): __** - Soma um valor ao progresso atual.\n- **complete(): __** - Define o progresso como concluído.\n- **reset(): __** - Reinicia o progresso e exibe o componente.\n- **show(): __** - Exibe o componente.\n- **hide(): __** - Oculta o componente.\n- **render(): __** - Renderiza o componente conforme o modo atual.\n\n### **Slots:**\n - **label** - Rótulo customizado do loading. Quando utilizado, a prop `label` é ignorada.\n- **cancel-button** - Conteúdo customizado do botão de cancelar. Quando utilizado, a prop `cancelLabel` é ignorada.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do loading.\n- **wrapper** - Wrapper do conteúdo do spinner/progress.\n- **svg** - Elemento SVG principal do loading.\n- **percentage** - Texto de percentual no modo `progress`.\n- **label-wrapper** - Wrapper do rótulo no modo `spinner`.\n- **cancel-button** - Botão de cancelamento no modo `progress` cancelável.",
       "attributes": [
         {
           "name": "label-position",
-          "description": "Define a posição da label em relação ao loading.",
+          "description": "Define a posição da label em relação ao loading. Valores inválidos usam `bottom`.",
           "values": [{ "name": "LoadingLabelPosition" }]
         },
         {
@@ -2260,7 +2288,7 @@
         },
         {
           "name": "mode",
-          "description": "Define o modo de exibição do componente.",
+          "description": "Define o modo de exibição do componente. Valores inválidos usam `spinner`.",
           "values": [{ "name": "LoadingMode" }]
         },
         {
@@ -2270,7 +2298,7 @@
         },
         {
           "name": "density",
-          "description": "Densidade visual canônica. Quando informada, tem precedência sobre `size`.",
+          "description": "Densidade visual canônica. Quando informada, tem precedência sobre `size`.\nAceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.",
           "values": [{ "name": "LoadingSize" }]
         },
         {
@@ -2280,7 +2308,7 @@
         },
         {
           "name": "speed",
-          "description": "Define a velocidade da animação/transição.",
+          "description": "Define a velocidade da animação/transição. Valores inválidos usam `normal`.",
           "values": [{ "name": "LoadingSpeed" }]
         },
         {
@@ -2290,12 +2318,12 @@
         },
         {
           "name": "value",
-          "description": "Define o progresso no modo `progress`.\nNo modo `spinner`, esta prop não tem efeito.\nValores inválidos são normalizados para `0`.",
+          "description": "Define o progresso no modo `progress`.\nNo modo `spinner`, esta prop não tem efeito.\nValores não numéricos usam `0`; valores fora de `0`–`100` são limitados ao intervalo.",
           "values": []
         },
         {
           "name": "completion",
-          "description": "Define o comportamento quando o progresso atinge 100.\nNo modo `spinner`, esta prop não tem efeito.",
+          "description": "Define o comportamento quando o progresso atinge 100. Valores inválidos usam `persist`.\nNo modo `spinner`, esta prop não tem efeito.",
           "values": [{ "name": "LoadingCompletionBehavior" }]
         },
         {
@@ -2313,7 +2341,7 @@
     },
     {
       "name": "br-magic-button",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/magic-button?tab=designer).\n---\n\n\n### **Methods:**\n - **render()** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Conteúdo interno do botão (texto ou ícone).\n- **icon** - Ícone customizado do botão. Quando utilizado, a prop `icon` é ignorada.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do magic-button.\n- **button** - Elemento button interno.",
+      "description": "O componente `br-magic-button` é o botão de ação flutuante (Floating Action Button - FAB) do GovBR-DS, projetado para destacar a ação primária ou mais relevante da tela, mantendo-se acessível e visível durante a navegação.\n\n### Para que serve\n\n- **Destaque da ação principal:** Cria um ponto focal imediato para a ação central de uma tela (ex.: \"Nova mensagem\", \"Criar solicitação\", \"Adicionar item\").\n- **Posicionamento persistente ou integrado:** Pode ser fixado em um canto da tela (em dispositivos móveis) ou posicionado no fluxo de leitura de painéis e tabelas.\n- **Modos circular e expandido:** Suporta visual circular compacto com ícone ou versão expandida com texto explicativo.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Houver uma única ação dominante que represente o principal objetivo da pessoa usuária naquela tela.\n  - Em aplicações móveis ou responsivas que necessitem de um atalho de fácil alcance para os polegares.\n- **Evite e prefira outro componente quando:**\n  - Houver múltiplas ações de importância equivalente (prefira uma barra de botões com `br-button`).\n  - A ação for secundária, destrutiva ou de cancelamento.\n\n### Estrutura e Slots\n\nO `br-magic-button` é um controle direto:\n- `default`: Slot para rótulo de texto ou conteúdo interno do botão.\n- `icon`: Slot para personalização do ícone de ação (como `br-icon`).\n\nPara 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/magic-button?tab=designer).\n---\n\n\n### **Methods:**\n - **render()** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Conteúdo interno do botão (texto ou ícone).\n- **icon** - Ícone customizado do botão. Quando utilizado, a prop `icon` é ignorada.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do magic-button.\n- **button** - Elemento button interno.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2327,12 +2355,12 @@
         },
         {
           "name": "icon",
-          "description": "Nome do ícone a ser exibido.\nDeve corresponder a um ícone disponível no sistema de ícones.",
+          "description": "Identificador legado do ícone a ser exibido.\nNomes simples (por exemplo, `question`) são resolvidos pelo registro SVG local.\nPara classes CSS ou SVGs personalizados, prefira o slot `icon`.",
           "values": []
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "BrDensity" }]
         },
         {
@@ -2350,7 +2378,7 @@
     },
     {
       "name": "br-menu",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).\n\n### Comportamento de Acionamento Automático\nO menu monitora eventos de clique globais no documento. Qualquer elemento que possua o atributo `data-toggle=\"menu\"`\ne cujo `data-target` coincida com o ID ou `customId` do menu (ou seja omitido) irá alternar automaticamente o estado do menu (`isOpen`).\n---\n\n\n### **Events:**\n - **brMenuStateChange** - Evento emitido quando o menu abre ou fecha.\n- **brMenuOpenChange** - Evento canônico emitido quando o menu abre ou fecha.\n`detail.open` contém o estado concluído e `detail.sourceId` identifica a instância pelo `id` ou `customId`.\n\n### **Methods:**\n - **onDocumentClick(ev: _MouseEvent_)** - Escuta cliques no documento para alternar o estado do menu automaticamente\nquando um elemento com o atributo `data-toggle=\"menu\"` é clicado.\nUtiliza o caminho completo do evento (composedPath) para permitir o funcionamento\ncorreto quando o botão acionador está dentro de outros componentes com Shadow DOM (ex: br-header).\n- **open(): _Promise<void>_** - Abre o painel do menu.\nPode ser chamado externamente: `menuEl.open()`.\n- **close(): _Promise<void>_** - Fecha o painel do menu.\nPode ser chamado externamente: `menuEl.close()`.\n- **toggle(): _Promise<void>_** - Alterna o estado do painel do menu (abre se fechado, fecha se aberto).\nPode ser chamado externamente: `menuEl.toggle()`.\n\n### **Slots:**\n - **default** - Slot para o conteúdo principal do menu (menu-list, menu-group e menu-item).\n- **header** - Slot para o cabeçalho do menu, exibido apenas em modo não contextual e não push.\n- **logo** - Slot para logotipos de parceiros no rodapé.\n- **link** - Slot para links externos no rodapé (use br-menu-link).\n- **social** - Slot para ícones de redes sociais no rodapé.\n- **info** - Slot para informações adicionais no rodapé.\n\n### **CSS Parts:**\n - **footer** - Parte para o contêiner principal do rodapé do menu, agrupando logos, links, redes sociais e informações.\n- **logo** - Parte para a área de logotipos de parceiros no rodapé.\n- **link** - Parte para links úteis ou navegação secundária no rodapé.\n- **social** - Parte para ícones de redes sociais no rodapé.\n- **info** - Parte para informações adicionais, como licença ou direitos autorais.\n- **container** - Parte para o container externo que envolve o menu inteiro.\n- **panel** - Parte para o painel de navegação do menu (o menu propriamente dito).\n- **body** - Parte principal onde ficam os links e grupos de navegação.\n- **trigger** - Botão de acionamento do menu (hambúrguer ou contextual).\n- **back-btn** - Botão de voltar do menu de navegação drill-down.",
+      "description": "O componente `br-menu` é o orquestrador completo de navegação lateral (drawer/sidebar) do GovBR-DS. Estrutura a navegação multinível de portais e sistemas públicos, oferecendo suporte a hierarquias em árvore, agrupamentos, busca interna, informações do usuário e canais sociais.\n\n### Para que serve\n\n- **Navegação estruturada em árvore:** Permite navegar por hierarquias profundas de seções e subsistemas governamentais.\n- **Modos responsivos:** Suporta exibição fixa/lateral no desktop e painel retrátil suspenso com cortina de fundo (`br-scrim`) em telas mobile.\n- **Acessibilidade completa:** Gerencia controle de foco por teclado, armadilha de foco (trap focus) quando aberto e atributos WAI-ARIA (`aria-expanded`, `role=\"dialog\"` ou `role=\"navigation\"`).\n- **Navegação multinível fluida:** Oferece transições suaves entre níveis hierárquicos com botões de retorno ao nível anterior.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A aplicação ou portal exigir uma estrutura de navegação lateral abrangente, com menus de múltiplos níveis e categorias.\n  - Houver necessidade de um menu que possa ser recolhido ou deslizado em dispositivos móveis com controle de foco integrado.\n- **Evite e prefira outro componente quando:**\n  - A navegação tiver poucos itens e puder ser acomodada confortavelmente apenas no cabeçalho (prefira `br-header`).\n  - O objetivo for alternar visualizações na mesma tela de forma plana (prefira `br-tab`).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-menu` | **Orquestrador principal.** Gerencia estado aberto/fechado, navegação multinível, scrim e armadilha de foco. | Deve ser declarado como contêiner principal da navegação lateral. |\n| `br-menu-header` | **Cabeçalho do menu.** Exibe título e botão de fechar o painel. | Inserido no topo do `br-menu`. |\n| `br-menu-group` | **Agrupador temático.** Agrupa itens sob um subtítulo de seção. | Inserido no corpo de navegação do `br-menu`. |\n| `br-menu-list` | **Lista de opções.** Estrutura semântica de lista contendo itens navegáveis. | Inserido no `br-menu` ou dentro de um `br-menu-group`. |\n| `br-menu-item` | **Item de menu.** Opção clicável de rota ou gatilho para submenu. | Deve ser utilizado dentro de um `br-menu-list`. |\n| `br-menu-link` | **Hiperlink.** Link textual padronizado no menu. | Inserido dentro de `br-menu-item` ou seções de apoio. |\n| `br-menu-info` | **Informações de apoio.** Exibe dados de sessão, versão ou contexto do sistema. | Posicionado na base ou topo do `br-menu`. |\n| `br-menu-logo` | **Logotipo.** Exibe a marca do órgão no interior do menu. | Posicionado no cabeçalho ou topo do `br-menu`. |\n| `br-menu-social` | **Redes sociais.** Bloco de canais sociais oficiais no menu. | Posicionado preferencialmente no rodapé do `br-menu`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-menu` atua como o orquestrador soberano da navegação. Ele controla a transição de visibilidade, a ativação do scrim de fundo e o comportamento dos subníveis. Ao navegar entre níveis, os itens (`br-menu-item`) comunicam suas seleções ao `br-menu`, que desliza os painéis correspondentes e mantém a ordem correta de tabulação do teclado.\n\nPara 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/menu?tab=designer).\n---\n\n\n### **Events:**\n - **brMenuStateChange** - Evento emitido quando o menu abre ou fecha.\n- **brMenuOpenChange** - Evento canônico emitido quando o menu abre ou fecha.\n`detail.open` contém o estado concluído e `detail.sourceId` identifica a instância pelo `id` ou `customId`.\n\n### **Methods:**\n - **onDocumentClick(ev: _MouseEvent_)** - Escuta cliques no documento para alternar o estado do menu automaticamente\nquando um elemento com o atributo `data-toggle=\"menu\"` é clicado.\nUtiliza o caminho completo do evento (composedPath) para permitir o funcionamento\ncorreto quando o botão acionador está dentro de outros componentes com Shadow DOM (ex: br-header).\n- **open(): _Promise<void>_** - Abre o painel do menu.\nPode ser chamado externamente: `menuEl.open()`.\n- **close(): _Promise<void>_** - Fecha o painel do menu.\nPode ser chamado externamente: `menuEl.close()`.\n- **toggle(): _Promise<void>_** - Alterna o estado do painel do menu (abre se fechado, fecha se aberto).\nPode ser chamado externamente: `menuEl.toggle()`.\n\n### **Slots:**\n - **default** - Slot para o conteúdo principal do menu (menu-list, menu-group e menu-item).\n- **header** - Slot para o cabeçalho do menu, exibido apenas em modo não contextual e não push.\n- **logo** - Slot para logotipos de parceiros no rodapé.\n- **link** - Slot para links externos no rodapé (use br-menu-link).\n- **social** - Slot para ícones de redes sociais no rodapé.\n- **info** - Slot para informações adicionais no rodapé.\n\n### **CSS Parts:**\n - **footer** - Parte para o contêiner principal do rodapé do menu, agrupando logos, links, redes sociais e informações.\n- **logo** - Parte para a área de logotipos de parceiros no rodapé.\n- **link** - Parte para links úteis ou navegação secundária no rodapé.\n- **social** - Parte para ícones de redes sociais no rodapé.\n- **info** - Parte para informações adicionais, como licença ou direitos autorais.\n- **container** - Parte para o container externo que envolve o menu inteiro.\n- **panel** - Parte para o painel de navegação do menu (o menu propriamente dito).\n- **body** - Parte principal onde ficam os links e grupos de navegação.\n- **trigger** - Botão de acionamento do menu (hambúrguer ou contextual).\n- **back-btn** - Botão de voltar do menu de navegação drill-down.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2359,7 +2387,7 @@
         },
         {
           "name": "breakpoints",
-          "description": "Classes CSS para definir breakpoints responsivos do menu.\nUtilize esta propriedade para controlar a largura do menu em diferentes tamanhos de tela.\nPor padrão não aplica colunas; quando contextual e sem valor definido, usa `col-sm-4 col-lg-3`.",
+          "description": "Classes de coluna do grid GovBR para definir a largura responsiva do painel sobreposto.\nExemplo: `col-sm-4 col-lg-3`. Os modos `push`, `fixed` e `contextual` não usam esta propriedade.\nQuando vazia, o painel ocupa a largura disponível.",
           "values": []
         },
         {
@@ -2384,7 +2412,7 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade dos itens do menu, alterando o espaçamento interno.\n- `small` (densidade alta): itens mais compactos\n- `medium` (padrão): equilíbrio entre economia de espaço e separação\n- `large` (densidade baixa): maior espaçamento (recomendado em touch)",
+          "description": "Define a densidade dos itens do menu, alterando o espaçamento interno.\n- `small` (densidade alta): itens mais compactos\n- `medium` (padrão): equilíbrio entre economia de espaço e separação\n- `large` (densidade baixa): maior espaçamento (recomendado em touch)\nValores inválidos usam `medium`.",
           "values": [{ "name": "MenuDensity" }]
         },
         {
@@ -2402,7 +2430,7 @@
     },
     {
       "name": "br-menu-group",
-      "description": "Agrupamento visual não interativo para itens de menu.\n---\n\n\n### **Slots:**\n - **default** - Itens do grupo.\n\n### **CSS Parts:**\n - **container** - Contêiner do agrupamento.\n- **label** - Rótulo visual do agrupamento.\n- **list** - Contêiner dos itens agrupados.",
+      "description": "O componente `br-menu-group` é o subcomponente do GovBR-DS que divide os itens de navegação em blocos ou agrupamentos temáticos com subtítulos.\n\n### Para que serve\n\n- **Segmentação visual:** Separa blocos de links afins para facilitar a leitura.\n- **Hierarquia clara:** Estabelece grupos com rótulos descritivos.\n\n### Papel na composição\n\nAtua como agrupador intermediário dentro do corpo do `br-menu`.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado no interior do componente `br-menu`.\n- Contém instâncias de `br-menu-list` ou `br-menu-item`.\n---\n\n\n### **Slots:**\n - **default** - Itens do grupo.\n\n### **CSS Parts:**\n - **container** - Contêiner do agrupamento.\n- **label** - Rótulo visual do agrupamento.\n- **list** - Contêiner dos itens agrupados.",
       "attributes": [
         {
           "name": "label",
@@ -2419,7 +2447,7 @@
     },
     {
       "name": "br-menu-header",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu-header?tab=designer).\n---\n\n\n### **Events:**\n - **brMenuToggle** - Evento emitido para alternar o estado do menu\n\n### **Slots:**\n - **logo** - Slot para logo personalizado no cabeçalho.\n- **signature** - Slot para a assinatura personalizada do sistema.\n\n### **CSS Parts:**\n - **container** - Wrapper do cabeçalho do menu.\n- **title** - Área do título com logo e assinatura.\n- **close** - Área do botão de fechar.\n- **logo** - Elemento de imagem do logotipo (se renderizado a partir de logoSrc).\n- **signature** - Elemento de texto contendo a assinatura do sistema.",
+      "description": "O componente `br-menu-header` é o subcomponente do GovBR-DS que fornece o cabeçalho superior do menu lateral, contendo o título da área e o botão de fechamento.\n\n### Para que serve\n\n- **Identificação da navegação:** Exibe o título do menu ou seção atual.\n- **Controle de fechamento:** Fornece o botão de fechar acessível que recolhe o menu.\n\n### Papel na composição\n\nAtua como cabeçalho funcional e acessível no topo do `br-menu`.\n\n### Regra de uso e relacionamento\n\n- Deve ser posicionado no início do orquestrador `br-menu`.\n- Dispara a ação de fechamento gerenciada pelo componente pai.\n---\n\n\n### **Events:**\n - **brMenuToggle** - Evento emitido para alternar o estado do menu\n\n### **Slots:**\n - **logo** - Slot para logo personalizado no cabeçalho.\n- **signature** - Slot para a assinatura personalizada do sistema.\n\n### **CSS Parts:**\n - **container** - Wrapper do cabeçalho do menu.\n- **title** - Área do título com logo e assinatura.\n- **close** - Área do botão de fechar.\n- **logo** - Elemento de imagem do logotipo (se renderizado a partir de logoSrc).\n- **signature** - Elemento de texto contendo a assinatura do sistema.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2446,7 +2474,7 @@
     },
     {
       "name": "br-menu-info",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu-info?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para conteúdo personalizado no lugar do texto padrão de informações.",
+      "description": "O componente `br-menu-info` é o subcomponente do GovBR-DS destinado a exibir textos informativos, versão do sistema, status da aplicação ou informações de usuário no menu.\n\n### Para que serve\n\n- **Informações contextuais:** Apresenta dados de apoio ao usuário sem poluir o fluxo de links.\n\n### Papel na composição\n\nAtua como área informativa complementar no menu.\n\n### Regra de uso e relacionamento\n\n- Posiciona-se geralmente no rodapé ou na área superior do `br-menu`.\n---\n\n\n### **Slots:**\n - **default** - Slot para conteúdo personalizado no lugar do texto padrão de informações.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2463,11 +2491,11 @@
     },
     {
       "name": "br-menu-item",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **default** - Conteúdo textual principal exibido no item de menu.\n- **icon** - Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`.\n\n### **CSS Parts:**\n - **link** - Elemento âncora do item de menu.\n- **icon** - Ícone do item de menu.\n- **content** - Conteúdo textual do item de menu.\n- **support** - Ícone de suporte (seta para baixo/direita).",
+      "description": "O componente `br-menu-item` é o subcomponente interativo do GovBR-DS que representa uma opção de navegação ou gatilho para submenu na árvore de menu.\n\n### Para que serve\n\n- **Opção de rota ou submenu:** Funciona como link direto para uma página ou como nó que abre um próximo nível hierárquico.\n- **Estados visuais de navegação:** Reflete estados ativo, focado, hover e selecionado.\n\n### Papel na composição\n\nAtua como item interativo central da navegação.\n\n### Regra de uso e relacionamento\n\n- Deve ser utilizado exclusivamente dentro de um `br-menu-list`.\n- Quando contiver subníveis, comunica-se com o orquestrador `br-menu` para ativar a transição entre telas.\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **default** - Conteúdo textual principal exibido no item de menu.\n- **icon** - Ícone personalizado. Quando preenchido, substitui o ícone definido por `icon`.\n\n### **CSS Parts:**\n - **link** - Elemento âncora do item de menu.\n- **icon** - Ícone do item de menu.\n- **content** - Conteúdo textual do item de menu.\n- **support** - Ícone de suporte (seta para baixo/direita).",
       "attributes": [
         {
           "name": "icon",
-          "description": "Ícone exibido no item do menu.\nUtilize esta propriedade para definir o ícone que será mostrado ao lado do conteúdo do item.",
+          "description": "Identificador legado do ícone exibido no item do menu.\nNomes simples conhecidos são resolvidos pelo registro SVG local; para\nclasses CSS, SVGs ou bibliotecas externas, prefira o slot `icon`.",
           "values": []
         },
         {
@@ -2477,7 +2505,7 @@
         },
         {
           "name": "target",
-          "description": "Define como o link será aberto.\n- `_self`: abre no mesmo contexto de navegação (padrão)\n- `_blank`: abre em nova aba ou janela\n- `_parent`: abre no contexto pai\n- `_top`: abre no contexto de nível superior",
+          "description": "Define como o link será aberto.\n- `_self`: abre no mesmo contexto de navegação (padrão)\n- `_blank`: abre em nova aba ou janela\n- `_parent`: abre no contexto pai\n- `_top`: abre no contexto de nível superior\nValores inválidos usam `_self`.",
           "values": [{ "name": "BrLinkTarget" }]
         },
         {
@@ -2492,7 +2520,7 @@
         },
         {
           "name": "display-mode",
-          "description": "Define o modo de exibição do item, controlando os ícones de expansão.\n- `accordion`: exibe setas para cima/baixo (usado em menus de nível 0).\n- `drill-down`: exibe seta para a direita (usado em menus de níveis 1+).\n- `none`: não exibe ícones de expansão.",
+          "description": "Define o modo de exibição do item, controlando os ícones de expansão.\n- `accordion`: exibe setas para cima/baixo (usado em menus de nível 0).\n- `drill-down`: exibe seta para a direita (usado em menus de níveis 1+).\n- `none`: não exibe ícones de expansão.\nValores inválidos usam `none`.",
           "values": [{ "name": "MenuItemDisplayMode" }]
         },
         {
@@ -2502,7 +2530,7 @@
         },
         {
           "name": "navigation-mode",
-          "description": "Controla como o componente integra a navegação mantendo `href` real no elemento navegável.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.",
+          "description": "Controla como o componente integra a navegação mantendo `href` real no elemento navegável.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.\nValores inválidos usam `native`.",
           "values": [{ "name": "BrNavigationMode" }]
         }
       ],
@@ -2510,7 +2538,7 @@
     },
     {
       "name": "br-menu-link",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).\n---\n\n\n### **Events:**\n - **brLinkClick** - Evento emitido quando o link externo é clicado.\n- **brMenuLinkClick** - Evento canônico emitido quando o link externo é clicado.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **icon** - Slot para ícone personalizado do link.\n- **url** - Slot para o texto exibido no link.\n\n### **CSS Parts:**\n - **link** - Elemento âncora do link.",
+      "description": "O componente `br-menu-link` é o subcomponente do GovBR-DS que renderiza um hiperlink textual acessível dentro da estrutura de menu.\n\n### Para que serve\n\n- **Navegação direta:** Oferece link textual para destinos internos ou externos.\n- **Estilo GovBR-DS:** Aplica a tipografia e cores padronizadas de links de menu.\n\n### Papel na composição\n\nAtua como elemento folha de navegação.\n\n### Regra de uso e relacionamento\n\n- Utilizado dentro de `br-menu-item` ou seções de apoio do `br-menu`.\n---\n\n\n### **Events:**\n - **brLinkClick** - Evento emitido quando o link externo é clicado.\n- **brMenuLinkClick** - Evento canônico emitido quando o link externo é clicado.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **icon** - Slot para ícone personalizado do link.\n- **url** - Slot para o texto exibido no link.\n\n### **CSS Parts:**\n - **link** - Elemento âncora do link.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2539,11 +2567,11 @@
     },
     {
       "name": "br-menu-list",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).\n---\n\n\n### **Events:**\n - **folderToggled** - Emitido quando um folder é expandido ou recolhido no nível 0 (comportamento acordeão).\n- **navigateToSubmenu** - Emitido quando navegando para um submenu nos níveis 1+ (comportamento drill-down).\n\n### **Slots:**\n - **default** - Itens filhos renderizados no conteúdo do grupo.\n- **icon** - Ícone personalizado do item principal. Quando preenchido, substitui `icon`.\n\n### **CSS Parts:**\n - **container** - Wrapper do grupo de menu.\n- **list** - Lista de itens do grupo.\n- **header-link** - Elemento âncora do item de menu principal (header).\n- **header-icon** - Ícone do item de menu principal (header).\n- **header-content** - Conteúdo textual do item de menu principal (header).\n- **header-support** - Ícone de suporte (seta) do item de menu principal (header).",
+      "description": "O componente `br-menu-list` é o subcomponente do GovBR-DS que fornece a estrutura semântica de lista de navegação para acomodar os itens interativos do menu.\n\n### Para que serve\n\n- **Semântica de lista:** Garante marcação acessível (`<ul>`) para tecnologias assistivas.\n- **Alinhamento e ordenação:** Organiza os itens verticalmente com espaçamentos padronizados.\n\n### Papel na composição\n\nAtua como contêiner semântico de itens dentro de `br-menu` ou `br-menu-group`.\n\n### Regra de uso e relacionamento\n\n- Deve ser inserido no interior de `br-menu` ou `br-menu-group`.\n- Acomoda múltiplos subcomponentes `br-menu-item`.\n---\n\n\n### **Events:**\n - **folderToggled** - Emitido quando um folder é expandido ou recolhido no nível 0 (comportamento acordeão).\n- **navigateToSubmenu** - Emitido quando navegando para um submenu nos níveis 1+ (comportamento drill-down).\n\n### **Slots:**\n - **default** - Itens filhos renderizados no conteúdo do grupo.\n- **icon** - Ícone personalizado do item principal. Quando preenchido, substitui `icon`.\n\n### **CSS Parts:**\n - **container** - Wrapper do grupo de menu.\n- **list** - Lista de itens do grupo.\n- **header-link** - Elemento âncora do item de menu principal (header).\n- **header-icon** - Ícone do item de menu principal (header).\n- **header-content** - Conteúdo textual do item de menu principal (header).\n- **header-support** - Ícone de suporte (seta) do item de menu principal (header).",
       "attributes": [
         {
           "name": "icon",
-          "description": "Ícone exibido no item do menu.\nUtilize esta propriedade para definir o ícone que será mostrado ao lado do label.",
+          "description": "Identificador legado do ícone exibido no item principal do menu.\nNomes simples conhecidos são resolvidos pelo registro SVG local; para\nclasses CSS, SVGs ou bibliotecas externas, prefira o slot `icon`.",
           "values": []
         },
         {
@@ -2571,7 +2599,7 @@
     },
     {
       "name": "br-menu-logo",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).\n---\n\n\n### **Events:**\n - **brMenuLogoError** - Emitido quando a imagem principal e o fallback falham.\n- **brMenuLogoError**\n\n### **Slots:**\n - **default** - Slot para logo ou conteúdo que substitui a imagem padrão.\n\n### **CSS Parts:**\n - **container** - Wrapper da logo.",
+      "description": "O componente `br-menu-logo` é o subcomponente do GovBR-DS que renderiza a logomarca do sistema ou do Governo Federal no menu lateral.\n\n### Para que serve\n\n- **Identidade no menu:** Reforça a marca da aplicação na navegação lateral móvel ou desktop.\n\n### Papel na composição\n\nAtua como identificador visual institucional no menu.\n\n### Regra de uso e relacionamento\n\n- Posiciona-se preferencialmente no topo ou no cabeçalho do `br-menu`.\n---\n\n\n### **Events:**\n - **brMenuLogoError** - Emitido quando a imagem principal e o fallback falham.\n- **brMenuLogoError**\n\n### **Slots:**\n - **default** - Slot para logo ou conteúdo que substitui a imagem padrão.\n\n### **CSS Parts:**\n - **container** - Wrapper da logo.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2604,7 +2632,7 @@
     },
     {
       "name": "br-menu-social",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/menu?tab=designer).\n---\n\n\n### **Events:**\n - **brSocialClick** - Evento emitido quando o link de rede social é clicado.\n- **brMenuSocialClick** - Evento canônico emitido quando o link de rede social é clicado.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **icon** - Slot para ícone personalizado da rede social.",
+      "description": "O componente `br-menu-social` é o subcomponente do GovBR-DS que reúne atalhos para os canais de redes sociais institucionais no interior do menu.\n\n### Para que serve\n\n- **Acesso rápido a mídias:** Permite que o cidadão acesse perfis institucionais a partir da gaveta de navegação.\n\n### Papel na composição\n\nAtua como bloco de engajamento social no menu.\n\n### Regra de uso e relacionamento\n\n- Posiciona-se preferencialmente na base ou rodapé interno do `br-menu`.\n---\n\n\n### **Events:**\n - **brSocialClick** - Evento emitido quando o link de rede social é clicado.\n- **brMenuSocialClick** - Evento canônico emitido quando o link de rede social é clicado.\n- **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **icon** - Slot para ícone personalizado da rede social.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2614,12 +2642,12 @@
         { "name": "href", "description": "URL do link.", "values": [] },
         {
           "name": "target",
-          "description": "Target do link quando href é fornecido.",
+          "description": "Target do link quando href é fornecido.\nAceita `_self`, `_blank`, `_parent` ou `_top`. Valores inválidos usam `_self`.",
           "values": [{ "name": "BrLinkTarget" }]
         },
         {
           "name": "navigation-mode",
-          "description": "Controla como o componente integra a navegação mantendo `href` real no elemento navegável.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.",
+          "description": "Controla como o componente integra a navegação mantendo `href` real no elemento navegável.\n- `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.\nCliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.\nValores inválidos usam `native`.",
           "values": [{ "name": "BrNavigationMode" }]
         },
         {
@@ -2627,13 +2655,17 @@
           "description": "Define o rótulo acessível usado por tecnologias assistivas.",
           "values": []
         },
-        { "name": "icon", "description": "Ícone da rede social", "values": [] }
+        {
+          "name": "icon",
+          "description": "Identificador da rede social. Os ícones oficiais mais comuns são\nrenderizados pelo registro SVG local; use o slot `icon` para uma fonte\ndiferente ou uma classe Font Awesome personalizada.",
+          "values": []
+        }
       ],
       "references": []
     },
     {
       "name": "br-message",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/message?tab=designer).\n---\n\n\n### **Events:**\n - **brDidClose** - Evento emitido quando o usuário fecha a mensagem, se closable for true.\n- **brMessageClose** - Evento canônico emitido quando a mensagem é fechada.\n\n### **Slots:**\n - **default** - Conteúdo principal da mensagem. Quando utilizado, a prop `message` é ignorada.\n- **icon** - Ícone customizado da mensagem. Quando utilizado, o ícone padrão gerado pela prop `state` é ignorado.\n- **message-title** - Título customizado da mensagem. Quando utilizado, a prop `messageTitle` é ignorada.\n- **message-body** - Corpo customizado da mensagem. Quando utilizado, a prop `message` é ignorada.\n- **close-button** - Botão de fechar customizado. Quando utilizado, o botão padrão é substituído.\n\n### **CSS Parts:**\n - **container** - Wrapper principal da mensagem.\n- **icon** - Área do ícone da mensagem.\n- **content** - Área de conteúdo da mensagem.\n- **close** - Área do botão de fechar.",
+      "description": "O componente `br-message` é a superfície de feedback contextual e notificação em linha do GovBR-DS, utilizada para comunicar mensagens de sucesso, informação, alerta ou erro diretamente associadas à tela ou a um formulário.\n\n### Para que serve\n\n- **Comunicação de estados do sistema:** Exibe mensagens com cores, ícones e semânticas padronizadas: `success` (sucesso), `info` (informação), `warning` (aviso) e `danger` (erro).\n- **Validação de formulários:** Atua como o contêiner oficial de mensagem de erro e orientação nos slots `feedback` de componentes de formulário (como `br-input`, `br-select` e `br-checkbox`).\n- **Opção de fechamento:** Suporta botão de dispensa (`closable`), permitindo que a pessoa usuária feche a notificação após a leitura.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - For necessário dar feedback sobre uma ação recém-executada (ex.: \"Dados salvos com sucesso\").\n  - Houver orientações contextuais ou erros de validação em campos de formulário.\n- **Evite e prefira outro componente quando:**\n  - A mensagem for crítica e exigir confirmação bloqueadora antes de continuar (prefira `br-modal`).\n  - As notificações forem assíncronas do sistema e acumuladas em uma central de mensagens (prefira `br-notification`).\n\n### Estrutura e Slots\n\nO `br-message` oferece personalização modular:\n- `message-title`: Slot para título de destaque da mensagem.\n- `message-body`: Slot para o corpo detalhado do texto.\n- `icon`: Slot para substituição do ícone contextual padrão.\n- `close-button`: Slot para botão de fechar customizado.\n- `default`: Slot livre para renderização direta do conteúdo.\n\nPara 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/message?tab=designer).\n---\n\n\n### **Events:**\n - **brDidClose** - Evento emitido quando o usuário fecha a mensagem, se closable for true.\n- **brMessageClose** - Evento canônico emitido quando a mensagem é fechada.\n\n### **Slots:**\n - **default** - Conteúdo principal da mensagem. Quando utilizado, a prop `message` é ignorada.\n- **icon** - Ícone customizado da mensagem. Quando utilizado, o ícone padrão gerado pela prop `state` é ignorado.\n- **message-title** - Título customizado da mensagem. Quando utilizado, a prop `messageTitle` é ignorada.\n- **message-body** - Corpo customizado da mensagem. Quando utilizado, a prop `message` é ignorada.\n- **close-button** - Botão de fechar customizado. Quando utilizado, o botão padrão é substituído.\n\n### **CSS Parts:**\n - **container** - Wrapper principal da mensagem.\n- **icon** - Área do ícone da mensagem.\n- **content** - Área de conteúdo da mensagem.\n- **close** - Área do botão de fechar.",
       "attributes": [
         {
           "name": "message-title",
@@ -2692,7 +2724,7 @@
         },
         {
           "name": "state",
-          "description": "Define o estado do message.\nOs possíveis valores são:\n- 'info': Mensagem informativa.\n- 'warning': Mensagem de aviso.\n- 'danger': Mensagem de erro ou alerta.\n- 'success': Mensagem de sucesso.\nO valor padrão é 'info'.",
+          "description": "Define o estado do message. Valores inválidos usam `info`.\nOs possíveis valores são:\n- 'info': Mensagem informativa.\n- 'warning': Mensagem de aviso.\n- 'danger': Mensagem de erro ou alerta.\n- 'success': Mensagem de sucesso.\nO valor padrão é 'info'.",
           "values": [{ "name": "BrFeedbackState" }]
         },
         {
@@ -2710,7 +2742,7 @@
     },
     {
       "name": "br-modal",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/modal?tab=designer).\n---\n\n\n### **Events:**\n - **brModalOpen** - Evento emitido quando o modal é aberto (quando `show` muda de `false` para `true`).\n- **brModalClose** - Evento emitido após o modal ser fechado (quando `show` muda de `true` para `false`).\n- **brModalBeforeClose** - Evento emitido antes do fechamento do modal (quando o botão X é clicado).\nSe autoClose está desativado, o desenvolvedor deve fechar manualmente o modal após este evento.\nSe autoClose está ativado, o modal fecha automaticamente após este evento.\n- **brModalOpened** - Evento emitido após o modal estar completamente aberto e com o foco estabilizado\ndentro dele. Complementa `brModalOpen` (que dispara imediatamente ao abrir):\nuse `brModalOpened` quando precisar interagir com o modal já pronto.\n\n### **Methods:**\n - **open()** - Método público para abrir o modal\n- **showModal(): _Promise<void>_** - Abre o modal usando a nomenclatura de `HTMLDialogElement`.\n- **close()** - Método público para fechar o modal\n- **requestClose(): _Promise<void>_** - Solicita fechamento e permite cancelamento pelo evento `cancel`.\n- **toggle()** - Método público para alternar a visibilidade do modal\n\n### **Slots:**\n - **header** - Cabeçalho do modal. Se não for usado, o `title-text` será exibido.\n- **default** - Corpo do modal.\n- **footer** - Rodapé do modal.\n- **close-button** - Botão de fechar customizado. Se não for usado, o botão padrão será exibido.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do modal.\n- **header** - Cabeçalho do modal.\n- **title** - Título do modal.\n- **body** - Corpo do modal.\n- **footer** - Rodapé do modal.\n- **close-button** - Botão de fechar do modal.",
+      "description": "O componente `br-modal` é a caixa de diálogo bloqueadora (dialog modal) do GovBR-DS, desenvolvida para capturar o foco e exigir a atenção imediata da pessoa usuária antes de permitir o retorno ao fluxo de trabalho normal.\n\n### Para que serve\n\n- **Confirmação de ações críticas:** Solicita confirmação explícita para ações irreversíveis ou de grande impacto (ex.: excluir registro, cancelar processo em andamento).\n- **Entrada de dados pontual:** Permite preencher formulários breves e contextuais sem sair da tela principal.\n- **Gestão de foco e acessibilidade WAI-ARIA:** Bloqueia o foco dentro do diálogo (`focus trap`), impede a rolagem do fundo, aplica `aria-modal=\"true\"` e fecha com a tecla Escape ou clique externo.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A decisão for estritamente obrigatória e a continuação sem ela puder causar perda de dados ou inconsistência.\n  - Apresentar detalhes suplementares que requerem fechamento explícito.\n- **Evite e prefira outro componente quando:**\n  - A mensagem for informativa e não exigir ação imediata (prefira `br-message`).\n  - O conteúdo for extenso, demandando navegação complexa (prefira uma nova página dedicada).\n\n### Estrutura e Slots\n\nO `br-modal` organiza o diálogo em regiões padronizadas:\n- `header`: Slot para cabeçalho e título (substitui a prop `title-text`).\n- `default`: Slot principal onde é inserido o corpo de texto ou formulário do modal.\n- `footer`: Slot para ações de rodapé (botões de confirmação, envio e cancelamento com `br-button`).\n- `close-button`: Slot para personalizar o botão de fechar do canto superior.\n\nPara 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/modal?tab=designer).\n---\n\n\n### **Events:**\n - **brModalOpen** - Evento emitido quando o modal é aberto (quando `show` muda de `false` para `true`).\n- **brModalClose** - Evento emitido após o modal ser fechado (quando `show` muda de `true` para `false`).\n- **brModalBeforeClose** - Evento emitido antes do fechamento do modal (quando o botão X é clicado).\nSe autoClose está desativado, o desenvolvedor deve fechar manualmente o modal após este evento.\nSe autoClose está ativado, o modal fecha automaticamente após este evento.\n- **brModalOpened** - Evento emitido após o modal estar completamente aberto e com o foco estabilizado\ndentro dele. Complementa `brModalOpen` (que dispara imediatamente ao abrir):\nuse `brModalOpened` quando precisar interagir com o modal já pronto.\n\n### **Methods:**\n - **open()** - Método público para abrir o modal\n- **showModal(): _Promise<void>_** - Abre o modal usando a nomenclatura de `HTMLDialogElement`.\n- **close()** - Método público para fechar o modal\n- **requestClose(): _Promise<void>_** - Solicita fechamento e permite cancelamento pelo evento `cancel`.\n- **toggle()** - Método público para alternar a visibilidade do modal\n\n### **Slots:**\n - **header** - Cabeçalho do modal. Se não for usado, o `title-text` será exibido.\n- **default** - Corpo do modal.\n- **footer** - Rodapé do modal.\n- **close-button** - Botão de fechar customizado. Se não for usado, o botão padrão será exibido.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do modal.\n- **header** - Cabeçalho do modal.\n- **title** - Título do modal.\n- **body** - Corpo do modal.\n- **footer** - Rodapé do modal.\n- **close-button** - Botão de fechar do modal.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2739,7 +2771,7 @@
         },
         {
           "name": "size",
-          "description": "Define o tamanho (largura) do modal.",
+          "description": "Define o tamanho (largura) do modal. Valores inválidos usam `medium`.",
           "values": [{ "name": "ModalSize" }]
         },
         {
@@ -2749,7 +2781,7 @@
         },
         {
           "name": "align-footer",
-          "description": "Define o alinhamento do conteúdo do rodapé (slot=\"footer\").",
+          "description": "Define o alinhamento do conteúdo do rodapé (slot=\"footer\"). Valores inválidos usam `center`.",
           "values": [{ "name": "ModalFooterAlign" }]
         }
       ],
@@ -2757,7 +2789,7 @@
     },
     {
       "name": "br-notification",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais,\nconsulte o [Design System do GovBR](https://www.gov.br/ds/components/notification?tab=designer).\n---\n\n\n### **Events:**\n - **brOpenChange** - Informa a mudança de estado aberto/fechado do painel.\n- **brNotificationOpen** - Informa que o painel foi aberto.\n- **brNotificationClose** - Informa que o painel foi fechado.\n- **brNotificationItemClick** - Expõe a interação com um item da lista.\n- **brNotificationTabChange** - Informa troca de aba quando o componente possuir navegação por tabs.\n\n### **Methods:**\n - **show()** - Abre o painel de notificações.\n- **hide(reason: _NotificationCloseReason_)** - Fecha o painel de notificações.\n- **toggle()** - Alterna o estado aberto/fechado.\n- **focusTrigger()** - Move o foco de volta para o acionador.\n- **focusFirstItem()** - Move o foco para o primeiro item interativo da lista.\n\n### **Slots:**\n - **trigger** - Elemento acionador externo responsável por abrir e fechar o painel.\n- **header** - Região superior do componente, para uso com subcomponentes de cabeçalho ou conteúdo customizado.\n- **tabs** - Região opcional para navegação por abas.\n- **default** - Região principal da lista de notificações.\n- **footer** - Região opcional para ações complementares, como \"ver todas\".\n\n### **CSS Parts:**\n - **base** - Superfície principal do painel.\n- **header** - Região superior do componente.\n- **body** - Região principal do componente.\n- **tabs** - Região de abas, quando existir.\n- **list** - Região com rolagem onde os itens são exibidos.\n- **close-button** - Botão de fechar do painel.\n- **divider** - Divisor entre itens da lista.",
+      "description": "O componente `br-notification` é o painel oficial do GovBR-DS para centralização e exibição de avisos, comunicados e notificações do sistema, tipicamente acionado a partir de um botão com ícone de sino no cabeçalho.\n\n### Para que serve\n\n- **Central de notificações do usuário:** Reúne em uma única gaveta ou painel suspenso todas as mensagens, lembretes e alertas direcionados à pessoa usuária.\n- **Estruturação por abas e contexto:** Permite organizar notificações por abas (ex.: \"Todas\", \"Não lidas\", \"Arquivadas\") com ações rápidas (marcar como lida, excluir).\n- **Gerenciamento de abertura e foco:** Controla abertura, fechamento, tecla Escape e foco acessível.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O sistema gerar eventos e comunicados assíncronos que a pessoa usuária precise consultar a qualquer momento.\n- **Evite e prefira outro componente quando:**\n  - A mensagem for uma resposta imediata a uma ação na tela atual (prefira `br-message`).\n  - O aviso exigir confirmação bloqueadora antes de continuar (prefira `br-modal`).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-notification` | **Orquestrador principal.** Gerencia a superfície flutuante, estado de visibilidade e foco. | Contêiner raiz obrigatório. |\n| `br-notification-header` | **Cabeçalho do painel.** Exibe o título, avatar do usuário, contadores e botão de fechar. | Declarado no slot `header` ou topo do `br-notification`. |\n| `br-notification-body` | **Corpo principal.** Contém a listagem das notificações e abas de filtro opcionais. | Declarado no slot padrão do `br-notification`. |\n| `br-notification-item` | **Notificação individual.** Representa cada mensagem com ícone, data, texto e ações. | Declarado dentro do `br-notification-body`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-notification` projeta o painel suspenso:\n1. O cabeçalho (`br-notification-header`) contextualiza o painel e fornece o botão de dispensa.\n2. O corpo (`br-notification-body`) agrupa e organiza a coleção de itens (`br-notification-item`).\n3. Cada item (`br-notification-item`) expõe eventos de clique e ações individuais (como marcar como lida).\n\nPara 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/notification?tab=designer).\n---\n\n\n### **Events:**\n - **brOpenChange** - Informa a mudança de estado aberto/fechado do painel.\n- **brNotificationOpen** - Informa que o painel foi aberto.\n- **brNotificationClose** - Informa que o painel foi fechado.\n- **brNotificationItemClick** - Expõe a interação com um item da lista.\n- **brNotificationTabChange** - Informa troca de aba quando o componente possuir navegação por tabs.\n\n### **Methods:**\n - **show()** - Abre o painel de notificações.\n- **hide(reason: _NotificationCloseReason_)** - Fecha o painel de notificações.\n- **toggle()** - Alterna o estado aberto/fechado.\n- **focusTrigger()** - Move o foco de volta para o acionador.\n- **focusFirstItem()** - Move o foco para o primeiro item interativo da lista.\n\n### **Slots:**\n - **trigger** - Elemento acionador externo responsável por abrir e fechar o painel.\n- **header** - Região superior do componente, para uso com subcomponentes de cabeçalho ou conteúdo customizado.\n- **tabs** - Região opcional para navegação por abas.\n- **default** - Região principal da lista de notificações.\n- **footer** - Região opcional para ações complementares, como \"ver todas\".\n\n### **CSS Parts:**\n - **base** - Superfície principal do painel.\n- **header** - Região superior do componente.\n- **body** - Região principal do componente.\n- **tabs** - Região de abas, quando existir.\n- **list** - Região com rolagem onde os itens são exibidos.\n- **close-button** - Botão de fechar do painel.\n- **divider** - Divisor entre itens da lista.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2796,7 +2828,7 @@
         },
         {
           "name": "placement",
-          "description": "Define o posicionamento do painel em relação ao acionador.",
+          "description": "Define o posicionamento do painel em relação ao acionador. Valores inválidos usam `bottom-end`.",
           "values": [{ "name": "NotificationPlacement" }]
         },
         {
@@ -2824,7 +2856,7 @@
     },
     {
       "name": "br-notification-body",
-      "description": "## Design System\n\nSubcomponente `br-notification-body`: representa a região principal do painel de notificações,\norganizando abas, lista e eventuais estados vazios.\n---\n\n\n### **Slots:**\n - **tabs** - Navegação por abas quando presente.\n- **default** - Lista principal de notificações.\n- **empty** - Conteúdo para estado vazio.",
+      "description": "Subcomponente de corpo da superfície `br-notification`, responsável por agrupar e organizar a lista de itens de notificação.\n\n### Papel na composição\n\n- Atua como contêiner com rolagem independente para a lista de comunicados (`br-notification-item`).\n- Suporta filtros por abas ou categorias de mensagens (ex.: \"Todas\", \"Não lidas\").\n\n### Regra de uso e relacionamento\n\nDeclarado dentro do slot padrão do `br-notification`, posicionado abaixo do cabeçalho. Ele recebe múltiplos elementos `br-notification-item` em seu interior. Não deve ser usado fora do painel de notificação.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/notification?tab=designer).\n---\n\n\n### **Slots:**\n - **tabs** - Navegação por abas quando presente.\n- **default** - Lista principal de notificações.\n- **empty** - Conteúdo para estado vazio.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2846,7 +2878,7 @@
     },
     {
       "name": "br-notification-header",
-      "description": "## Design System\n\nSubcomponente `br-notification-header`: representa a região superior do painel de notificações,\nresponsável por agrupar dados do usuário, título contextual e botão de fechar.\n---\n\n\n### **Events:**\n - **brNotificationHeaderClose** - Solicita o fechamento do painel a partir do cabeçalho.\n\n### **Slots:**\n - **avatar** - Área para avatar ou elemento visual do usuário.\n- **title** - Conteúdo customizado do título.\n- **subtitle** - Conteúdo customizado do subtítulo.\n- **actions** - Região para botão de fechar ou outras ações contextuais.",
+      "description": "Subcomponente de cabeçalho da superfície `br-notification`, responsável pela identificação da área e controles de fechamento.\n\n### Papel na composição\n\n- Exibe o título da central de notificações, avatar da pessoa autenticada e botão de ação para fechar o painel.\n- Fornece contexto visual imediato ao abrir a gaveta de notificações.\n\n### Regra de uso e relacionamento\n\nDeve ser utilizado como o elemento inicial dentro do orquestrador `br-notification`. Ele é coordenado pelo painel pai para disparar o evento de fechamento quando o botão de dispensa é acionado. Não deve ser usado fora de um `br-notification`.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/notification?tab=designer).\n---\n\n\n### **Events:**\n - **brNotificationHeaderClose** - Solicita o fechamento do painel a partir do cabeçalho.\n\n### **Slots:**\n - **avatar** - Área para avatar ou elemento visual do usuário.\n- **title** - Conteúdo customizado do título.\n- **subtitle** - Conteúdo customizado do subtítulo.\n- **actions** - Região para botão de fechar ou outras ações contextuais.",
       "attributes": [
         {
           "name": "custom-id",
@@ -2878,7 +2910,7 @@
     },
     {
       "name": "br-notification-item",
-      "description": "## Design System\n\nSubcomponente `br-notification-item`: representa uma entrada individual de notificação.\nRespeita a organização visual e os estados interativos equivalentes ao componente `item` do design system.\n---\n\n\n### **Events:**\n - **brNotificationItemSelect** - Informa seleção ou acionamento do item.\n- **brNotificationItemRead** - Informa mudança de estado para lido.\n\n### **Methods:**\n - **callFocus()** - Move o foco para o elemento interativo do item.\n\n### **Slots:**\n - **status** - Região para tag, badge ou marcador visual de status.\n- **title** - Conteúdo customizado do título.\n- **meta** - Região para informação cronológica ou metadados.\n- **default** - Conteúdo principal da notificação.\n- **actions** - Ações contextuais do item.",
+      "description": "Subcomponente individual de `br-notification`, utilizado para representar visualmente cada mensagem, aviso ou comunicado do sistema.\n\n### Papel na composição\n\n- Exibe o ícone de status (sucesso, aviso, erro, informação), título do comunicado, data/hora e texto explicativo.\n- Suporta indicação visual de lida/não lida e botões de ação específicos (ex.: \"Ver detalhes\", \"Arquivar\").\n\n### Regra de uso e relacionamento\n\nDeve ser declarado dentro do contêiner `br-notification-body` (ou no slot padrão do `br-notification`). Comunica interações da pessoa usuária (clique no item, dispensa) através de eventos emitidos para a aplicação.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/notification?tab=designer).\n---\n\n\n### **Events:**\n - **brNotificationItemSelect** - Informa seleção ou acionamento do item.\n- **brNotificationItemRead** - Informa mudança de estado para lido.\n\n### **Methods:**\n - **callFocus()** - Move o foco para o elemento interativo do item.\n\n### **Slots:**\n - **status** - Região para tag, badge ou marcador visual de status.\n- **title** - Conteúdo customizado do título.\n- **meta** - Região para informação cronológica ou metadados.\n- **default** - Conteúdo principal da notificação.\n- **actions** - Ações contextuais do item.",
       "attributes": [
         {
           "name": "item-id",
@@ -2912,7 +2944,7 @@
         },
         {
           "name": "state",
-          "description": "Define o estado visual da notificação.",
+          "description": "Define o estado visual da notificação.\nAceita `success`, `danger`, `warning` ou `info`.\nValores inválidos são ignorados.",
           "values": [{ "name": "NotificationItemState" }]
         }
       ],
@@ -2920,36 +2952,36 @@
     },
     {
       "name": "br-pagination",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/pagination?tab=designer).\n---\n\n\n### **Events:**\n - **pageChange** - Solicita uma página por interação do usuário ou pelo método público.\n\nEm `controlled`, o evento informa a página solicitada, mas `current` só\nmuda quando a aplicação confirma o resultado. O componente não faz\nchamadas remotas nem cancela a consulta do consumidor.\n- **brPaginationPageChange** - Evento canônico para iniciar o carregamento de uma página.\nO `detail` contém `{ page }`; o evento não é cancelável.\n- **perPageChange** - Solicita uma quantidade de itens por página (variante contextual).\nEm `controlled`, a aplicação confirma a mudança atribuindo `perPage`.\n- **brPaginationPerPageChange** - Evento canônico para iniciar o carregamento de uma nova quantidade de\nitens. O `detail` contém `{ perPage }`; o evento não é cancelável.\n\n### **Methods:**\n - **setPage(page: _number_): _Promise<void>_** - Define programaticamente a página atual dentro do intervalo permitido.\n- **goToPage(page: _number_): _Promise<void>_** - Solicita navegação programática para uma página (1-indexada).\nEm `controlled`, aguarda a confirmação externa para alterar `current`.\n\n### **Slots:**\n - **pagination-info** - Informação customizada da paginação contextual. Quando utilizado, o texto padrão de contagem é substituído.\n- **loading** - Indicador exibido enquanto uma página é carregada.\n\n### **CSS Parts:**\n - **nav** - Parte para o contêiner raiz da paginação (elemento nav), usada para estilização via ::part().\n- **list** - Parte para a lista de páginas (elemento ul), usada para estilização via ::part().\n- **page** - Parte para os itens de página numérica (elemento a), usada para estilização via ::part().\n- **ellipsis** - Parte para o botão de reticências e seu contêiner.\n- **ellipsis-button** - Parte encaminhada do botão de reticências.\n- **per-page** - Parte para o seletor de itens por página na variante contextual.\n- **per-page-container** - Contêiner encaminhado do seletor de itens por página.\n- **per-page-input** - Campo encaminhado do seletor de itens por página.\n- **per-page-list** - Lista encaminhada do seletor de itens por página.\n- **go-to** - Parte para o seletor de navegação direta na variante contextual.\n- **go-to-container** - Contêiner encaminhado do seletor de navegação direta.\n- **go-to-input** - Campo encaminhado do seletor de navegação direta.\n- **go-to-list** - Lista encaminhada do seletor de navegação direta.\n- **prev-button** - Parte para o botão de página anterior, usada para estilização via ::part().\n- **prev-button-inner** - Botão interno encaminhado da página anterior.\n- **next-button** - Parte para o botão de próxima página, usada para estilização via ::part().\n- **next-button-inner** - Botão interno encaminhado da próxima página.\n- **loading** - Área do indicador de carregamento.",
+      "description": "O componente `br-pagination` é o controle de navegação paginada do GovBR-DS, desenvolvido para segmentar grandes volumes de dados ou conteúdos extensos em páginas sequenciais numeradas.\n\n### Para que serve\n\n- **Segmentação de dados volumosos:** Divide listas, tabelas e catálogos em blocos gerenciáveis de itens, reduzindo o tempo de carregamento da página e o consumo de memória.\n- **Navegação direta e sequencial:** Oferece botões para avançar, retroceder, ir diretamente a uma página específica e navegar através de atalhos de reticências.\n- **Variante contextual completa:** Permite alterar a quantidade de itens exibidos por página (ex.: 10, 20, 50, 100 itens) e pular diretamente para qualquer página através de campo de digitação integrado.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O número total de itens for superior ao limite recomendado para visualização em uma única rolagem (geralmente mais de 20 a 50 registros).\n  - Integrar com tabelas de dados (`br-table`) ou grades de cartões (`br-card`).\n- **Evite e prefira outro componente quando:**\n  - O conjunto completo de itens for pequeno (menos de 20 itens) e puder ser visualizado sem perda de performance.\n  - A navegação representar etapas interdependentes de um processo sequencial com validação (prefira `br-step` ou `br-wizard`).\n\n### Estrutura e Slots\n\nO `br-pagination` disponibiliza slots para complementar a navegação:\n- `pagination-info`: Slot para customização do texto de contagem (ex.: \"Exibindo 1-20 de 240 itens\").\n- `loading`: Slot para indicador visual exibido durante a troca assíncrona de páginas.\n\nPara 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/pagination?tab=designer).\n---\n\n\n### **Events:**\n - **pageChange** - Solicita uma página por interação do usuário ou pelo método público.\n\nEm `controlled`, o evento informa a página solicitada, mas `current` só\nmuda quando a aplicação confirma o resultado. O componente não faz\nchamadas remotas nem cancela a consulta do consumidor.\n- **brPaginationPageChange** - Evento canônico para iniciar o carregamento de uma página.\nO `detail` contém `{ page }`; o evento não é cancelável.\n- **perPageChange** - Solicita uma quantidade de itens por página (variante contextual).\nEm `controlled`, a aplicação confirma a mudança atribuindo `perPage`.\n- **brPaginationPerPageChange** - Evento canônico para iniciar o carregamento de uma nova quantidade de\nitens. O `detail` contém `{ perPage }`; o evento não é cancelável.\n\n### **Methods:**\n - **setPage(page: _number_): _Promise<void>_** - Define programaticamente a página atual dentro do intervalo permitido.\n- **goToPage(page: _number_): _Promise<void>_** - Solicita navegação programática para uma página (1-indexada).\nEm `controlled`, aguarda a confirmação externa para alterar `current`.\n\n### **Slots:**\n - **pagination-info** - Informação customizada da paginação contextual. Quando utilizado, o texto padrão de contagem é substituído.\n- **loading** - Indicador exibido enquanto uma página é carregada.\n\n### **CSS Parts:**\n - **nav** - Parte para o contêiner raiz da paginação (elemento nav), usada para estilização via ::part().\n- **list** - Parte para a lista de páginas (elemento ul), usada para estilização via ::part().\n- **page** - Parte para os itens de página numérica (elemento a), usada para estilização via ::part().\n- **ellipsis** - Parte para o botão de reticências e seu contêiner.\n- **ellipsis-button** - Parte encaminhada do botão de reticências.\n- **per-page** - Parte para o seletor de itens por página na variante contextual.\n- **per-page-container** - Contêiner encaminhado do seletor de itens por página.\n- **per-page-input** - Campo encaminhado do seletor de itens por página.\n- **per-page-list** - Lista encaminhada do seletor de itens por página.\n- **go-to** - Parte para o seletor de navegação direta na variante contextual.\n- **go-to-container** - Contêiner encaminhado do seletor de navegação direta.\n- **go-to-input** - Campo encaminhado do seletor de navegação direta.\n- **go-to-list** - Lista encaminhada do seletor de navegação direta.\n- **prev-button** - Parte para o botão de página anterior, usada para estilização via ::part().\n- **prev-button-inner** - Botão interno encaminhado da página anterior.\n- **next-button** - Parte para o botão de próxima página, usada para estilização via ::part().\n- **next-button-inner** - Botão interno encaminhado da próxima página.\n- **loading** - Área do indicador de carregamento.",
       "attributes": [
         {
           "name": "color-mode",
-          "description": "Define se a paginação usará um esquema de cores escuro.\nQuando definido como `dark`, aplica a classe `dark-mode` ao container principal.",
+          "description": "Define se a paginação usará um esquema de cores escuro. Valores inválidos são ignorados.\nQuando definido como `dark`, aplica a classe `dark-mode` ao container principal.",
           "values": [{ "name": "PaginationColorMode" }]
         },
         {
           "name": "custom-id",
-          "description": "Identificador único do componente.\nQuando omitido, um valor é gerado automaticamente.\n\n> **Padrão:** valor único gerado por Helpers.generateUniqueId().\n\n> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `customId`.",
+          "description": "Identificador único do componente.\nQuando omitido, um valor é gerado automaticamente.\n\n> **Padrão:** valor único gerado por `generateUniqueId()`.\n\n> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `customId`.",
           "values": []
         },
         {
           "name": "total",
-          "description": "Quantidade total de páginas (mínimo 1).",
+          "description": "Quantidade total de páginas (inteiro mínimo 1). Valores inválidos usam 1.",
           "values": []
         },
         {
           "name": "total-pages",
-          "description": "Quantidade total de páginas. Tem precedência sobre `total`.",
+          "description": "Quantidade total de páginas. Tem precedência sobre `total`; valores inválidos usam 1.",
           "values": []
         },
         {
           "name": "current",
-          "description": "Página atual (1-indexada). Valores fora do intervalo serão ajustados.",
+          "description": "Página atual (inteira e 1-indexada). Valores inválidos usam 1; valores fora do intervalo são ajustados.",
           "values": []
         },
         {
           "name": "current-page",
-          "description": "Página atual. Tem precedência sobre `current`.",
+          "description": "Página atual. Tem precedência sobre `current`; valores inválidos usam 1.",
           "values": []
         },
         {
@@ -2974,12 +3006,12 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\n> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `density`.",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\n> **Uso compartilhado:** mantenha esta descrição idêntica em todos os componentes que usam `density`.\nValores inválidos usam `medium`.",
           "values": [{ "name": "PaginationDensity" }]
         },
         {
           "name": "variant",
-          "description": "Variante de renderização do componente.\n- `default`: paginação numérica (padrão)\n- `contextual`: paginação contextual com seletores e informação de itens",
+          "description": "Variante de renderização do componente. Valores inválidos usam `default`.\n- `default`: paginação numérica (padrão)\n- `contextual`: paginação contextual com seletores e informação de itens",
           "values": [{ "name": "PaginationVariant" }]
         },
         {
@@ -2994,17 +3026,17 @@
         },
         {
           "name": "total-items",
-          "description": "Total de itens (aplicável na variante contextual).",
+          "description": "Total de itens (inteiro não negativo, aplicável na variante contextual). Valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "per-page",
-          "description": "Itens por página (aplicável na variante contextual).",
+          "description": "Itens por página (inteiro positivo, aplicável na variante contextual). Valores inválidos usam 10.",
           "values": []
         },
         {
           "name": "per-page-options",
-          "description": "Opções disponíveis de itens por página (variante contextual).",
+          "description": "Opções disponíveis de itens por página na variante `contextual`.\nPasse o array por property binding; atributos HTML não representam arrays.",
           "values": [{ "name": "number[]" }]
         },
         {
@@ -3027,13 +3059,18 @@
     },
     {
       "name": "br-radio",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/radio?tab=designer).\n---\n\n\n### **Events:**\n - **checkedChange** - Disparado depois que o valor do `checked` foi alterado.\n- **brRadioValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **handleCheckedChange(event: _CustomEvent<boolean>_)** - @deprecated A coordenação interna agora é limitada à raiz DOM do grupo. - Mantém o protocolo legado de sincronização por `checkedChange`.\n- **handleKeyDown(event: _KeyboardEvent_)** - Navega e seleciona o próximo/anterior rádio habilitado no grupo via teclas de seta.\nAtivado por 'keydown', move a seleção entre rádios do mesmo 'name'\nusando as setas, partindo do rádio atualmente checado.\n- **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do radio for válido, caso contrário `false`.\nSe o radio for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do radio for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o radio.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do radio e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **toggleChecked()** - @deprecated Atualize a propriedade `checked` diretamente. - Inverte o valor da prop `checked`\n- **setFocus()** - Move o foco para o input radio nativo interno.\n\n### **Slots:**\n - **default** - Slot para o rótulo do rádio, como alternativa à propriedade label.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do radio.\n- **radio-input** - Elemento input nativo do radio.\n- **radio-label** - Rótulo do radio.\n- **feedback** - Contêiner da mensagem de validação.",
+      "description": "O componente `br-radio` é o controle de formulário do GovBR-DS para seleção de uma única opção dentro de um conjunto mutuamente exclusivo. Compatível com as diretrizes WAI-ARIA, ele integra-se nativamente a formulários HTML via `formAssociated`.\n\n### Para que serve\n\n- **Escolha exclusiva:** Permite que a pessoa usuária escolha exatamente uma alternativa entre as opções apresentadas no mesmo grupo.\n- **Integração com formulários:** Comunica valor, estado de seleção (`checked`), desativação e validação diretamente com a API nativa de formulários HTML (`ElementInternals`).\n- **Navegação acessível:** Suporta foco e seleção via teclado (teclas de seta e barra de espaço) quando agrupado.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Houver um conjunto pequeno de opções (entre 2 e 5 alternativas) mutuamente exclusivas e for importante manter todas as opções imediatamente visíveis.\n- **Evite e prefira outro componente quando:**\n  - O número de opções for superior a 5 ou 7 itens: prefira `br-select` para economizar espaço de tela.\n  - A pessoa usuária puder selecionar múltiplas opções simultaneamente: prefira `br-checkbox` ou `br-checkbox-group`.\n  - Houver uma escolha binária simples de ativação/desativação imediata: prefira `br-switch`.\n\n### Estrutura e Slots\n\nO `br-radio` é um controle individual:\n- `default`: Slot para o texto do rótulo da opção (alternativa à propriedade `label`).\n\nPara 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/radio?tab=designer).\n---\n\n\n### **Events:**\n - **checkedChange** - Disparado depois que o valor do `checked` foi alterado.\n- **brRadioValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **handleCheckedChange(event: _CustomEvent<boolean>_)** - @deprecated A coordenação interna agora é limitada à raiz DOM do grupo. - Mantém o protocolo legado de sincronização por `checkedChange`.\n- **handleKeyDown(event: _KeyboardEvent_)** - Navega e seleciona o próximo/anterior rádio habilitado no grupo via teclas de seta.\nAtivado por 'keydown', move a seleção entre rádios do mesmo 'name'\nusando as setas, partindo do rádio atualmente checado.\n- **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do radio for válido, caso contrário `false`.\nSe o radio for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do radio for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o radio.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do radio e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **toggleChecked()** - @deprecated Atualize a propriedade `checked` diretamente. - Inverte o valor da prop `checked`\n- **setFocus()** - Move o foco para o input radio nativo interno.\n\n### **Slots:**\n - **default** - Slot para o rótulo do rádio, como alternativa à propriedade label.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do radio.\n- **radio-input** - Elemento input nativo do radio.\n- **radio-label** - Rótulo do radio.\n- **feedback** - Contêiner da mensagem de validação.",
       "attributes": [
         {
           "name": "checked",
           "description": "Define o estado de seleção do radio.\nSe definido como verdadeiro, o radio estará marcado. Caso contrário, estará desmarcado.",
           "values": []
         },
+        {
+          "name": "uncheck-on-click",
+          "description": "Permite desmarcar o radio ao clicar novamente sobre ele quando já estiver selecionado.\nPor padrão, um radio selecionado permanece marcado ao receber um novo clique.\nQuando usada junto com `uncheckOnDoubleClick`, esta opção tem precedência.",
+          "values": []
+        },
         {
           "name": "uncheck-on-double-click",
           "description": "Permite desmarcar o radio ao clicar duas vezes sobre ele.\nPor padrão, um radio selecionado permanece marcado ao receber um segundo clique.",
@@ -3051,7 +3088,7 @@
         },
         {
           "name": "validator",
-          "description": "Regra síncrona ou assíncrona aplicada ao estado booleano do radio.",
+          "description": "Regra síncrona ou assíncrona aplicada ao estado booleano do radio.\nRetorne uma mensagem para invalidar ou `null` para aceitar o valor.",
           "values": [{ "name": "RadioValidator" }]
         },
         {
@@ -3099,7 +3136,7 @@
     },
     {
       "name": "br-radio-group",
-      "description": "## Design System\n\nGrupo semântico de radios que representa um único campo de formulário. Consulte também as\n[diretrizes do Radio no Design System GovBR](https://www.gov.br/ds/components/radio?tab=designer).\n---\n\n\n### **Events:**\n - **brRadioGroupValidationChange** - Emitido ao iniciar e concluir uma validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Verifica a validade do grupo.\n- **reportValidity(): _Promise<boolean>_** - Verifica a validade e apresenta a mensagem do grupo.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define a mensagem de validade customizada do grupo.\n- **validate(): _Promise<boolean>_** - Executa o validator do grupo.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna o snapshot de validade do grupo.\n- **setFocus(): _Promise<void>_** - Move o foco para o radio marcado ou para o primeiro radio habilitado.\n\n### **Slots:**\n - **default** - Radios pertencentes ao grupo.\n- **label** - Legenda do grupo, como alternativa à propriedade `label`.\n- **description** - Texto auxiliar do grupo.\n- **feedback** - Mensagem de validação do grupo.\n- **validation-loading** - Indicador exibido durante validação assíncrona.\n\n### **CSS Parts:**\n - **group** - Fieldset semântico do grupo.\n- **legend** - Legenda e nome acessível do grupo.\n- **options** - Contêiner das opções.\n- **description** - Área de texto auxiliar.\n- **feedback** - Área de mensagem de validação.\n- **validation-loading** - Área do indicador de validação assíncrona.",
+      "description": "O componente `br-radio-group` é o contêiner semântico e orquestrador de opções `br-radio` no GovBR-DS, responsável por garantir a exclusividade mútua de seleção, a navegação contínua por teclado e a validação integrada do grupo.\n\n### Para que serve\n\n- **Coordenação de seleção mútua:** Garante que apenas um botão de rádio permaneça selecionado por vez entre todos os rádios filhos.\n- **Navegação acessível por teclado WAI-ARIA:** Implementa o padrão de navegação com setas direcionais (cima/baixo/esquerda/direita) com foco cíclico dentro do grupo.\n- **Agrupamento semântico:** Estrutura o grupo com a semântica de `radiogroup`, fornecendo rótulo acessível para tecnologias assistivas.\n- **Associação com formulários:** Atua como controle integrado (`formAssociated`), emitindo o valor consolidado selecionado para o formulário pai.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Apresentar um conjunto de 2 a 5 alternativas mutuamente exclusivas onde todas as opções devam ser comparadas lado a lado ou em lista vertical.\n- **Evite e prefira outro componente quando:**\n  - Houver muitas alternativas (mais de 5 a 7 opções): prefira `br-select`.\n  - A seleção permitir múltiplas alternativas independentes: prefira `br-checkbox-group`.\n\n### Estrutura e Slots\n\nO `br-radio-group` é um orquestrador de seleção:\n- `default`: Slot onde devem ser declarados os componentes filhos `br-radio`.\n- `label`: Slot para personalização do rótulo ou enunciado da pergunta do grupo.\n\nPara 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/radio-group?tab=designer).\n---\n\n\n### **Events:**\n - **brRadioGroupValidationChange** - Emitido ao iniciar e concluir uma validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Verifica a validade do grupo.\n- **reportValidity(): _Promise<boolean>_** - Verifica a validade e apresenta a mensagem do grupo.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define a mensagem de validade customizada do grupo.\n- **validate(): _Promise<boolean>_** - Executa o validator do grupo.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna o snapshot de validade do grupo.\n- **setFocus(): _Promise<void>_** - Move o foco para o radio marcado ou para o primeiro radio habilitado.\n\n### **Slots:**\n - **default** - Radios pertencentes ao grupo.\n- **label** - Legenda do grupo, como alternativa à propriedade `label`.\n- **description** - Texto auxiliar do grupo.\n- **feedback** - Mensagem de validação do grupo.\n- **validation-loading** - Indicador exibido durante validação assíncrona.\n\n### **CSS Parts:**\n - **group** - Fieldset semântico do grupo.\n- **legend** - Legenda e nome acessível do grupo.\n- **options** - Contêiner das opções.\n- **description** - Área de texto auxiliar.\n- **feedback** - Área de mensagem de validação.\n- **validation-loading** - Área do indicador de validação assíncrona.",
       "attributes": [
         {
           "name": "name",
@@ -3128,7 +3165,7 @@
         },
         {
           "name": "orientation",
-          "description": "Orientação visual das opções.",
+          "description": "Orientação visual das opções. Valores inválidos usam `vertical`.",
           "values": [{ "name": "RadioGroupOrientation" }]
         },
         {
@@ -3143,12 +3180,12 @@
         },
         {
           "name": "feedback-state",
-          "description": "Estado visual opcional do feedback. A validade real vem de ElementInternals.",
+          "description": "Estado visual opcional do feedback. Valores inválidos não aplicam estado. A validade real vem de ElementInternals.",
           "values": [{ "name": "valid" }, { "name": "invalid" }]
         },
         {
           "name": "validator",
-          "description": "Regra síncrona ou assíncrona aplicada ao valor do grupo.",
+          "description": "Regra síncrona ou assíncrona aplicada ao valor do grupo.\nRecebe a string selecionada ou `null` quando nenhuma opção está marcada.",
           "values": [{ "name": "RadioGroupValidator" }]
         },
         {
@@ -3161,7 +3198,7 @@
     },
     {
       "name": "br-scrim",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/scrim?tab=designer).\n---\n\n\n### **Events:**\n - **brScrimOpen** - Indica que o scrim foi aberto.\n- **brScrimClose** - Indica que o scrim foi fechado\n\n### **Methods:**\n - **setScrollThreshold(threshold: _number_)** - Define o limite de rolagem para o fechamento automático do scrim.\n- **open()** - Método público para exibir o scrim\n- **close()** - Método público para esconder o scrim\n- **toggle()** - Método público para alternar o estado de exibição do scrim\n- **updateSpotlight()** - Recalcula manualmente a posição e dimensões da fresta do scrim vazado.\nÚtil quando o elemento alvo muda de posição sem disparar resize ou scroll.\n- **handleDocumentKeyDown(event: _KeyboardEvent_)** - Intercepta todos os eventos de teclado globalmente quando o scrim está ativo.\n\nUsa `composedPath()[0]` para obter o elemento real com foco, mesmo dentro de shadow roots.\n`event.target` é redirecionado ao cruzar shadow boundaries e não reflete o elemento concreto\nquando o foco está dentro do shadow DOM de componentes filhos como `br-modal`.\n\n### **Slots:**\n - **default** - Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.\n- **activator** - Slot para o elemento ativador do scrim, com prioridade sobre a propriedade activator.",
+      "description": "O componente `br-scrim` é a camada de sobreposição visual (backdrop / máscara) do GovBR-DS, utilizada para escurecer temporariamente a interface e direcionar a atenção da pessoa usuária para um ponto de interesse ou diálogo.\n\n### Para que serve\n\n- **Destaque visual exclusivo (Spotlight):** Cria um foco exclusivo sobre determinado elemento da página (como um tour guiado ou tutorial introdutório).\n- **Bloqueio de interação com o fundo:** Impede cliques acidentais e rolagem na interface subjacente enquanto uma superfície flutuante estiver ativa.\n- **Comportamento acessível de fechamento:** Suporta fechamento ao clicar na máscara ou ao pressionar a tecla Escape, com controle de foco previsível.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - For necessário criar máscaras de fundo personalizadas para fluxos de onboarding, tutoriais ou menus temporários imersivos.\n- **Evite e prefira outro componente quando:**\n  - Estiver implementando uma caixa de diálogo padrão com cabeçalho, corpo e rodapé (prefira `br-modal`, que já inclui seu próprio scrim interno).\n\n### Estrutura e Slots\n\nO `br-scrim` atua como superfície de sobreposição:\n- `default`: Slot para inserção do elemento que receberá o destaque em primeiro plano sobre a máscara.\n\nPara 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/scrim?tab=designer).\n---\n\n\n### **Events:**\n - **brScrimOpen** - Indica que o scrim foi aberto.\n- **brScrimClose** - Indica que o scrim foi fechado\n\n### **Methods:**\n - **setScrollThreshold(threshold: _number_)** - Define o limite de rolagem para o fechamento automático do scrim.\n- **open()** - Método público para exibir o scrim\n- **close()** - Método público para esconder o scrim\n- **toggle()** - Método público para alternar o estado de exibição do scrim\n- **updateSpotlight()** - Recalcula manualmente a posição e dimensões da fresta do scrim vazado.\nÚtil quando o elemento alvo muda de posição sem disparar resize ou scroll.\n- **handleDocumentKeyDown(event: _KeyboardEvent_)** - Intercepta todos os eventos de teclado globalmente quando o scrim está ativo.\n\nUsa `composedPath()[0]` para obter o elemento real com foco, mesmo dentro de shadow roots.\n`event.target` é redirecionado ao cruzar shadow boundaries e não reflete o elemento concreto\nquando o foco está dentro do shadow DOM de componentes filhos como `br-modal`.\n\n### **Slots:**\n - **default** - Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.\n- **activator** - Slot para o elemento ativador do scrim, com prioridade sobre a propriedade activator.",
       "attributes": [
         {
           "name": "custom-id",
@@ -3185,7 +3222,7 @@
         },
         {
           "name": "z-index",
-          "description": "Define o valor de z-index do scrim",
+          "description": "Define o valor de z-index do scrim. Deve ser um inteiro entre 0 e Number.MAX_SAFE_INTEGER; valores inválidos usam 0.",
           "values": []
         },
         {
@@ -3195,7 +3232,7 @@
         },
         {
           "name": "custom-opacity",
-          "description": "Define a opacidade personalizada do scrim",
+          "description": "Define a opacidade personalizada do scrim. O valor é limitado ao intervalo `0`–`1`; entradas inválidas usam `0.4`.",
           "values": []
         },
         {
@@ -3210,7 +3247,7 @@
         },
         {
           "name": "scroll-threshold",
-          "description": "Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim.",
+          "description": "Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim. Valores negativos usam `0`.",
           "values": []
         },
         {
@@ -3238,6 +3275,11 @@
           "description": "Define o tamanho da faixa de cobertura da variante `legibility`, usado em\nconjunto com `legibilityAnchor`.\n\nAceita qualquer valor CSS de comprimento válido:\n- Percentual relativo ao elemento pai: `'40%'`, `'75%'`\n- Comprimento absoluto: `'120px'`, `'8rem'`, `'6em'`\n- Função CSS: `'calc(100% - 2rem)'`\n\nQuando `null` (padrão), a máscara ocupa **100%** da dimensão relevante:\n- **altura** para âncoras `top`, `bottom` e `center`\n- **largura** para âncoras `left` e `right`\n\nSó tem efeito quando `variant=\"legibility\"` está definido.",
           "values": []
         },
+        {
+          "name": "legibility-target-id",
+          "description": "Seletor CSS do elemento que deve receber o posicionamento da variante\n`legibility`. Quando não informado (padrão), o alvo é o elemento pai\ndireto do `<br-scrim>`.",
+          "values": []
+        },
         {
           "name": "spotlight-target-id",
           "description": "Ativa o modo de scrim vazado (variante 'spotlight'), criando uma área de fresta no overlay\nque destaca o elemento referenciado pelo seletor CSS fornecido.",
@@ -3245,7 +3287,7 @@
         },
         {
           "name": "spotlight-padding",
-          "description": "Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado.",
+          "description": "Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado. Valores negativos usam `0`.",
           "values": []
         },
         {
@@ -3263,7 +3305,7 @@
     },
     {
       "name": "br-select",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).\n---\n\n\n### **Events:**\n - **brSelectStateChange** - Evento emitido quando o estado público do select muda.\n- **valueChange** - Evento emitido quando o valor público do select é alterado.\n- **optionHover** - Emite a opção que recebeu foco ou hover.\n- **brSelectSearch** - Emitido uma vez por edição do campo de busca, inclusive ao limpar a consulta.\nO `detail` contém `{ query }`; o evento é informativo e não cancelável.\nA aplicação deve controlar debounce, transporte e ciclo de vida da busca.\n- **opened** - Emitido quando a lista é aberta.\n- **closed** - Emitido quando a lista é fechada.\n- **brSelectValidationChange** - Informa o início e o resultado de uma validação síncrona ou assíncrona.\nO `detail` contém `validating`, `valid` e `message`.\n\n### **Methods:**\n - **enable(): __** - Habilita o select para interação do usuário.\n- **disable(): __** - Desabilita o select e impede novas interações.\n- **show(): __** - Abre a lista de opções quando o componente está habilitado.\n- **close(): __** - Fecha a lista de opções quando o componente está habilitado.\n- **toggleOpen(): _Promise<void>_** - Alterna entre os estados aberto e fechado do select.\n- **clear(): _Promise<void>_** - @deprecated Use `setValue('')` ou a API de formulário. - Limpa a seleção atual.\n- **getValue(): _Promise<string | string[]>_** - @deprecated Leia a propriedade `value` diretamente. - Retorna o valor público atual.\n- **setValue(value: _string | string[]_): _Promise<void>_** - @deprecated Atribua a propriedade `value` diretamente. - Define o valor público do select.\n- **setFocus(): _Promise<void>_** - @deprecated Use o foco nativo do componente quando possível. - Move o foco para o campo interno.\n- **setOptions(options: _SelectOptionData[]_): __** - Substitui a coleção atual de opções por uma nova lista.\n- **setOption(option: _SelectOptionData_): __** - Adiciona ou atualiza uma única opção na coleção interna.\n\n### **Slots:**\n - **default** - Opções declaradas com elementos br-select-option.\n- **feedback** - Mensagem de validação, normalmente um br-message.\n- **validation-loading** - Indicador exibido durante validação assíncrona.\n- **loading** - Indicador exibido durante a busca remota de opções.\n\n### **CSS Parts:**\n - **container** - Contêiner visual principal do select.\n- **input** - Campo de seleção e busca.\n- **input-container** - Contêiner visual do campo.\n- **input-label** - Rótulo do campo.\n- **input-field** - Campo input nativo.\n- **input-group** - Grupo visual do campo.\n- **input-icon** - Ícone do campo.\n- **input-action** - Botão de abertura e fechamento.\n- **input-action-button** - Botão interno da ação.\n- **list** - Lista de opções.\n- **option** - Opção individual.\n- **select-all** - Alias legado para a opção de selecionar todos.\n- **empty-option** - Alias legado para a opção vazia da lista.\n- **option-checkbox** - Alias legado para o checkbox da opção.\n- **option-radio** - Alias legado para o radio da opção.\n- **hidden-select** - Select nativo invisível usado na integração com formulários.\n- **feedback** - Área de mensagem de validação.\n- **validation-loading** - Área do indicador de validação assíncrona.",
+      "description": "O componente `br-select` é o controle oficial de seleção do GovBR-DS, desenvolvido para permitir que o usuário escolha uma ou múltiplas opções a partir de uma lista expansível. Compatível com o padrão WAI-ARIA Combobox, ele reúne em um único componente acessível o campo de acionamento/digitação, a lista suspensa e as opções selecionáveis, integrando-se nativamente a formulários HTML e frameworks modernos.\n\n### Para que serve\n\nO `br-select` gerencia todo o fluxo de interação de seleção:\n- **Seleção simples e múltipla:** Permite selecionar uma única opção ou múltiplas opções (`multiple`), incluindo a opção de selecionar ou desmarcar todas em lote.\n- **Busca e filtragem:** Oferece filtro local integrado (conforme o usuário digita) e suporte a busca remota assíncrona (`search-mode=\"remote\"`), disparando eventos para carregamento sob demanda via API.\n- **Agrupamento de opções:** Organiza opções contíguas por categoria, preservando virtualização, busca local e semântica nativa de formulário.\n- **Integração com formulários:** É associado a formulários nativos (`formAssociated`), comunicando seu valor, estado de validação (válido/inválido), mensagens de erro contextuais e eventos padrão (`change`, `input`).\n- **Navegação acessível:** Suporta controle total via teclado (setas para cima/baixo, Enter, Escape, Home, End), foco gerenciado e anúncios para leitores de tela.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O número de opções for moderado a grande (mais de 5 a 7 itens), onde listar todas diretamente na tela consumiria muito espaço visual.\n  - For necessário filtrar opções por texto (digitação em lista longa).\n  - As opções forem carregadas dinamicamente de uma API externa (busca remota/paginada).\n  - O espaço no leiaute for restrito e exigir um controle compacto e expansível.\n- **Evite e prefira outro componente quando:**\n  - Houver poucas opções fixas (de 2 a 4 opções mutuamente exclusivas): prefira `br-radio` ou `br-radio-group` para manter as alternativas imediatamente visíveis.\n  - Houver uma escolha binária (sim/não, ativo/inativo): prefira `br-switch` ou `br-checkbox`.\n  - Houver seleção múltipla com até 4 alternativas: prefira `br-checkbox` ou um grupo de checkboxes visíveis.\n\n### Composição e Subcomponentes\n\nO ecossistema do Select é composto pelo elemento principal orquestrador e três subcomponentes especializados:\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-select` | **Orquestrador principal.** Gerencia o valor, ciclo de vida, acessibilidade, busca, formulário e renderização dos elementos internos. | Deve ser o único componente diretamente instanciado no template da aplicação. |\n| `br-select-input` | **Campo de acionamento.** Exibe o valor selecionado, o rótulo (`label`), o campo de busca/digitação e o botão de expandir/recolher. | Coordenado automaticamente pelo `br-select`; utilize isoladamente apenas em composições arquiteturais avançadas. |\n| `br-select-list` | **Lista suspensa virtualizada.** Contêiner flutuante que renderiza as opções de forma otimizada com suporte a rolagem e virtualização. | Gerenciada exclusivamente pelo `br-select`; não deve ser usada como controle autônomo. |\n| `br-select-option` | **Item individual de opção.** Representa um valor selecionável, exibindo texto, estado de seleção e checkbox/radio associado. | Deve ser declarado dentro do slot padrão do `br-select` para cada opção desejada. |\n\nAlém dos subcomponentes, o `br-select` oferece slots dedicados:\n- `default`: Slot principal onde são passados os elementos `br-select-option`.\n- `feedback`: Slot para exibição de mensagens de validação (ex.: `br-message`).\n- `loading`: Slot para indicador de carregamento durante busca remota.\n- `validation-loading`: Slot para indicador visual durante validação assíncrona.\n\n### Como fornecer opções\n\nO `br-select` possui uma API declarativa canônica e uma API imperativa para atualizações dinâmicas:\n\n1. **Slot com `br-select-option`:** é a forma declarativa canônica para código novo. O pai lê os atributos e o conteúdo de cada opção e os transforma em dados para a lista. Em frameworks, a coleção também pode ser renderizada como vários elementos `br-select-option`.\n2. **Método `setOptions()`:** substitui a coleção de forma imperativa e deve ser reservado para dados dinâmicos, especialmente respostas de busca remota. A lista recebe os objetos e cria internamente somente a janela visível de opções.\n\n`br-select-input` e `br-select-list` não substituem essas fontes. Eles são peças internas da composição: o primeiro controla o campo de acionamento e busca; o segundo recebe a coleção normalizada e renderiza a lista virtualizada.\n\nEvite misturar slot e dados imperativos sem necessidade. Na inicialização, opções declaradas no slot têm precedência quando existem. Depois que `options` é alterada ou `setOptions()` é chamado, a coleção imperativa passa a ser a fonte de dados e alterações posteriores no slot não são sincronizadas.\n\nA prop `options` é uma API legada e está depreciada. Ela continua funcionando apenas para preservar compatibilidade: no HTML, recebe uma string JSON; em JavaScript e frameworks, recebe um array por property binding. Não a adote em código novo; use `br-select-option` ou, para respostas dinâmicas/remotas, `setOptions()`.\n\nCada objeto deve conter `value` string e pode conter `label`, `selected`, `disabled`, `indeterminate` e `content`. `content` é renderizado como HTML na lista; não use esse campo com conteúdo não confiável.\n\n### O Conceito \"Lego\" e a Diferença entre os Componentes {#conceito-lego}\n\nO ecossistema de seleção do GovBR-DS foi projetado seguindo o **conceito de peças de Lego**: modular, flexível e combinável:\n\n1. **`br-select` (Componente Principal / Modelo Pronto):**\n   É o **componente principal**. Já vem montado com todas as peças essenciais integradas: o acionador (`br-select-input`), a lista flutuante virtualizada (`br-select-list`), a navegação por teclado e a integração nativa com formulários (`formAssociated`). Na quase totalidade das aplicações (99% dos casos), você deve usar apenas `<br-select>`.\n\n2. **`br-select-option` (Peça de Conteúdo):**\n   É a peça de Lego que você encaixa diretamente no slot padrão do `<br-select>` para definir cada valor selecionável.\n\n3. **`br-select-input` e `br-select-list` (Subcomponentes Internos):**\n   São as peças internas que formam a estrutura do `br-select`. No uso comum, **não devem ser declarados manualmente**, pois o `br-select` já os instancia e os sincroniza automaticamente.\n\n#### Quando usar apenas `<br-select>`?\nUse apenas `<br-select>` em quase todos os fluxos. Para opções fixas, declare os itens `<br-select-option>` no slot padrão; para opções dinâmicas, alimente a coleção com `setOptions()`. A prop `options` permanece disponível somente para compatibilidade legada.\n\n#### Quando montar os componentes separadamente?\nA montagem separada das peças avulsas de Lego (`br-select-input` + `br-select-list` + `br-select-option`) destina-se exclusivamente a **composições arquiteturais avançadas**, onde o leiaute exige desacoplar fisicamente o campo de acionamento da lista suspensa (ex.: campo de busca fixo na barra superior e a lista exibida dentro de um drawer ou modal lateral). Nesse caso, a aplicação precisa implementar manualmente a sincronização de foco, abertura, navegação por teclado e repasse de valor ao formulário.\n\n### Como os subcomponentes se relacionam\n\nA arquitetura do `br-select` segue o padrão de **orquestrador centralizado**:\n1. **O componente pai coordena o estado:** A aplicação declara o `<br-select>` com múltiplos `<br-select-option>` filhos ou usa `setOptions()` para dados dinâmicos. O `br-select` projeta internamente o `<br-select-input>` e a `<br-select-list>`, garantindo sincronia total de foco, estados de abertura, termos pesquisados e eventos. A prop `options` não é uma alternativa para código novo; existe somente para compatibilidade legada.\n2. **Evite montagem manual desarticulada:** Tentar declarar manualmente `br-select-input` e `br-select-list` fora do `br-select` quebra as relações de acessibilidade WAI-ARIA (combobox, controles expandidos, aria-activedescendant) e desvincula o controle da validação nativa de formulários (`ElementInternals`).\n3. **Comunicação por eventos:** Para busca remota ou resposta a seleção, a aplicação escuta os eventos disparados diretamente pelo `br-select` (`brSearch`, `change`, `input`), sem precisar interceptar nós internos da lista ou do campo de texto.\n\nPara 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/select?tab=designer).\n---\n\n\n### **Events:**\n - **brSelectStateChange** - Evento emitido quando o estado público do select muda.\n- **valueChange** - Evento emitido quando o valor público do select é alterado.\n- **optionHover** - Emite a opção que recebeu foco ou hover.\n- **brSelectSearch** - Emitido uma vez por edição do campo de busca, inclusive ao limpar a consulta.\nO `detail` contém `{ query }`; o evento é informativo e não cancelável.\nA aplicação deve controlar debounce, transporte e ciclo de vida da busca.\n- **opened** - Emitido quando a lista é aberta.\n- **closed** - Emitido quando a lista é fechada.\n- **brSelectValidationChange** - Informa o início e o resultado de uma validação síncrona ou assíncrona.\nO `detail` contém `validating`, `valid` e `message`.\n\n### **Methods:**\n - **handleSelectOptionPropsChange(event: _Event_)** - Recalcula a coleção quando uma opção projetada muda por atribuição direta\nde `selected`, `disabled`, `label`, `group` ou `value`. A lista virtualizada em\nShadow DOM não é uma fonte independente; ela recebe o snapshot pelo seu\ncontrato público `options`.\n- **enable(): __** - Habilita o select para interação do usuário.\n- **disable(): __** - Desabilita o select e impede novas interações.\n- **show(): __** - Abre a lista de opções quando o componente está habilitado.\n- **close(): __** - Fecha a lista de opções quando o componente está habilitado.\n- **toggleOpen(): _Promise<void>_** - Alterna entre os estados aberto e fechado do select.\n- **clear(): _Promise<void>_** - @deprecated Use `setValue('')` ou a API de formulário. - Limpa a seleção atual.\n- **getValue(): _Promise<string | string[]>_** - @deprecated Leia a propriedade `value` diretamente. - Retorna o valor público atual.\n- **setValue(value: _string | string[]_): _Promise<void>_** - @deprecated Atribua a propriedade `value` diretamente. - Define o valor público do select.\n- **setFocus(): _Promise<void>_** - @deprecated Use o foco nativo do componente quando possível. - Move o foco para o campo interno.\n- **setOptions(options: _SelectOptionData[]_): __** - Substitui a coleção atual de opções por uma nova lista.\n- **setOption(option: _SelectOptionData_): __** - Adiciona ou atualiza uma única opção na coleção interna.\n\n### **Slots:**\n - **default** - Opções declaradas com elementos br-select-option.\n- **feedback** - Mensagem de validação, normalmente um br-message.\n- **validation-loading** - Indicador exibido durante validação assíncrona.\n- **loading** - Indicador exibido durante a busca remota de opções.\n\n### **CSS Parts:**\n - **container** - Contêiner visual principal do select.\n- **input** - Campo de seleção e busca.\n- **input-container** - Contêiner visual do campo.\n- **input-label** - Rótulo do campo.\n- **input-field** - Campo input nativo.\n- **input-group** - Grupo visual do campo.\n- **input-icon** - Ícone do campo.\n- **input-action** - Botão de abertura e fechamento.\n- **input-action-button** - Botão interno da ação.\n- **list** - Lista de opções.\n- **option** - Opção individual.\n- **option-group** - Cabeçalho visual de um grupo de opções.\n- **select-all** - Alias legado para a opção de selecionar todos.\n- **empty-option** - Alias legado para a opção vazia da lista.\n- **option-checkbox** - Alias legado para o checkbox da opção.\n- **option-radio** - Alias legado para o radio da opção.\n- **hidden-select** - Select nativo invisível usado na integração com formulários.\n- **feedback** - Área de mensagem de validação.\n- **validation-loading** - Área do indicador de validação assíncrona.",
       "attributes": [
         {
           "name": "borderless",
@@ -3275,6 +3317,11 @@
           "description": "Desativa toda a interação do select.",
           "values": []
         },
+        {
+          "name": "density",
+          "description": "Define a densidade visual compartilhada pelo campo e pela lista de opções.\nAceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.",
+          "values": [{ "name": "BrDensity" }]
+        },
         {
           "name": "is-inline",
           "description": "Exibe label e campo na mesma linha.",
@@ -3302,12 +3349,12 @@
         },
         {
           "name": "visible-items",
-          "description": "Define quantas opções ficam visíveis na janela da lista.",
+          "description": "Define quantas linhas visuais ficam visíveis na janela da lista.\nCabeçalhos de grupo também ocupam uma linha quando existem.\nDeve ser um inteiro positivo; valores inválidos usam 6.",
           "values": []
         },
         {
           "name": "item-height",
-          "description": "Informa a altura base de cada opção para o cálculo de virtual scroll.",
+          "description": "Informa a altura base de cada opção ou cabeçalho para o cálculo de virtual scroll.\nDeve ser um número finito positivo; valores inválidos usam 40.",
           "values": []
         },
         {
@@ -3317,7 +3364,7 @@
         },
         {
           "name": "overscan",
-          "description": "Define quantas opções extras são renderizadas antes e depois da área visível no virtual scroll.",
+          "description": "Define quantas opções extras são renderizadas antes e depois da área visível no virtual scroll.\nDeve ser um inteiro não negativo; valores inválidos usam 1.",
           "values": []
         },
         {
@@ -3387,17 +3434,18 @@
         },
         {
           "name": "options",
-          "description": "Opções fornecidas como array ou JSON, além das opções projetadas por slot.",
+          "description": "Fornece opções como array ou JSON, além das opções projetadas por slot.\nUse property binding para arrays em JavaScript e frameworks; no atributo\nHTML, informe uma string JSON válida. Na inicialização, opções no slot têm\nprecedência quando existem. Depois de uma alteração nesta prop ou de uma\nchamada a `setOptions()`, a coleção imperativa passa a ser a fonte de dados.\nNão use em código novo. Declare `br-select-option` no slot padrão ou, para\nrespostas dinâmicas/remotas, atualize a coleção com `setOptions()`.",
           "values": [
+            { "name": "" },
             {
-              "name": "{ label: string; value: string; selected?: boolean }[]"
+              "name": "{ group?: string; label: string; value: string; selected?: boolean }[]"
             },
             { "name": "SelectOptionData[]" }
           ]
         },
         {
           "name": "autocomplete",
-          "description": "Controla o autocomplete do campo de busca interno.",
+          "description": "Controla o autocomplete do campo de busca interno. Aceita `on` ou `off`; valores inválidos são ignorados.",
           "values": [{ "name": "InputToggle" }]
         },
         {
@@ -3407,17 +3455,17 @@
         },
         {
           "name": "min-selections",
-          "description": "Quantidade mínima de opções selecionadas no modo múltiplo.",
+          "description": "Quantidade mínima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "max-selections",
-          "description": "Quantidade máxima de opções selecionadas no modo múltiplo.",
+          "description": "Quantidade máxima de opções selecionadas no modo múltiplo. Deve ser um inteiro não negativo; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "validator",
-          "description": "Validação síncrona ou assíncrona executada no método `validate()`.",
+          "description": "Validação síncrona ou assíncrona executada no método `validate()`.\nRecebe uma string no modo simples e um array de strings no modo múltiplo.",
           "values": [{ "name": "SelectValidator" }]
         }
       ],
@@ -3425,7 +3473,7 @@
     },
     {
       "name": "br-select-input",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).\n---\n\n\n### **Events:**\n - **brSelectInputFocus** - Evento emitido quando o campo interno recebe foco.\n- **brSelectInputValueChange** - Evento emitido quando o valor digitado no campo de busca muda.\n- **brSelectInputActionClick** - Evento emitido quando o usuário aciona o ícone de abertura/fechamento.\n- **brSelectInputClick** - Evento emitido quando o usuário clica no campo do select.\n\n### **Methods:**\n - **flipUp(): __** - Atualiza o ícone para o estado visual de lista aberta.\n- **flipDown(): __** - Atualiza o ícone para o estado visual de lista fechada.\n- **setFocus(): __** - Reaplica o foco no input nativo encapsulado por `br-input`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do campo.\n- **input** - Campo input nativo.\n- **label** - Rótulo do campo.\n- **group** - Grupo visual do campo.\n- **icon** - Ícone do campo.\n- **action** - Botão de ação.\n- **action-button** - Botão interno da ação.",
+      "description": "Subcomponente especializado de `br-select` responsável pelo campo de acionamento, entrada de texto e controle de expansão do popup.\n\n### Papel na composição\n- Exibe o rótulo (`label`), texto de espaço reservado (`placeholder`) e o resumo dos itens atualmente selecionados.\n- Atua como campo de entrada textual para digitação de filtros e termos de busca local ou remota.\n- Contém o botão de ação para abrir ou recolher a lista de opções (`br-select-list`), controlando a rotação do ícone indicador.\n\n### Regra de uso e relacionamento\nNa quase totalidade das aplicações, este componente é instanciado e gerenciado internamente pelo orquestrador `br-select`. Ele não fornece nem renderiza a coleção de opções: recebe do pai o valor exibido, o termo de busca e os estados de abertura e desabilitação. Não deve ser declarado manualmente na página, pois depende da coordenação do pai para foco, ARIA, eventos e sincronização com formulários. Use isoladamente apenas em composições arquiteturais altamente customizadas onde a aplicação assumir explicitamente toda a orquestração de foco e estado.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).\n---\n\n\n### **Events:**\n - **brSelectInputFocus** - Evento emitido quando o campo interno recebe foco.\n- **brSelectInputValueChange** - Evento emitido quando o valor digitado no campo de busca muda.\n- **brSelectInputActionClick** - Evento emitido quando o usuário aciona o ícone de abertura/fechamento.\n- **brSelectInputClick** - Evento emitido quando o usuário clica no campo do select.\n\n### **Methods:**\n - **flipUp(): __** - Atualiza o ícone para o estado visual de lista aberta.\n- **flipDown(): __** - Atualiza o ícone para o estado visual de lista fechada.\n- **setFocus(): __** - Reaplica o foco no input nativo encapsulado por `br-input`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do campo.\n- **input** - Campo input nativo.\n- **label** - Rótulo do campo.\n- **group** - Grupo visual do campo.\n- **icon** - Ícone do campo.\n- **action** - Botão de ação.\n- **action-button** - Botão interno da ação.",
       "attributes": [
         {
           "name": "borderless",
@@ -3434,7 +3482,7 @@
         },
         {
           "name": "autocomplete",
-          "description": "Controla o preenchimento automático do input interno.",
+          "description": "Controla o preenchimento automático do input interno. Aceita `on` ou `off`; valores inválidos são ignorados.",
           "values": [{ "name": "InputToggle" }]
         },
         {
@@ -3442,6 +3490,11 @@
           "description": "Desativa toda a interação do campo de entrada.",
           "values": []
         },
+        {
+          "name": "density",
+          "description": "Define a densidade visual do campo e do input interno.\nAceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.",
+          "values": [{ "name": "BrDensity" }]
+        },
         {
           "name": "is-inline",
           "description": "Exibe label e campo na mesma linha.",
@@ -3492,11 +3545,16 @@
     },
     {
       "name": "br-select-list",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).\n---\n\n\n### **Methods:**\n - **open(): __** - Abre a lista e agenda a medição das opções quando necessário.\n- **close(): __** - Fecha a lista de opções.\n- **setOptions(options: _SelectOptionData[]_): __** - Substitui todas as opções renderizadas pela lista.\n- **setOption(option: _SelectOptionData_): __** - Adiciona ou atualiza uma única opção na coleção atual.\n- **setSearchTerm(term: _string_): _Promise<void>_** - Atualiza o termo de busca e reinicia a janela virtual no topo.\n- **setMultiple(isMultiple: _boolean_): __** - Alterna a lista entre modo simples e múltiplo.\n- **getOptions(): __** - Retorna uma cópia das opções atualmente controladas pela lista.\n- **scrollOptionToTop(index: _number_): __** - Posiciona uma opção no topo da viewport virtual, respeitando o limite final da lista.\n- **scrollFirstSelectedOptionToTop(): __** - Posiciona no topo a primeira opção selecionada na ordem visual da lista.\nA opção auxiliar de selecionar tudo não participa dessa escolha.\n- **focusOption(index: _number_): __** - Garante visibilidade e foco para uma opção específica.\n- **setOptionSelected(index: _number_, selected: _boolean_): __** - Aciona a seleção programática de uma opção específica.\n\n### **Slots:**\n - **loading** - Indicador exibido enquanto resultados remotos são carregados.\n\n### **CSS Parts:**\n - **list** - Contêiner visual da lista virtualizada.\n- **loading** - Área do indicador de carregamento.",
+      "description": "Subcomponente de lista virtualizada de opções, projetado para renderizar o conjunto de escolhas do `br-select`.\n\n### Papel na composição\n- Atua como o painel suspenso (popup `listbox`) que exibe os itens `br-select-option`.\n- Implementa virtualização de itens para oferecer alta performance mesmo em listas extensas com centenas ou milhares de opções.\n- Mantém o posicionamento flutuante e controla a rolagem de visualização do item ativo em navegação por teclado.\n\n### Regra de uso e relacionamento\nGerenciado exclusivamente pelo componente pai `br-select`, que injeta a coleção normalizada em `options`, controla o estado de exibição (aberto/fechado), a seleção múltipla e o índice ativo. A prop `options` desta lista é um contrato interno de composição e não substitui a API de opções do `br-select`. A lista cria internamente elementos `br-select-option` para a janela virtualizada, em vez de exibir diretamente os filhos declarados no slot do pai. Não utilize `br-select-list` como controle autônomo de formulário, pois ele não possui associação nativa com formulários (`formAssociated`) nem campo de acionamento próprio.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).\n---\n\n\n### **Methods:**\n - **open(): __** - Abre a lista e agenda a medição das opções quando necessário.\n- **close(): __** - Fecha a lista de opções.\n- **setOptions(options: _SelectOptionData[]_): __** - Substitui todas as opções renderizadas pela lista.\n- **setOption(option: _SelectOptionData_): __** - Adiciona ou atualiza uma única opção na coleção atual.\n- **setSearchTerm(term: _string_): _Promise<void>_** - Atualiza o termo de busca e reinicia a janela virtual no topo.\n- **setMultiple(isMultiple: _boolean_): __** - Alterna a lista entre modo simples e múltiplo.\n- **getOptions(): __** - Retorna uma cópia das opções atualmente controladas pela lista.\n- **scrollOptionToTop(index: _number_): __** - Posiciona uma opção no topo da viewport virtual, respeitando o limite final da lista.\n- **scrollFirstSelectedOptionToTop(): __** - Posiciona no topo a primeira opção selecionada na ordem visual da lista.\nA opção auxiliar de selecionar tudo não participa dessa escolha.\n- **focusOption(index: _number_): __** - Garante visibilidade e foco para uma opção específica.\n- **setOptionSelected(index: _number_, selected: _boolean_): __** - Aciona a seleção programática de uma opção específica.\n\n### **Slots:**\n - **loading** - Indicador exibido enquanto resultados remotos são carregados.\n\n### **CSS Parts:**\n - **list** - Contêiner visual da lista virtualizada.\n- **loading** - Área do indicador de carregamento.\n- **option-group** - Cabeçalho visual de um grupo de opções.",
       "attributes": [
+        {
+          "name": "density",
+          "description": "Define a densidade visual da lista, das opções e do indicador de carregamento.\nAceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.",
+          "values": [{ "name": "BrDensity" }]
+        },
         {
           "name": "options",
-          "description": "Coleção de opções exibidas pela lista.",
+          "description": "É um contrato de composição abastecido pelo `br-select`; não é a API de\nopções do componente principal. Cada opção deve conter `value` string e\npode conter `label` e `group` como strings opcionais; entradas inválidas\nsão ignoradas.",
           "values": [{ "name": "SelectOptionData[]" }]
         },
         {
@@ -3511,17 +3569,17 @@
         },
         {
           "name": "visible-items",
-          "description": "Define quantas opções permanecem visíveis na viewport da lista.",
+          "description": "Define quantas linhas visuais permanecem visíveis na viewport da lista.\nCabeçalhos de grupo também ocupam uma linha quando existem.\nDeve ser um inteiro positivo; valores inválidos usam 6.",
           "values": []
         },
         {
           "name": "item-height",
-          "description": "Informa a altura base usada no cálculo de posicionamento das opções.",
+          "description": "Informa a altura base usada no cálculo de posicionamento das opções.\nDeve ser um número finito positivo; valores inválidos usam 56.",
           "values": []
         },
         {
           "name": "overscan",
-          "description": "Define quantas opções extras são renderizadas fora da viewport quando o virtual scroll está ativo.",
+          "description": "Define quantas opções extras são renderizadas fora da viewport quando o virtual scroll está ativo.\nDeve ser um inteiro não negativo; valores inválidos usam 0.",
           "values": []
         },
         {
@@ -3536,7 +3594,7 @@
         },
         {
           "name": "active-option-index",
-          "description": "Índice da opção atualmente ativa para navegação por teclado.",
+          "description": "Índice da opção atualmente ativa para navegação por teclado.\nDeve ser um inteiro maior ou igual a -1; valores inválidos usam -1.",
           "values": []
         }
       ],
@@ -3544,8 +3602,13 @@
     },
     {
       "name": "br-select-option",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).\n---\n\n\n### **Events:**\n - **brSelectOptionStateChange** - Evento emitido quando o estado da opção muda.\n- **brSelectOptionPropsChange** - Evento legado emitido quando as propriedades da opção são alteradas.\n\n### **Methods:**\n - **getItemHeight(): __** - Retorna a altura efetiva da opção para cálculo de virtual scroll.\n- **setFocus(): __** - Encaminha o foco para o elemento interativo interno da opção.\n- **setSelectedState(selected: _boolean_): _Promise<void>_** - Atualiza programaticamente o estado selecionado da opção.\n\n### **Slots:**\n - **default** - Conteúdo ou rótulo visual da opção.\n\n### **CSS Parts:**\n - **option** - Item visual da opção.\n- **checkbox** - Checkbox exibido no modo múltiplo.",
+      "description": "Subcomponente que representa uma opção individual dentro de um `br-select`.\n\n### Papel na composição\n- Define o valor de submissão (`value`) e o rótulo legível exibido para o usuário.\n- Identifica opcionalmente o grupo visual e semântico ao qual a opção pertence.\n- Exibe os estados de seleção (`selected`), desativação (`disabled`) e, no modo de seleção múltipla, o checkbox correspondente.\n- Suporta marcação com destaque textual correspondente aos filtros de busca aplicados.\n\n### Regra de uso e relacionamento\nDeve ser declarado no slot padrão do `br-select` (ou projetado pela lista). É a forma declarativa canônica de fornecer opções em código novo, inclusive quando um framework repete o elemento a partir de uma coleção. O `br-select` lê seus atributos e conteúdo, transforma-os em dados e entrega uma janela virtualizada à lista; portanto, o elemento declarado no slot é a fonte declarativa, não o item visual final da lista. Evite misturá-lo com a prop legada `options` ou com `setOptions()` sem necessidade, pois a coleção imperativa passa a ter precedência depois de ser utilizada. O item comunica suas mudanças de estado ao `br-select` pai, que por sua vez atualiza o valor geral do formulário e o resumo no campo de entrada. O `br-select-option` não deve ser utilizado fora do contexto de seleção.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/select?tab=designer).\n---\n\n\n### **Events:**\n - **brSelectOptionStateChange** - Evento emitido quando o estado da opção muda.\n- **brSelectOptionPropsChange** - Evento legado emitido quando as propriedades da opção são alteradas.\n\n### **Methods:**\n - **getItemHeight(): __** - Retorna a altura efetiva da opção para cálculo de virtual scroll.\n- **setFocus(): __** - Encaminha o foco para o elemento interativo interno da opção.\n- **setSelectedState(selected: _boolean_): _Promise<void>_** - Atualiza programaticamente o estado selecionado da opção.\n\n### **Slots:**\n - **default** - Conteúdo ou rótulo visual da opção.\n\n### **CSS Parts:**\n - **option** - Item visual da opção.\n- **checkbox** - Checkbox exibido no modo múltiplo.",
       "attributes": [
+        {
+          "name": "density",
+          "description": "Define a densidade visual da opção e do item interno.\nAceita `small`, `medium` ou `large`. Valores inválidos usam `medium`.",
+          "values": [{ "name": "BrDensity" }]
+        },
         {
           "name": "disabled",
           "description": "Desativa a interação da opção.",
@@ -3561,6 +3624,11 @@
           "description": "Rótulo textual exibido para a opção.",
           "values": []
         },
+        {
+          "name": "group",
+          "description": "Nome do grupo visual e semântico da opção dentro do `br-select`.\nString vazia é tratada como ausência de grupo.",
+          "values": []
+        },
         {
           "name": "indeterminate",
           "description": "Indica o estado intermediário da opção.",
@@ -3586,7 +3654,7 @@
     },
     {
       "name": "br-sign-in",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/sign-in?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **default** - Slot para o texto do sign-in.\n- **icon** - Slot para ícone personalizado, com padrão fa6-solid:user para shape=\"circle\".\n- **image** - Slot para imagem ou ícone ao lado do texto.\n\n### **CSS Parts:**\n - **content** - Parte para a área de conteúdo/texto do sign-in, usada para estilização via ::part().\n- **image** - Parte para a área da imagem/ícone, usada para controle de tamanho via CSS e ::part().",
+      "description": "O componente `br-sign-in` é o controle oficial de autenticação e identificação unificada do GovBR-DS, padronizado para representar o acesso via conta Gov.BR (\"Entrar com gov.br\").\n\n### Para que serve\n\n- **Identificação oficial do cidadão:** Ponto de entrada padrão para os serviços públicos digitais federais integrados ao provedor de identidade Gov.BR.\n- **Padronização visual obrigatória:** Aplica tipografia, cores institucionais, ícone da marca gov.br e dimensões em estrita conformidade com o Manual de Identidade Visual do Governo Federal.\n- **Estados de carregamento e desativação:** Suporta indicação de espera durante o redirecionamento de login.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O sistema exigir login e autenticação através da plataforma gov.br.\n- **Evite e prefira outro componente quando:**\n  - O botão executar uma ação genérica do sistema que não seja login via gov.br (prefira `br-button`).\n  - O usuário já estiver autenticado e a intenção for apenas exibir o perfil (prefira `br-avatar`).\n\n### Estrutura e Slots\n\nO `br-sign-in` é um botão de autenticação estilizado com a marca oficial do Governo Federal, recebendo propriedades de rótulo e variantes institucionais.\n\nPara 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/sign-in?tab=designer).\n---\n\n\n### **Events:**\n - **brNavigate** - Evento cancelável emitido em `navigation-mode=\"event\"` para cliques primários sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navegação nativa e entregar `event.detail.href` ao roteador da SPA.\n\n### **Slots:**\n - **default** - Slot para o texto do sign-in.\n- **icon** - Slot para ícone personalizado; em `shape=\"circle\"`, o padrão é um SVG local de usuário.\n- **image** - Slot para imagem ou ícone ao lado do texto.\n\n### **CSS Parts:**\n - **content** - Parte para a área de conteúdo/texto do sign-in, usada para estilização via ::part().\n- **image** - Parte para a área da imagem/ícone, usada para controle de tamanho via CSS e ::part().",
       "attributes": [
         {
           "name": "custom-id",
@@ -3600,7 +3668,7 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "BrDensity" }]
         },
         {
@@ -3643,7 +3711,7 @@
     },
     {
       "name": "br-skip-link",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).\n---\n\n\n### **Events:**\n - **brSkiplinkNavigation** - Evento emitido quando um item do skiplink é ativado.\nO evento contém informações sobre o item acionado e o elemento target.\n- **brSkipLinkNavigate** - Evento canônico emitido quando um destino é ativado.\n- **brDidShow** - Evento emitido quando o skiplink se torna visível.\n- **brSkipLinkShow** - Evento canônico emitido ao exibir o componente.\n- **brDidHide** - Evento emitido quando o skiplink se torna oculto.\n- **brSkipLinkHide** - Evento canônico emitido ao ocultar o componente.\n\n### **Methods:**\n - **watchModeChanges()** - Observa mudanças nos estados que afetam o modo efetivo (simple/compound)\ne atualiza as contagens dos itens quando necessário.\n- **handleItemNavigation(event: _CustomEvent<{ itemId: string; target: string }>_)** - Listener para eventos de navegação dos itens filhos.\n- **handleFocusIn()** - Listener para evento de foco no componente.\n- **handleFocusOut(event: _FocusEvent_)** - Listener para evento de perda de foco no componente.\n- **handleKeyDown(event: _KeyboardEvent_)** - Listener para a tecla Escape.\n- **hide(): _Promise<void>_** - Oculta o componente programaticamente.\n- **show(): _Promise<void>_** - Exibe o componente programaticamente.\n\n### **Slots:**\n - **default** - Slot para inserir os itens de navegação rápida (br-skiplink-item).\n\n### **CSS Parts:**\n - **container** - Parte para o contêiner principal do componente skip-link, usada para estilização via ::part().",
+      "description": "O componente `br-skip-link` é o bloco essencial de acessibilidade posicionado no topo da página, permitindo que pessoas que utilizam teclado ou tecnologias assistivas saltem blocos repetitivos e acessem diretamente áreas principais da aplicação.\n\n### Para que serve\n\n- **Atalho de teclado imediato:** Fornece links diretos (\"Ir para o conteúdo principal\", \"Ir para o menu\", \"Ir para a busca\", \"Ir para o rodapé\") logo no primeiro acionamento da tecla Tab.\n- **Conformidade WCAG obrigatória:** Atende ao critério de sucesso 2.4.1 (Bypass Blocks) da WCAG 2.1, essencial para portais e serviços públicos.\n- **Comportamento visual discreto:** Permanece oculto visualmente por padrão, tornando-se visível imediatamente assim que recebe o foco do teclado.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Obrigatoriamente em todas as páginas e aplicações do GovBR-DS, posicionado como o primeiro elemento interativo do corpo do documento.\n- **Evite e prefira outro componente quando:**\n  - O link tiver a intenção de navegação comum no corpo do texto (use `br-link`).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-skip-link` | **Orquestrador de atalhos.** Agrupa a lista de links rápidos e gerencia visibilidade no foco. | Deve ser o primeiro elemento interativo no topo da página. |\n| `br-skip-link-item` | **Item individual de atalho.** Especifica o destino e o texto do salto. | Declarado no slot padrão do `br-skip-link`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-skip-link` atua como contêiner que abriga múltiplos elementos `br-skip-link-item`. Cada item referencia o `id` do elemento de destino na página (ex.: `#main-content`), conduzindo o foco imediatamente para a região desejada.\n\nPara 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/skip-link?tab=designer).\n---\n\n\n### **Events:**\n - **brSkiplinkNavigation** - Evento emitido quando um item do skiplink é ativado.\nO evento contém informações sobre o item acionado e o elemento target.\n- **brSkipLinkNavigate** - Evento canônico emitido quando um destino é ativado.\n- **brDidShow** - Evento emitido quando o skiplink se torna visível.\n- **brSkipLinkShow** - Evento canônico emitido ao exibir o componente.\n- **brDidHide** - Evento emitido quando o skiplink se torna oculto.\n- **brSkipLinkHide** - Evento canônico emitido ao ocultar o componente.\n\n### **Methods:**\n - **watchModeChanges()** - Observa mudanças nos estados que afetam o modo efetivo (simple/compound)\ne atualiza as contagens dos itens quando necessário.\n- **handleItemNavigation(event: _CustomEvent<{ itemId: string; target: string }>_)** - Listener para eventos de navegação dos itens filhos.\n- **handleFocusIn(event: _FocusEvent_)** - Listener para evento de foco no componente.\n- **handleFocusOut(event: _FocusEvent_)** - Listener para evento de perda de foco no componente.\n- **handleKeyDown(event: _KeyboardEvent_)** - Listener para a tecla Escape.\n- **hide(): _Promise<void>_** - Oculta o componente programaticamente.\n- **show(): _Promise<void>_** - Exibe o componente programaticamente.\n\n### **Slots:**\n - **default** - Slot para inserir os itens de navegação rápida (br-skip-link-item). A tag br-skiplink-item é aceita por compatibilidade.\n\n### **CSS Parts:**\n - **container** - Parte para o contêiner principal do componente skip-link, usada para estilização via ::part().",
       "attributes": [
         {
           "name": "custom-id",
@@ -3657,17 +3725,17 @@
         },
         {
           "name": "variant",
-          "description": "Define se o skip link apresenta um ou múltiplos itens visíveis.\n- 'simple': Exibe apenas um item por vez.\n- 'compound': Exibe uma lista com múltiplos itens.",
+          "description": "Define se o skip link apresenta um ou múltiplos itens visíveis.\n- 'simple': Exibe apenas um item por vez.\n- 'compound': Exibe uma lista com múltiplos itens.\nValores inválidos usam 'compound'.",
           "values": [{ "name": "SkipLinkVariant" }]
         },
         {
           "name": "position",
-          "description": "Define a posição do skip link na tela.\n- 'top-left': Posicionado no canto superior esquerdo.\n- 'top-center': Posicionado no centro superior.\n- 'top-right': Posicionado no canto superior direito.",
+          "description": "Define a posição do skip link na tela.\n- 'top-left': Posicionado no canto superior esquerdo.\n- 'top-center': Posicionado no centro superior.\n- 'top-right': Posicionado no canto superior direito.\nValores inválidos usam 'top-left'.",
           "values": [{ "name": "SkipLinkPosition" }]
         },
         {
           "name": "z-index",
-          "description": "Define o z-index do componente.\nControla a ordem de empilhamento do componente na página.",
+          "description": "Define o z-index do componente.\nControla a ordem de empilhamento do componente na página.\nDeve ser um inteiro entre 0 e Number.MAX_SAFE_INTEGER; valores inválidos usam 0.",
           "values": []
         },
         {
@@ -3680,7 +3748,7 @@
     },
     {
       "name": "br-skip-link-item",
-      "description": "Nome canônico de `br-skiplink-item`.\n---\n\n\n### **Slots:**\n - **default** - Texto do link de navegação rápida.\n- **tag** - Conteúdo da indicação do atalho.",
+      "description": "Nome canônico de `br-skip-link-item`, usado como cada atalho dentro de `br-skip-link`.\nInforme em `target` o `id` ou seletor existente para onde o foco deve ser levado.\nUse um item por região importante da página. A tag `br-skiplink-item` é legada e não deve ser combinada com esta para o mesmo destino.\n---\n\n\n### **Methods:**\n - **itemFocus(): _Promise<void>_** - Encaminha o foco para o item legado sem expor seu Shadow DOM ao pai.\n- **navigateToTarget(): _Promise<void>_** - Encaminha a navegação para o item legado sem expor seu Shadow DOM ao pai.\n\n### **Slots:**\n - **default** - Texto do link de navegação rápida.\n- **tag** - Conteúdo da indicação do atalho.",
       "attributes": [
         {
           "name": "target",
@@ -3689,7 +3757,7 @@
         },
         {
           "name": "key-number",
-          "description": "Número do atalho de teclado.",
+          "description": "Número inteiro de 1 a 9 do atalho de teclado; valores inválidos são ignorados.",
           "values": []
         },
         {
@@ -3707,7 +3775,7 @@
     },
     {
       "name": "br-skiplink-item",
-      "description": "@deprecated Use `br-skip-link-item`.\n\nPara a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).\n---\n\n\n### **Events:**\n - **brSkiplinkItemClick** - Evento emitido quando o item é clicado/ativado.\nO evento contém informações sobre o item e o target.\n- **brSkipLinkItemActivate** - Evento canônico emitido quando o item é ativado.\n- **brSkiplinkItemFocus** - Evento emitido quando o item recebe foco.\n- **brSkipLinkItemFocus** - Evento canônico emitido quando o item recebe foco.\n\n### **Methods:**\n - **handleClick(_event: _MouseEvent_)** - Listener para cliques no item.\n- **handleKeyDown(event: _KeyboardEvent_)** - Listener para teclas Enter, Space e atalho Alt+[keyNumber].\n- **handleFocus()** - Listener para foco no item.\n- **itemFocus(): _Promise<void>_** - Move o foco para este item.\n- **navigateToTarget(): _Promise<void>_** - Navega para o target definido.\nMove o foco para o elemento alvo e ajusta a rolagem da página se necessário.\n\n### **Slots:**\n - **default** - Slot para o texto do link de navegação rápida.\n- **tag** - Slot para personalizar a tag numérica do atalho de teclado, exibindo o valor de key-number por padrão.",
+      "description": "@deprecated Use `br-skip-link-item`.\n\nSubcomponente individual de `br-skip-link`, utilizado para declarar cada atalho específico de salto de bloco acessível.\n\n### Papel na composição\n\n- Define o texto descritivo do atalho (ex.: \"Ir para o conteúdo\") e o identificador do alvo na página (`targetId` ou `href`).\n- Transfere o foco programático e visual diretamente para o elemento alvo ao ser acionado com Enter ou espaço.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado no slot padrão do orquestrador `br-skip-link`. Cada item deve apontar para um elemento existente na página dotado de `id` e foco acessível (`tabindex=\"-1\"`). Não deve ser usado fora do contexto do skip-link.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/skip-link?tab=designer).\n---\n\n\n### **Events:**\n - **brSkiplinkItemClick** - Evento emitido quando o item é clicado/ativado.\nO evento contém informações sobre o item e o target.\n- **brSkipLinkItemActivate** - Evento canônico emitido quando o item é ativado.\n- **brSkiplinkItemFocus** - Evento emitido quando o item recebe foco.\n- **brSkipLinkItemFocus** - Evento canônico emitido quando o item recebe foco.\n\n### **Methods:**\n - **handleClick(_event: _MouseEvent_)** - Listener para cliques no item.\n- **handleKeyDown(event: _KeyboardEvent_)** - Listener para teclas Enter, Space e atalho Alt+[keyNumber].\n- **handleFocus()** - Listener para foco no item.\n- **itemFocus(): _Promise<void>_** - Move o foco para este item.\n- **navigateToTarget(): _Promise<void>_** - Navega para o target definido.\nMove o foco para o elemento alvo e ajusta a rolagem da página se necessário.\n\n### **Slots:**\n - **default** - Slot para o texto do link de navegação rápida.\n- **tag** - Slot para personalizar a tag numérica do atalho de teclado, exibindo o valor de key-number por padrão.",
       "attributes": [
         {
           "name": "target",
@@ -3716,7 +3784,7 @@
         },
         {
           "name": "key-number",
-          "description": "Número da tecla para acesso rápido.\nPermite que o usuário ative este item pressionando Alt+[keyNumber].\nAceita valores de 1 a 9.\nEsta propriedade implementa uma alternativa ao accessKey nativa,\nfornecendo um atalho de teclado consistente e acessível.",
+          "description": "Número da tecla para acesso rápido.\nPermite que o usuário ative este item pressionando Alt+[keyNumber].\nAceita valores de 1 a 9.\nEsta propriedade implementa uma alternativa ao accessKey nativa,\nfornecendo um atalho de teclado consistente e acessível.\nValores inválidos são ignorados.",
           "values": []
         },
         {
@@ -3734,7 +3802,7 @@
     },
     {
       "name": "br-slider",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/slider?tab=designer).\n---\n\n\n### **Events:**\n - **brDidChangeValue** - Disparado após alteração do valor da alça inicial.\n- **brDidChangeValueEnd** - Disparado após alteração do valor da alça final (modo composto).\n- **brSliderValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna se o slider atende às constraints configuradas.\n- **reportValidity(): _Promise<boolean>_** - Valida e solicita ao navegador a apresentação do erro atual.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define ou limpa uma mensagem de validade customizada.\n- **validate(): _Promise<boolean>_** - Executa o validator do slider e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n\n### **Slots:**\n - **ref-start** - Conteúdo exibido como referência inicial abaixo da trilha.\n- **ref-end** - Conteúdo exibido como referência final abaixo da trilha.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **base** - Contêiner principal do slider.\n- **layout** - Contêiner de layout do slider.\n- **body** - Área que agrupa trilha e referências.\n- **track** - Área interativa da trilha.\n- **track-visual** - Trilha visual do slider.\n- **tick-labels** - Contêiner das etiquetas das marcações.\n- **tick-label** - Etiqueta de uma marcação intermediária.\n- **filled-track** - Trecho preenchido da trilha.\n- **value-label** - Etiqueta com o valor da alça.\n- **value-label-arrow** - Seta da etiqueta de valor.\n- **thumb** - Alça de controle do slider.\n- **thumb-start** - Alça inicial do slider.\n- **thumb-end** - Alça final do slider em modo composto.\n- **references** - Contêiner das referências inicial e final.\n- **reference-start** - Referência inicial.\n- **reference-end** - Referência final.\n- **reference-bound** - Valor fixo de limite renderizado por `show-bounds`.\n- **input-wrapper** - Contêiner do campo numérico.\n- **input** - Campo numérico sincronizado com o slider.\n- **feedback** - Contêiner da mensagem de validação.",
+      "description": "O componente `br-slider` é o controle deslizante do GovBR-DS, desenvolvido para permitir que a pessoa usuária selecione um valor numérico único ou uma faixa contínua de valores dentro de um intervalo delimitado.\n\n### Para que serve\n\n- **Seleção numérica fluida:** Permite escolher valores deslizando uma alça (thumb) ao longo de uma trilha graduada, com atualização em tempo real.\n- **Modo simples e composto (faixa / range):** Suporta uma única alça para valor individual ou duas alças para delimitação de intervalo mínimo e máximo (ex.: faixa de preços, período de anos).\n- **Entrada numérica sincronizada:** Oferece campo de entrada numérico integrado opcional para digitação exata com sincronização bidirecional.\n- **Acessibilidade WAI-ARIA:** Suporta controle total por teclado (setas direcionais, Page Up, Page Down, Home e End) e comunica valores atuais via `aria-valuenow`.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O usuário precisar definir grandezas graduais onde a exploração intuitiva seja mais conveniente do que a digitação manual isolada.\n  - Para filtros de faixa de valores (ex.: \"De R$ 100 até R$ 500\").\n- **Evite e prefira outro componente quando:**\n  - A precisão exata for estritamente necessária e o intervalo for arbitrário (prefira `br-input` numérico).\n  - O valor for uma escolha categórica sem escala quantitativa (prefira `br-select` ou `br-radio`).\n\n### Estrutura e Slots\n\nO `br-slider` possui estrutura rica com slots de referência, validação e customização da alça:\n- `ref-start`: Slot para customização do rótulo de início da trilha.\n- `ref-end`: Slot para customização do rótulo de fim da trilha.\n- `feedback`: Slot para mensagens de validação (como `br-message`).\n- `thumb-icon`: Slot para ícone personalizado na alça de controle em modo simples.\n- `thumb-start-icon`: Slot para ícone na alça inicial em modo composto (`range`).\n- `thumb-end-icon`: Slot para ícone na alça final em modo composto (`range`).\n\nPara 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/slider?tab=designer).\n---\n\n\n### **Events:**\n - **brDidChangeValue** - Disparado após alteração do valor da alça inicial.\n- **brDidChangeValueEnd** - Disparado após alteração do valor da alça final (modo composto).\n- **brSliderValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna se o slider atende às constraints configuradas.\n- **reportValidity(): _Promise<boolean>_** - Valida e solicita ao navegador a apresentação do erro atual.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define ou limpa uma mensagem de validade customizada.\n- **validate(): _Promise<boolean>_** - Executa o validator do slider e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n\n### **Slots:**\n - **ref-start** - Conteúdo exibido como referência inicial abaixo da trilha.\n- **ref-end** - Conteúdo exibido como referência final abaixo da trilha.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n- **thumb-icon** - Ícone customizado na alça de controle em modo simples.\n- **thumb-start-icon** - Ícone customizado na alça inicial em modo composto.\n- **thumb-end-icon** - Ícone customizado na alça final em modo composto.\n\n### **CSS Parts:**\n - **base** - Contêiner principal do slider.\n- **layout** - Contêiner de layout do slider.\n- **body** - Área que agrupa trilha e referências.\n- **track** - Área interativa da trilha.\n- **track-visual** - Trilha visual do slider.\n- **tick-labels** - Contêiner das etiquetas das marcações.\n- **tick-label** - Etiqueta de uma marcação intermediária.\n- **filled-track** - Trecho preenchido da trilha.\n- **value-label** - Etiqueta com o valor da alça.\n- **value-label-arrow** - Seta da etiqueta de valor.\n- **thumb** - Alça de controle do slider.\n- **thumb-start** - Alça inicial do slider.\n- **thumb-end** - Alça final do slider em modo composto.\n- **references** - Contêiner das referências inicial e final.\n- **reference-start** - Referência inicial.\n- **reference-end** - Referência final.\n- **reference-bound** - Valor fixo de limite renderizado por `show-bounds`.\n- **input-wrapper** - Contêiner do campo numérico.\n- **input** - Campo numérico sincronizado com o slider.\n- **feedback** - Contêiner da mensagem de validação.\n- **steps** - Contêiner das marcações de passos customizados.\n- **step** - Botão indicador de passo customizado individual.",
       "attributes": [
         {
           "name": "custom-id",
@@ -3753,37 +3821,37 @@
         },
         {
           "name": "min",
-          "description": "Valor mínimo aceito pelo slider.",
+          "description": "Valor mínimo aceito pelo slider. Valores inválidos usam `0`.",
           "values": []
         },
         {
           "name": "max",
-          "description": "Valor máximo aceito pelo slider.",
+          "description": "Valor máximo aceito pelo slider. Deve ser maior que `min`; valores inválidos usam `100` e relações inválidas usam `min + 100`.",
           "values": []
         },
         {
           "name": "step",
-          "description": "Incremento aplicado a cada passo.",
+          "description": "Incremento aplicado a cada passo. Deve ser maior que `0`; valores inválidos usam `1`.",
           "values": []
         },
         {
           "name": "validator",
-          "description": "Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado.",
+          "description": "Regra síncrona ou assíncrona aplicada ao número ou intervalo selecionado.\nNo modo `range`, recebe um objeto com `start` e `end`.",
           "values": [{ "name": "SliderValidator" }]
         },
         {
           "name": "value",
-          "description": "Valor atual do slider (alça inicial no modo composto).",
+          "description": "Valor atual do slider (alça inicial no modo composto). Valores não finitos usam o limite mínimo;\nvalores fora do intervalo são limitados.",
           "values": []
         },
         {
           "name": "value-end",
-          "description": "Valor da alça final no modo composto (`range`).\nQuando não fornecido em modo composto, assume o valor de `max`.",
+          "description": "Valor da alça final no modo composto (`range`).\nQuando não fornecido em modo composto, assume o valor de `max`. Valores não finitos usam `max`,\nvalores fora do intervalo são limitados.",
           "values": []
         },
         {
           "name": "range-value",
-          "description": "Valor estruturado das duas alças no modo `range`.",
+          "description": "Valor estruturado das duas alças no modo `range`.\nDeve conter `start` e `end` finitos; valores inválidos mantêm o último valor efetivo.\nPasse o objeto por property binding.",
           "values": [{ "name": "SliderRangeValue" }]
         },
         {
@@ -3791,11 +3859,6 @@
           "description": "Desativa o slider, tornando-o não interativo.",
           "values": []
         },
-        {
-          "name": "density",
-          "description": "Densidade da alça de controle.\n`small` = 16px (desktop compacto), `medium` = 20px (desktop padrão), `large` = 24px (mobile).",
-          "values": [{ "name": "SliderDensity" }]
-        },
         {
           "name": "vertical",
           "description": "Exibe o slider na orientação vertical.",
@@ -3803,7 +3866,7 @@
         },
         {
           "name": "orientation",
-          "description": "Orientação canônica. Quando informada, tem precedência sobre `vertical`.",
+          "description": "Orientação canônica. Quando informada, tem precedência sobre `vertical`; valores inválidos usam `horizontal`.",
           "values": [{ "name": "horizontal" }, { "name": "vertical" }]
         },
         {
@@ -3818,7 +3881,7 @@
         },
         {
           "name": "show-input",
-          "description": "Exibe campo de entrada numérico sincronizado com a alça.\nQuando ativo, a etiqueta de valor não é exibida.",
+          "description": "Exibe um `br-input` numérico sincronizado com a alça.\nNo modo `range`, exibe um campo para o início e outro para o fim; na\norientação horizontal ficam nas extremidades esquerda e direita, e na\nvertical ficam acima e abaixo da trilha. Quando ativo, a etiqueta de valor\nnão é exibida.",
           "values": []
         },
         {
@@ -3835,57 +3898,87 @@
           "name": "show-bounds",
           "description": "Exibe os limites nas referências inicial e final: `min` no início e `max` no fim\n(limites fixos), tanto em modo simples quanto em modo composto (`range`). O valor\nselecionado por cada alça é exibido na etiqueta (`show-label`), não nas referências.\nQuando ativo, sobrescreve o conteúdo dos slots `ref-start` e `ref-end`.",
           "values": []
+        },
+        {
+          "name": "density",
+          "description": "Densidade visual do componente.\nAltera exclusivamente as dimensões da alça de controle (thumb).\nValores aceitos: 'small' (16px), 'medium' (20px - padrão), 'large' (24px).\n'high' e 'low' são aceitos como sinônimos de 'small' e 'large'.",
+          "values": [{ "name": "SliderDensity" }]
+        },
+        {
+          "name": "thumb-icon",
+          "description": "Nome do ícone a ser exibido no interior da alça de controle (thumb).\nNo modo `range`, aplica-se a ambas as alças caso `thumbStartIcon` ou `thumbEndIcon` não sejam especificados.\nExemplo: 'fa-solid:arrows-left-right', 'fa-solid:circle'.",
+          "values": []
+        },
+        {
+          "name": "thumb-start-icon",
+          "description": "Nome do ícone da alça inicial (no modo `range`, alça à esquerda/inferior).",
+          "values": []
+        },
+        {
+          "name": "thumb-end-icon",
+          "description": "Nome do ícone da alça final (no modo `range`, alça à direita/superior).",
+          "values": []
+        },
+        {
+          "name": "gradient",
+          "description": "Habilita gradiente de cores na trilha e sincroniza dinamicamente a cor da alça (thumb)\ne da etiqueta de valor (tooltip) com a cor correspondente à posição atual.\nPode ser um booleano (usa gradiente padrão verde -> amarelo -> vermelho)\nou uma string com cores/gradiente customizado (ex.: '#168821, #ffcd07, #e52207' ou 'linear-gradient(...)').",
+          "values": []
+        },
+        {
+          "name": "steps",
+          "description": "Lista de passos customizados para o slider.\nCada passo pode definir `value`, `label` (texto exibido no tooltip e/ou abaixo da trilha)\ne `icon` (nome do ícone exibido abaixo da marcação do passo).\nAceita array de objetos `SliderStep[]`, array de strings `string[]`, ou string JSON.",
+          "values": [{ "name": "SliderStep[]" }]
         }
       ],
       "references": []
     },
     {
       "name": "br-step",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/step?tab=designer).\n---\n\n\n### **Events:**\n - **brStepChange** - Emite um evento quando o step ativo muda.\nO evento carrega o índice do novo step ativo (0-based).\n\n### **Methods:**\n - **activeStepChanged(newValue: _number_, oldValue: _number_)** - Observa mudanças na etapa ativa e sincroniza os itens filhos.\n- **initialStepChanged(newValue: _string | number_, oldValue: _string | number_)** - Observa mudanças no passo inicial e atualiza a etapa ativa.\n- **labelPositionChanged()** - Observa mudanças na posição do label e propaga aos itens.\n- **contentTypeChanged()** - Observa mudanças no tipo de conteúdo e propaga aos itens.\n- **modeChanged(newValue: _StepMode_)** - Observa mudanças no modo e propaga aos itens.\n- **layoutChanged()** - Observa mudanças no layout e atualiza a linha do tempo dos itens.\n- **progressionTypeChanged()** - Observa mudanças no tipo de progressão e atualiza itens desabilitados.\n- **verticalContentPlacementChanged()** - Observa mudanças na posição do conteúdo vertical e propaga aos itens.\n- **handleClick(event: _MouseEvent_)** - listener para ouvir o evento de click no componente step\nAtravés desse listener o componente define qual será o proximo passo do step que terá o estado ativo\n- **ProceedToNextStep()** - @deprecated Use `next`. - Método disponibilizado via API do elemento que controla o componente Step, responsável por avançar para o próximo passo e atualizar o valor do estado activeStep\n- **next(): _Promise<void>_** - Avança para o próximo passo.\n- **BackToPreviousStep()** - @deprecated Use `previous`. - Método disponibilizado via API do elemento que controla o componente Step, responsável por retornar ao passo anterior e atualizar o valor do estado activeStep\n- **previous(): _Promise<void>_** - Retorna ao passo anterior.\n- **StepValidation(validationStatus: _StepValidationStatus_)** - @deprecated Use `setCurrentValidation`. - Método disponibilizado via API do elemento que integra um componente externo ao componente Step, permitindo sinalizar validações ou destacar a etapa com estado ativo.\n- **setCurrentValidation(validationStatus: _StepValidationStatus_): _Promise<void>_** - Define o estado de validação do passo ativo.\n- **GetActiveStep()** - \nMétodo disponibilizado via API do elemento que permite a um componente externo obter a etapa com o estado ativo do componente Step.\n\n### **Slots:**\n - **default** - Slot para os itens do step (br-step-item), aceitando apenas esse componente.\n\n### **CSS Parts:**\n - **container** - Parte para o contêiner principal envolvendo todos os step-items, usada para estilizar layout geral via ::part().",
+      "description": "O componente `br-step` é o indicador visual de etapas e progresso do GovBR-DS, desenvolvido para orientar a pessoa usuária ao longo de fluxos sequenciais e processos com múltiplos passos.\n\n### Para que serve\n\n- **Visualização de progresso:** Informa claramente em qual etapa do processo o usuário se encontra, quais já foram concluídas e quais ainda estão pendentes.\n- **Orientação flexível:** Suporta leiaute horizontal (ideal para telas amplas) e vertical (ideal para fluxos em barra lateral ou dispositivos móveis).\n- **Semântica e acessibilidade WAI-ARIA:** Comunica o passo ativo através de `aria-current=\"step\"` e indica etapas concluídas ou bloqueadas.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - O fluxo tiver entre 2 e 5 etapas lógicas com uma sequência recomendada de execução (ex.: Identificação > Dados > Pagamento > Confirmação).\n- **Evite e prefira outro componente quando:**\n  - A pessoa usuária puder alternar livremente entre as seções em qualquer ordem sem dependência de progresso (prefira `br-tab`).\n  - For necessário um contêiner completo que gerencie também os painéis de formulário e botões de avançar/voltar (prefira `br-wizard`).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-step` | **Orquestrador de progresso.** Gerencia a orientação, conecta as linhas de fluxo e calcula os estados das etapas. | Contêiner raiz da barra de progresso. |\n| `br-step-item` | **Etapa individual.** Representa cada passo com número, rótulo e estado. | Declarado dentro do slot padrão do `br-step`. |\n\n### Como os subcomponentes se relacionam\n\nO componente pai `br-step` recebe múltiplos elementos `br-step-item` em seu slot padrão:\n1. Com base na propriedade `current` ou nos índices declarados, o pai calcula as linhas conectoras visuais entre as etapas.\n2. Sincroniza os estados de cada etapa: concluída (`completed`), ativa (`active`) ou desabilitada (`disabled`).\n\nPara 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/step?tab=designer).\n---\n\n\n### **Events:**\n - **brStepChange** - Emite um evento quando o step ativo muda.\nO evento carrega o índice do novo step ativo (0-based).\n\n### **Methods:**\n - **activeStepChanged(newValue: _number_, oldValue: _number_)** - Observa mudanças na etapa ativa e sincroniza os itens filhos.\n- **initialStepChanged(newValue: _string | number_, oldValue: _string | number_)** - Observa mudanças no passo inicial e atualiza a etapa ativa.\n- **labelPositionChanged()** - Observa mudanças na posição do label e propaga aos itens.\n- **contentTypeChanged()** - Observa mudanças no tipo de conteúdo e propaga aos itens.\n- **modeChanged(_newValue: _StepMode_)** - Observa mudanças no modo e propaga aos itens.\n- **layoutChanged()** - Observa mudanças no layout e atualiza a linha do tempo dos itens.\n- **progressionTypeChanged()** - Observa mudanças no tipo de progressão e atualiza itens desabilitados.\n- **verticalContentPlacementChanged()** - Observa mudanças na posição do conteúdo vertical e propaga aos itens.\n- **handleClick(event: _MouseEvent_)** - listener para ouvir o evento de click no componente step\nAtravés desse listener o componente define qual será o proximo passo do step que terá o estado ativo\n- **ProceedToNextStep()** - @deprecated Use `next`. - \nMétodo disponibilizado via API do elemento que controla o componente Step, responsável por avançar para o próximo passo e atualizar o valor do estado activeStep\n- **next(): _Promise<void>_** - Avança para o próximo passo.\n- **BackToPreviousStep()** - @deprecated Use `previous`. - \nMétodo disponibilizado via API do elemento que controla o componente Step, responsável por retornar ao passo anterior e atualizar o valor do estado activeStep\n- **previous(): _Promise<void>_** - Retorna ao passo anterior.\n- **StepValidation(validationStatus: _StepValidationStatus_)** - @deprecated Use `setCurrentValidation`. - \nMétodo disponibilizado via API do elemento que integra um componente externo ao componente Step, permitindo sinalizar validações ou destacar a etapa com estado ativo.\n- **setCurrentValidation(validationStatus: _StepValidationStatus_): _Promise<void>_** - Define o estado de validação do passo ativo.\n- **GetActiveStep()** - \nMétodo disponibilizado via API do elemento que permite a um componente externo obter a etapa com o estado ativo do componente Step.\n\n### **Slots:**\n - **default** - Slot para os itens do step (br-step-item), aceitando apenas esse componente.\n\n### **CSS Parts:**\n - **container** - Parte para o contêiner principal envolvendo todos os step-items, usada para estilizar layout geral via ::part().",
       "attributes": [
         {
           "name": "layout",
-          "description": "propriedade responsável por definir a orientação do componente Step",
+          "description": "propriedade responsável por definir a orientação do componente Step. Valores inválidos usam `horizontal`.",
           "values": [{ "name": "BrOrientation" }]
         },
         {
           "name": "orientation",
-          "description": "Orientação do componente. Quando informada, tem precedência sobre `layout`.",
+          "description": "Orientação do componente. Quando informada, tem precedência sobre `layout`; valores inválidos usam `horizontal`.",
           "values": [{ "name": "BrOrientation" }]
         },
         {
           "name": "initial-step",
-          "description": "\ndefine o passo que começará destacado",
+          "description": "\ndefine o passo que começará destacado. Valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "initial-index",
-          "description": "Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`.",
+          "description": "Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "label-position",
-          "description": "\nPropriedade que  define a posição onde o texto de destaque,label, ficará localizado no stepItem",
+          "description": "\nPropriedade que define a posição onde o texto de destaque, label, ficará localizado no stepItem. Valores inválidos usam `bottom`.",
           "values": [{ "name": "StepLabelPosition" }]
         },
         {
           "name": "content-type",
-          "description": "\nPropriedade que define o tipo de conteúdo a ser exibido dentro do componente step  e stepItem",
+          "description": "\nPropriedade que define o tipo de conteúdo a ser exibido dentro do componente step e stepItem. Valores inválidos usam `default`.",
           "values": [{ "name": "StepContentType" }]
         },
         {
           "name": "mode",
-          "description": "\nPropriedade que define o tipo de comportamento que o componente Step deverá seguir",
+          "description": "\nPropriedade que define o tipo de comportamento que o componente Step deverá seguir. Valores inválidos usam `step`.",
           "values": [{ "name": "StepMode" }]
         },
         {
           "name": "progression-type",
-          "description": "\nPropriedade que define o tipo de progressão de etapas que o step vai executar",
+          "description": "\nPropriedade que define o tipo de progressão de etapas que o step vai executar. Valores inválidos usam `nonlinear`.",
           "values": [{ "name": "BrProgressionType" }]
         },
         {
           "name": "vertical-content-placement",
-          "description": "Define a posição do conteúdo de cada etapa no layout vertical.\n- `between`: conteúdo abaixo do indicador/rótulo, entre as etapas.\n- `side`: conteúdo em coluna lateral à linha de indicadores.",
+          "description": "Define a posição do conteúdo de cada etapa no layout vertical.\n- `between`: conteúdo abaixo do indicador/rótulo, entre as etapas.\n- `side`: conteúdo em coluna lateral à linha de indicadores.\nValores inválidos usam `between`.",
           "values": [{ "name": "StepVerticalContentPlacement" }]
         }
       ],
@@ -3893,7 +3986,7 @@
     },
     {
       "name": "br-step-item",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/step?tab=designer).\n---\n\n\n### **Methods:**\n - **setStepItemPositionStatus(value: _StepItemPositionStatus_)** - \nMétodo disponibilizado via api do elemento que indica a posição do step item, ele serve para setar o state stepItemPositionStatus do componente\n- **handleShowTimeLine(value: _boolean_, layout: _StepItemLayout_)** - Método que define a orientação do stepItem e controla a exibição da linha do tempo após o componente.\n- **setLabelPosition(value: _StepItemLabelPosition_)** - \nMétodo disponibilizado via api do elemento que atribui o valor ao estado que define onde o label, o texto de destaque, irá ficar localizado\n- **setContentType(value: _StepItemContentType_)** - \nMétodo disponibilizado via api do elemento que atribui o valor que irá definir o tipo de conteúdo apresentado dentro do componente stepItem\n- **setMode(value: _StepItemMode_)** - \nMétodo disponibilizado via api do elemento que atribui o valor que irá definir o modo como o componente irá se comportar e exibir seu estilo.\n- **setItemRole(value: _StepItemRole_)** - Define o role ARIA do botão interno.\nChamado pelo componente pai quando o contexto semântico exige um role\ndiferente do padrão `option` (ex.: `tab` em contexto de tablist).\n- **setContent(value: _string_)** - \nMétodo disponibilizado via api do elemento que atribui o valor que irá ser exibido dentro do componente stepItem\n- **setVerticalContentPlacement(value: _StepItemVerticalContentPlacement_)** - Método que define a posição do conteúdo no layout vertical.\n\n### **Slots:**\n - **content-area** - Slot para conteúdo customizado dentro do botão do item do step.\n- **step-content** - Slot para conteúdo da etapa exibido no layout vertical (texto, formulário, etc.).\n\n### **CSS Parts:**\n - **label** - Parte para o contêiner do texto da etapa, usada para estilizar tipografia e cor via ::part().",
+      "description": "Subcomponente individual de `br-step`, responsável por representar visualmente e semanticamente uma etapa específica do fluxo.\n\n### Papel na composição\n\n- Exibe o indicador numérico ou ícone da etapa, o rótulo descritivo e o estado de conclusão.\n- Permite navegação interativa opcional caso etapas anteriores possam ser revisitadas diretamente com clique.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado no slot padrão do orquestrador `br-step`. O componente pai calcula a orientação (horizontal ou vertical), as linhas de conexão intermediárias e aplica os atributos de acessibilidade da etapa atual. Não deve ser usado fora de um `br-step`.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/step?tab=designer).\n---\n\n\n### **Methods:**\n - **setStepItemPositionStatus(value: _StepItemPositionStatus_)** - \nMétodo disponibilizado via api do elemento que indica a posição do step item, ele serve para setar o state stepItemPositionStatus do componente\n- **handleShowTimeLine(value: _boolean_, layout: _StepItemLayout_)** - Método que define a orientação do stepItem e controla a exibição da linha do tempo após o componente.\n- **setLabelPosition(value: _StepItemLabelPosition_)** - \nMétodo disponibilizado via api do elemento que atribui o valor ao estado que define onde o label, o texto de destaque, irá ficar localizado\n- **setContentType(value: _StepItemContentType_)** - \nMétodo disponibilizado via api do elemento que atribui o valor que irá definir o tipo de conteúdo apresentado dentro do componente stepItem\n- **setMode(value: _StepItemMode_)** - \nMétodo disponibilizado via api do elemento que atribui o valor que irá definir o modo como o componente irá se comportar e exibir seu estilo.\n- **setItemRole(value: _StepItemRole_)** - Define o role ARIA do botão interno.\nChamado pelo componente pai quando o contexto semântico exige um role\ndiferente do padrão `option` (ex.: `tab` em contexto de tablist).\n- **setContent(value: _string_)** - \nMétodo disponibilizado via api do elemento que atribui o valor que irá ser exibido dentro do componente stepItem\n- **setVerticalContentPlacement(value: _StepItemVerticalContentPlacement_)** - Método que define a posição do conteúdo no layout vertical.\n\n### **Slots:**\n - **content-area** - Slot para conteúdo customizado dentro do botão do item do step.\n- **step-content** - Slot para conteúdo da etapa exibido no layout vertical (texto, formulário, etc.).\n\n### **CSS Parts:**\n - **label** - Parte para o contêiner do texto da etapa, usada para estilizar tipografia e cor via ::part().",
       "attributes": [
         {
           "name": "label",
@@ -3927,7 +4020,7 @@
         },
         {
           "name": "br-icon-name",
-          "description": "Nome Iconify do ícone exibido como conteúdo do step item quando `contentType` é `br-icon`.",
+          "description": "Identificador legado do ícone exibido como conteúdo do step item quando `contentType` é `br-icon`.\nPrefira o slot `content-area` com um SVG ou elemento de ícone controlado pela aplicação.",
           "values": []
         },
         {
@@ -3940,7 +4033,7 @@
     },
     {
       "name": "br-switch",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/switch?tab=designer).\n---\n\n\n### **Events:**\n - **checkedChange** - Disparado depois que o valor do `checked` foi alterado.\n- **brSwitchValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do switch for válido, caso contrário `false`.\nSe o switch for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do componente for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o switch.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do switch e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **toggleChecked()** - @deprecated Atualize a propriedade `checked` diretamente. - Inverte o valor da prop `checked`\n\n### **Slots:**\n - **default** - Slot para o rótulo do switch, com prioridade sobre a propriedade label.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do switch.\n- **input** - Elemento input nativo com role switch.\n- **label** - Rótulo do switch.\n- **data** - Elemento com textos de estado ligado/desligado.\n- **feedback** - Contêiner da mensagem de validação.",
+      "description": "O componente `br-switch` é o interruptor de alternância do GovBR-DS, desenvolvido para ativar ou desativar instantaneamente um recurso, modo ou configuração na interface.\n\n### Para que serve\n\n- **Alternância binária imediata:** Alterna entre dois estados mutuamente exclusivos (ligado/desligado, ativo/inativo, habilitado/desabilitado) com efeito imediato na aplicação.\n- **Rótulo contextual dinâmico:** Suporta textos explicativos de estado (ex.: \"Ativado\" / \"Desativado\") e ícones de apoio.\n- **Acessibilidade nativa WAI-ARIA:** Utiliza internamente o papel semântico `role=\"switch\"` com o atributo `aria-checked`, garantindo anúncio claro de estado para leitores de tela.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A alteração de estado entrar em vigor imediatamente após a interação, sem depender de um botão \"Salvar\" ou submissão de formulário.\n  - Para preferências do sistema (ex.: \"Tema escuro\", \"Notificações ativas\", \"Wi-Fi ligado\").\n- **Evite e prefira outro componente quando:**\n  - A escolha fizer parte de um formulário com múltiplos campos que serão submetidos juntos (prefira `br-checkbox`).\n  - A escolha for entre duas opções com nomes explícitos diferentes de ligado/desligado (prefira `br-radio`).\n\n### Estrutura e Slots\n\nO `br-switch` é um controle direto:\n- `default`: Slot para personalização do rótulo descritivo do switch (com prioridade sobre a propriedade `label`).\n- `feedback`: Slot para mensagens de validação contextual (como `br-message`).\n\nPara 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/switch?tab=designer).\n---\n\n\n### **Events:**\n - **checkedChange** - Disparado depois que o valor do `checked` foi alterado.\n- **brSwitchValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do switch for válido, caso contrário `false`.\nSe o switch for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do componente for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o switch.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do switch e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **toggleChecked()** - @deprecated Atualize a propriedade `checked` diretamente. - Inverte o valor da prop `checked`\n\n### **Slots:**\n - **default** - Slot para o rótulo do switch, com prioridade sobre a propriedade label.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **container** - Contêiner visual do switch.\n- **input** - Elemento input nativo com role switch.\n- **label** - Rótulo do switch.\n- **data** - Elemento com textos de estado ligado/desligado.\n- **feedback** - Contêiner da mensagem de validação.",
       "attributes": [
         {
           "name": "disabled",
@@ -3954,7 +4047,7 @@
         },
         {
           "name": "validator",
-          "description": "Regra síncrona ou assíncrona aplicada ao estado booleano do switch.",
+          "description": "Regra síncrona ou assíncrona aplicada ao estado booleano do switch.\nRetorne uma mensagem para invalidar ou `null` para aceitar o valor.",
           "values": [{ "name": "SwitchValidator" }]
         },
         {
@@ -3974,7 +4067,7 @@
         },
         {
           "name": "label-position",
-          "description": "Posição do rótulo em relação ao switch.",
+          "description": "Posição do rótulo em relação ao switch. Valores inválidos usam `left`.",
           "values": [{ "name": "right" }, { "name": "left" }, { "name": "top" }]
         },
         {
@@ -4009,7 +4102,7 @@
         },
         {
           "name": "density",
-          "description": "Ajusta a área de interação: `small` é compacto, `medium` é o padrão e `large` é mais espaçado.",
+          "description": "Ajusta a área de interação: `small` é compacto, `medium` é o padrão e `large` é mais espaçado.\nValores inválidos usam `medium`.",
           "values": [
             { "name": "large" },
             { "name": "medium" },
@@ -4021,7 +4114,7 @@
     },
     {
       "name": "br-tab",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tab?tab=designer).\n---\n\n\n### **Events:**\n - **brTabChange** - Evento disparado quando um tab é ativado.\n\n### **Methods:**\n - **activeTabChanged(newId: _string_)** - Observa mudanças no tab ativo para atualizar os estados\n- **colorModeChanged(newValue: _string_)** - Observa mudanças no color mode para propagar aos filhos\n- **handleTabItemPropsChange()** - Escuta evento de mudança de propriedades dos tab-items filhos.\nEste listener garante que o componente pai seja re-renderizado quando\npropriedades mudam dinamicamente, sincronizando o painel ativo.\n- **setActiveTab(tabId: _string_): _Promise<void>_** - Ativa programaticamente uma aba a partir do seu identificador.\n- **getActiveTab(): _Promise<string | undefined>_** - Retorna o identificador da aba ativa atual.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para inserir os itens das abas (br-tab-item)\n\n### **CSS Parts:**\n - **container** - Contêiner principal que envolve toda a estrutura do componente (navegação e conteúdo). Expõe o elemento para customizações de fundo, bordas e espaçamentos globais.\n- **nav** - Área de navegação (`tablist`) onde os botões das abas estão localizados. Permite customizar o alinhamento, espaçamento e plano de fundo da barra de abas.\n- **button** - Botão individual de cada aba.\n- **indicator** - Indicador visual da aba ativa.\n- **content** - Área de conteúdo das abas.",
+      "description": "O componente `br-tab` é o organizador de navegação por abas do GovBR-DS, desenvolvido para permitir que a pessoa usuária alterne entre diferentes visões ou painéis de conteúdo correlacionados sem sair da mesma página.\n\n### Para que serve\n\n- **Segmentação de conteúdo em mesmo nível:** Agrupa informações que compartilham o mesmo contexto geral (ex.: \"Visão Geral\", \"Especificações\", \"Histórico\", \"Anexos\").\n- **Economia de espaço vertical:** Evita rolagens excessivas na página mantendo apenas o painel selecionado visível no momento.\n- **Navegação acessível WAI-ARIA Tablist:** Implementa o padrão oficial de abas acessíveis: papéis semânticos `tablist`, `tab` e `tabpanel`, com controle total por setas do teclado e foco cíclico.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Houver conjuntos equivalentes de informação entre os quais a pessoa usuária pode navegar livremente e em qualquer ordem.\n- **Evite e prefira outro componente quando:**\n  - O conteúdo for sequencial com dependência de avanço ou conclusão de etapas anteriores (prefira `br-step` ou `br-wizard`).\n  - As abas tiverem a função de navegar para rotas e URLs distintas da aplicação (prefira uma barra de links com `br-link` ou `br-header`).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-tab` | **Orquestrador de abas.** Constrói a barra de navegação acessível (`tablist`), controla a aba ativa e gerencia o teclado. | Contêiner raiz obrigatório declarado no template. |\n| `br-tab-item` | **Aba e painel associado.** Define simultaneamente o rótulo do botão da aba e o conteúdo do painel correspondente. | Declarado no slot padrão do `br-tab`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-tab` adota uma arquitetura declarativa prática:\n1. A aplicação declara os elementos `br-tab-item` dentro do slot padrão do `br-tab`.\n2. O componente pai extrai os rótulos e ícones de cada item para renderizar a barra superior de abas (`role=\"tab\"`).\n3. O pai controla a visibilidade dos painéis (`role=\"tabpanel\"`), exibindo exclusivamente o conteúdo da aba selecionada e garantindo a correlação de IDs acessíveis (`aria-controls`, `aria-labelledby`).\n\nPara 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/tab?tab=designer).\n---\n\n\n### **Events:**\n - **brTabChange** - Evento disparado quando um tab é ativado.\n\n### **Methods:**\n - **activeTabChanged(newId: _string_)** - Observa mudanças no tab ativo para atualizar os estados\n- **colorModeChanged(_newValue: _string_)** - Observa mudanças no color mode para propagar aos filhos\n- **handleTabItemPropsChange()** - Escuta evento de mudança de propriedades dos tab-items filhos.\nEste listener garante que o componente pai seja re-renderizado quando\npropriedades mudam dinamicamente, sincronizando o painel ativo.\n- **setActiveTab(tabId: _string_): _Promise<void>_** - Ativa programaticamente uma aba a partir do seu identificador.\n- **getActiveTab(): _Promise<string | undefined>_** - Retorna o identificador da aba ativa atual.\n- **render(): __** - Renderiza o componente.\n\n### **Slots:**\n - **default** - Slot para inserir os itens das abas (br-tab-item)\n\n### **CSS Parts:**\n - **container** - Contêiner principal que envolve toda a estrutura do componente (navegação e conteúdo). Expõe o elemento para customizações de fundo, bordas e espaçamentos globais.\n- **nav** - Área de navegação (`tablist`) onde os botões das abas estão localizados. Permite customizar o alinhamento, espaçamento e plano de fundo da barra de abas.\n- **button** - Botão individual de cada aba.\n- **indicator** - Indicador visual da aba ativa.\n- **content** - Área de conteúdo das abas.",
       "attributes": [
         {
           "name": "active-tab-id",
@@ -4035,12 +4128,12 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "TabDensity" }]
         },
         {
           "name": "color-mode",
-          "description": "Define se o Tab usará um esquema de cores escuro.",
+          "description": "Define se o Tab usará um esquema de cores escuro. Valores inválidos são ignorados.",
           "values": [{ "name": "TabColorMode" }]
         },
         {
@@ -4055,7 +4148,7 @@
         },
         {
           "name": "alignment",
-          "description": "Alinhamento horizontal canônico. Quando informado, tem precedência sobre `alignItemsTab`.",
+          "description": "Alinhamento horizontal canônico. Quando informado, tem precedência sobre `alignItemsTab`; valores inválidos usam `start`.",
           "values": [{ "name": "TabAlignItems" }]
         },
         {
@@ -4078,7 +4171,7 @@
     },
     {
       "name": "br-tab-item",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tab?tab=designer).\n---\n\n\n### **Events:**\n - **brTabItemPropsChange** - Evento disparado quando as propriedades do tab-item mudam.\nO componente pai (br-tab) escuta este evento para atualizar a navegação.\n\n### **Methods:**\n - **tabItemTitleChanged()** - Observa mudanças no título e notifica o pai\n- **iconChanged()** - Observa mudanças no ícone e notifica o pai\n- **counterChanged()** - Observa mudanças no contador e notifica o pai\n- **onlyIconChanged()** - Observa mudanças em onlyIcon e notifica o pai\n- **isActiveChanged()** - Observa mudanças no estado ativo (alterações via JS/DOM direto) e notifica o pai\n\n### **Slots:**\n - **default** - Slot para o conteúdo do item da aba.",
+      "description": "Subcomponente individual de `br-tab`, responsável por representar conjuntamente a aba de seleção e o respectivo painel de conteúdo associado.\n\n### Papel na composição\n\n- Define o título ou rótulo da aba (propriedade `label` ou slot `label`), ícones de apoio e o estado de seleção (`active`) ou desativação (`disabled`).\n- Contém o corpo de elementos que compõem o painel renderizado quando a aba é selecionada.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado dentro do slot padrão do orquestrador `br-tab`. O componente pai é responsável por montar a barra de botões acessíveis, sincronizar os atributos WAI-ARIA e controlar a alternância de visibilidade do painel. Não deve ser usado isoladamente sem o `br-tab` pai.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tab?tab=designer).\n---\n\n\n### **Events:**\n - **brTabItemPropsChange** - Evento disparado quando as propriedades do tab-item mudam.\nO componente pai (br-tab) escuta este evento para atualizar a navegação.\n\n### **Methods:**\n - **tabItemTitleChanged()** - Observa mudanças no título e notifica o pai\n- **iconChanged()** - Observa mudanças no ícone e notifica o pai\n- **counterChanged()** - Observa mudanças no contador e notifica o pai\n- **onlyIconChanged()** - Observa mudanças em onlyIcon e notifica o pai\n- **isActiveChanged()** - Observa mudanças no estado ativo (alterações via JS/DOM direto) e notifica o pai\n\n### **Slots:**\n - **default** - Slot para o conteúdo do item da aba.",
       "attributes": [
         {
           "name": "tab-item-id",
@@ -4097,7 +4190,7 @@
         },
         {
           "name": "icon",
-          "description": "Define o ícone do item de tab. Aceita o nome Iconify legado ou classes CSS\nde uma biblioteca carregada pela aplicação, como `fas fa-bell`.",
+          "description": "Define o ícone do item de tab usando classes CSS do Font Awesome 5, como `fas fa-bell`.\nO formato Iconify é aceito apenas para compatibilidade legada e não deve ser usado em novos códigos.",
           "values": []
         },
         {
@@ -4135,7 +4228,7 @@
     },
     {
       "name": "br-table",
-      "description": "## Design System\n\nTabela baseada em CSS Grid com controle via tokens.\n\nA tabela é composta de vários subcomponentes, incluindo:\n- br-table-header: Define o cabeçalho da tabela, agrupando as linhas de cabeçalho.\n- br-table-row: Representa uma linha da tabela, podendo conter células de conteúdo ou células de cabeçalho.\n- br-table-header-cell: Representa uma célula de cabeçalho, permitindo a definição de propriedades como largura e alinhamento que podem ser herdadas pelas células de conteúdo associadas.\n- br-table-cell: Representa uma célula de conteúdo da tabela, onde os dados são inseridos.\n- br-table-body: Agrupa as linhas de conteúdo da tabela, representadas pelo subcomponente br-table-row.\n---\n\n\n### **Methods:**\n \n\n\n\n\n- **startLoading(): _Promise<void>_** - Inicia o estado de carregamento da tabela.\n- **stopLoading(): _Promise<void>_** - Interrompe o estado de carregamento da tabela.\n- **render(): __** - Renderiza o host do componente.\n\n### **Slots:**\n - **loading** - Indicador exibido enquanto as linhas são atualizadas.\n\n### **CSS Parts:**\n - **container** - Wrapper principal da tabela.\n- **content** - Área de conteúdo que contém header e body.\n- **loading** - Área do indicador de carregamento.",
+      "description": "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.\n\n### Para que serve\n\n- **Apresentação de conjuntos de dados relacionais:** Organiza registros com múltiplos atributos comparáveis (ex.: relatórios, tabelas de processos, listagens financeiras).\n- **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`.\n- **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.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - As informações compartilharem campos e atributos fixos que justifiquem a comparação lado a lado em colunas.\n  - A pessoa usuária precisar ordenar, filtrar ou selecionar múltiplos registros da lista.\n- **Evite e prefira outro componente quando:**\n  - Os itens forem heterogêneos com estruturas visuais distintas (prefira `br-card`).\n  - Houver apenas um texto linear simples por item (prefira `br-list`).\n\n### Composição e Subcomponentes\n\nO ecossistema da Tabela segue a hierarquia semântica modular:\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `br-table` | **Orquestrador principal.** Gerencia o grid de colunas, ordenação, seleção de linhas e densidade. | Contêiner raiz da tabela. |\n| `br-table-header` | **Seção de cabeçalho.** Agrupa as linhas de títulos das colunas. | Declarado no slot `header` da tabela. |\n| `br-table-body` | **Corpo de dados.** Agrupa as linhas de registros de conteúdo. | Declarado no slot `body` (ou padrão) da tabela. |\n| `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`. |\n| `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. |\n| `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. |\n\n### Como os subcomponentes se relacionam\n\nA arquitetura de `br-table` reflete a semântica nativa de tabelas HTML de forma modular:\n`br-table` → `br-table-header` / `br-table-body` → `br-table-row` → `br-table-header-cell` / `br-table-cell`.\nO componente pai orquestra o alinhamento das colunas via tokens de Grid, distribuindo automaticamente os estados de seleção e foco para as linhas filhas.\n\nPara 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).\n---\n\n\n### **Methods:**\n \n\n\n\n\n- **startLoading(): _Promise<void>_** - Inicia o estado de carregamento da tabela.\n- **stopLoading(): _Promise<void>_** - Interrompe o estado de carregamento da tabela.\n- **render(): __** - Renderiza o host do componente.\n\n### **Slots:**\n - **loading** - Indicador exibido enquanto as linhas são atualizadas.\n\n### **CSS Parts:**\n - **container** - Wrapper principal da tabela.\n- **content** - Área de conteúdo que contém header e body.\n- **loading** - Área do indicador de carregamento.",
       "attributes": [
         {
           "name": "column-width",
@@ -4144,7 +4237,7 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`. Quando omitida, a densidade média é aplicada ao token.",
           "values": [{ "name": "TableDensity" }]
         },
         {
@@ -4207,13 +4300,13 @@
     },
     {
       "name": "br-table-body",
-      "description": "## Design System\n\nO br-table-body é um subcomponente da tabela que tem a função de agrupar as linhas de conteúdo da tabela, representadas pelo subcomponente br-table-row.\nEle é utilizado para organizar e estruturar o conteúdo do corpo da tabela, permitindo a definição de múltiplas linhas de conteúdo, cada uma contendo células de conteúdo representadas pelo subcomponente br-table-cell.\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **body** - Wrapper do corpo da tabela.",
+      "description": "Subcomponente de corpo de dados de `br-table`, responsável por agrupar as linhas de registros de conteúdo.\n\n### Papel na composição\n\n- Define a região principal da tabela com a semântica de `rowgroup` de conteúdo.\n- Recebe as linhas de dados `br-table-row` preenchidas com as células de valor `br-table-cell`.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado dentro do slot `body` (ou padrão) de `br-table`. Ele organiza o fluxo vertical de registros coordenado pelo pai. Não deve ser usado fora de uma tabela.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **body** - Wrapper do corpo da tabela.",
       "attributes": [],
       "references": []
     },
     {
       "name": "br-table-cell",
-      "description": "## Design System\n\nO br-table-cell é um subcomponente da tabela que representa uma célula de conteúdo dentro da tabela, sendo utilizado para definir o conteúdo e as propriedades de formatação das células de dados da tabela.\nEle é projetado para ser utilizado dentro do subcomponente br-table-row, que representa uma linha da tabela, permitindo a organização e estruturação do conteúdo das células de dados da tabela.\n---\n\n\n### **Events:**\n - **brAlignmentChange** - Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula reaja dinamicamente a mudanças nos tokens de alinhamento.\n- **brOverflowChange** - Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula reaja dinamicamente a mudanças no token de overflow.\n\n### **Methods:**\n \n\n- **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **cell** - Wrapper da célula.\n- **content** - Área de conteúdo da célula.",
+      "description": "Subcomponente de célula de dados de `br-table`, utilizado para renderizar o valor ou conteúdo de um registro em uma coluna específica.\n\n### Papel na composição\n\n- Exibe o dado pontual da coluna (`role=\"cell\"`), podendo conter texto, badges, ícones, botões de ação ou links.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado dentro de um `br-table-row` situado no `br-table-body`. O dimensionamento e posicionamento são calculados pelas regras de CSS Grid da tabela pai.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).\n---\n\n\n### **Events:**\n - **brAlignmentChange** - Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula reaja dinamicamente a mudanças nos tokens de alinhamento.\n- **brOverflowChange** - Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula reaja dinamicamente a mudanças no token de overflow.\n\n### **Methods:**\n \n\n- **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **cell** - Wrapper da célula.\n- **content** - Área de conteúdo da célula.",
       "attributes": [
         {
           "name": "horizontal-alignment",
@@ -4245,17 +4338,17 @@
     },
     {
       "name": "br-table-header",
-      "description": "## Design System\n\nO br-table-header é um subcomponente estrutural da tabela, responsável por agrupar as linhas de cabeçalho da tabela, representadas pelo subcomponente br-table-row.\nEle é utilizado para organizar e estruturar o conteúdo do cabeçalho da tabela, permitindo a definição de múltiplas linhas de cabeçalho, cada uma contendo células de cabeçalho representadas pelo subcomponente br-table-header-cell.\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **header** - Wrapper do cabeçalho da tabela.",
+      "description": "Subcomponente de cabeçalho de `br-table`, utilizado para agrupar as linhas de títulos das colunas.\n\n### Papel na composição\n\n- Define a região superior da tabela com a semântica de `rowgroup` de cabeçalho.\n- Recebe uma ou mais linhas `br-table-row` que contêm as células de título `br-table-header-cell`.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado dentro do slot `header` do componente pai `br-table`. O orquestrador da tabela aplica a configuração de colunas e espaçamentos sobre o cabeçalho. Não deve ser usado isoladamente.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).\n---\n\n\n### **Methods:**\n - **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **header** - Wrapper do cabeçalho da tabela.",
       "attributes": [],
       "references": []
     },
     {
       "name": "br-table-header-cell",
-      "description": "## Design System\n\nO br-table-header-cell é um subcomponente da table que representa uma célula de cabeçalho dentro da tabela, sendo utilizado para definir o conteúdo e as propriedades de formatação do cabeçalho da tabela.\nEle é projetado para ser utilizado dentro do subcomponente br-table-row, que representa uma linha da tabela, permitindo a organização e estruturação do conteúdo do cabeçalho da tabela.\n---\n\n\n### **Events:**\n - **brColumnWidthChange** - Evento customizado emitido quando a largura da coluna é alterada, permitindo que as células reajam dinamicamente a mudanças no layout.\n- **brAlignmentChange** - Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças nos tokens de alinhamento.\n- **brOverflowChange** - Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças no token de overflow.\n\n### **Methods:**\n \n\n\n- **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **cell** - Wrapper da célula de cabeçalho.\n- **content** - Área de conteúdo da célula de cabeçalho.",
+      "description": "Subcomponente de célula de cabeçalho de `br-table`, responsável por nomear uma coluna e oferecer controles opcionais de ordenação.\n\n### Papel na composição\n\n- Define o rótulo da coluna com `role=\"columnheader\"`.\n- Suporta gatilho interativo de ordenação crescente e decrescente (`sortable`), emitindo eventos para reordenação de dados.\n\n### Regra de uso e relacionamento\n\nDeve ser declarado dentro de um `br-table-row` situado no `br-table-header`. O alinhamento horizontal segue a definição da coluna na tabela pai.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).\n---\n\n\n### **Events:**\n - **brColumnWidthChange** - Evento customizado emitido quando a largura da coluna é alterada, permitindo que as células reajam dinamicamente a mudanças no layout.\n- **brAlignmentChange** - Evento customizado emitido quando o alinhamento é alterado, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças nos tokens de alinhamento.\n- **brOverflowChange** - Evento customizado emitido quando a configuração de overflow é alterada, permitindo que a célula de cabeçalho reaja dinamicamente a mudanças no token de overflow.\n\n### **Methods:**\n \n\n\n- **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **cell** - Wrapper da célula de cabeçalho.\n- **content** - Área de conteúdo da célula de cabeçalho.",
       "attributes": [
         {
           "name": "column-width",
-          "description": "Define a largura da coluna.",
+          "description": "Define a largura da coluna.\nAceita `fill`, `content`, larguras positivas em `px` ou frações positivas em `fr`.\nValores inválidos usam o fallback da tabela.",
           "values": [{ "name": "ColumnWidth" }]
         },
         {
@@ -4288,7 +4381,7 @@
     },
     {
       "name": "br-table-row",
-      "description": "## Design System\n\nO br-table-row é um subcomponente da tabela que representa uma linha da tabela, podendo conter células de conteúdo (br-table-cell) ou células de cabeçalho (br-table-header-cell).\nEle é utilizado para organizar e estruturar o conteúdo da tabela, permitindo a definição de propriedades como alinhamento e overflow que podem ser herdadas pelas células associadas.\n---\n\n\n### **Events:**\n - **brAlignmentChange** - Evento customizado emitido quando o alinhamento é alterado, permitindo que as células reajam dinamicamente a mudanças nos tokens de alinhamento.\n- **brOverflowChange** - Evento customizado emitido quando a configuração de overflow é alterada, permitindo que as células reajam dinamicamente a mudanças no token de overflow.\n\n### **Methods:**\n \n\n- **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **row** - Wrapper da linha da tabela.",
+      "description": "Subcomponente de linha de `br-table`, utilizado tanto no cabeçalho quanto no corpo de dados para agrupar uma sequência horizontal de células.\n\n### Papel na composição\n\n- Representa uma linha de registro (`role=\"row\"`).\n- Suporta estados de seleção (`selected`), foco e hover coordenados com o pai.\n\n### Regra de uso e relacionamento\n\nDeclarado dentro de `br-table-header` (quando contiver `br-table-header-cell`) ou dentro de `br-table-body` (quando contiver `br-table-cell`). Não deve ser usado isoladamente.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/table?tab=designer).\n---\n\n\n### **Events:**\n - **brAlignmentChange** - Evento customizado emitido quando o alinhamento é alterado, permitindo que as células reajam dinamicamente a mudanças nos tokens de alinhamento.\n- **brOverflowChange** - Evento customizado emitido quando a configuração de overflow é alterada, permitindo que as células reajam dinamicamente a mudanças no token de overflow.\n\n### **Methods:**\n \n\n- **render(): __** - Renderiza o host do componente.\n\n### **CSS Parts:**\n - **row** - Wrapper da linha da tabela.",
       "attributes": [
         {
           "name": "horizontal-alignment",
@@ -4320,7 +4413,7 @@
     },
     {
       "name": "br-tag",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/textarea?tag=designer).\n---\n\n\n### **Events:**\n - **radioSelected** - Evento emitido quando a tag é selecionada.\n- **brTagValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna se a tag selecionável atende às constraints configuradas.\n- **reportValidity(): _Promise<boolean>_** - Valida e solicita ao navegador a apresentação do erro atual.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define ou limpa uma mensagem de validade customizada.\n- **validate(): _Promise<boolean>_** - Executa o validator da tag e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n\n### **Slots:**\n - **default** - Slot para inserir o conteúdo da tag, como rótulo ou ícone.\n- **label** - Rótulo customizado da tag. Quando utilizado, a prop `label` é ignorada.\n- **icon** - Ícone customizado da tag. Quando utilizado, a prop `icon` é ignorada.\n- **close-button** - Botão de fechar customizado. Quando utilizado, o botão padrão é substituído.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **tag** - Elemento principal da tag.\n- **input** - Elemento input da tag de seleção.\n- **label** - Rótulo da tag de seleção.\n- **feedback** - Contêiner da mensagem de validação.",
+      "description": "O componente `br-tag` é o elemento visual compacto do GovBR-DS utilizado para rotular, categorizar, exibir metadados ou aplicar filtros rápidos na interface.\n\n### Para que serve\n\n- **Categorização e metadados:** Identifica o tipo, categoria ou atributos de um item (ex.: \"Educação\", \"Tecnologia\", \"Urgente\").\n- **Sinalização de status:** Exibe estados operacionais de processos ou documentos através de cores semânticas e ícones (ex.: \"Aprovado\", \"Pendente\", \"Cancelado\").\n- **Filtros interativos dispensáveis:** Suporta botão de fechamento (`closable`), permitindo remover filtros dinamicamente.\n- **Tags de seleção:** Suporta modo interativo selecionável com integração nativa a formulários (`formAssociated`).\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Exibir palavras-chave associadas a um conteúdo ou cartão.\n  - Exibir status sucinto de registros em tabelas (`br-table`) ou cabeçalhos.\n  - Oferecer filtros aplicados que podem ser removidos com um clique.\n- **Evite e prefira outro componente quando:**\n  - O elemento for a ação primária ou um comando executável (prefira `br-button`).\n  - O texto for extenso e exigir explicações detalhadas (prefira `br-message`).\n\n### Estrutura e Slots\n\nO `br-tag` oferece flexibilidade estrutural:\n- `default`: Slot principal para texto ou conteúdo livre da tag.\n- `label`: Slot para rótulo customizado.\n- `icon`: Slot para inserção de ícone auxiliar (`br-icon`).\n- `close-button`: Slot para customizar o botão de remoção.\n- `feedback`: Slot para mensagem de validação contextual.\n\nPara 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).\n---\n\n\n### **Events:**\n - **radioSelected** - Evento emitido quando a tag é selecionada.\n- **brTagValidationChange** - Emitido ao iniciar e concluir a validação customizada.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna se a tag selecionável atende às constraints configuradas.\n- **reportValidity(): _Promise<boolean>_** - Valida e solicita ao navegador a apresentação do erro atual.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define ou limpa uma mensagem de validade customizada.\n- **validate(): _Promise<boolean>_** - Executa o validator da tag e retorna se o valor atual é válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n\n### **Slots:**\n - **default** - Slot para inserir o conteúdo da tag, como rótulo ou ícone.\n- **label** - Rótulo customizado da tag. Quando utilizado, a prop `label` é ignorada.\n- **icon** - Ícone customizado da tag. Quando utilizado, a prop `icon` é ignorada.\n- **close-button** - Botão de fechar customizado. Quando utilizado, o botão padrão é substituído.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n\n### **CSS Parts:**\n - **tag** - Elemento principal da tag.\n- **input** - Elemento input da tag de seleção.\n- **label** - Rótulo da tag de seleção.\n- **feedback** - Contêiner da mensagem de validação.",
       "attributes": [
         {
           "name": "label",
@@ -4329,7 +4422,7 @@
         },
         {
           "name": "icon-name",
-          "description": "A propriedade 'iconName' define um nome Iconify para o ícone exibido ao lado do texto.",
+          "description": "Identificador legado do ícone exibido ao lado do texto.",
           "values": []
         },
         {
@@ -4344,7 +4437,7 @@
         },
         {
           "name": "validator",
-          "description": "Regra síncrona ou assíncrona aplicada ao estado e valor da tag.",
+          "description": "Regra síncrona ou assíncrona aplicada ao estado, valor e rótulo da tag.",
           "values": [{ "name": "TagValidator" }]
         },
         {
@@ -4369,7 +4462,7 @@
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "BrDensity" }]
         },
         {
@@ -4384,7 +4477,7 @@
         },
         {
           "name": "variant",
-          "description": "Variante funcional canônica. Quando informada, tem precedência sobre os modos booleanos legados.",
+          "description": "Variante funcional canônica. Aceita `default`, `status`, `action` ou `selectable`.\nValores inválidos são ignorados; nesse caso, os aliases booleanos legados\ncontinuam disponíveis para manter a compatibilidade.",
           "values": [{ "name": "TagVariant" }]
         },
         {
@@ -4414,12 +4507,12 @@
         },
         {
           "name": "min-selections",
-          "description": "Quantidade mínima de tags selecionadas no mesmo grupo.",
+          "description": "Quantidade mínima de tags selecionadas no mesmo grupo. Deve ser um inteiro não negativo; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "max-selections",
-          "description": "Quantidade máxima de tags selecionadas no mesmo grupo. Zero significa sem limite.",
+          "description": "Quantidade máxima de tags selecionadas no mesmo grupo. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam 0.",
           "values": []
         },
         {
@@ -4437,7 +4530,7 @@
     },
     {
       "name": "br-textarea",
-      "description": "## Design System\n\nPara a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/textarea?tab=designer).\n---\n\n\n### **Events:**\n - **valueChange** - Valor atualizado do textarea\n- **brTextareaValidationChange** - Informa o início e o resultado do validator; o `detail` contém\n`validating`, `valid` e `message`.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do textarea for válido, caso contrário `false`.\nSe o textarea for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do textarea for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o textarea.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator customizado e retorna se o textarea está válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **select(): _Promise<void>_** - Seleciona todo o texto do controle nativo, conforme HTMLTextAreaElement.select().\n- **setRangeText(replacement: _string_, start: _number_, end: _number_, selectionMode: _SelectionMode_): _Promise<void>_** - Substitui um intervalo de texto usando a API nativa do textarea.\n- **setSelectionRange(start: _number_, end: _number_, direction: _'forward' | 'backward' | 'none'_): _Promise<void>_** - Define o intervalo selecionado no controle nativo.\n- **setValue(newValue: _string_)** - Define um novo valor para o textarea.\n\n### **Slots:**\n - **default** - Slot para texto adicional ou instruções a serem exibidos junto ao textarea.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n- **validation-loading** - Indicador exibido durante validação assíncrona.\n\n### **CSS Parts:**\n - **container** - Contêiner visual principal.\n- **label** - Rótulo do textarea.\n- **textarea** - Elemento textarea nativo.\n- **counter** - Contêiner do contador.\n- **counter-text** - Texto do contador.\n- **helper** - Contêiner do conteúdo auxiliar do slot default.\n- **feedback** - Contêiner da mensagem de validação.",
+      "description": "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.\n\n### Para que serve\n\n- **Entrada de texto extenso:** Permite que a pessoa usuária digite parágrafos de texto livre com quebra de linha e rolagem vertical.\n- **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.\n- **Integração com formulários:** É associado nativamente a formulários HTML (`formAssociated`), sincronizando valor, estado de validação e foco acessível.\n- **Redimensionamento controlado:** Oferece opções de redimensionamento vertical, horizontal ou fixo.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A entrada esperada tiver mais de uma frase ou exigir formatação multilinha (comentários, manifestações, relatórios, justificativas).\n  - Houver restrição estrita de caracteres com necessidade de feedback quantitativo dinâmico.\n- **Evite e prefira outro componente quando:**\n  - O dado for curto e couber em uma única linha (como nomes, e-mails, títulos, documentos): prefira `br-input`.\n  - For necessário um editor rico WYSIWYG com formatação em negrito, tabelas e links.\n\n### Estrutura e Slots\n\nO `br-textarea` é composto pelo campo e slots de apoio:\n- `default`: Slot para instruções adicionais ou textos de ajuda.\n- `feedback`: Slot para mensagens de validação contextual (como `br-message`).\n- `validation-loading`: Slot para indicador de carregamento durante validações assíncronas.\n\nPara 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).\n---\n\n\n### **Events:**\n - **valueChange** - Valor atualizado do textarea\n- **brTextareaValidationChange** - Informa o início e o resultado do validator; o `detail` contém\n`validating`, `valid` e `message`.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do textarea for válido, caso contrário `false`.\nSe o textarea for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do textarea for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o textarea.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator customizado e retorna se o textarea está válido.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **select(): _Promise<void>_** - Seleciona todo o texto do controle nativo, conforme HTMLTextAreaElement.select().\n- **setRangeText(replacement: _string_, start: _number_, end: _number_, selectionMode: _SelectionMode_): _Promise<void>_** - Substitui um intervalo de texto usando a API nativa do textarea.\n- **setSelectionRange(start: _number_, end: _number_, direction: _'forward' | 'backward' | 'none'_): _Promise<void>_** - Define o intervalo selecionado no controle nativo.\n- **setValue(newValue: _string_)** - Define um novo valor para o textarea.\n\n### **Slots:**\n - **default** - Slot para texto adicional ou instruções a serem exibidos junto ao textarea.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n- **validation-loading** - Indicador exibido durante validação assíncrona.\n\n### **CSS Parts:**\n - **container** - Contêiner visual principal.\n- **label** - Rótulo do textarea.\n- **textarea** - Elemento textarea nativo.\n- **counter** - Contêiner do contador.\n- **counter-text** - Texto do contador.\n- **helper** - Contêiner do conteúdo auxiliar do slot default.\n- **feedback** - Contêiner da mensagem de validação.",
       "attributes": [
         {
           "name": "value",
@@ -4486,12 +4579,12 @@
         },
         {
           "name": "minlength",
-          "description": "Número mínimo de caracteres necessário para o valor ser válido.",
+          "description": "Número mínimo de caracteres necessário para o valor ser válido. Deve ser um inteiro não negativo; valores inválidos usam 0.",
           "values": []
         },
         {
           "name": "maxlength",
-          "description": "Número máximo de caracteres permitidos no textarea. Se definido como 0, não há limite.",
+          "description": "Número máximo de caracteres permitidos no textarea. Se definido como 0, não há limite.\nDeve ser um inteiro não negativo; valores inválidos usam 0.",
           "values": []
         },
         {
@@ -4501,7 +4594,7 @@
         },
         {
           "name": "state",
-          "description": "Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'.",
+          "description": "Define o estado visual do componente, podendo ser 'danger', 'success' ou 'warning'. Valores inválidos não aplicam estado.",
           "values": [
             { "name": "danger" },
             { "name": "success" },
@@ -4510,7 +4603,7 @@
         },
         {
           "name": "feedback-state",
-          "description": "Estado de feedback canônico. Quando informado, tem precedência sobre `state`.",
+          "description": "Estado de feedback canônico. Quando informado, tem precedência sobre `state`; valores inválidos não aplicam estado.",
           "values": [
             { "name": "danger" },
             { "name": "success" },
@@ -4524,7 +4617,7 @@
         },
         {
           "name": "density",
-          "description": "Ajusta a densidade do componente, podendo ser 'small', 'medium' ou 'large'.",
+          "description": "Ajusta a densidade do componente, podendo ser 'small', 'medium' ou 'large'.\nValores inválidos usam `medium`.",
           "values": [
             { "name": "small" },
             { "name": "medium" },
@@ -4543,20 +4636,35 @@
         },
         {
           "name": "rows",
-          "description": "Número de linhas visíveis no textarea.\nDefine a altura do componente em relação ao número de linhas de texto exibidas.",
+          "description": "Número de linhas visíveis no textarea.\nDefine a altura do componente em relação ao número de linhas de texto exibidas.\nDeve ser um inteiro positivo; valores inválidos são ignorados.",
           "values": []
         },
         {
           "name": "cols",
-          "description": "Número de colunas (caracteres) visíveis no textarea.\nDefine a largura do componente em relação ao número de caracteres por linha.",
+          "description": "Número de colunas (caracteres) visíveis no textarea.\nDefine a largura do componente em relação ao número de caracteres por linha.\nDeve ser um inteiro positivo; valores inválidos são ignorados.",
+          "values": []
+        },
+        {
+          "name": "auto-grow",
+          "description": "Ajusta automaticamente a altura ao conteúdo sem exibir rolagem vertical.\nQuando ativo, o componente controla a dimensão vertical; `resize=\"vertical\"`\ne `resize=\"both\"` passam a se comportar como `none`, enquanto\n`resize=\"horizontal\"` continua disponível.",
           "values": []
+        },
+        {
+          "name": "resize",
+          "description": "Define os eixos que a pessoa usuária pode redimensionar manualmente.\nQuando omitida, preserva o comportamento nativo atual do navegador.\nValores inválidos são ignorados.",
+          "values": [{ "name": "TextareaResize" }]
+        },
+        {
+          "name": "wrap",
+          "description": "Encaminha a política nativa de quebra de linha ao `<textarea>` interno.\nQuando omitida, o navegador usa o comportamento nativo `soft`.\nValores inválidos são ignorados.",
+          "values": [{ "name": "TextareaWrap" }]
         }
       ],
       "references": []
     },
     {
       "name": "br-tooltip",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/tooltip?tab=designer).\n---\n\n\n### **Events:**\n - **brDidOpen** - Emitido quando o tooltip abre.\n- **brDidClose** - Emitido quando o tooltip fecha.\n\n### **Methods:**\n - **handleVisibilityChange(visible: _boolean_): __** - Watcher para monitorar alterações na propriedade `isVisible`.\n- **handleFocusIn()** - Exibe o tooltip quando o acionador recebe foco.\n- **handleFocusOut()** - Oculta o tooltip quando o acionador perde foco.\n- **handleKeyDown(event: _KeyboardEvent_)** - Fecha com Escape enquanto o tooltip estiver visível.\n- **setTriggerElement(element: _HTMLElement | null_)** - Define um trigger externo para o tooltip.\n- **showTooltip()** - Exibe o tooltip programaticamente.\n- **hideTooltip()** - Oculta o tooltip programaticamente.\n- **show()** - Exibe o tooltip programaticamente (alias para `showTooltip`).\n- **hide()** - Oculta o tooltip programaticamente (alias para `hideTooltip`).\n- **render(): __** - Renderiza o componente.\nEste método é responsável por gerar o conteúdo HTML do componente.\nEle utiliza a função `h` do Stencil para criar elementos JSX.\n\n### **Slots:**\n - **trigger** - Slot para o elemento que aciona a exibição do tooltip.\n- **content** - Slot para o conteúdo exibido no tooltip.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do tooltip.\n- **trigger** - Área do acionador do tooltip.\n- **content** - Área de conteúdo do tooltip.\n- **arrow** - Seta indicativa do tooltip.",
+      "description": "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.\n\n### Para que serve\n\n- **Esclarecimento contextual imediato:** Revela descrições sucintas para botões de ícone, termos técnicos, siglas ou campos que necessitem de auxílio extra.\n- **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.\n- **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.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Fornecer o rótulo descritivo de um botão que contenha apenas ícone.\n  - Explicar uma sigla ou termo abreviado na interface.\n- **Evite e prefira outro componente quando:**\n  - 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).\n  - A informação for indispensável para a conclusão de uma tarefa crítica (ela deve estar sempre visível na tela).\n\n### Estrutura e Slots\n\nO `br-tooltip` é composto por acionador e conteúdo:\n- `trigger`: Slot obrigatório onde a aplicação declara o elemento de controle gatilho (ex.: um `br-button` de ícone).\n- `content`: Slot onde é inserido o texto ou balão de conteúdo exibido pelo tooltip.\n\nPara 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).\n---\n\n\n### **Events:**\n - **brDidOpen** - Emitido quando o tooltip abre.\n- **brDidClose** - Emitido quando o tooltip fecha.\n\n### **Methods:**\n - **handleVisibilityChange(visible: _boolean_): __** - Watcher para monitorar alterações na propriedade `isVisible`.\n- **handleMatchTriggerWidthChange()** - Recalcula a superfície visível quando a política de largura muda.\n- **handleFocusIn()** - Exibe o tooltip quando o acionador recebe foco.\n- **handleFocusOut()** - Oculta o tooltip quando o acionador perde foco.\n- **handleKeyDown(event: _KeyboardEvent_)** - Fecha com Escape enquanto o tooltip estiver visível.\n- **setTriggerElement(element: _HTMLElement | null_)** - Define um trigger externo para o tooltip.\n- **showTooltip()** - Exibe o tooltip programaticamente.\n- **hideTooltip()** - Oculta o tooltip programaticamente.\n- **show()** - Exibe o tooltip programaticamente (alias para `showTooltip`).\n- **hide()** - Oculta o tooltip programaticamente (alias para `hideTooltip`).\n- **render(): __** - Renderiza o componente.\nEste método é responsável por gerar o conteúdo HTML do componente.\nEle utiliza a função `h` do Stencil para criar elementos JSX.\n\n### **Slots:**\n - **trigger** - Slot para o elemento que aciona a exibição do tooltip.\n- **content** - Slot para o conteúdo exibido no tooltip.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do tooltip.\n- **trigger** - Área do acionador do tooltip.\n- **content** - Área de conteúdo do tooltip.\n- **arrow** - Seta indicativa do tooltip.",
       "attributes": [
         {
           "name": "custom-id",
@@ -4570,27 +4678,27 @@
         },
         {
           "name": "position",
-          "description": "Posição do tooltip em relação ao acionador.",
+          "description": "Posição do tooltip em relação ao acionador. Valores inválidos usam `top`.",
           "values": [{ "name": "TooltipPosition" }]
         },
         {
           "name": "type",
-          "description": "Tipo do tooltip: 'standard' (simples) ou 'popover' (mais rico, com fechamento por interação).",
+          "description": "Tipo do tooltip: 'standard' (simples) ou 'popover' (mais rico, com fechamento por interação). Valores inválidos usam `standard`.",
           "values": [{ "name": "TooltipType" }]
         },
         {
           "name": "interaction",
-          "description": "Modo de interação para exibição do tooltip: 'hover' ou 'click'.",
+          "description": "Modo de interação para exibição do tooltip: 'hover' ou 'click'. Valores inválidos usam `hover`.",
           "values": [{ "name": "hover" }, { "name": "click" }]
         },
         {
           "name": "density",
-          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).",
+          "description": "Define a densidade visual do componente.\n\n- `small`: Alta densidade (componente menor, mais compacto e com menos espaçamento).\n- `medium`: Densidade intermediária, padrão recomendado para a maioria dos casos.\n- `large`: Baixa densidade (componente maior, mais espaçamento e altura).\n\nValores inválidos usam `medium`.",
           "values": [{ "name": "TooltipDensity" }]
         },
         {
           "name": "state",
-          "description": "Estado visual do tooltip: 'info', 'warning', 'error', 'danger' ou 'success'.",
+          "description": "Estado visual do tooltip: 'info', 'warning', 'error', 'danger' ou 'success'. Valores inválidos usam `info`.",
           "values": [{ "name": "TooltipState" }]
         },
         {
@@ -4598,14 +4706,19 @@
           "description": "Exibe automaticamente sem interação quando true; caso contrário, depende do acionador.",
           "values": []
         },
+        {
+          "name": "match-trigger-width",
+          "description": "Faz o conteúdo acompanhar a largura do acionador enquanto estiver visível.\nO valor padrão `false` preserva a largura determinada pelo conteúdo.",
+          "values": []
+        },
         {
           "name": "show-delay",
-          "description": "Atraso em milissegundos antes de exibir.",
+          "description": "Atraso em milissegundos antes de exibir. Valores negativos usam `0`.",
           "values": []
         },
         {
           "name": "hide-delay",
-          "description": "Atraso em milissegundos antes de ocultar.",
+          "description": "Atraso em milissegundos antes de ocultar. Valores negativos usam `0`.",
           "values": []
         }
       ],
@@ -4613,7 +4726,7 @@
     },
     {
       "name": "br-upload",
-      "description": "## Design System\n---\n\n\n### **Events:**\n - **selectedFilesChange** - Emitido quando a lista de arquivos selecionados muda.\n- **brRemove** - Evento emitido quando um arquivo da lista `uploadFiles` (externos) é removido pelo usuário.\nO objeto emitido contém os dados do arquivo removido.\n- **brUploadRemove** - Evento canônico emitido quando um arquivo existente é removido.\n- **brUploadCancel** - Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada.\n- **brUploadValidationChange** - Emitido ao iniciar e concluir a validação customizada.\nO `detail` contém `validating`, `valid` e `message`.\n- **brUploadStart** - Emitido antes de o `uploadHandler` processar um arquivo.\n- **brUploadProgress** - Emitido quando o `uploadHandler` informa o progresso de um arquivo.\n- **brUploadSuccess** - Emitido quando o `uploadHandler` conclui um arquivo.\n- **brUploadError** - Emitido quando o `uploadHandler` falha ao enviar um arquivo.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do componente for válido, caso contrário `false`.\nSe o componente for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do componente for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o upload.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do upload e retorna se a lista atual é válida.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **cancelUpload(): _Promise<void>_** - Cancela o envio atual iniciado pelo `uploadHandler`.\n\n### **Slots:**\n - **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.\n- **upload-list** - Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.\n- **label** - Rótulo customizado do upload. Quando utilizado, a prop `label` é ignorada.\n- **helper** - Texto auxiliar exibido abaixo da superfície de seleção.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n- **loading** - Conteúdo exibido enquanto o handler fornecido pela aplicação envia um arquivo.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do upload.\n- **label** - Rótulo do campo de upload.\n- **input** - Elemento input de arquivo.\n- **button** - Botão de seleção de arquivo.\n- **helper** - Texto auxiliar do upload.\n- **remove-button** - Botão de remoção de arquivo.\n- **file-list** - Lista de arquivos selecionados.\n- **feedback** - Contêiner da mensagem de validação.\n- **loading** - Estado e progresso do envio assíncrono.",
+      "description": "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.\n\n### Para que serve\n\n- **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.\n- **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.\n- **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.\n- **Integração com formulários:** Integrado nativamente via `formAssociated`, permitindo submissão tradicional de formulários ou upload assíncrono programático.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - A pessoa usuária precisar enviar comprovantes, relatórios, fotografias ou documentos digitais.\n  - For necessário limitar e validar os tipos de arquivo e o tamanho máximo antes do envio ao servidor.\n- **Evite e prefira outro componente quando:**\n  - A captura for exclusivamente de texto ou URLs externas (prefira `br-input`).\n\n### Estrutura e Slots\n\nO `br-upload` possui estrutura rica com múltiplos slots:\n- `default`: Slot para texto personalizado do botão de upload (padrão: \"Selecione o arquivo\").\n- `upload-list`: Slot opcional para substituição da área padrão de listagem de arquivos.\n- `label`: Slot para personalização do rótulo do campo.\n- `helper`: Slot para instruções ou restrições de formato/tamanho exibidas abaixo do campo.\n- `feedback`: Slot para mensagens de validação e erro (como `br-message`).\n- `loading`: Slot para indicador exibido durante o envio assíncrono dos arquivos.\n\nPara 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).\n---\n\n\n### **Events:**\n - **selectedFilesChange** - Emitido quando a lista de arquivos selecionados muda.\n- **brRemove** - Evento emitido quando um arquivo da lista `uploadFiles` (externos) é removido pelo usuário.\nO objeto emitido contém os dados do arquivo removido.\n- **brUploadRemove** - Evento canônico emitido quando um arquivo existente é removido.\n- **brUploadCancel** - Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada.\n- **brUploadValidationChange** - Emitido ao iniciar e concluir a validação customizada.\nO `detail` contém `validating`, `valid` e `message`.\n- **brUploadStart** - Emitido antes de o `uploadHandler` processar um arquivo.\n- **brUploadProgress** - Emitido quando o `uploadHandler` informa o progresso de um arquivo.\n- **brUploadSuccess** - Emitido quando o `uploadHandler` conclui um arquivo.\n- **brUploadError** - Emitido quando o `uploadHandler` falha ao enviar um arquivo.\n\n### **Methods:**\n - **checkValidity(): _Promise<boolean>_** - Retorna `true` se o valor do componente for válido, caso contrário `false`.\nSe o componente for inválido, dispara um evento 'invalid'.\n- **reportValidity(): _Promise<boolean>_** - Retorna `true` se o valor do componente for válido, caso contrário `false`.\nSe for inválido, exibe a mensagem de erro padrão do navegador.\n- **setCustomValidity(message: _string_): _Promise<void>_** - Define uma mensagem de validação customizada para o upload.\nSe a mensagem for uma string vazia, o erro customizado é limpo.\n- **validate(): _Promise<boolean>_** - Executa o validator do upload e retorna se a lista atual é válida.\n- **getValidationState(): _Promise<FormValidationState>_** - Retorna um snapshot serializável da Constraint Validation API.\n- **cancelUpload(): _Promise<void>_** - Cancela o envio atual iniciado pelo `uploadHandler`.\n\n### **Slots:**\n - **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.\n- **upload-list** - Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.\n- **label** - Rótulo customizado do upload. Quando utilizado, a prop `label` é ignorada.\n- **helper** - Texto auxiliar exibido abaixo da superfície de seleção.\n- **feedback** - Mensagem de validação, normalmente um `br-message`.\n- **loading** - Conteúdo exibido enquanto o handler fornecido pela aplicação envia um arquivo.\n\n### **CSS Parts:**\n - **container** - Wrapper principal do upload.\n- **label** - Rótulo do campo de upload.\n- **input** - Elemento input de arquivo.\n- **button** - Botão de seleção de arquivo.\n- **helper** - Texto auxiliar do upload.\n- **remove-button** - Botão de remoção de arquivo.\n- **file-list** - Lista de arquivos selecionados.\n- **feedback** - Contêiner da mensagem de validação.\n- **loading** - Estado e progresso do envio assíncrono.",
       "attributes": [
         {
           "name": "custom-id",
@@ -4632,7 +4745,7 @@
         },
         {
           "name": "capture",
-          "description": "Sugere a câmera usada na captura de imagem ou vídeo.\nO navegador pode ignorar a preferência conforme dispositivo e permissões.",
+          "description": "Sugere a câmera usada na captura de imagem ou vídeo. Valores inválidos são ignorados.\nO navegador pode ignorar a preferência conforme dispositivo e permissões.",
           "values": [
             { "name": "''" },
             { "name": "user" },
@@ -4646,12 +4759,12 @@
         },
         {
           "name": "upload-files",
-          "description": "Lista de arquivos já enviados (para edição ou pré-visualização).\nPode ser uma string JSON ou um array de objetos IUploadFile.",
+          "description": "Lista de arquivos já enviados (para edição ou pré-visualização).\nPode 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.",
           "values": [{ "name": "IUploadFile[]" }]
         },
         {
           "name": "existing-files",
-          "description": "Arquivos já existentes. Quando informada, tem precedência sobre `uploadFiles`.",
+          "description": "Arquivos já existentes. Quando informada, tem precedência sobre `uploadFiles`.\nCada item deve ter `name` não vazio e `size` numérico não negativo opcional.\nUse JSON no atributo HTML ou um array por property binding.",
           "values": [{ "name": "IUploadFile[]" }]
         },
         {
@@ -4666,7 +4779,7 @@
         },
         {
           "name": "state",
-          "description": "Estado visual: 'info', 'warning', 'danger' ou 'success'.",
+          "description": "Estado visual: 'info', 'warning', 'danger' ou 'success'. Valores inválidos não aplicam estado.",
           "values": [{ "name": "BrFeedbackState" }]
         },
         {
@@ -4681,17 +4794,17 @@
         },
         {
           "name": "min-files",
-          "description": "Quantidade mínima de arquivos, incluindo arquivos já enviados.",
+          "description": "Quantidade mínima de arquivos, incluindo arquivos já enviados. Deve ser um inteiro não negativo; valores inválidos usam `0`.",
           "values": []
         },
         {
           "name": "max-files",
-          "description": "Quantidade máxima de arquivos. Zero significa sem limite.",
+          "description": "Quantidade máxima de arquivos. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam `0`.",
           "values": []
         },
         {
           "name": "max-file-size",
-          "description": "Tamanho máximo permitido para cada arquivo, em bytes. Zero significa sem limite.",
+          "description": "Tamanho máximo permitido para cada arquivo, em bytes. Zero significa sem limite. Deve ser um inteiro não negativo; valores inválidos usam `0`.",
           "values": []
         },
         {
@@ -4714,7 +4827,7 @@
     },
     {
       "name": "br-wizard",
-      "description": "Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).\n---\n\n\n### **Events:**\n - **brWizardStepChange** - Evento emitido APÓS mudar de etapa com sucesso.\n\nEste evento é disparado independente da origem da navegação:\n- Botões \"Avançar\" ou \"Voltar\"\n- Click direto em um step do indicador de progresso\n- Chamadas programáticas via métodos públicos (goToStep, nextStep, etc)\n- **brWizardBeforeStepChange** - Evento emitido ANTES de mudar de etapa (permite validação e cancelamento).\n\nComportamento:\n- Disparado apenas ao AVANÇAR (targetStep > currentStep)\n- Não é disparado ao VOLTAR (targetStep < currentStep)\n- Funciona tanto para cliques nos botões quanto para cliques diretos nos steps\n- Pode ser cancelado com `event.preventDefault()` para bloquear a navegação\n- **brWizardComplete** - Evento emitido ao concluir o wizard (última etapa).\n- **brWizardCancel** - Evento emitido ao cancelar o wizard.\n- **brWizardNavigationBlocked** - Evento emitido quando uma ação é bloqueada (validação falha, progressão linear impedida).\nEmite uma string indicando o motivo: 'linear-progression' ou 'validation-failed'.\nUse getCurrentStepIndex() para obter o contexto da etapa atual.\n\n### **Methods:**\n - **handleProgressionTypeChange()** - Observa mudanças no tipo de progressão.\nAtualiza a navegação dos painéis quando muda entre linear/nonlinear.\n- **handleInitialStepChange()** - Observa mudanças na etapa inicial.\nReinicializa o wizard quando a prop initialStep é alterada externamente.\n- **handleCurrentStepChange(newStep: _number_, oldStep: _number_)** - Observa mudanças na etapa atual (fonte única de verdade).\nSincroniza com br-step, atualiza painéis, anuncia mudança e move foco.\n- **handleSlotChange(event: _Event_)** - Detecta quando o slot muda (painéis adicionados/removidos dinamicamente).\nRedescobre os painéis e ressincroniza o estado.\n- **handleStepChange(event: _CustomEvent<{ activeStep: number }>_)** - Detecta quando o br-step muda de etapa ativa.\nValida e sincroniza a navegação com o componente interno br-step.\n- **nextStep(): __** - Avança para a próxima etapa.\nExecuta validação via evento `brWizardBeforeStepChange` antes de navegar.\n- **next(): _Promise<boolean>_** - Avança para a próxima etapa.\n- **previousStep(): __** - Volta para a etapa anterior.\nNão executa validação ao retornar.\n- **previous(): _Promise<boolean>_** - Retorna para a etapa anterior.\n- **goToStep(stepNumber: _number_): __** - Navega para uma etapa específica.\nExecuta validação se estiver avançando (etapa alvo > etapa atual).\n- **reset(): __** - Retorna à primeira etapa do wizard.\nNão executa validação (útil para reiniciar o fluxo).\n- **getCurrentStep(): __** - Retorna o elemento HTML do painel ativo no momento.\n- **getAllSteps(): __** - Retorna todos os painéis do wizard.\n- **getStepByIndex(stepNumber: _number_): __** - Retorna um painel específico pelo índice.\n- **getCurrentStepIndex(): __** - Retorna o índice (número) da etapa atual.\nA numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).\n- **getTotalSteps(): __** - Retorna o número total de etapas do wizard.\n- **render(): __** - Método de renderização principal do componente.\nMonta a estrutura completa do wizard com acessibilidade integrada.\n\n### **Slots:**\n - **default** - Slot para os painéis de etapa (br-wizard-panel) do wizard.\n- **cancel-button** - Conteúdo customizado do botão de cancelar. Quando utilizado, o texto padrão \"Cancelar\" é substituído.\n- **next-button** - Conteúdo customizado do botão de avançar/concluir. Quando utilizado, os textos padrão \"Avançar\" e \"Concluir\" são substituídos.\n- **previous-button** - Conteúdo customizado do botão de voltar. Quando utilizado, o texto padrão \"Voltar\" é substituído.\n\n### **CSS Parts:**\n - **form** - Área do formulário do wizard.\n- **panel** - Painel ativo do wizard.\n- **progress** - Área de progresso do wizard.\n- **content** - Conteúdo do painel ativo.\n- **buttons** - Área de botões de navegação.",
+      "description": "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.\n\n### Para que serve\n\n- **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.\n- **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\".\n- **Validação por etapa:** Permite interceptar o avanço de cada passo para validação antes de liberar o próximo painel.\n\n### Quando utilizar\n\n- **Utilize quando:**\n  - Houver um processo de cadastro, requerimento, compra ou configuração estruturado em etapas com dependência de sequência.\n  - For essencial oferecer navegação pré-programada de retorno e avanço com controle de estado.\n- **Evite e prefira outro componente quando:**\n  - O objetivo for apenas mostrar o status de um pedido já concluído (use `br-step` simples).\n  - O usuário puder navegar em qualquer ordem entre as seções da tela (use `br-tab`).\n\n### Composição e Subcomponentes\n\n| Subcomponente | Papel | Regra de uso |\n| --- | --- | --- |\n| `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. |\n| `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`. |\n\n### Como os subcomponentes se relacionam\n\nO `br-wizard` gerencia ativamente os elementos `br-wizard-panel` declarados em seu interior:\n1. O pai exibe apenas o painel correspondente à etapa atual (`activeStep`), mantendo os demais ocultos.\n2. 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é.\n\nPara 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).\n---\n\n\n### **Events:**\n - **brWizardStepChange** - Evento emitido APÓS mudar de etapa com sucesso.\n\nEste evento é disparado independente da origem da navegação:\n- Botões \"Avançar\" ou \"Voltar\"\n- Click direto em um step do indicador de progresso\n- Chamadas programáticas via métodos públicos (goToStep, nextStep, etc)\n- **brWizardBeforeStepChange** - Evento emitido ANTES de mudar de etapa (permite validação e cancelamento).\n\nComportamento:\n- Disparado apenas ao AVANÇAR (targetStep > currentStep)\n- Não é disparado ao VOLTAR (targetStep < currentStep)\n- Funciona tanto para cliques nos botões quanto para cliques diretos nos steps\n- Pode ser cancelado com `event.preventDefault()` para bloquear a navegação\n- **brWizardComplete** - Evento emitido ao concluir o wizard (última etapa).\n- **brWizardCancel** - Evento emitido ao cancelar o wizard.\n- **brWizardNavigationBlocked** - Evento emitido quando uma ação é bloqueada (validação falha, progressão linear impedida).\nEmite uma string indicando o motivo: 'linear-progression' ou 'validation-failed'.\nUse getCurrentStepIndex() para obter o contexto da etapa atual.\n\n### **Methods:**\n - **handleProgressionTypeChange()** - Observa mudanças no tipo de progressão.\nAtualiza a navegação dos painéis quando muda entre linear/nonlinear.\n- **handleInitialStepChange()** - Observa mudanças na etapa inicial.\nReinicializa o wizard quando a prop initialStep é alterada externamente.\n- **handleCurrentStepChange(newStep: _number_, oldStep: _number_)** - Observa mudanças na etapa atual (fonte única de verdade).\nSincroniza com br-step, atualiza painéis, anuncia mudança e move foco.\n- **handleSlotChange(event: _Event_)** - Detecta quando o slot muda (painéis adicionados/removidos dinamicamente).\nRedescobre os painéis e ressincroniza o estado.\n- **handleStepChange(event: _CustomEvent<{ activeStep: number }>_)** - Detecta quando o br-step muda de etapa ativa.\nValida e sincroniza a navegação com o componente interno br-step.\n- **nextStep(): __** - Avança para a próxima etapa.\nExecuta validação via evento `brWizardBeforeStepChange` antes de navegar.\n- **next(): _Promise<boolean>_** - Avança para a próxima etapa.\n- **previousStep(): __** - Volta para a etapa anterior.\nNão executa validação ao retornar.\n- **previous(): _Promise<boolean>_** - Retorna para a etapa anterior.\n- **goToStep(stepNumber: _number_): __** - Navega para uma etapa específica.\nExecuta validação se estiver avançando (etapa alvo > etapa atual).\n- **reset(): __** - Retorna à primeira etapa do wizard.\nNão executa validação (útil para reiniciar o fluxo).\n- **getCurrentStep(): __** - Retorna o elemento HTML do painel ativo no momento.\n- **getAllSteps(): __** - Retorna todos os painéis do wizard.\n- **getStepByIndex(stepNumber: _number_): __** - Retorna um painel específico pelo índice.\n- **getCurrentStepIndex(): __** - Retorna o índice (número) da etapa atual.\nA numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).\n- **getTotalSteps(): __** - Retorna o número total de etapas do wizard.\n- **render(): __** - Método de renderização principal do componente.\nMonta a estrutura completa do wizard com acessibilidade integrada.\n\n### **Slots:**\n - **default** - Slot para os painéis de etapa (br-wizard-panel) do wizard.\n- **cancel-button** - Conteúdo customizado do botão de cancelar. Quando utilizado, o texto padrão \"Cancelar\" é substituído.\n- **next-button** - Conteúdo customizado do botão de avançar/concluir. Quando utilizado, os textos padrão \"Avançar\" e \"Concluir\" são substituídos.\n- **previous-button** - Conteúdo customizado do botão de voltar. Quando utilizado, o texto padrão \"Voltar\" é substituído.\n\n### **CSS Parts:**\n - **form** - Área do formulário do wizard.\n- **panel** - Painel ativo do wizard.\n- **progress** - Área de progresso do wizard.\n- **content** - Conteúdo do painel ativo.\n- **buttons** - Área de botões de navegação.",
       "attributes": [
         {
           "name": "step",
@@ -4723,12 +4836,12 @@
         },
         {
           "name": "initial-step",
-          "description": "Índice da etapa inicial do wizard.\nDefine qual etapa será exibida ao carregar o componente.\nA numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).",
+          "description": "Índice da etapa inicial do wizard.\nDefine qual etapa será exibida ao carregar o componente.\nA numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).\nValores inválidos usam 1.",
           "values": []
         },
         {
           "name": "initial-index",
-          "description": "Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`.",
+          "description": "Índice inicial zero-based. Quando informado, tem precedência sobre `initialStep`; valores inválidos usam 0.",
           "values": []
         },
         {
@@ -4756,7 +4869,7 @@
     },
     {
       "name": "br-wizard-panel",
-      "description": "Wizard Panel (Painel de etapa do Wizard)\nRepresenta uma etapa individual dentro do br-wizard.\n---\n\n\n### **Slots:**\n - **default** - Slot para o conteúdo da etapa (formulários, campos ou informações da fase atual).\n\n### **CSS Parts:**\n - **panel** - Wrapper do painel.\n- **content** - Área de conteúdo do painel.",
+      "description": "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.\n\n### Papel na composição\n\n- Agrupa todos os campos de formulário e conteúdos daquela etapa.\n- Informa o título e subtítulo da etapa que serão refletidos na barra de progresso do wizard.\n\n### Regra de uso e relacionamento\n\nDeve 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`.\n\nPara a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).\n---\n\n\n### **Slots:**\n - **default** - Slot para o conteúdo da etapa (formulários, campos ou informações da fase atual).\n\n### **CSS Parts:**\n - **panel** - Wrapper do painel.\n- **content** - Área de conteúdo do painel.",
       "attributes": [
         {
           "name": "label",