@schenkerjon/ng-govbr-tw 1.1.0 → 1.2.0

package/README.md

@@ -1,8 +1,81 @@
 # @schenkerjon/ng-govbr-tw
 
-Biblioteca Angular de componentes baseados no **Design System do Governo Federal (GovBR DS)**, estilizados com **Tailwind CSS 3**. Componentes standalone, acessíveis e prontos para produção.
+<p align="center">
+  <a href="https://jordaobass.github.io/ng-govbr-tw/">
+    <img src="https://img.shields.io/badge/🚀_SHOWCASE-Ver_Demo_Online-1351b4?style=for-the-badge&labelColor=071D41" alt="Ver Demo Online" />
+  </a>
+</p>
+
+<p align="center">
+  <img src="https://www.gov.br/++theme++padrao_govbr/img/govbr-logo-large.png" alt="Gov.br" height="60" />
+</p>
+
+<p align="center">
+  Biblioteca Angular <strong>open-source</strong> que implementa componentes visuais baseados no <strong>Gov.br Design System</strong>, utilizando <strong>Tailwind CSS 3</strong> para estilização.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@schenkerjon/ng-govbr-tw"><img src="https://img.shields.io/npm/v/@schenkerjon/ng-govbr-tw.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@schenkerjon/ng-govbr-tw"><img src="https://img.shields.io/npm/dm/@schenkerjon/ng-govbr-tw.svg" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/Angular-17%2B-dd0031.svg" alt="Angular 17+" />
+  <img src="https://img.shields.io/badge/Tailwind-3.x-38bdf8.svg" alt="Tailwind CSS 3" />
+  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" />
+</p>
+
+---
+
+## Índice
+
+- [Visão Geral](#visão-geral)
+- [Instalação](#instalação)
+- [Configuração](#configuração)
+  - [Tailwind CSS](#1-tailwind-css)
+  - [CSS Base](#2-css-base)
+  - [Font Awesome](#3-font-awesome-opcional)
+- [Uso Básico](#uso-básico)
+- [Componentes](#componentes)
+  - [Formulários](#formulários)
+  - [Feedback](#feedback)
+  - [Navegação](#navegação)
+  - [Conteúdo](#conteúdo)
+  - [Avançados](#avançados)
+- [Animações](#animações)
+  - [Configuração de Animações](#configuração-de-animações)
+  - [Componentes Animados](#componentes-animados)
+- [Acessibilidade](#acessibilidade)
+- [Tokens Gov.br](#tokens-govbr)
+- [Exemplos Detalhados](#exemplos-detalhados)
+  - [Formulário Completo](#formulário-completo)
+  - [Select com Busca](#select-com-busca)
+  - [Modal](#modal)
+  - [Tabs](#tabs)
+  - [Accordion](#accordion)
+  - [Sidebar com Menu](#sidebar-com-menu)
+  - [Wizard Multi-etapas](#wizard-multi-etapas)
+  - [Upload de Arquivos](#upload-de-arquivos)
+  - [Toast Notifications](#toast-notifications)
+- [Inputs Especializados](#inputs-especializados)
+- [Demo](#demo)
+- [Contribuição](#contribuição)
+- [Licença](#licença)
+
+---
+
+## Visão Geral
+
+O objetivo deste projeto é oferecer uma alternativa leve e moderna para construir interfaces de sistemas governamentais brasileiros com Angular, seguindo os padrões visuais definidos pelo Gov.br.
+
+### Características
+
+- **Standalone Components** — Compatível com Angular 17+
+- **Tailwind CSS 3** — Classes utilitárias para fácil customização
+- **Acessibilidade** — ARIA labels, navegação por teclado, suporte a reduced-motion
+- **Formulários Reativos** — ControlValueAccessor em todos os inputs
+- **Animações Suaves** — Transições respeitando preferências do usuário
+- **LGPD Ready** — Componente de cookies integrado
+- **Sem dependências pesadas** — Não depende do Web Components oficial
 
-Compatível com Angular 17, 18 e 19.
+---
 
 ## Instalação
 
@@ -10,1120 +83,735 @@ Compatível com Angular 17, 18 e 19.
 npm install @schenkerjon/ng-govbr-tw
 ```
 
-### Configuração automática (recomendado)
-
-```bash
-ng add @schenkerjon/ng-govbr-tw
-```
+---
 
-O schematic configura automaticamente:
-- Preset Tailwind no `tailwind.config.js`
-- Fontes Rawline e Font Awesome no `index.html`
-- Import do CSS no `styles.css`
+## Configuração
 
-### Configuração manual
+### 1. Tailwind CSS
 
-1. Adicione o preset ao `tailwind.config.js`:
+Adicione o preset da biblioteca no seu `tailwind.config.js`:
 
 ```js
-const govbrPreset = require('@schenkerjon/ng-govbr-tw/tailwind.preset');
-
 module.exports = {
-  presets: [govbrPreset],
+  presets: [require('@schenkerjon/ng-govbr-tw/tailwind.preset')],
   content: [
     "./src/**/*.{html,ts}",
-    "./node_modules/@schenkerjon/ng-govbr-tw/**/*.{mjs,js}"
+    "./node_modules/@schenkerjon/ng-govbr-tw/**/*.{html,ts,mjs}"
   ],
+  // ...
 };
 ```
 
-2. Adicione as fontes no `index.html`:
-
-```html
-<link href="https://fonts.googleapis.com/css2?family=Raleway:wght@100;300;400;500;600;700;900&display=swap" rel="stylesheet" />
-<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" rel="stylesheet" />
-```
+### 2. CSS Base
 
-3. Importe o CSS base:
+Importe o CSS base no seu `styles.css`:
 
 ```css
-/* styles.css */
-@import '@schenkerjon/ng-govbr-tw/src/lib/styles/govbr-tw.css';
-```
-
----
-
-## Uso
-
-Todos os componentes são **standalone** — importe diretamente:
-
-```typescript
-import { BrButtonComponent, BrInputComponent } from '@schenkerjon/ng-govbr-tw';
-
-@Component({
-  standalone: true,
-  imports: [BrButtonComponent, BrInputComponent],
-})
-```
-
----
-
-## Sumário de Componentes
-
-| Categoria | Componentes |
-|-----------|-------------|
-| **Layout** | `br-layout`, `br-header`, `br-footer`, `br-menu`, `br-menu-item`, `br-sidebar` |
-| **Navegação** | `br-menu-bar`, `br-mega-menu`, `br-breadcrumb`, `br-tab`, `br-pagination` |
-| **Formulários** | `br-input`, `br-select`, `br-checkbox`, `br-radio-group`, `br-textarea`, `br-datepicker`, `br-timepicker`, `br-datetimepicker` |
-| **Botões** | `br-button`, `br-magic-button` |
-| **Dados** | `br-table`, `br-card`, `br-item`, `br-list`, `br-badge` |
-| **Feedback** | `br-message`, `br-modal`, `br-loading`, `br-tooltip` |
-| **Utilitários** | `br-accordion`, `br-wizard`, `br-cookiebar` |
-
----
-
-## Layout
-
-### br-layout
-
-Estrutura principal da aplicação. Organiza header, menu lateral (push), conteúdo e footer.
-
-```html
-<br-layout>
-  <br-header
-    systemTitle="Meu Sistema"
-    logoSrc="assets/logo.png"
-    (menuToggle)="menuOpen = $event"
-  ></br-header>
-
-  <br-menu [open]="menuOpen" (openChange)="menuOpen = $event">
-    <br-menu-item label="Início" icon="house" route="/"></br-menu-item>
-    <br-menu-item label="Documentos" icon="file" route="/docs"></br-menu-item>
-  </br-menu>
-
-  <div>Conteúdo da página</div>
-
-  <br-footer logoSrc="assets/logo.png"></br-footer>
-</br-layout>
-```
-
----
-
-### br-header
+@import 'tailwindcss/base';
+@import 'tailwindcss/components';
+@import 'tailwindcss/utilities';
 
-Header GovBR DS com duas linhas: logo/ações (topo) e título/busca (inferior).
-
-```html
-<br-header
-  systemTitle="Nome do Sistema"
-  systemSubtitle="Órgão responsável"
-  logoSrc="assets/gov-logo.png"
-  logoHref="/"
-  signature="gov.br"
-  variant="primary"
-  density="medium"
-  [sticky]="true"
-  menuMode="sidebar"
-  [showSearch]="true"
-  [showLogin]="true"
-  [hasLinks]="true"
-  [hasFunctions]="true"
-  userName="João Silva"
-  userRole="Administrador"
-  avatarSrc="assets/avatar.jpg"
-  (menuToggle)="menuOpen = $event"
-  (searchSubmit)="onSearch($event)"
-  (signIn)="onLogin()"
-  (logout)="onLogout()"
->
-  <!-- Links de acesso rápido (dropdown ⋮) -->
-  <a header-links href="/acessibilidade" class="block px-4 py-2 text-sm hover:bg-gray-50">
-    Acessibilidade
-  </a>
-  <a header-links href="/mapa-do-site" class="block px-4 py-2 text-sm hover:bg-gray-50">
-    Mapa do site
-  </a>
-
-  <!-- Funcionalidades do sistema (dropdown ⊞) -->
-  <a header-functions href="/notificacoes" class="block px-4 py-2 text-sm hover:bg-gray-50">
-    Notificações
-  </a>
-
-  <!-- Menu do avatar -->
-  <a avatar-menu href="/perfil" class="block px-4 py-2 text-sm hover:bg-gray-50">
-    Meu perfil
-  </a>
-</br-header>
+@import '@schenkerjon/ng-govbr-tw/styles/govbr-tw.css';
 ```
 
-| Input | Tipo | Padrão | Descrição |
-|-------|------|--------|-----------|
-| `systemTitle` | `string` | `''` | Título do sistema |
-| `systemSubtitle` | `string` | — | Subtítulo (órgão, departamento) |
-| `logoSrc` | `string` | `''` | URL do logo |
-| `logoHref` | `string` | — | Link do logo |
-| `signature` | `string` | — | Assinatura (ex: "gov.br") |
-| `variant` | `'primary' \| 'white'` | `'primary'` | Tema de cores |
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` | Tamanho do header |
-| `sticky` | `boolean` | `false` | Header fixo no topo |
-| `menuMode` | `'sidebar' \| 'mega' \| 'none'` | `'sidebar'` | Tipo de menu |
-| `showSearch` | `boolean` | `true` | Exibir busca |
-| `showContrast` | `boolean` | `false` | Exibir botão de alto contraste |
-| `contrastActive` | `boolean` | `false` | Alto contraste ativo |
-| `showLogin` | `boolean` | `true` | Exibir botão entrar |
-| `hasLinks` | `boolean` | `false` | Exibir dropdown de links rápidos |
-| `hasFunctions` | `boolean` | `false` | Exibir dropdown de funcionalidades |
-| `userName` | `string` | — | Nome do usuário logado |
-| `userRole` | `string` | — | Cargo/papel do usuário |
-| `avatarSrc` | `string` | — | URL da foto do avatar |
-
-| Output | Tipo | Descrição |
-|--------|------|-----------|
-| `menuToggle` | `boolean` | Menu abriu/fechou |
-| `searchSubmit` | `string` | Texto pesquisado |
-| `signIn` | `void` | Clicou em "Entrar" |
-| `logout` | `void` | Clicou em "Sair" |
-| `contrastChange` | `boolean` | Alto contraste alterado |
-
-**Slots de conteúdo:** `[header-links]`, `[header-functions]`, `[avatar-menu]`
+### 3. Font Awesome (Opcional)
 
----
-
-### br-menu
-
-Menu lateral push — quando aberto, empurra o conteúdo para o lado.
+Os ícones utilizam Font Awesome. Adicione no `index.html`:
 
 ```html
-<br-menu [open]="menuOpen" (openChange)="menuOpen = $event" variant="white" width="default">
-  <br-menu-item label="Início" icon="house" route="/" [exact]="true"></br-menu-item>
-  <br-menu-item label="Usuários" icon="users" route="/usuarios"></br-menu-item>
-
-  <!-- Item com submenu -->
-  <br-menu-item label="Configurações" icon="gear" [hasChildren]="true" [expanded]="configExpanded" (expandedChange)="configExpanded = $event">
-    <br-menu-item label="Geral" route="/config/geral"></br-menu-item>
-    <br-menu-item label="Segurança" route="/config/seguranca"></br-menu-item>
-  </br-menu-item>
-
-  <!-- Footer do menu -->
-  <div menu-footer>
-    <span class="text-xs text-gray-500">v1.0.0</span>
-  </div>
-</br-menu>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css" />
 ```
 
-| Input | Tipo | Padrão | Descrição |
-|-------|------|--------|-----------|
-| `open` | `boolean` | `true` | Menu aberto/fechado |
-| `variant` | `'white' \| 'light'` | `'white'` | Cor de fundo |
-| `width` | `'narrow' \| 'default' \| 'wide'` | `'default'` | Largura (60/64/72) |
-| `hasFooter` | `boolean` | `false` | Exibir área de footer |
-| `ariaLabel` | `string` | `'Menu principal'` | Label de acessibilidade |
-
-### br-menu-item
-
-| Input | Tipo | Padrão | Descrição |
-|-------|------|--------|-----------|
-| `route` | `string \| unknown[]` | — | Rota Angular (routerLink) |
-| `label` | `string` | `''` | Texto do item |
-| `icon` | `string` | — | Nome Font Awesome (sem `fa-`) |
-| `badge` | `string \| number` | — | Badge/contador vermelho |
-| `exact` | `boolean` | `false` | routerLinkActive exato |
-| `hasChildren` | `boolean` | `false` | Tem submenu |
-| `expanded` | `boolean` | `false` | Submenu expandido |
-
----
-
-### br-footer
-
-```html
-<br-footer logoSrc="assets/logo-footer.png">
-  <div class="text-sm text-gray-600">© 2024 Governo Federal</div>
-</br-footer>
-```
+Ou instale via npm:
 
----
-
-## Navegação
-
-### br-menu-bar
-
-Barra de navegação horizontal abaixo do header.
-
-```html
-<br-menu-bar variant="primary">
-  <br-menu-bar-item label="Início" icon="house" route="/"></br-menu-bar-item>
-  <br-menu-bar-item label="Serviços" icon="grid" [hasSubmenu]="true">
-    <br-menu-bar-sub-item label="Consulta" route="/servicos/consulta"></br-menu-bar-sub-item>
-    <br-menu-bar-sub-item label="Solicitação" route="/servicos/solicitacao"></br-menu-bar-sub-item>
-  </br-menu-bar-item>
-</br-menu-bar>
-```
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `variant` | `'primary' \| 'dark' \| 'white'` | `'primary'` |
-
----
-
-### br-mega-menu
-
-Menu mega com colunas e categorias.
-
-```html
-<br-mega-menu variant="primary" [activePanel]="activePanel" (activePanelChange)="activePanel = $event">
-  <br-mega-menu-trigger label="Serviços" panelId="servicos" icon="grid"></br-mega-menu-trigger>
-  <br-mega-menu-trigger label="Institucional" panelId="institucional"></br-mega-menu-trigger>
-
-  <br-mega-menu-panel panelId="servicos" [isActive]="activePanel === 'servicos'">
-    <br-mega-menu-column title="Cidadão">
-      <br-mega-menu-link label="CPF" route="/servicos/cpf" icon="id-card"></br-mega-menu-link>
-      <br-mega-menu-link label="Passaporte" route="/servicos/passaporte"></br-mega-menu-link>
-    </br-mega-menu-column>
-  </br-mega-menu-panel>
-</br-mega-menu>
+```bash
+npm install @fortawesome/fontawesome-free
 ```
 
 ---
 
-### br-breadcrumb
-
-```html
-<br-breadcrumb [items]="breadcrumbs" [showHome]="true" homeRoute="/"></br-breadcrumb>
-```
+## Uso Básico
 
 ```typescript
-import { BrBreadcrumbItem } from '@schenkerjon/ng-govbr-tw';
+import { BrButtonComponent } from '@schenkerjon/ng-govbr-tw';
 
-breadcrumbs: BrBreadcrumbItem[] = [
-  { label: 'Serviços', route: '/servicos' },
-  { label: 'Consulta', route: '/servicos/consulta' },
-  { label: 'Resultado' },
-];
-```
-
----
-
-### br-tab
-
-```html
-<br-tab density="medium" [activeIndex]="0" (activeIndexChange)="onTabChange($event)">
-  <br-tab-panel label="Dados" icon="file">
-    Conteúdo da aba Dados
-  </br-tab-panel>
-  <br-tab-panel label="Histórico" icon="clock" [counter]="5">
-    Conteúdo da aba Histórico
-  </br-tab-panel>
-  <br-tab-panel label="Desativada" [disabled]="true">
-    ...
-  </br-tab-panel>
-</br-tab>
-```
-
-| Input (br-tab) | Tipo | Padrão |
-|-------|------|--------|
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` |
-| `activeIndex` | `number` | `0` |
-| `inverted` | `boolean` | `false` |
-
-| Input (br-tab-panel) | Tipo | Padrão |
-|-------|------|--------|
-| `label` | `string` | `''` |
-| `icon` | `string` | — |
-| `counter` | `number` | — |
-| `disabled` | `boolean` | `false` |
-
----
-
-### br-pagination
-
-```html
-<br-pagination
-  [page]="currentPage"
-  [totalPages]="20"
-  [maxVisible]="5"
-  [showFirstLast]="true"
-  density="medium"
-  (pageChange)="currentPage = $event"
-></br-pagination>
-```
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `page` | `number` | `1` |
-| `totalPages` | `number` | `1` |
-| `maxVisible` | `number` | `5` |
-| `showFirstLast` | `boolean` | `false` |
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` |
-
----
-
-## Formulários
-
-Todos os componentes de formulário implementam `ControlValueAccessor` — funcionam com `[(ngModel)]` e `formControl`.
-
-### br-input
-
-```html
-<br-input
-  label="Nome completo"
-  placeholder="Digite seu nome"
-  [(ngModel)]="nome"
-  [required]="true"
-  icon="user"
-  density="medium"
-  helperText="Informe seu nome completo"
-></br-input>
-
-<!-- Com validação -->
-<br-input label="E-mail" type="email" [(ngModel)]="email" error="E-mail inválido"></br-input>
-
-<!-- Busca -->
-<br-input type="search" placeholder="Pesquisar..." [(ngModel)]="busca" (searchSubmit)="pesquisar($event)"></br-input>
-
-<!-- Arquivo -->
-<br-input label="Documento" type="file" (fileSelected)="onFile($event)"></br-input>
-```
-
-| Input | Tipo | Padrão | Descrição |
-|-------|------|--------|-----------|
-| `label` | `string` | — | Rótulo do campo |
-| `type` | `string` | `'text'` | text, email, password, number, search, file, select, textarea |
-| `placeholder` | `string` | `''` | Placeholder |
-| `required` | `boolean` | `false` | Obrigatório |
-| `error` | `string` | — | Mensagem de erro |
-| `successMessage` | `string` | — | Mensagem de sucesso |
-| `warningMessage` | `string` | — | Mensagem de aviso |
-| `helperText` | `string` | — | Texto auxiliar |
-| `icon` | `string` | — | Ícone Font Awesome |
-| `iconRight` | `boolean` | `false` | Ícone à direita |
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` | Tamanho |
-| `highlight` | `boolean` | `false` | Destaque visual |
-| `maxLength` | `number` | — | Máximo de caracteres |
-
----
-
-### br-select
-
-```html
-<br-select
-  label="Estado"
-  placeholder="Selecione o estado"
-  [(ngModel)]="estado"
-  [options]="estados"
-  [searchable]="true"
-  [required]="true"
-></br-select>
-
-<!-- Seleção múltipla -->
-<br-select label="Categorias" [(ngModel)]="categorias" [options]="categoriasOpts" [multiple]="true"></br-select>
-```
+@Component({
+  standalone: true,
+  imports: [BrButtonComponent],
+  template: `<br-button variant="primary">Entrar</br-button>`
+})
+export class MyComponent {}
+```
+
+---
+
+## Componentes
+
+### Formulários
+
+| Componente | Seletor | Descrição |
+|---|---|---|
+| `BrButtonComponent` | `<br-button>` | Botão com variantes primary, secondary, danger, outline |
+| `BrInputComponent` | `<br-input>` | Campo de entrada com validação e máscara |
+| `BrSelectComponent` | `<br-select>` | Select com busca e multi-seleção |
+| `BrTextareaComponent` | `<br-textarea>` | Área de texto com contagem de caracteres |
+| `BrCheckboxComponent` | `<br-checkbox>` | Checkbox com estados valid/invalid/indeterminate |
+| `BrRadioGroupComponent` | `<br-radio-group>` | Grupo de radio buttons |
+| `BrSwitchComponent` | `<br-switch>` | Toggle switch on/off |
+| `BrDatepickerComponent` | `<br-datepicker>` | Seletor de data com calendário |
+| `BrTimepickerComponent` | `<br-timepicker>` | Seletor de horário |
+| `BrDatetimepickerComponent` | `<br-datetimepicker>` | Seletor de data e hora combinado |
+| `BrUploadComponent` | `<br-upload>` | Upload de arquivos com drag & drop |
+
+### Feedback
+
+| Componente | Seletor | Descrição |
+|---|---|---|
+| `BrBadgeComponent` | `<br-badge>` | Badge/tag de status |
+| `BrChipComponent` | `<br-chip>` | Chip selecionável/removível |
+| `BrMessageComponent` | `<br-message>` | Mensagem de feedback (success, danger, warning, info) |
+| `BrTooltipComponent` | `<br-tooltip>` | Tooltip posicionável com variantes |
+| `BrLoadingComponent` | `<br-loading>` | Spinner e barra de progresso |
+| `BrSkeletonComponent` | `<br-skeleton>` | Placeholder de carregamento |
+| `BrModalComponent` | `<br-modal>` | Dialog/modal com footer configurável |
+| `BrNotificationComponent` | `<br-notification>` | Badge de notificação com contador |
+| `BrToastComponent` | `<br-toast>` | Toast notifications |
+
+### Navegação
+
+| Componente | Seletor | Descrição |
+|---|---|---|
+| `BrHeaderComponent` | `<br-header>` | Cabeçalho do sistema Gov.br |
+| `BrFooterComponent` | `<br-footer>` | Rodapé do sistema |
+| `BrMenuComponent` | `<br-menu>` | Menu lateral push |
+| `BrMenuItemComponent` | `<br-menu-item>` | Item do menu |
+| `BrMenuBarComponent` | `<br-menu-bar>` | Barra de menu horizontal |
+| `BrMegaMenuComponent` | `<br-mega-menu>` | Mega menu com painéis |
+| `BrSidebarComponent` | `<br-sidebar>` | Sidebar colapsável com mobile drawer |
+| `BrBreadcrumbComponent` | `<br-breadcrumb>` | Navegação breadcrumb |
+| `BrTabComponent` | `<br-tab>` | Navegação por abas |
+| `BrPaginationComponent` | `<br-pagination>` | Paginação com itens por página |
+
+### Conteúdo
+
+| Componente | Seletor | Descrição |
+|---|---|---|
+| `BrCardComponent` | `<br-card>` | Card informativo com ícone e link |
+| `BrTableComponent` | `<br-table>` | Tabela com ordenação e paginação |
+| `BrListComponent` | `<br-list>` | Lista estruturada |
+| `BrItemComponent` | `<br-item>` | Item de lista com avatar/ícone/tag |
+| `BrAccordionComponent` | `<br-accordion>` | Accordion com modo single/multiple |
+| `BrDividerComponent` | `<br-divider>` | Divisor horizontal/vertical |
+| `BrAvatarComponent` | `<br-avatar>` | Avatar com imagem ou iniciais |
+| `BrTimelineComponent` | `<br-timeline>` | Timeline de eventos |
+| `BrLayoutComponent` | `<br-layout>` | Layout principal (header + menu + content + footer) |
+
+### Avançados
+
+| Componente | Seletor | Descrição |
+|---|---|---|
+| `BrWizardComponent` | `<br-wizard>` | Stepper para fluxos multi-etapas |
+| `BrStepperComponent` | `<br-stepper>` | Indicador de progresso em etapas |
+| `BrCookiebarComponent` | `<br-cookiebar>` | Barra de consentimento de cookies (LGPD) |
+| `BrMagicButtonComponent` | `<br-magic-button>` | Botão flutuante (FAB) com speed dial |
+| `BrSigninComponent` | `<br-signin>` | Botão de login Gov.br |
+
+---
+
+## Animações
+
+A biblioteca inclui animações suaves em vários componentes, todas respeitando a preferência do usuário por movimento reduzido (`prefers-reduced-motion`).
+
+### Configuração de Animações
 
 ```typescript
-import { BrSelectOption } from '@schenkerjon/ng-govbr-tw';
-
-estados: BrSelectOption[] = [
-  { label: 'São Paulo', value: 'SP' },
-  { label: 'Rio de Janeiro', value: 'RJ' },
-  { label: 'Minas Gerais', value: 'MG' },
-];
-```
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `label` | `string` | — |
-| `placeholder` | `string` | `'Selecione'` |
-| `options` | `BrSelectOption[]` | `[]` |
-| `required` | `boolean` | `false` |
-| `error` | `string` | — |
-| `multiple` | `boolean` | `false` |
-| `searchable` | `boolean` | `false` |
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` |
+import { BrAnimationService } from '@schenkerjon/ng-govbr-tw';
 
----
-
-### br-checkbox
-
-```html
-<br-checkbox label="Aceito os termos de uso" [(ngModel)]="aceitoTermos"></br-checkbox>
-
-<br-checkbox label="Selecionar todos" [indeterminate]="algumSelecionado" [(ngModel)]="todosSelecionados"></br-checkbox>
-```
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `label` | `string` | — |
-| `indeterminate` | `boolean` | `false` |
-| `error` | `string` | — |
-| `size` | `'default' \| 'small'` | `'default'` |
-| `state` | `'default' \| 'valid' \| 'invalid'` | `'default'` |
-
----
+@Component({...})
+export class AppComponent {
+  private animationService = inject(BrAnimationService);
 
-### br-radio-group
+  // Desabilitar animações globalmente
+  disableAnimations() {
+    this.animationService.setEnabled(false);
+  }
 
-```html
-<br-radio-group
-  legend="Tipo de pessoa"
-  [(ngModel)]="tipoPessoa"
-  [options]="tipoPessoaOpts"
-  [inline]="true"
-></br-radio-group>
+  // Verificar status
+  isEnabled() {
+    return this.animationService.isEnabled();
+  }
+}
 ```
 
-```typescript
-import { BrRadioOption } from '@schenkerjon/ng-govbr-tw';
+### Componentes Animados
 
-tipoPessoaOpts: BrRadioOption[] = [
-  { label: 'Pessoa Física', value: 'PF' },
-  { label: 'Pessoa Jurídica', value: 'PJ' },
-];
-```
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `legend` | `string` | — |
-| `options` | `BrRadioOption[]` | `[]` |
-| `required` | `boolean` | `false` |
-| `error` | `string` | — |
-| `inline` | `boolean` | `false` |
-| `size` | `'default' \| 'small'` | `'default'` |
+| Componente | Tipo de Animação | Descrição |
+|---|---|---|
+| `br-message` | Slide-in | Mensagens deslizam ao aparecer |
+| `br-select` | Dropdown | Menu abre com fade + slide |
+| `br-notification` | Bounce | Badge pulsa ao aparecer |
+| `br-sidebar` | Slide + Fade | Drawer mobile desliza, overlay faz fade |
+| `br-tab` | Fade-in | Conteúdo das abas faz fade suave |
+| `br-datepicker` | Dropdown | Calendário abre com animação |
+| `br-timepicker` | Dropdown | Painel de horário abre com animação |
+| `br-cookiebar` | Slide-up | Barra sobe da parte inferior |
+| `br-menu` | Slide-in | Menu desliza da esquerda |
+| `br-mega-menu` | Dropdown | Painel mega menu abre com animação |
+| `br-wizard` | Fade-slide | Steps deslizam horizontalmente |
+| `br-upload` | Enter | Arquivos aparecem com animação |
+| `br-modal` | Scale + Fade | Modal escala ao abrir |
+| `br-accordion` | Collapse | Conteúdo expande/colapsa suavemente |
+| `br-tooltip` | Fade | Tooltip aparece com fade |
+| `br-loading` | Spin/Pulse | Animação contínua de loading |
 
 ---
 
-### br-textarea
-
-```html
-<br-textarea
-  label="Observações"
-  placeholder="Digite suas observações..."
-  [(ngModel)]="observacoes"
-  [rows]="5"
-  [maxLength]="500"
-  helperText="Máximo de 500 caracteres"
-  resizable="vertical"
-></br-textarea>
-```
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `label` | `string` | — |
-| `placeholder` | `string` | `''` |
-| `rows` | `number` | `4` |
-| `maxLength` | `number` | — |
-| `helperText` | `string` | — |
-| `error` | `string` | — |
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` |
-| `resizable` | `'none' \| 'vertical' \| 'both'` | `'vertical'` |
-
----
+## Acessibilidade
 
-### br-datepicker
+Todos os componentes seguem as diretrizes WCAG 2.1:
 
-Seletor de data com calendário dropdown. Valor no formato `"dd/mm/aaaa"`.
+- **ARIA Labels** — Atributos aria-label, aria-describedby, role
+- **Navegação por Teclado** — Tab, Enter, Escape, Arrow keys
+- **Focus Visible** — Indicadores de foco visíveis
+- **Reduced Motion** — Respeita `prefers-reduced-motion`
+- **Contraste** — Cores seguem o padrão Gov.br (AA/AAA)
+- **Screen Readers** — Textos alternativos e live regions
 
 ```html
-<br-datepicker
-  label="Data de nascimento"
-  [(ngModel)]="dataNascimento"
-  [required]="true"
-  hint="Formato: dd/mm/aaaa"
-></br-datepicker>
+<!-- Exemplo de acessibilidade -->
+<br-button
+  variant="primary"
+  ariaLabel="Enviar formulário de contato"
+  [loading]="true"
+  loadingText="Enviando..."
+>
+  Enviar
+</br-button>
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `label` | `string` | — |
-| `placeholder` | `string` | `'dd/mm/aaaa'` |
-| `hint` | `string` | — |
-| `error` | `string` | — |
-| `required` | `boolean` | `false` |
-| `block` | `boolean` | `true` |
-
 ---
 
-### br-timepicker
-
-Seletor de hora com painel de horas e minutos. Valor no formato `"HH:MM"`.
-
-```html
-<br-timepicker label="Horário" [(ngModel)]="horario" [step]="15"></br-timepicker>
-```
+## Tokens Gov.br
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `label` | `string` | — |
-| `placeholder` | `string` | `'HH:MM'` |
-| `step` | `number` | `5` |
-| `hint` | `string` | — |
-| `error` | `string` | — |
-| `required` | `boolean` | `false` |
+O preset Tailwind mapeia os tokens oficiais do Design System:
 
----
+### Cores
 
-### br-datetimepicker
+| Token | Valor | Uso |
+|---|---|---|
+| `govbr-primary` | #1351b4 | Cor principal (blue-warm-vivid-70) |
+| `govbr-primary-dark` | #0c326f | Hover/active |
+| `govbr-primary-lightest` | #d4e5ff | Backgrounds suaves |
+| `govbr-success` | #168821 | Sucesso, confirmação |
+| `govbr-danger` | #e52207 | Erro, alerta crítico |
+| `govbr-warning` | #ffcd07 | Atenção |
+| `govbr-info` | #155bcb | Informação |
+| `govbr-gray-80` | #333333 | Texto principal |
+| `govbr-gray-60` | #636363 | Texto secundário |
+| `govbr-gray-20` | #cccccc | Bordas |
 
-Composição de `br-datepicker` + `br-timepicker`. Valor no formato `"dd/mm/aaaa HH:MM"`.
+### Tipografia
 
-```html
-<br-datetimepicker
-  label="Agendamento"
-  [(ngModel)]="agendamento"
-  [minuteStep]="15"
-  layout="horizontal"
-></br-datetimepicker>
+```css
+font-rawline    /* Rawline, Raleway, sans-serif */
+text-govbr-xs   /* 11px */
+text-govbr-sm   /* 13px */
+text-govbr-base /* 14px */
+text-govbr-lg   /* 16px */
+text-govbr-xl   /* 20px */
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `label` | `string` | — |
-| `dateLabel` | `string` | `'Data'` |
-| `timeLabel` | `string` | `'Hora'` |
-| `minuteStep` | `number` | `5` |
-| `layout` | `'horizontal' \| 'vertical'` | `'horizontal'` |
-| `hint` | `string` | — |
-| `dateError` | `string` | — |
-| `timeError` | `string` | — |
-
----
-
-## Botões
-
-### br-button
-
-Botão seguindo o padrão GovBR DS com suporte a emphasis, density, modo escuro e mais.
+### Bordas e Espaçamentos
 
-```html
-<!-- Emphasis (ênfase) -->
-<br-button emphasis="primary" (clicked)="salvar()">Salvar</br-button>
-<br-button emphasis="secondary" icon="download">Download</br-button>
-<br-button emphasis="tertiary" icon="trash">Excluir</br-button>
-<br-button emphasis="danger" icon="warning">Remover</br-button>
-
-<!-- Density (densidade) -->
-<br-button emphasis="primary" density="small">Pequeno</br-button>
-<br-button emphasis="primary" density="medium">Médio</br-button>
-<br-button emphasis="primary" density="large">Grande</br-button>
-
-<!-- Circular (icon-only) -->
-<br-button emphasis="primary" [circle]="true" icon="plus" density="large"></br-button>
-
-<!-- Block (largura total) -->
-<br-button emphasis="primary" [block]="true">Largura total</br-button>
-
-<!-- Loading -->
-<br-button emphasis="primary" [loading]="salvando">Salvando...</br-button>
-
-<!-- Modo escuro (para fundos escuros) -->
-<br-button emphasis="primary" [dark]="true">Modo escuro</br-button>
-<br-button emphasis="secondary" [dark]="true">Outlined escuro</br-button>
-
-<!-- Ícone à direita -->
-<br-button emphasis="primary" icon="arrow-right" iconPosition="right">Próximo</br-button>
-
-<!-- Estado ativo -->
-<br-button emphasis="primary" [active]="true">Ativo</br-button>
+```css
+rounded-govbr-sm   /* 4px */
+rounded-govbr-md   /* 8px */
+rounded-govbr-pill /* 100em */
 ```
 
-| Input | Tipo | Padrão | Descrição |
-|-------|------|--------|-----------|
-| `emphasis` | `'primary' \| 'secondary' \| 'tertiary' \| 'danger'` | `'primary'` | Nível de ênfase: primary (preenchido), secondary (outlined), tertiary (somente texto), danger |
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` | Densidade/tamanho |
-| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Tipo do botão HTML |
-| `icon` | `string` | — | Ícone Font Awesome (sem `fa-`) |
-| `iconPosition` | `'left' \| 'right'` | `'left'` | Posição do ícone |
-| `circle` | `boolean` | `false` | Botão circular (icon-only) |
-| `block` | `boolean` | `false` | Largura total |
-| `loading` | `boolean` | `false` | Estado de carregamento com spinner |
-| `disabled` | `boolean` | `false` | Desabilitado |
-| `active` | `boolean` | `false` | Estado ativo/pressionado |
-| `dark` | `boolean` | `false` | Modo escuro (cores invertidas para fundos escuros) |
-
-> **Backward compatibility:** `variant` e `size` ainda funcionam como aliases para `emphasis` e `density`.
-
 ---
 
-### br-magic-button
+## Exemplos Detalhados
 
-Botão flutuante (FAB) com speed dial de ações rápidas.
-
-```html
-<!-- FAB simples -->
-<br-magic-button icon="plus" (fabClick)="criarNovo()"></br-magic-button>
-
-<!-- FAB com ações -->
-<br-magic-button icon="plus" [actions]="acoes" position="bottom-right" (actionClick)="onAction($event)"></br-magic-button>
-```
+### Formulário Completo
 
 ```typescript
-import { BrMagicAction } from '@schenkerjon/ng-govbr-tw';
+import {
+  BrInputComponent,
+  BrSelectComponent,
+  BrCheckboxComponent,
+  BrButtonComponent
+} from '@schenkerjon/ng-govbr-tw';
+import { FormGroup, FormControl, Validators, ReactiveFormsModule } from '@angular/forms';
 
-acoes: BrMagicAction[] = [
-  { id: 'doc', label: 'Novo documento', icon: 'file' },
-  { id: 'foto', label: 'Tirar foto', icon: 'camera' },
-  { id: 'msg', label: 'Nova mensagem', icon: 'envelope' },
-];
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, BrInputComponent, BrSelectComponent, BrCheckboxComponent, BrButtonComponent],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <br-input
+        label="Nome completo"
+        formControlName="nome"
+        [required]="true"
+        placeholder="Digite seu nome"
+      ></br-input>
+
+      <br-input
+        label="E-mail"
+        type="email"
+        formControlName="email"
+        [required]="true"
+        hint="Usaremos para contato"
+      ></br-input>
+
+      <br-select
+        label="Estado"
+        formControlName="estado"
+        [options]="estados"
+        [searchable]="true"
+        placeholder="Selecione"
+      ></br-select>
+
+      <br-checkbox
+        label="Aceito os termos de uso"
+        formControlName="termos"
+      ></br-checkbox>
+
+      <br-button
+        type="submit"
+        variant="primary"
+        [disabled]="form.invalid"
+        [loading]="submitting"
+      >
+        Enviar
+      </br-button>
+    </form>
+  `
+})
+export class FormularioComponent {
+  submitting = false;
+
+  form = new FormGroup({
+    nome: new FormControl('', Validators.required),
+    email: new FormControl('', [Validators.required, Validators.email]),
+    estado: new FormControl(''),
+    termos: new FormControl(false, Validators.requiredTrue)
+  });
+
+  estados = [
+    { label: 'São Paulo', value: 'SP' },
+    { label: 'Rio de Janeiro', value: 'RJ' },
+    { label: 'Minas Gerais', value: 'MG' },
+  ];
+
+  onSubmit() {
+    this.submitting = true;
+    // ...
+  }
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `icon` | `string` | `'plus'` |
-| `actions` | `BrMagicAction[]` | `[]` |
-| `variant` | `'primary' \| 'secondary' \| 'danger'` | `'primary'` |
-| `size` | `'medium' \| 'large'` | `'large'` |
-| `position` | `'bottom-right' \| 'bottom-left' \| 'bottom-center'` | `'bottom-right'` |
-| `showLabels` | `boolean` | `true` |
-
----
-
-## Dados
+### Select com Busca
 
-### br-card
+```typescript
+import { BrSelectComponent, BrSelectOption } from '@schenkerjon/ng-govbr-tw';
 
-```html
-<!-- Card com imagem -->
-<br-card
-  cardTitle="Título"
-  subtitle="Descrição breve"
-  imageSrc="assets/imagem.jpg"
-  imageRatio="16:9"
-  tag="Novo"
-  linkText="Ver mais"
-  linkRoute="/detalhes"
-></br-card>
-
-<!-- Card horizontal -->
-<br-card layout="horizontal" cardTitle="Documento" imageSrc="assets/thumb.jpg"></br-card>
-
-<!-- Card com ícone e footer customizado -->
-<br-card cardTitle="Estatísticas" icon="chart-bar">
-  <p class="text-2xl font-bold">1.234</p>
-  <div card-footer>
-    <a href="#">Ver relatório</a>
-  </div>
-</br-card>
+@Component({
+  standalone: true,
+  imports: [BrSelectComponent],
+  template: `
+    <br-select
+      label="Município"
+      [options]="municipios"
+      [searchable]="true"
+      [multiple]="true"
+      searchPlaceholder="Digite para buscar..."
+      [(ngModel)]="selecionados"
+    ></br-select>
+  `
+})
+export class SelectComponent {
+  selecionados: string[] = [];
+  municipios: BrSelectOption[] = [
+    { label: 'São Paulo', value: 'sao-paulo' },
+    { label: 'Campinas', value: 'campinas' },
+    { label: 'Santos', value: 'santos' },
+  ];
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `cardTitle` | `string` | — |
-| `subtitle` | `string` | — |
-| `icon` | `string` | — |
-| `tag` | `string` | — |
-| `imageSrc` | `string` | — |
-| `imageAlt` | `string` | — |
-| `imageRatio` | `'16:9' \| '4:3' \| '1:1'` | `'16:9'` |
-| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` |
-| `linkText` | `string` | — |
-| `linkRoute` | `string \| unknown[]` | — |
-| `clickable` | `boolean` | `false` |
-
-**Slots:** `[card-footer]`
+### Modal
 
----
+```typescript
+import { BrModalComponent, BrButtonComponent } from '@schenkerjon/ng-govbr-tw';
 
-### br-table
+@Component({
+  standalone: true,
+  imports: [BrModalComponent, BrButtonComponent],
+  template: `
+    <br-button (click)="modalOpen = true">Abrir Modal</br-button>
+
+    <br-modal
+      [isOpen]="modalOpen"
+      title="Confirmar ação"
+      size="medium"
+      [showCloseButton]="true"
+      (closed)="modalOpen = false"
+      (confirmed)="onConfirm()"
+    >
+      <p>Você tem certeza que deseja continuar com esta ação?</p>
+      <p class="text-sm text-govbr-gray-60 mt-2">Esta ação não pode ser desfeita.</p>
+    </br-modal>
+  `
+})
+export class ModalComponent {
+  modalOpen = false;
 
-```html
-<br-table headerVariant="blue" [page]="page" [totalPages]="10" (pageChange)="page = $event">
-  <thead>
-    <tr><th>Nome</th><th>E-mail</th><th>Status</th></tr>
-  </thead>
-  <tbody>
-    @for (u of users; track u) {
-    <tr>
-      <td>{{ u.nome }}</td>
-      <td>{{ u.email }}</td>
-      <td><br-badge [variant]="u.ativo ? 'success' : 'danger'">{{ u.ativo ? 'Ativo' : 'Inativo' }}</br-badge></td>
-    </tr>
-    }
-  </tbody>
-</br-table>
+  onConfirm() {
+    console.log('Confirmado!');
+    this.modalOpen = false;
+  }
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `headerVariant` | `'blue' \| 'light'` | `'blue'` |
-| `page` | `number` | `1` |
-| `totalPages` | `number` | `1` |
+### Tabs
 
----
-
-### br-badge
+```typescript
+import { BrTabComponent, BrTabItem } from '@schenkerjon/ng-govbr-tw';
 
-```html
-<br-badge variant="success">Ativo</br-badge>
-<br-badge variant="danger">Inativo</br-badge>
-<br-badge variant="warning">Pendente</br-badge>
-<br-badge variant="neutral">Rascunho</br-badge>
+@Component({
+  standalone: true,
+  imports: [BrTabComponent],
+  template: `
+    <br-tab
+      [tabs]="tabs"
+      [(activeIndex)]="activeTab"
+      density="medium"
+    >
+      @switch (activeTab) {
+        @case (0) {
+          <div class="p-4">
+            <h3>Dados Pessoais</h3>
+            <p>Conteúdo da primeira aba...</p>
+          </div>
+        }
+        @case (1) {
+          <div class="p-4">
+            <h3>Endereço</h3>
+            <p>Conteúdo da segunda aba...</p>
+          </div>
+        }
+        @case (2) {
+          <div class="p-4">
+            <h3>Documentos</h3>
+            <p>Conteúdo da terceira aba...</p>
+          </div>
+        }
+      }
+    </br-tab>
+  `
+})
+export class TabsComponent {
+  activeTab = 0;
+  tabs: BrTabItem[] = [
+    { label: 'Dados Pessoais', icon: 'user' },
+    { label: 'Endereço', icon: 'location-dot' },
+    { label: 'Documentos', icon: 'file', counter: 3 },
+  ];
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `variant` | `'primary' \| 'success' \| 'danger' \| 'warning' \| 'neutral'` | `'primary'` |
-
----
-
-### br-item / br-list
+### Accordion
 
-Lista estruturada de itens.
+```typescript
+import { BrAccordionComponent, BrAccordionItemComponent } from '@schenkerjon/ng-govbr-tw';
 
-```html
-<br-list title="Documentos recentes" variant="card">
-  <br-item
-    title="Relatório Anual 2024"
-    subtitle="Atualizado em 15/01/2024"
-    icon="file-pdf"
-    tag="PDF"
-    [clickable]="true"
-    [showArrow]="true"
-    (itemClick)="abrirDoc('relatorio')"
-  >
-    <span item-meta class="text-xs text-gray-500">2.4 MB</span>
-  </br-item>
-
-  <br-item
-    title="João da Silva"
-    subtitle="Analista de Sistemas"
-    avatarSrc="assets/avatar.jpg"
-    [clickable]="true"
-  >
-    <div item-actions>
-      <br-button density="small" emphasis="secondary" icon="envelope" [circle]="true"></br-button>
-    </div>
-  </br-item>
-</br-list>
+@Component({
+  standalone: true,
+  imports: [BrAccordionComponent, BrAccordionItemComponent],
+  template: `
+    <br-accordion mode="single" [negative]="false">
+      <br-accordion-item title="O que é o Gov.br?" [open]="true">
+        <p>O Gov.br é a plataforma de relacionamento digital única entre cidadão e Governo.</p>
+      </br-accordion-item>
+
+      <br-accordion-item title="Como criar uma conta?">
+        <p>Acesse gov.br/conta e siga as instruções para criar sua conta.</p>
+      </br-accordion-item>
+
+      <br-accordion-item title="Esqueci minha senha" [disabled]="true">
+        <p>Conteúdo indisponível.</p>
+      </br-accordion-item>
+    </br-accordion>
+  `
+})
+export class AccordionComponent {}
 ```
 
-**br-list:**
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `title` | `string` | — |
-| `subtitle` | `string` | — |
-| `variant` | `'default' \| 'bordered' \| 'card'` | `'default'` |
-| `role` | `'list' \| 'listbox' \| 'menu'` | `'list'` |
-
-**br-item:**
-
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `title` | `string` | `''` |
-| `subtitle` | `string` | — |
-| `icon` | `string` | — |
-| `avatarSrc` | `string` | — |
-| `tag` | `string` | — |
-| `clickable` | `boolean` | `false` |
-| `showArrow` | `boolean` | `false` |
-| `selected` | `boolean` | `false` |
-| `disabled` | `boolean` | `false` |
-| `variant` | `'default' \| 'compact'` | `'default'` |
+### Sidebar com Menu
 
-**Slots:** `[item-meta]`, `[item-actions]`
-
----
-
-## Feedback
+```typescript
+import {
+  BrSidebarComponent,
+  BrSidebarGroupComponent,
+  BrSidebarGroupLabelComponent,
+  BrSidebarItemComponent,
+  BrSidebarSubComponent
+} from '@schenkerjon/ng-govbr-tw';
 
-### br-message
+@Component({
+  standalone: true,
+  imports: [
+    BrSidebarComponent,
+    BrSidebarGroupComponent,
+    BrSidebarGroupLabelComponent,
+    BrSidebarItemComponent,
+    BrSidebarSubComponent
+  ],
+  template: `
+    <br-sidebar
+      [(collapsed)]="collapsed"
+      [collapsible]="true"
+      [hasHeader]="true"
+      [hasFooter]="true"
+    >
+      <div sidebar-header>
+        <img src="logo.png" alt="Logo" class="h-8" />
+      </div>
 
-```html
-<br-message type="info" title="Informação">Sua solicitação foi recebida.</br-message>
-<br-message type="success" [dismissible]="true">Cadastro realizado!</br-message>
-<br-message type="warning" [autoDismiss]="5000" title="Atenção">Sessão expira em breve.</br-message>
-<br-message type="danger" title="Erro">Falha ao processar.</br-message>
+      <br-sidebar-group>
+        <br-sidebar-group-label>Principal</br-sidebar-group-label>
+        <br-sidebar-item
+          route="/dashboard"
+          label="Dashboard"
+          icon="home"
+          [collapsed]="collapsed"
+        ></br-sidebar-item>
+        <br-sidebar-item
+          route="/usuarios"
+          label="Usuários"
+          icon="users"
+          badge="5"
+          [collapsed]="collapsed"
+        ></br-sidebar-item>
+      </br-sidebar-group>
+
+      <br-sidebar-group>
+        <br-sidebar-group-label>Configurações</br-sidebar-group-label>
+        <br-sidebar-sub
+          label="Sistema"
+          icon="gear"
+          [collapsed]="collapsed"
+        >
+          <br-sidebar-item route="/config/geral" label="Geral"></br-sidebar-item>
+          <br-sidebar-item route="/config/seguranca" label="Segurança"></br-sidebar-item>
+        </br-sidebar-sub>
+      </br-sidebar-group>
+
+      <div sidebar-footer>
+        <span class="text-xs text-govbr-gray-40">v1.0.0</span>
+      </div>
+    </br-sidebar>
+  `
+})
+export class SidebarComponent {
+  collapsed = false;
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `type` | `'success' \| 'danger' \| 'warning' \| 'info'` | `'info'` |
-| `title` | `string` | — |
-| `dismissible` | `boolean` | `false` |
-| `autoDismiss` | `number` | — |
+### Wizard Multi-etapas
 
-**Método público:** `show()` — reexibe a mensagem após dismiss.
-
----
+```typescript
+import { BrWizardComponent, BrWizardStepComponent } from '@schenkerjon/ng-govbr-tw';
 
-### br-modal
+@Component({
+  standalone: true,
+  imports: [BrWizardComponent, BrWizardStepComponent],
+  template: `
+    <br-wizard
+      [(currentStep)]="step"
+      [showNavigation]="true"
+      (complete)="onComplete()"
+    >
+      <br-wizard-step label="Dados Pessoais" icon="user">
+        <h3 class="text-lg font-semibold mb-4">Informações Pessoais</h3>
+        <p>Preencha seus dados pessoais...</p>
+      </br-wizard-step>
+
+      <br-wizard-step label="Endereço" icon="location-dot">
+        <h3 class="text-lg font-semibold mb-4">Endereço</h3>
+        <p>Informe seu endereço...</p>
+      </br-wizard-step>
+
+      <br-wizard-step label="Confirmação" icon="check">
+        <h3 class="text-lg font-semibold mb-4">Revisar dados</h3>
+        <p>Confira as informações antes de enviar...</p>
+      </br-wizard-step>
+    </br-wizard>
+  `
+})
+export class WizardComponent {
+  step = 0;
 
-```html
-<br-modal
-  [isOpen]="modalAberto"
-  title="Confirmar exclusão"
-  size="small"
-  primaryText="Excluir"
-  (confirmed)="excluir()"
-  (canceled)="modalAberto = false"
-  (closed)="modalAberto = false"
->
-  <p>Tem certeza que deseja excluir?</p>
-</br-modal>
+  onComplete() {
+    console.log('Wizard finalizado!');
+  }
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `isOpen` | `boolean` | `false` |
-| `title` | `string` | `''` |
-| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'auto'` | `'medium'` |
-| `showCloseButton` | `boolean` | `true` |
-| `primaryText` | `string` | `'Confirmar'` |
-| `cancelText` | `string` | `'Cancelar'` |
-| `primaryDisabled` | `boolean` | `false` |
-| `loading` | `boolean` | `false` |
-| `closeOnScrim` | `boolean` | `true` |
-| `closeOnEscape` | `boolean` | `true` |
-| `hasCustomFooter` | `boolean` | `false` |
-
-**Slot:** `[modal-footer]` — footer customizado (com `[hasCustomFooter]="true"`)
-
----
+### Upload de Arquivos
 
-### br-loading
+```typescript
+import { BrUploadComponent, BrUploadFile } from '@schenkerjon/ng-govbr-tw';
 
-```html
-<br-loading size="medium"></br-loading>
-<br-loading [progress]="75" [showPercentage]="true" label="Carregando..."></br-loading>
+@Component({
+  standalone: true,
+  imports: [BrUploadComponent],
+  template: `
+    <br-upload
+      label="Documentos"
+      accept=".pdf,.doc,.docx"
+      [multiple]="true"
+      [maxSizeMB]="5"
+      [maxFiles]="3"
+      helperText="Arquivos PDF ou Word, máximo 5MB cada"
+      (filesChange)="onFilesChange($event)"
+      (fileAdded)="onFileAdded($event)"
+      (fileRemoved)="onFileRemoved($event)"
+    ></br-upload>
+  `
+})
+export class UploadComponent {
+  onFilesChange(files: BrUploadFile[]) {
+    console.log('Arquivos:', files);
+  }
+
+  onFileAdded(file: BrUploadFile) {
+    console.log('Adicionado:', file.name);
+  }
+
+  onFileRemoved(file: BrUploadFile) {
+    console.log('Removido:', file.name);
+  }
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
-| `progress` | `number` | — |
-| `showPercentage` | `boolean` | `true` |
-| `label` | `string` | — |
-
----
+### Toast Notifications
 
-### br-tooltip
-
-```html
-<br-tooltip text="Informação adicional" place="top">
-  <i class="fa-solid fa-circle-info"></i>
-</br-tooltip>
+```typescript
+import { BrToastService } from '@schenkerjon/ng-govbr-tw';
+
+@Component({...})
+export class ToastComponent {
+  private toastService = inject(BrToastService);
+
+  showSuccess() {
+    this.toastService.success('Operação realizada com sucesso!');
+  }
+
+  showError() {
+    this.toastService.danger('Erro ao processar solicitação.');
+  }
+
+  showWarning() {
+    this.toastService.warning('Atenção: verifique os dados.');
+  }
+
+  showInfo() {
+    this.toastService.info('Nova atualização disponível.', {
+      duration: 5000,
+      position: 'top-right'
+    });
+  }
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `text` | `string` | `''` |
-| `place` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` |
-| `variant` | `'info' \| 'success' \| 'danger' \| 'warning'` | `'info'` |
-| `timer` | `number` | — |
-
 ---
 
-## Utilitários
+## Inputs Especializados
 
-### br-accordion
+A biblioteca inclui inputs com máscaras brasileiras:
 
-```html
-<br-accordion mode="single" [bordered]="true">
-  <br-accordion-item title="Seção 1" icon="file" [open]="true">
-    Conteúdo da seção 1.
-  </br-accordion-item>
-  <br-accordion-item title="Seção 2" badge="3">
-    Conteúdo da seção 2.
-  </br-accordion-item>
-</br-accordion>
-```
+| Componente | Seletor | Formato |
+|---|---|---|
+| `BrInputCpfComponent` | `<br-input-cpf>` | 000.000.000-00 |
+| `BrInputCnpjComponent` | `<br-input-cnpj>` | 00.000.000/0000-00 |
+| `BrInputCepComponent` | `<br-input-cep>` | 00000-000 |
+| `BrInputTelefoneComponent` | `<br-input-telefone>` | (00) 00000-0000 |
+| `BrInputMoneyComponent` | `<br-input-money>` | R$ 1.234,56 |
 
-| Input (accordion) | Tipo | Padrão |
-|-------|------|--------|
-| `mode` | `'single' \| 'multiple'` | `'multiple'` |
-| `variant` | `'default' \| 'negative'` | `'default'` |
-| `bordered` | `boolean` | `true` |
-
-| Input (item) | Tipo | Padrão |
-|-------|------|--------|
-| `title` | `string` | `''` |
-| `icon` | `string` | — |
-| `badge` | `string \| number` | — |
-| `open` | `boolean` | `false` |
-| `disabled` | `boolean` | `false` |
-| `density` | `'small' \| 'medium' \| 'large'` | `'medium'` |
-
----
-
-### br-wizard
+```typescript
+import { BrInputCpfComponent, BrInputCepComponent } from '@schenkerjon/ng-govbr-tw';
 
-Stepper para fluxos multi-etapas.
+@Component({
+  standalone: true,
+  imports: [BrInputCpfComponent, BrInputCepComponent],
+  template: `
+    <br-input-cpf
+      label="CPF"
+      [(ngModel)]="cpf"
+      [required]="true"
+    ></br-input-cpf>
+
+    <br-input-cep
+      label="CEP"
+      [(ngModel)]="cep"
+      (cepChange)="onCepChange($event)"
+    ></br-input-cep>
+  `
+})
+export class InputsComponent {
+  cpf = '';
+  cep = '';
 
-```html
-<br-wizard [currentStep]="step" (stepChange)="step = $event" (complete)="onComplete()">
-  <br-wizard-step label="Dados Pessoais" icon="user">
-    <br-input label="Nome" [(ngModel)]="nome"></br-input>
-    <br-input label="CPF" [(ngModel)]="cpf"></br-input>
-  </br-wizard-step>
-
-  <br-wizard-step label="Endereço" icon="location-dot">
-    <br-input label="CEP" [(ngModel)]="cep"></br-input>
-  </br-wizard-step>
-
-  <br-wizard-step label="Confirmação" icon="check">
-    <p>Revise seus dados antes de enviar.</p>
-  </br-wizard-step>
-</br-wizard>
+  onCepChange(cep: string) {
+    // Buscar endereço por CEP...
+  }
+}
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `currentStep` | `number` | `0` |
-| `variant` | `'simple' \| 'numbered'` | `'numbered'` |
-| `showNavigation` | `boolean` | `true` |
-| `allowJump` | `boolean` | `false` |
-
-| Output | Tipo |
-|--------|------|
-| `stepChange` | `number` |
-| `complete` | `void` |
-
-**Métodos públicos:** `next()`, `previous()`, `goToStep(index)`
-
 ---
 
-### br-cookiebar
+## Demo
 
-Barra de consentimento de cookies (LGPD).
-
-```html
-<br-cookiebar
-  [(visible)]="showCookies"
-  [cookieGroups]="cookieGroups"
-  (acceptAll)="onAcceptAll()"
-  (acceptSelected)="onAcceptSelected($event)"
-  (reject)="onReject()"
->
-  <p>
-    Este site utiliza cookies para melhorar sua experiência.
-    <a href="/politica" class="underline font-semibold">Política de Privacidade</a>.
-  </p>
-</br-cookiebar>
-```
+**[🔗 Ver Demo Online](https://jordaobass.github.io/ng-govbr-tw/)** — Showcase interativo com todos os componentes.
 
-```typescript
-import { BrCookieGroup } from '@schenkerjon/ng-govbr-tw';
+Para rodar localmente:
 
-cookieGroups: BrCookieGroup[] = [
-  { id: 'essential', label: 'Essenciais', description: 'Necessários para o site funcionar.', required: true, enabled: true },
-  { id: 'analytics', label: 'Analíticos', description: 'Nos ajudam a entender o uso do site.', enabled: false },
-  { id: 'marketing', label: 'Marketing', description: 'Exibir anúncios relevantes.', enabled: false },
-];
+```bash
+git clone https://github.com/jordaobass/ng-govbr-tw.git
+cd ng-govbr-tw
+npm install
+npm run build
+ng serve demo
 ```
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `visible` | `boolean` | `false` |
-| `cookieGroups` | `BrCookieGroup[]` | `[]` |
-
-| Output | Tipo |
-|--------|------|
-| `acceptAll` | `void` |
-| `acceptSelected` | `BrCookieGroup[]` |
-| `reject` | `void` |
-| `visibleChange` | `boolean` |
+Acesse `http://localhost:4200` para ver o showcase completo.
 
 ---
 
-## Sidebar (alternativa ao br-menu)
+## Contribuição
 
-Para layouts com sidebar colapsável estilo shadcn:
+Contribuições são bem-vindas!
 
-```html
-<br-sidebar [collapsed]="collapsed" (collapsedChange)="collapsed = $event" [collapsible]="true" [hasHeader]="true">
-  <div sidebar-header>Logo</div>
-
-  <br-sidebar-group>
-    <br-sidebar-group-label>Menu</br-sidebar-group-label>
-    <br-sidebar-item label="Dashboard" icon="gauge" route="/dashboard"></br-sidebar-item>
-    <br-sidebar-item label="Relatórios" icon="chart-bar" route="/relatorios" badge="5"></br-sidebar-item>
-    <br-sidebar-sub label="Configurações" icon="gear" [open]="true">
-      <br-sidebar-item label="Geral" route="/config/geral"></br-sidebar-item>
-    </br-sidebar-sub>
-  </br-sidebar-group>
-
-  <div sidebar-footer>Footer</div>
-</br-sidebar>
-```
+1. Fork o repositório
+2. Crie uma branch (`git checkout -b feature/nova-feature`)
+3. Commit suas mudanças (`git commit -m 'Adiciona nova feature'`)
+4. Push para a branch (`git push origin feature/nova-feature`)
+5. Abra um Pull Request
 
-| Input | Tipo | Padrão |
-|-------|------|--------|
-| `collapsed` | `boolean` | `false` |
-| `collapsible` | `boolean` | `true` |
-| `variant` | `'sidebar' \| 'floating' \| 'inset'` | `'sidebar'` |
-| `hasHeader` | `boolean` | `false` |
-| `hasFooter` | `boolean` | `false` |
-| `mobileOpen` | `boolean` | `false` |
-
----
+### Reportar Bugs
 
-## Tokens de Cor
-
-| Token | Cor |
-|-------|-----|
-| `govbr-primary` | `#1351b4` |
-| `govbr-primary-dark` | `#0c326f` |
-| `govbr-primary-darkest` | `#071d41` |
-| `govbr-primary-light` | `#c5d4eb` |
-| `govbr-primary-lightest` | `#dbe8fb` |
-| `govbr-success` | `#168821` |
-| `govbr-danger` | `#e52207` |
-| `govbr-warning` | `#ffcd07` |
-| `govbr-info` | `#155bcb` |
-| `govbr-focus` | `#c2850c` |
+Abra uma issue em [github.com/jordaobass/ng-govbr-tw/issues](https://github.com/jordaobass/ng-govbr-tw/issues)
 
 ---
 
-## Exemplo Completo
-
-```typescript
-import { Component } from '@angular/core';
-import {
-  BrLayoutComponent, BrHeaderComponent, BrMenuComponent,
-  BrMenuItemComponent, BrFooterComponent, BrCardComponent,
-} from '@schenkerjon/ng-govbr-tw';
-
-@Component({
-  selector: 'app-root',
-  standalone: true,
-  imports: [
-    BrLayoutComponent, BrHeaderComponent, BrMenuComponent,
-    BrMenuItemComponent, BrFooterComponent, BrCardComponent,
-  ],
-  template: `
-    <br-layout>
-      <br-header
-        systemTitle="Portal de Serviços"
-        systemSubtitle="Ministério da Economia"
-        logoSrc="assets/gov-logo.png"
-        (menuToggle)="menuOpen = $event"
-        (searchSubmit)="onSearch($event)"
-      ></br-header>
-
-      <br-menu [open]="menuOpen" (openChange)="menuOpen = $event">
-        <br-menu-item label="Início" icon="house" route="/" [exact]="true"></br-menu-item>
-        <br-menu-item label="Serviços" icon="grid" route="/servicos"></br-menu-item>
-        <br-menu-item label="Documentos" icon="file" route="/docs" badge="3"></br-menu-item>
-      </br-menu>
-
-      <div class="max-w-4xl mx-auto">
-        <h2 class="text-xl font-bold mb-4">Bem-vindo</h2>
-        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-          <br-card cardTitle="Consultar CPF" icon="id-card" linkText="Acessar" linkRoute="/cpf"></br-card>
-          <br-card cardTitle="Emitir certidão" icon="file-certificate" linkText="Acessar" linkRoute="/certidao"></br-card>
-        </div>
-      </div>
+## Licença
 
-      <br-footer logoSrc="assets/gov-logo.png"></br-footer>
-    </br-layout>
-  `,
-})
-export class AppComponent {
-  menuOpen = true;
-  onSearch(query: string) { console.log('Busca:', query); }
-}
-```
+MIT © [Jordan Bass](https://github.com/jordaobass)
 
 ---
 
-## Licença
-
-MIT
+<p align="center">
+  Feito com ❤️ para a comunidade brasileira de desenvolvedores Angular
+</p>