# GLOBAL STYLE GUIDE — IDeia

> Versão 1.12.0 · 2026-11-04 · Vale para todos os sistemas da IDeia, em qualquer stack.
> **Arquivo gerado** pelo build a partir de `apps/site/guide/` no repositório ideia-design-system. Não edite aqui: mude a seção e rode `pnpm build:site`.
> Guia visual: https://design.ideiabusiness.com.br · Demonstração ao vivo: https://design.ideiabusiness.com.br/live · MCP: https://design.ideiabusiness.com.br/mcp

---

## Como usar este guia

- **Para quem:** as IAs e as pessoas que criam ou alteram qualquer tela de um sistema da IDeia.
  **Leia antes de criar ou alterar uma tela, um componente, um botão.** Toda vez, não só na primeira.
- **Demonstração ao vivo:** https://design.ideiabusiness.com.br/live mostra um sistema de exemplo com
  todos os componentes e padrões deste guia funcionando: menus, formulários, tabelas, filtros, kanban,
  rodapé, login, troca de produto, tema e idioma, e os estados de rede (lenta e com erro). Na dúvida
  sobre um comportamento, veja lá.
- **Escopo:** sistemas (painéis e aplicações com login). Landing pages e sites institucionais não
  seguem este guia.
- **Neutro de stack:** este guia diz como cada coisa é e como se comporta, não como se escreve em
  React, Vue, Flutter ou HTML puro. Cada projeto tem um `docs/DESIGN.md` local que mapeia este guia
  para a biblioteca dele: qual componente faz o quê, como se instala, como os tokens são declarados.
  O local nunca contradiz o global; ele só diz como implementar. Projeto na **stack padrão do
  front** (shadcn/ui + Tailwind, Parte 4) usa a Parte 4 como mapa, e o `DESIGN.md` local só para o
  que é específico dele.
- **Precedência:** este guia > `DESIGN.md` local > o jeito de uma tela antiga. Na dúvida entre o guia
  e uma tela existente, vale o guia. Mudar uma regra daqui é decisão humana, nunca da IA.
- **Quatro partes:** o **Style Guide** (o visual: logo, cores, tipografia, ícones, espaçamento), o
  **UI Kit** (os componentes: como cada um é, variantes e estados), a **Pattern Library** (os
  padrões: layout, navegação, formulários, tabelas, feedback, i18n, acessibilidade, texto) e a
  **Implementação de referência** (como tudo isso vira código na stack padrão do front: shadcn/ui
  + Tailwind).
- No fim há um **checklist**: a tela só está pronta quando passa nele.

---

## Princípios

1. **Mesma experiência em todos os produtos.** A cor primária e o logo mudam de produto para
   produto. Todo o resto é igual: neutros, semânticas, tipografia, ícones, espaçamento, componentes
   e comportamento.
2. **Menos é mais.** Layout limpo, espaço em branco generoso, uma ação principal por contexto.
3. **Tudo vive numa box.** Nenhum conteúdo solto sobre o fundo da página: tabela, formulário, lista,
   KPI, estado vazio e erro ficam dentro de uma superfície elevada.
4. **Hierarquia dentro da box:** título > descrição > conteúdo > ação secundária. A tela em si não
   tem título: o nome dela é o do breadcrumb.
5. **Feedback para toda ação.** Carregando, deu certo, deu errado, nada aqui: cada estado tem um
   componente e um lugar.
6. **Mobile-first e container-first.** A tela nasce no celular e cresce. Dentro do shell, o
   componente responde à largura do seu contêiner, não da janela.
7. **Acessível por padrão.** Contraste mínimo, foco visível, nome acessível em todo controle,
   teclado em tudo.
8. **Texto curto.** Uma frase por aviso. O usuário decide com o que lê, não estuda.
9. **Tema claro e escuro, sempre.** Nenhuma cor fixa na tela: só tokens.
10. **Preparado para três idiomas.** Nenhum texto fixo no código: tudo vem de dicionário.

---

# Parte 1 — Style Guide

## 1.1 Marca e logo

Cada produto tem o seu logo e a sua cor primária. Os logos oficiais ficam no **CDN da IDeia**
(`cdn.ideiabusiness.com.br`) e se enviam pelo painel administrativo, neste padrão de caminho:

```text
https://cdn.ideiabusiness.com.br/logos/<slug>/<slug>-clara.png             logo completo, colorido, para o tema claro
https://cdn.ideiabusiness.com.br/logos/<slug>/<slug>-escura.png            logo completo, todo branco, para o tema escuro
https://cdn.ideiabusiness.com.br/logos/<slug>/<slug>-icone-clara.png       só o símbolo, quadrado, colorido, para o tema claro
https://cdn.ideiabusiness.com.br/logos/<slug>/<slug>-icone-escura.png      só o símbolo, quadrado, branco, para o tema escuro
https://design.ideiabusiness.com.br/logos/index.json                       o índice: quais arquivos cada produto tem, com largura, altura e bytes
```

- **O logo troca sozinho.** Um envio novo pelo painel grava na mesma URL e limpa o cache do CDN; o navegador
  pode mostrar o anterior por até uma hora. Pela API dos produtos, a URL vem com `?v=` da versão atual, e a troca
  aparece na hora. Os endereços antigos, em `design.ideiabusiness.com.br/logos/…`, redirecionam para o CDN.
- **Do CDN direto para o navegador:** `<img>`, ou `<Image unoptimized>` no Next. Sem o `unoptimized`, o otimizador
  de imagens da Vercel baixa cada logo e entra no uso cobrado do projeto. Nunca copie o arquivo para dentro do
  projeto: ele perderia a troca.

- O `slug` é o nome do produto em minúsculas, sem acento, com hífen no lugar de espaço:
  `rede-ideia`, `ideia-chat`, `ideia-devtasks`, `ideia-signer`, `lapidai`.
- **O sistema confere que os arquivos existem antes de usar**, pelo `index.json` ou pelo MCP
  (`get_logo_urls`). Produto sem a versão escura usa a clara nos dois temas; sem o ícone, usa o logo
  completo; nunca inventa um logo nem escreve o nome do produto em texto no lugar dele.
- **Famílias:** Rede Ideia e os produtos IDeia (Business, Academy, Benefits, Signer, Pay, Partner,
  Sales, Publi, MEI, DevTeam, Timestamp, Client, NF) compartilham o navy `#153261` e o verde
  `#26c148`. IDeia Chat e MultiChat usam o azul `#265e9f`. Os demais (DevTasks, Agenda, Vault,
  Cockpit, Lapid.ai, Arsenal, Polaria, Plure, Lumoria, MDE, B2B, Conecta RI, DEIA) têm cor própria.

| Onde | Qual versão | Tamanho |
|---|---|---|
| Login, painel da marca | logo completo na versão escura (branca), canto superior esquerdo do painel | 32px de altura |
| Sidebar expandida, no topo | logo completo, na primeira linha do topo, com a empresa abaixo (2.15) | 32px de altura |
| Sidebar recolhida em ícones | ícone | 32px de altura, a mesma do logo completo |
| Favicon e ícone de app | ícone | o que a plataforma pedir |

Regras:
- **Na sidebar, o logo completo e o ícone têm a mesma altura, 32px**, e o topo não muda de altura ao
  recolher *(decisão do usuário, 2026-10-26)*. O logo fica numa linha de 48px, alinhado à esquerda
  com o avatar da empresa logo abaixo.
- O logo já traz o nome do produto: **nunca** escreva o nome ao lado dele.
- Área de respiro de pelo menos metade da altura do logo em volta. Largura mínima do logo completo:
  120px.
- Nunca distorça, recolora, rotacione, aplique sombra ou ponha sobre fundo que não seja o
  `background` ou o `sidebar` do tema.
- No tema escuro entra a versão escura (branca). Nunca o logo colorido sobre fundo escuro.
- O logo não muda de cor com a primária. Quem deriva da cor do logo é o token, nunca o contrário.

## 1.2 Cores

As cores são **tokens** com papel fixo. A tela nunca usa um valor de cor: usa o papel. Tokens vêm
em pares: a superfície e o `-foreground`, que é a cor do texto e dos ícones sobre ela.

### Neutros (iguais em todos os produtos)

No claro, neutros frios, com leve viés azul (slate). No escuro, grafite sem matiz: o tema "Modern
Minimal" do tweakcn.com, só no escuro *(decisão do usuário, 2026-10-26)*. Do tweakcn vêm só os
neutros: a primária, as semânticas, o `secondary` e o `accent` são nossos, e a sombra é a do shadcn.

| Token | Papel | Claro | Escuro |
|---|---|---|---|
| `background` | fundo da página; só o vazio entre as boxes | `#f8fafc` | `#171717` |
| `foreground` | texto e ícones padrão | `#0f172a` | `#e5e5e5` |
| `card` / `card-foreground` | superfície elevada: card, box, tabela, formulário | `#ffffff` / `#0f172a` | `#262626` / `#e5e5e5` |
| `popover` / `popover-foreground` | superfície flutuante: menu, popover, modal, toast | `#ffffff` / `#0f172a` | `#262626` / `#e5e5e5` |
| `sidebar` | menu lateral e painel da direita | `#ffffff` | `#171717` |
| `muted` / `muted-foreground` | superfície sutil e texto de menor peso (descrição, placeholder, ajuda) | `#f1f5f9` / `#475569` | `#1f1f1f` / `#a8a8a8` |
| `secondary` / `secondary-foreground` | ação secundária preenchida | `#f1f5f9` / `#0f172a` | `#404040` / `#e5e5e5` |
| `accent` | hover de item de menu e de linha; igual ao `muted` | `#f1f5f9` | `#1f1f1f` |
| item ativo do menu | `primary` cheia com texto `primary-foreground` *(2026-10-22: a 12% o texto não ficava nítido no escuro)* | = `primary` | = `primary` |
| `border` | bordas e separadores | `#e2e8f0` | `#404040` |
| `input` | borda dos controles de formulário (campo, select, checkbox); 3:1 contra card e fundo | `#8592a6` | `#737373` |
| `ring` | anel de foco | = `primary` | = `primary` |
| `link` | texto de link (a variante `link` do botão, link dentro de texto) | = `primary` (escurecida só se não chegar a 4,5:1) | a primária clareada até 4,5:1 contra fundo, card, popover e muted *(decisão do usuário, 2026-10-26)* |

No escuro, `card` e `popover` são mais claros que o `background`; a `sidebar` é igual ao fundo,
separada pela borda. O `muted` fica entre os dois. No claro, card, popover e sidebar são brancos
sobre o cinza-claro da página, e a borda separa. Se faltar separação, ajusta-se o token, nunca o
componente.

O que não vem do tweakcn, e por quê:
- `secondary` escuro `#404040`: no tweakcn é a cor do card, e o botão secundário sumiria sobre ele.
- `accent` = `muted`, nos dois temas: o hover do shadcn é `bg-muted` (botão ghost e outline, toggle,
  item do Command), e os itens de menu e de select usam `bg-accent`. Iguais, todo hover tem a mesma
  cara, e o `muted-foreground` continua com 4,5:1 sobre a linha em hover. O do tweakcn é azul.
- `muted-foreground` escuro `#a8a8a8`, um degrau acima do `#a3a3a3` do tweakcn: o placeholder fica
  sobre o fundo do campo do shadcn (`dark:bg-input/30`), e ali o `#a3a3a3` dava 4,3:1.

### Primária e destaque (as únicas cores que mudam por produto)

| Token | Papel |
|---|---|
| `primary` / `primary-foreground` | a ação principal, o item ativo do menu, o foco, o avatar sem foto, o contador do sino |
| `link` | todo texto que é link. Nunca `primary` como cor de texto: no escuro, ela tem 3:1, e texto precisa de 4,5:1 |
| `accent-brand` | a segunda cor do logo, quando existe; só decoração (gráfico, ilustração, detalhe). Nunca texto, nunca fundo de botão |
| `brand` | a primária **clara**, fixa nos dois temas. Só o painel do login (2.20) a usa |

**Como derivar a primária do logo.** O logo nunca muda; o token deriva dele.
- **Claro:** a cor dominante do logo. Se o texto branco sobre ela não chega a **4,5:1**, escurece-se
  o mesmo matiz até chegar.
- **Escuro:** o mesmo matiz, clareado até ter **3:1** contra o `card` escuro (`#262626`). O texto
  sobre ela é branco se der 4,5:1; senão, é o `background` escuro (`#171717`).
- `primary-foreground` é branco no claro. No escuro, branco ou `#171717`, conforme a regra acima.
- O script `apps/site/scripts/derive-product-colors.py` aplica a receita e lê o card de `packages/tokens/base.json`.
  Mudou o tema escuro, roda-se com `--escuro`: recalcula só a primária escura de todos os produtos.

Valores já calculados (os outros produtos seguem a mesma receita):

| Produto | Cor do logo | `primary` claro | `primary` escuro | texto sobre ela no escuro |
|---|---|---|---|---|
| Rede Ideia e família IDeia | `#153261` | `#153261` | `#2e6cd2` | branco |
| IDeia Chat / MultiChat | `#265e9f` | `#265e9f` | `#2e71c0` | branco |
| IDeia DevTasks | `#396cae` | `#396cae` | `#3c71b6` | branco |
| Ideia Agenda | `#004ffb` | `#004ffb` | `#1b62ff` | branco |
| Ideia Vault | `#027771` | `#027771` | `#02817b` | branco |
| Ideia Cockpit | `#fd7f01` | `#b65b01` (escurecida: a original dá 2,2:1) | `#fd7f01` | `#171717` |
| Lapid.ai | `#1f216e` | `#1f216e` | `#6265d3` | branco |

Produto cujo matiz primário coincide com uma semântica (o laranja do Cockpit, do Arsenal e da
Polaria é o matiz da atenção) mantém as semânticas como estão: o ícone carrega o significado, e a
primária aparece só em ação principal, menu e foco.

### Semânticas (iguais em todos os produtos)

| Token | Significado | Ícone fixo | Claro | Escuro |
|---|---|---|---|---|
| `success` | deu certo; estado bom; ligado | `circle-check` | `#15803d` | `#4ade80` |
| `warning` | atenção: aconteceu ou vai acontecer algo com consequência | `triangle-alert` | `#b45309` | `#fbbf24` |
| `danger` | erro, recusa, ação destrutiva; desligado | `circle-alert` | `#b91c1c` | `#f87171` |
| `info` | contexto neutro: o que vale, o que muda depois | `info` | `#0369a1` | `#38bdf8` |

O `-foreground` das quatro (texto sobre a cor cheia) é branco no claro e `#171717` no escuro.

Cada semântica tem ainda um tom **`-strong`**, só para **texto e ícone sobre a superfície tingida** (badge e
alerta). A cor base perde contraste quando ganha uma tinta por baixo: o `success` sobre a própria tinta de 12%
dá 4,27:1 no claro, abaixo do mínimo *(achado pela auditoria automática da demonstração, 2026-10-23)*.

| Token | Claro | Escuro |
|---|---|---|
| `success-strong` | `#166534` | `#86efac` |
| `warning-strong` | `#92400e` | `#fcd34d` |
| `danger-strong` | `#991b1b` | `#fca5a5` |
| `info-strong` | `#075985` | `#7dd3fc` |

Sobre a tinta de 12%, no pior fundo (card, muted ou página), o texto forte fica entre 5,5:1 e 6,2:1 no
claro e entre 6,7:1 e 8,4:1 no escuro.

Três intensidades, e só estas:
- **Texto e ícone no tom:** a cor direto no texto ou no ícone.
- **Superfície tingida:** fundo com a cor a 12% (badge), a 8% com borda a 30% (alerta) ou a 10%
  (botão de perigo, o `destructive` do shadcn; 20% no escuro), texto e ícone no tom **`-strong`**.
  É o padrão para badge de status, alerta e botão de perigo.
- **Superfície cheia:** fundo na cor, texto no `-foreground`. Só para selo de destaque.

Não existe quinto tipo. Não se usa a primária com sentido semântico, nem uma semântica como
decoração.

### Contraste

- Mínimo **4,5:1** para texto, **3:1** para texto grande (≥ 24px, ou ≥ 19px em peso 600), ícone,
  borda de controle e contorno. Nos dois temas.
- **Quem cumpre o 3:1 da borda de controle é o token `input`** (campo, select, checkbox), contra o
  `card` e o fundo: claro `#8592a6` (3,15:1 no card, 3,01:1 no fundo), escuro `#737373` (3,19:1 e
  3,78:1). O `border` dos separadores pode ser suave: não é ele que mostra que ali é um campo
  *(decisão do usuário, 2026-10-26)*.
- O build confere os pares de cada tema e de cada produto (texto 4,5:1; `input`, primária e ícone
  3:1) e falha se algum sair do mínimo.
- **Contraste se corrige onde nasce.** Se falta no valor de um token, corrige-se o token (decisão
  humana), nunca um remendo numa tela só. Se falta por uma opacidade que a tela pôs, a tela tira a
  opacidade.
- Texto que carrega informação (descrição, erro, ajuda) nunca leva opacidade. O esmaecido vai no
  rótulo, no ícone e no controle desabilitado.

### Cor que vem do banco

A cor que o usuário escolhe para uma fila, etiqueta, categoria ou avatar é a única cor que não é
token. Ela entra por variável, nunca escrita na tela, e **toda marca com cor do banco leva um
contorno de 1px em `foreground` a 20%**: a cor pode ser quase branca ou quase preta, e o contorno
garante que ela apareça nos dois temas. Nunca se troca a cor do usuário por tema.

### Gráficos

Séries na primária e em degraus dela (mais clara e mais escura); neutros para o que é referência.
Semântica só quando o dado é semântico (vencido em `danger`, no prazo em `success`). Cada série
precisa de 3:1 contra o `card` do tema. Rótulos no `muted-foreground`, grade na `border`.

## 1.3 Tipografia

- **Fonte: Roboto** em títulos e corpo, em todos os produtos. Pesos: 400 (texto, item de menu,
  célula, tooltip), 500 (rótulo, botão, badge, cabeçalho de tabela, título de box), 600 (título de
  seção e título grande), 700 (só número de KPI e a vitrine do login). São os pesos dos componentes
  do shadcn: não se muda o peso de um componente.
- **Roboto Mono** só para bloco de código e citação literal do sistema: log, payload, ID, hash,
  chave. Nunca em texto corrido, rótulo ou tabela comum.
- **Tamanho base do sistema: 14px.** Controles, menus, células e descrições são 14px. O texto
  digitado num campo tem 16px abaixo de 768px de janela, para o iPhone não ampliar a tela ao focar
  (o shadcn já faz: `text-base md:text-sm`).
- Números em coluna ou em KPI usam dígitos tabulares.
- Nunca um tamanho fora da escala. Nunca outra fonte, nem por CSS, nem por imagem com texto.

| Papel | Tamanho / linha | Peso | Onde |
|---|---|---|---|
| Legenda | 12 / 16 | 400 | tooltip, ajuda curta, rodapé de tabela, hora (o badge usa 12 em 500) |
| Corpo do sistema | 14 / 20 | 400 | controle, célula, menu, descrição, parágrafo de tela |
| Rótulo e botão | 14 / 20 | 500 | label de campo, botão, cabeçalho de tabela |
| Leitura | 16 / 24 | 400 | mensagem de chat, e-mail, texto longo |
| Título de box | 16 / 22 | 500 | título de card, de modal, de folha lateral (o `CardTitle` e o `DialogTitle` do shadcn) |
| Título de seção | 20 / 28 | 600 | seção dentro de uma tela longa, título de página de login |
| Título grande | 24 / 32 | 600 | login, onboarding, telas fora do shell |
| Número de KPI | 30 / 36 | 700 | o valor de um card de KPI |
| Vitrine | 36 / 44 | 700 | só a frase do produto no painel do login (2.20) |

Hierarquia dentro de uma box: título (16/500) › descrição (14, `muted-foreground`) › conteúdo (14)
› ação secundária. A tela não tem título nem subtítulo: o nome dela é o do breadcrumb, e o `h1`
existe só para leitor de tela.

## 1.4 Ícones

- **Biblioteca: Lucide**, em todos os produtos (existe para web, React, Vue, Svelte, Flutter e SVG
  puro). Traço de 2px, cantos arredondados, sem preenchimento. Nenhuma outra biblioteca, nenhum
  emoji como ícone.
- Tamanhos: o componente do shadcn dimensiona o ícone. **16px** no tamanho padrão (botão de
  qualquer altura a partir do padrão, campo, célula, alerta, item de menu e da sidebar, estado
  vazio), **14px** no botão `sm` e no separador do breadcrumb, **12px** no botão `xs` e no badge.
  **20px** só solto, ao lado de um título de seção. A tela não passa tamanho dentro de botão ou
  campo.
- O ícone acompanha a cor do texto onde está. Ícone com cor própria só nas semânticas e no
  indicador de estado.
- Ícone nunca vai sozinho sem nome acessível: botão só de ícone tem `aria-label` e tooltip com o
  mesmo texto.

| Contexto | Ícone |
|---|---|
| Campo e-mail · senha · nome · busca | `mail` · `lock` · `user` · `search` |
| Adicionar · editar · excluir · voltar · tentar de novo · fechar | `plus` · `pencil` · `trash-2` · `arrow-left` · `refresh-cw` · `x` |
| Sucesso · erro · atenção · informação | `circle-check` · `circle-alert` · `triangle-alert` · `info` |
| Ações da linha ("…") | `ellipsis` |
| Abrir o menu do usuário | `chevrons-up-down` |
| Recolher a sidebar · notificações | `panel-left` · `bell` |
| Tema claro · tema escuro · idioma | `sun` · `moon` · `languages` |
| Perfil · configurações · sair | `user` · `settings` · `log-out` |
| Colunas da tabela · filtro | `columns-3` · `filter` |
| Carregando | não é ícone: Skeleton ou Spinner (UI Kit) |

## 1.5 Espaçamento, tamanhos, raio e elevação

**Os componentes têm as medidas do shadcn/ui, estilo `nova`, e o guia não muda nenhuma** *(decisão do
usuário, 2026-10-26)*. As tabelas abaixo dizem quais são, para conferir uma tela e para quem
implementa em outra stack. Dentro de um componente valem os valores dele (6, 10, 20px…); **o layout
da tela** (margens, distância entre boxes, entre botões, entre colunas) usa a **escala de 4px: 4, 8,
12, 16, 24, 32, 48**.

| Onde | Valor |
|---|---|
| Padding da página (dentro do shell) | 24px no desktop, 16px no celular |
| Entre boxes (cards, seções) | 16px |
| Padding de card | 16px (12px no card `sm`) |
| Padding de modal e de folha lateral | 16px |
| Entre cabeçalho, conteúdo e rodapé de card e de modal | 16px |
| Entre campos de formulário | 20px (grupo dentro de grupo: 16px) |
| Entre o rótulo e o controle, e o controle e a ajuda | 8px |
| Entre botões numa barra | 8px |
| Botão: padding horizontal · ícone até o texto | 10px · 6px (`sm` e `xs`: 4px; `xs` com 8px de padding) |
| Campo e select: padding horizontal | 10px |
| Célula de tabela | 8px |
| Item de menu, de select e de lista de opções | 4px × 6px |

| Elemento | Altura / largura |
|---|---|
| Controle padrão (botão, campo, select, toggle) | 32px |
| Controle `sm` | 28px |
| Controle `lg` | 36px; não se usa nas telas: numa barra, tudo tem a altura padrão |
| Controle `xs` (dentro de outro componente: chip removível, botão dentro do campo) | 24px |
| Botão só de ícone | quadrado na altura do tamanho: `icon` 32, `icon-sm` 28, `icon-lg` 36, `icon-xs` 24 |
| Área de texto | no mínimo 64px; cresce com o texto |
| Checkbox · rádio · switch | 16px · 16px · 32 × 18px (`sm` 24 × 14) |
| Badge | 20px de altura |
| Item de menu suspenso e de select | 28px |
| Cabeçalho de tabela | 40px |
| Item do menu da sidebar | 32px (`sm` 28; `lg` 48, o do topo e o do usuário) |
| Header da tela | 64px (48px com a sidebar recolhida) |
| Sidebar expandida · recolhida · gaveta do celular | 256px · 48px · 288px |
| Painel da direita | 256px |
| Card de login | até 384px de largura |
| Tela de configuração sem tabela | até 720px de largura, centralizada (3.1) |
| Modal | 384px (o padrão) · 512px · 672px, largura máxima (2.13) |
| Confirmação (diálogo de alerta) | 384px; 320px no celular |
| Folha lateral | 3/4 da tela, até 384px |
| Popover · menu suspenso | 288px · no mínimo 128px |
| Tooltip | até 320px |
| Avatar | 32px (`sm` 24, em lista densa; `lg` 40, em cabeçalho de perfil); 96px só na foto do Perfil (2.19) |
| Logo na sidebar (completo e ícone) · topo da sidebar | 32px de altura, aberta e recolhida · duas linhas de 48px (logo e empresa), sem mudar ao recolher |

Não existe tamanho `xl`. Altura, padding, raio e tamanho de texto de componente **não se ajustam por
`className`** (`h-10`, `px-4`, `text-base`…): se uma medida parecer errada, quem muda é o guia.

**O tamanho se escolhe pela classe, nunca por valor à mão** *(decisão do usuário, 2026-10-26)*. No shadcn,
é a prop `size` do componente (`size="sm"`; sem a prop, o padrão). Fora dele (outra stack, a página do
guia, a demonstração ao vivo), as alturas vêm de uma escala só, gerada dos tokens no `tokens.css`:
`--size-xs` (24), `--size-sm` (28), `--size-default` (32) e `--size-lg` (36), mais `--size-item` (28,
item de menu) e `--size-sidebar-lg` (48). O componente lê a altura dessa escala, e a tela só escolhe
a classe (`.btn`, `.btn-sm`…). Nenhum `height` escrito num elemento ou numa regra de tela.

**Raio:** um valor só, `--radius: 0.5rem` (8px), igual em todos os produtos. Os outros saem dele pela
escala do shadcn, que multiplica:

| Classe | Raio | Onde |
|---|---|---|
| `rounded-lg` (o raio) | 8px | botão, campo, select, toggle, alerta, popover, menu suspenso |
| `rounded-xl` (× 1,4) | 11px | card, modal, diálogo de alerta, lista de comandos, estado vazio |
| `rounded-md` (× 0,8) | 6px | item de menu, de select e da sidebar, tooltip, skeleton, botão `sm` e `xs` |
| 4px | 4px | checkbox |
| `rounded-full` | redondo | badge, avatar, switch, rádio, bolinha de cor |

**Elevação:** plana por padrão.
- **Box** (card, tabela, formulário, painel): fundo `card`, **contorno de 1px em `foreground` a 10%**
  (`ring-1 ring-foreground/10`, como o shadcn desenha o card), **sem sombra**. A cor `border` fica
  para separadores, linhas de tabela e a borda da sidebar.
- **Flutuante** (menu, popover, select): fundo `popover`, o mesmo contorno e a sombra média
  (`shadow-md`: `0 4px 6px -1px` e `0 2px 4px -2px`, preto a 10%, nos dois temas). A folha lateral
  usa `shadow-lg`.
- **Modal e confirmação:** contorno, sem sombra, sobre um véu preto a 10% com desfoque leve.
- Nada mais tem sombra. Profundidade vem dos tokens de superfície, não de sombra.

## 1.6 Tema claro e escuro

- **Os dois temas são obrigatórios** em todo sistema. Toda tela é feita e conferida nos dois.
- A escolha fica no **menu do usuário**, na linha "Tema", com o Sol (claro) e a Lua (escuro). A
  escolha é guardada por usuário e vale em toda sessão seguinte.
- Tema inicial de quem nunca escolheu: **claro**, ou o do sistema operacional quando a stack
  permitir sem complicação.
- O tema troca sem piscar e sem animação. Nenhum componente decide o que renderizar pelo tema:
  tudo é token, e o token responde ao tema.
- Imagens que dependem do tema (o logo) têm as duas versões e a tela mostra a certa.

## 1.7 Movimento

- Controles (hover, foco, toggle): 150ms, a transição padrão do Tailwind.
- Flutuantes: as animações do próprio shadcn, sem edição. Modal, menu, popover e select aparecem em
  100ms (opacidade e escala de 95% a 100%); a folha lateral desliza em 200ms; o tooltip aparece em
  150ms.
- Nada anima na troca de tema. Nada anima em loop, exceto o Spinner e o pulsar do Skeleton.
- Quem pede movimento reduzido no sistema operacional não vê animação nenhuma.

---

# Parte 2 — UI Kit

Cada componente abaixo é canônico: toda tela usa o componente da biblioteca do projeto que
corresponde a ele (o `DESIGN.md` local diz qual). A ordem para qualquer coisa nova é: (1) um
componente do kit, (2) uma composição de componentes do kit, (3) um componente próprio, só quando
nada disso existe, e montado com os do kit. HTML puro fica para a estrutura do layout, nunca para
controle interativo.

## 2.1 Botão

| Variante | Visual | Uso | Quantos por contexto |
|---|---|---|---|
| `primary` | fundo `primary`, texto `primary-foreground` | a ação principal do contexto | **1** |
| `secondary` | fundo `secondary` | ação de apoio preenchida | vários |
| `outline` | borda `border` e fundo `background` (no escuro, borda `input` e fundo `input` a 30%) | ação de apoio, filtros, "Editar" | vários |
| `ghost` | sem fundo nem borda; `muted` no hover | cancelar, voltar, botão só de ícone em barra | com moderação |
| `link` | texto no token `link` (a primária; no escuro, mais clara, 1.2), sublinhado no hover | navegação dentro de texto | com moderação |
| `danger` | tinta de `danger` (10%; 20% no escuro) com o texto em `danger-strong` | só ação destrutiva, só depois de confirmação ou dentro dela | 1 |

- Tamanhos, os do shadcn: `xs` 24px, `sm` 28px, padrão 32px, `lg` 36px. **Não existe `xl`.** Só de
  ícone: quadrado na mesma altura (`icon-xs`, `icon-sm`, `icon`, `icon-lg`). **Padrão em tudo,
  inclusive no "Novo…"**: botões, campos e filtros de uma mesma barra têm a mesma altura. `sm` e `xs`
  só dentro de outro componente. `lg` não se usa nas telas dos sistemas.
- Ícone à **esquerda** do rótulo, 16px (14 no `sm`, 12 no `xs`), a 6px do texto (4 no `sm` e no
  `xs`). Ícone à direita só para "abre algo" (seta, chevron, link externo).
- O `danger` é a tinta do `destructive` do shadcn com o texto no tom `-strong`: com o texto em
  `danger` puro, o escuro fica abaixo de 4,5:1 (1.2).
- **Rótulo é verbo no infinitivo:** "Salvar", "Excluir fila", "Nova fila". Nunca "OK", "Sim",
  "Clique aqui".
- **Botão só de ícone:** `aria-label` **e** tooltip com o mesmo texto. Sem exceção.
- **Carregando:** desabilitado, com o Spinner no lugar do ícone e o rótulo mantido ("Salvar", não
  "Salvando…").
- Desabilitado: 50% de opacidade, sem hover, cursor padrão. Desabilitado não some: fica visível
  com tooltip explicando por quê, quando o motivo não é óbvio.
- Link com cara de botão é um link com o estilo do botão. Nunca um link dentro de um botão.
- **"Novo…" (criar) fica dentro do card da lista que ele alimenta, no canto superior direito**
  *(decisão do usuário, 2026-10-26)*: `primary`, no `size` padrão do `Button` (sem a prop `size`, 32px), da mesma altura da busca,
  dos filtros e dos outros botões da barra *(o usuário reviu a D5: em `lg`, ficava desalinhado deles)*;
  ícone `plus`, o único primário do card. Card com título: nas ações do cabeçalho (`CardAction`). Card sem
  título: no fim da primeira linha da barra de ferramentas, depois da busca e dos filtros (3.5).
  Abaixo de 40rem de largura do card, vira botão só de ícone (`icon`) com `aria-label` e tooltip
  ("Nova fila"). Nunca no header nem numa barra acima do card (3.3).
- Não existe botão "Atualizar": os dados se atualizam sozinhos (3.8). "Tentar de novo" continua
  nos estados de erro.

## 2.2 Campo de texto e área de texto

Anatomia, de cima para baixo, com 8px entre as partes: **rótulo** (14/500, sempre ligado ao
controle) › **controle** (32px, borda `input`, raio 8, 10px de padding, fundo transparente; no escuro,
`input` a 30%) › **ajuda** (14, `muted-foreground`) ou **erro** (14, `danger`, com a borda do controle
em `danger` e um anel de 3px em `danger` a 20%).

- Placeholder é exemplo do formato ("dd/mm/aaaa", "nome@empresa.com.br"), nunca o rótulo.
- Campo opcional diz "Opcional" na ajuda. Obrigatório não leva asterisco.
- Ícone dentro do campo, à esquerda, 16px, `muted-foreground` (e-mail, senha, busca). Ação dentro
  do campo (mostrar senha, limpar) à direita, como botão só de ícone `ghost` `icon-xs` (24px).
- Área de texto: altura mínima de 64px; cresce com o texto.
- Foco: a borda vira `ring` e ganha um anel de 3px em `ring` a 50%, colado ao controle. Erro: borda
  `danger` e mensagem; a mensagem diz o que fazer ("Informe um número maior que zero.").
- Campo de busca: ícone `search` à esquerda, placeholder "Buscar <o quê>", largura máxima de 320px
  numa barra.

## 2.3 Select, combobox e data

- **Select:** mesma anatomia e altura do campo (32px; `sm` 28), chevron à direita, itens de 28px,
  até 8 opções. Acima disso, **combobox**
  com busca. Seleção múltipla mostra chips dentro do controle, cada chip com o seu "×" nomeado.
- **Data:** campo digitável no formato do idioma (`dd/mm/aaaa` em pt-BR) com o ícone `calendar`
  dentro do campo, à direita, que abre o calendário. No calendário, **mês e ano são dropdowns**,
  nunca só setas. Data pela metade não é erro enquanto se digita: quem valida é o envio.
- Período: dois campos de data lado a lado ("De", "Até") ou um atalho de período (Hoje, 7 dias,
  30 dias, Personalizado). Como filtro, é o controle "Período" (2.22) e mora na linha de filtros do
  card de relatório (2.24). Dashboard não tem período: o recorte é fixo (3.1).

## 2.4 Checkbox, rádio e switch

- **Checkbox** para escolha múltipla e para "aceito". Rótulo à direita, clicável.
- **Rádio** para escolha única entre 2 e 5 opções visíveis. Acima disso, select.
- **Switch** para ligar e desligar algo **com efeito imediato** (uma configuração que salva sozinha).
  Dentro de um formulário que tem "Salvar", é checkbox, não switch.
- Checkbox e rádio têm 16px (a área de clique do checkbox é maior que o desenho); o switch tem
  32 × 18px (`sm` 24 × 14). Os três com foco visível e o estado marcado na `primary`.

## 2.5 Badge

- Pílula de 20px de altura (raio redondo), 12/500, 2px × 8px de padding, ícone de 12px à esquerda
  quando há, a 4px do texto.
- Variantes: `neutral` (fundo `muted`), `primary` (cheia), `success`, `warning`, `danger`, `info`
  (tingidas a 12%, texto e ícone no tom `-strong`; ver 1.2).
- **Badge de status sempre leva ícone e texto**, para não depender só da cor: "● Ativa" com
  `circle-check` em `success`; "Inativa" com `circle-x` em `danger`.
- Contador (não lidos, pendências): badge na `primary` com o número, 20px de altura e no mínimo
  20px de largura. No menu da sidebar, o `SidebarMenuBadge` (20px, 12/500).

## 2.6 Alerta

A caixa que fica na tela até a condição mudar. Quatro tipos, e o tipo escolhe o ícone e a cor; a
tela não escolhe nenhum dos dois.

| Tipo | Quando |
|---|---|
| `success` | deu certo e precisa ficar à vista. Se é passageiro, é toast |
| `danger` | erro ou recusa: a ação não aconteceu |
| `warning` | aconteceu ou vai acontecer, e tem consequência que a pessoa precisa saber |
| `info` | contexto neutro: o que está valendo, o que muda depois |

- Anatomia: ícone fixo 16px › texto (14). Título (14/500) só quando a mensagem precisa de manchete;
  com uma frase, só a descrição.
- Fundo tingido a 8%, borda a 30%, texto e ícone no tom `-strong` (1.2). Raio 8, padding 8 × 10.
- Pode ficar dentro de um modal: é o lugar da recusa do servidor numa confirmação.
- **Texto: uma frase**, com o que a pessoa precisa para decidir.
- Quando NÃO é alerta: o que fica à vista enquanto uma condição vale (modo do compositor, conexão
  caída) é **indicador de estado**, não alerta: variante neutra, `role="status"`, ícone próprio.

## 2.7 Toast

Aviso passageiro, no canto inferior direito (no celular, embaixo, largura total).

- Anatomia: ícone do tipo › **título de até 5 palavras** › descrição opcional de uma linha › "×".
  Ação opcional ("Ver", "Desfazer") como botão `ghost` `sm`.
- Some em **6 segundos**; erro fica até fechar. Pausa enquanto o mouse está sobre ele. No máximo 3
  ao mesmo tempo; o mais antigo sai.
- Toast é para o que **não precisa ficar**: "Fila criada", "Alterações salvas". O que precisa ficar
  é alerta. Erro de formulário nunca é toast: vai no campo ou acima do rodapé.
- Leitor de tela anuncia o toast de erro na hora e os outros quando puder.

## 2.8 Tooltip

- Toda dica ao passar o mouse ou focar é tooltip: fundo `foreground` e texto `background`
  (invertido: escuro no claro, claro no escuro), 12/400, 6px × 12px, raio 6, até 320px de largura.
  Abre sem atraso, como o `TooltipProvider` do shadcn vem.
- **Nunca o atributo nativo `title`**, nem junto do tooltip, nem sozinho.
- Obrigatório em todo botão só de ícone, com o mesmo texto do `aria-label`. Atalho de teclado na
  dica vai num `kbd`.
- Botão desabilitado não dispara tooltip: envolve-se num elemento que dispara.
- Tooltip não guarda informação necessária: o que a pessoa precisa saber está na tela.

## 2.9 Card e box

- A superfície que embala todo conteúdo: fundo `card`, contorno de 1px em `foreground` a 10%, raio
  11 (`rounded-xl`), padding 16 (12 no card `sm`), sem sombra. É o `Card` do shadcn como vem.
- Anatomia opcional, com 16px entre as partes: **cabeçalho** (título 16/500 e descrição 14
  `muted-foreground`; ação do cabeçalho no canto direito: o "Novo…" da lista, 2.1, ou as ações do
  registro no detalhe) › **conteúdo** › **rodapé** (faixa com
  borda em cima e fundo `muted` a 50%; ações alinhadas à direita, ou contagem à esquerda e
  "Carregar mais" à direita).
- **Card de KPI:** rótulo (14, `muted-foreground`) em cima, valor (30/700, tabular) embaixo,
  variação opcional como badge. No dashboard, uma linha de 12 `muted-foreground` diz o recorte e
  contra o que a variação compara ("Últimos 30 dias, contra os 30 anteriores", 3.1). Grade de 1 coluna no celular, 2 a partir de 28rem de contêiner, 3
  ou 4 a partir de 42rem.
- Card clicável inteiro tem hover (`muted` leve) e foco visível; e tem uma ação só.

## 2.10 Tabela de dados

Toda listagem tabular é uma tabela de dados completa, nunca uma `<table>` solta. **Toda listagem tem
o padrão completo** *(decisão do usuário, 2026-10-26)*: busca, colunas ordenáveis, paginação, "…" de
ações e os estados (skeleton, vazio, erro). Lista curta não é desculpa para faltar nenhum.

Anatomia, dentro de um card:
1. **Barra de ferramentas** (acima da tabela): busca à esquerda (máx. 320px), **um filtro por
   coluna de conjunto fechado** ao lado (até três à vista, o resto em "Filtros", 3.5), e à direita
   o menu "Colunas" e, no fim, o **"Novo…"** (`primary`, na altura padrão, como o resto da barra), o único primário do card; com título
   no card, o "Novo…" vai nas ações do cabeçalho (2.1).
2. **Cabeçalho:** 40px, 14/500 em `foreground`. **Toda coluna de valor único é ordenável** (abaixo).
   Número alinhado à direita, com dígitos tabulares.
3. **Linhas:** 14, padding 8, separadas por `border`, hover em `muted` a 50%. Status como badge
   com ícone. Cor do banco como bolinha com contorno.
4. **Ações da linha:** todas num único botão "…" (`ellipsis`) na última coluna, `ghost` `icon-sm`, com
   `aria-label` e tooltip "Ações", que abre um menu: itens com ícone; o que desliga ou apaga vem
   por último, depois de um separador; o que pede confirmação abre o diálogo a partir do item.
   Nunca botões soltos na linha. A exceção é a primeira etapa da listagem em duas etapas (3.18): a
   ação que leva à segunda etapa é um botão com o verbo ("Ver acessos ›").
5. **Rodapé:** "N de M linhas" à esquerda; "Linhas por página", página atual e setas à direita.
   Lista paginada por cursor no servidor não pagina no cliente: mostra o que veio e "Carregar mais"
   no rodapé do card, ao lado de "N carregados".

**Ordenação** *(decisão do usuário, 2026-10-26)*:
- **Toda coluna de valor único ordena**, inclusive telefone, e-mail, código e data. Não ordenam: a
  coluna de ações, a de seleção (caixa de marcação), coluna com vários valores na célula
  (etiquetas, avatares) e texto livre longo (descrição, observações). Coluna de vários valores com
  um número natural ordena por ele: "Atendentes" ordena pela quantidade.
- O título do cabeçalho é um botão: um clique ordena crescente, outro, decrescente. O `th` leva
  `aria-sort` (`ascending` ou `descending` na coluna ordenada, `none` nas outras ordenáveis, nada nas
  que não ordenam), e o ícone (`arrow-up` ou `arrow-down`, 14px) aparece só na coluna ordenada.
- Texto pela ordem alfabética do idioma, sem diferença de acento e de caixa; número e data pelo
  valor; status, prioridade e etapa pela ordem do conjunto (Ativa antes de Inativa, Baixa até
  Urgente, Entrada até Concluído), não pelo alfabeto. Vazio vai para o fim, nos dois sentidos.
- A tabela abre numa ordem que o cabeçalho mostra (em geral a coluna principal, crescente). A ordem
  vive na URL, como os filtros (3.5), e mudá-la volta à primeira página.
- Tela que também tem "Ordenar" na barra (a de tarefas, porque o kanban não tem cabeçalho): na lista,
  o "Ordenar" e o cabeçalho são a mesma ordenação; escolher num desliga o outro.

**Coluna de conjunto fechado vira filtro** *(decisão do usuário, 2026-10-26)*:
- Coluna cujo valor vem de um conjunto fechado (Status, Setor, Origem, Prioridade, Tipo, Cargo,
  Pessoa, Etiquetas…) tem o seu filtro na barra de ferramentas, com o nome da coluna no gatilho.
- **Até 5 valores: escolha única**, no select de filtro ("Status: todos"). **Mais de 5, ou quando o
  normal é combinar valores** (Pessoa, Etiquetas): seletor múltiplo com busca (2.22).
- Até três filtros à vista, os mais usados; os excedentes vão para "Filtros" (3.5).
- Texto livre (nome, empresa, título) não vira filtro: é da busca.

Estados:
- **Primeira carga:** linhas de Skeleton no formato da tabela.
- **Recarregando** (busca, filtro, ordenação, página): os dados ficam na tela e um Spinner aparece
  na barra de ferramentas. Nunca na releitura automática, em segundo plano (3.8).
- **Vazio:** estado vazio dentro do card (2.12). Com filtro ativo, o texto diz que não há resultado
  para o filtro e oferece limpar.
- **Erro ao carregar:** estado vazio com `circle-alert`, a mensagem e "Tentar de novo".
- Busca vai ao servidor com atraso de 300ms; quando o servidor entrega a lista inteira, filtra no
  cliente, sem atraso.
- Largura: a tabela mede o próprio contêiner. Colunas secundárias somem abaixo da largura em que
  cabem, e o que elas mostrariam desce para a coluna principal. **A página nunca rola para o lado**;
  se precisar, só a tabela rola dentro do card.

## 2.11 Skeleton e Spinner

Duas situações, um componente cada. Nunca um texto "Carregando…" solto.

| Situação | Componente |
|---|---|
| O componente ainda não tem os dados para aparecer (primeira carga de tabela, card, conversa, menu) | **Skeleton**, no formato do conteúdo final: mesmas alturas, larguras e colunas, dentro da box |
| O componente já está na tela e uma informação está sendo buscada ou processada (salvar, buscar, enviar, carregar mais) | **Spinner**, 16px, no botão ou na barra de ferramentas |

- Skeleton: fundo `muted` pulsando devagar (o `animate-pulse` do shadcn), raio 6; larguras fixas,
  nunca aleatórias.
- Spinner nunca substitui um componente inteiro, e nunca aparece na releitura periódica em segundo
  plano, na do foco da janela ou na releitura depois de uma ação.
- Toda chamada a servidor tem um dos dois. Nenhuma tela fica muda esperando.

## 2.12 Estado vazio

Dentro da box, centralizado, com 24px de padding: ícone 16px num quadrado de 32px em `muted`, raio
8 (o `EmptyMedia variant="icon"`) › **título** (14/500:
"Nenhum contato ainda") › **descrição** (14 `muted-foreground`, uma frase: "Cadastre o primeiro
para começar.") › **ação** (botão `primary` com o verbo: "Novo contato"), quando a pessoa pode agir.
  No card de uma lista, o "Novo…" já está no canto (2.1): a ação do vazio é `outline`, para o card
  não ter dois primários.

- Primeiro uso e "nada encontrado" são textos diferentes. Com filtro: "Nenhum resultado para
  'x'" e a ação é "Limpar filtros" (`outline`).
- Erro ao carregar usa o mesmo formato, com `circle-alert` e "Tentar de novo".

## 2.13 Modal (diálogo)

- Flutuante: fundo `popover`, contorno de 1px em `foreground` a 10%, raio 11, padding 16, sem
  sombra, sobre um véu preto a 10% com desfoque leve. Larguras máximas: **384px**, o padrão do
  shadcn (até 4 campos numa coluna); **512px** (`sm:max-w-lg`) para o formulário de até 8 campos em
  duas colunas; **672px** (`sm:max-w-2xl`) só para conteúdo largo. No celular, ocupa a largura toda
  com 16px de margem, e um formulário longo vira folha de baixo para cima.
- Anatomia, com 16px entre as partes: **título** (16/500) e **descrição** (14 `muted-foreground`) à
  esquerda, "×" no canto (`ghost` `icon-sm`, `aria-label` "Fechar", tooltip) › **conteúdo** ›
  **rodapé**: faixa com borda em cima e fundo `muted` a 50%, ações à direita: "Cancelar" (`ghost`)
  e a ação principal (`primary`, ou `danger` na confirmação destrutiva). No celular, as ações
  empilham com a principal em cima.
- Fecha com "×", "Cancelar", Esc e clique fora. Se há formulário com alteração não salva, pergunta
  antes de descartar.
- O foco entra no modal ao abrir e **volta ao botão que o abriu** ao fechar.
- Um modal por vez. Modal não abre modal; abre, no máximo, uma confirmação.
- Recusa do servidor aparece como alerta `danger` dentro do modal, acima do rodapé, sem fechar.

**Confirmação** (diálogo de alerta, 384px; 320px no celular): título em pergunta ("Excluir a fila Retenção?"), uma frase de
consequência ("As 12 conversas abertas voltam para a triagem."), "Cancelar" e o botão `danger` com
o verbo ("Excluir fila"). Nunca "Sim" e "Não". Ação que dá para desfazer não pede confirmação:
executa e oferece "Desfazer" no toast.

## 2.14 Menu suspenso (dropdown)

- Flutuante (fundo `popover`, contorno, sombra média), raio 8, padding 4, largura mínima de 128px.
  Itens de 28px (4px × 6px) com ícone 16px à esquerda a 6px do texto, 14/400, raio 6, hover
  `muted`. Até 2 níveis.
- Grupos separados por linha `border`. Rótulo de grupo 12/500 `muted-foreground`.
- Item destrutivo por último, depois de um separador, em `danger`.
- Item com atalho mostra o atalho à direita em `kbd`. Item que abre diálogo termina em "…".
- Abre com clique ou Enter, navega com setas, fecha com Esc e devolve o foco ao gatilho.

## 2.15 Shell: sidebar, header e painel da direita

Toda tela do sistema vive dentro do shell. A tela não monta menu, header nem painel lateral próprios.

```text
+------------+------------------------------------------+------------+
| [Logo]     | [≡] | Grupo › Tela     [●] [?] [✨] [🔔]  | Painel     |
| [EE] Emp. ⇕|                                          | da         |
|            +------------------------------------------+ direita    |
| GRUPO      |                                           | (opcional, |
|  Item    3 |  +------------------------------------+   |  só a      |
|  Item      |  | box                                |   |  partir de |
| GRUPO      |  |                                    |   |  1024px)   |
|  Item ativo|  +------------------------------------+   |            |
|            |  +------------------------------------+   |            |
|            |  | box                                |   |            |
| [MS] Nome ⇕|  +------------------------------------+   |            |
+------------+------------------------------------------+------------+
```

- **Sidebar** (256px, fundo `sidebar`, borda à direita): **topo em duas linhas de 48px**, o logo do
  produto (32px de altura) e, logo abaixo, o seletor da empresa (componente **Troca de empresa**)
  *(decisão do usuário, 2026-10-26)*;
  **grupos** com rótulo (12/500, `sidebar-foreground` a 70%) e itens (ícone 16 + rótulo 14, 32px de
  altura, raio 6; **ativo em `primary` cheia com texto `primary-foreground`** *(decisão do usuário,
  2026-10-22: a 12% o texto não ficava nítido no escuro)*; contador à direita, 20px, que no item
  ativo fica em `primary-foreground` a 20%); **rodapé** com a entrada da área de administração (2.30,
  só para quem está como Sysadmin) e o botão do usuário (2.16). A troca de empresa e o botão do
  usuário são itens de 48px (`SidebarMenuButton size="lg"`).
- **Os itens do menu são os do papel ativo** (2.16). Na área de administração (2.30), a sidebar ganha
  o tom suave da primária e mostra só os itens da área.
- Recolhe para **ícones** (48px): só o ícone de cada item, com tooltip; o logo vira o ícone do
  produto, **com a mesma altura de 32px**; a empresa e o usuário viram só o avatar, com tooltip.
  **O topo não muda de altura ao recolher**: as duas linhas continuam com 48px *(decisão do usuário,
  2026-10-26)*. Estado guardado por usuário. Atalho Ctrl+B (⌘B).
- Abaixo de 768px, a sidebar vira **gaveta** de 288px sobre a tela, aberta pelo botão do header.
- **Header** (64px, dentro da área de conteúdo): botão de recolher (`panel-left`, `ghost`, tooltip
  "Recolher menu" com o atalho) › separador vertical › **breadcrumb** "Grupo › Tela" (o grupo é
  texto, não link; some no header compacto) › à direita, nesta ordem, os indicadores de estado (ex.:
  "Sem tempo real"), o **?** da ajuda (2.28), o **✨** do assistente (2.29, só nos produtos com IA) e
  o **sino** *(decisão do usuário, 2026-10-26)*: botões só de ícone `ghost` `icon-sm`, a altura do botão
  de recolher (numa barra, tudo na mesma altura). **O header é só disso. Nenhuma ação da tela vai nele:** a ajuda, o assistente e o sino são do shell.
- **Painel da direita** (256px, fundo `sidebar`, borda à esquerda): informações adicionais da tela
  (os dados do contato num atendimento). Opcional; só existe a partir de 1024px; sem conteúdo, não
  aparece. A tela preenche o painel do shell, nunca monta um painel dentro do próprio conteúdo. O
  **assistente de IA** (2.29) usa este lugar, com 384px: aberto, toma o lugar do painel da tela, que
  volta quando ele fecha.
- **Segundo menu** (224px, fundo `muted`, abaixo do header, à esquerda do conteúdo): só no item cujas
  seções são telas próprias, como as configurações (2.27). O item continua ativo na sidebar.
- O conteúdo começa logo abaixo do header, com padding 24 (16 no celular), sem título e **sem
  barra de ações** (3.3): a primeira box vem direto. O "Novo…" fica no card que ele alimenta (2.1).

## 2.16 Menu do usuário

No rodapé da sidebar, um botão de 48px com **avatar** (32px, iniciais na `primary` quando não há foto),
**nome** (14/500) e **e-mail** (12 `muted-foreground`), e o ícone `chevrons-up-down` à direita.
Abre um menu flutuante ao lado (embaixo, no celular), nesta ordem:

1. Cabeçalho: avatar, nome, e-mail e, numa terceira linha, o **papel**: "Papel: **Sysadmin**" (12
   `muted-foreground`, o papel em `foreground` 500), como no DevTasks. Quem tem **mais de um papel**
   não vê essa terceira linha: o papel vai para a linha de troca, logo abaixo do cabeçalho (ver
   **Trocar de papel**).
2. **Perfil** e **Configurações** (ícones `user` e `settings`). Tudo o que é do usuário mora aqui,
   e sai do menu principal. "Configurações" só aparece para o papel que tem a tela.
3. **Ver como…** (`eye`), **só para o Sysadmin** *(decisão do usuário, 2026-10-26)*. Com o modo
   ligado, no lugar dele, **Voltar ao meu usuário** (`undo-2`).
4. Separador.
5. Linha **Idioma:** o rótulo à esquerda e, à direita, os três botões em sigla: **PT · EN · ES**
   (tooltip com o nome: Português, English, Español). Sem bandeira.
6. Linha **Tema:** o rótulo à esquerda e, à direita, o Sol (Claro) e a Lua (Escuro).
7. Separador.
8. **Sair** (`log-out`), por último.

Trocar idioma ou tema não fecha o menu. Na sidebar recolhida o botão mostra só o avatar, com
tooltip.

**Trocar de papel.** Quem tem mais de um papel escolhe com qual está *(decisão do usuário,
2026-10-27)*. O Sysadmin tem todos: Sysadmin, Dev e Suporte. A diferença para o "Ver como": a pessoa
continua sendo ela mesma, só com outro dos papéis dela.

```text
+--------------------------------+
| [MS] Marcos Silva              |
|      marcos@empresa.com.br     |  +---------------------------------+
| [id] Papel: Sysadmin         ⇄ |->| Trocar de papel                 |
|--------------------------------|  | ✓ Sysadmin                      |
| Perfil                         |  |   Tudo, com a administração     |
| Configurações                  |  |   Dev                           |
| Ver como…                      |  |   Tarefas, relatórios e acesso  |
```

- **A linha de troca**, logo abaixo do cabeçalho: um item do menu com o crachá (`id-card`),
  "Papel:" em `muted-foreground`, o nome do papel em 500 e, à direita, **o ícone de troca
  (`arrow-left-right`) no lugar da seta do submenu** *(decisão do usuário, 2026-10-27)*. O ícone
  diz o que a linha faz; ela continua abrindo o submenu ao lado.
- **O submenu** "Trocar de papel" abre ao lado da linha (embaixo, no celular). Tem um item por papel:
  o nome e, embaixo, uma linha com o que o papel vê (12, `muted-foreground`). O papel atual tem o
  `check`. A seta para a direita abre o submenu; a seta para a esquerda volta.
- **Escolher:** o menu fecha e **a tela remonta limpa** no papel novo, como na troca de empresa
  (2.25). Se o papel novo não tem a tela, vai para o início. Um toast avisa: "Agora você está como
  Dev" (2.7). Escolher o papel atual só fecha o menu.
- **O papel decide o menu e as permissões:** os itens, as telas e as ações são os do papel ativo.
  A área de administração (2.30) e o "Ver como" só existem como Sysadmin. Para voltar, a mesma linha.
- **Sem faixa e sem anel no avatar:** não é um modo de exceção, é a própria pessoa. O papel fica à
  vista no menu do usuário.
- **O papel escolhido fica** guardado por pessoa, no servidor, até a pessoa trocar de novo, também
  depois de sair e entrar. O servidor revalida tudo pelo papel ativo, e a troca vai para o registro
  de auditoria.
- **Quando a linha some:** quem tem um papel só não vê a troca; a terceira linha do cabeçalho mostra
  o papel como texto. No "Ver como", a linha também some, e o cabeçalho mostra o papel da pessoa
  escolhida.

**Ver como.** O Sysadmin passa a ver o sistema como outra pessoa, para conferir o que ela vê e
reproduzir um problema dela.

- "Ver como…" fecha o menu e abre um diálogo (modal padrão, 384px, 2.13): título "Ver como", a
  consequência numa frase ("O menu e as telas passam a ser os da pessoa escolhida. O que você
  fizer fica registrado no seu nome.") e a **busca de pessoas** por nome ou e-mail, com a lista
  logo abaixo (avatar, nome, e-mail e papel; setas e Enter escolhem). Escolher liga o modo; Esc ou
  "×" desiste.
- Com o modo ligado, **o sistema se comporta como a pessoa escolhida**: o botão e o menu do
  usuário (nome, e-mail, foto e papel dela), o Perfil, os filtros "meus" ("Só o que é meu" passa a
  ser dela), os contadores, o sino e as preferências. A tela atual remonta limpa, como na troca de
  empresa.
- **A faixa**, fixa acima do header, na largura da coluna de conteúdo *(decisão do usuário,
  2026-10-26)*:

```text
+------------+------------------------------------------------------------------+
| [Logo]     | Você está vendo como Ana Ribeiro           [Voltar ao meu usuário] |  faixa, 40px
|            +------------------------------------------------------------------+
|            | [≡] | Grupo › Tela atual                                      [sino] |  header
|            |  +------------------------------------------------------------+  |
| [AR] Ana  ⇕|  | box                                                        |  |
+------------+------------------------------------------------------------------+
```

- A faixa tem 40px, fundo `warning` a 12% sobre o `background`, texto em `warning-strong`, borda de
  baixo em `warning` a 30%, o ícone `eye`, a frase "Você está vendo como **Ana Ribeiro**" e, à
  direita, **"Voltar ao meu usuário"** (`outline` `sm`, ícone `undo-2`; no celular, só o ícone, com
  tooltip). Sem "×": só sai pelo botão. `role="status"`, para o leitor de tela anunciar a troca. É a
  mesma faixa da troca de empresa (2.25), com outro ícone e outro botão; quando as duas valem, uma
  embaixo da outra, a do "Ver como" primeiro.
- O **avatar do rodapé da sidebar** ganha o anel de atenção (2.19) enquanto o modo vale.
- **O modo não sobrevive ao "Sair"**: sair encerra a sessão e o "Ver como" junto; quem entra de
  novo entra como si mesmo. Recarregar a página mantém o modo, como mantém a sessão.
- No servidor, a sessão guarda as duas pessoas: as permissões e os dados são os da escolhida, e o
  registro de auditoria leva quem fez ("Marcos Silva, vendo como Ana Ribeiro").

## 2.17 Breadcrumb

"Grupo › Tela" no header, 14, com o `chevron-right` de 14px como separador. O grupo em `muted-foreground`, sem link; a tela em `foreground` 500.
Tela de detalhe: "Grupo › Lista › Item" com a lista como link. Segunda etapa de uma listagem em duas
etapas, o mesmo: "Grupo › Tela › Escolha", com a tela como link para a primeira etapa (3.18). Seção
de um segundo menu: "Grupo › Item › Seção", com o item como link para a primeira seção (2.27).
Encurta com reticências antes de empurrar o que está à direita.

## 2.18 Paginação

Rodapé da tabela: "N de M linhas" à esquerda; à direita, "Linhas por página" (select de 32px,
10/25/50), "Página X de Y" e as setas (`outline` só de ícone, 32px, desabilitadas no limite). Abaixo de 24rem de
contêiner some a contagem; abaixo de 36rem some o "Linhas por página".

## 2.19 Avatar

32px (`sm` 24, `lg` 40), redondo. Foto, ou as iniciais sobre a `primary` (14; 12 no `sm`). Em
grupo, sobrepostos em 8px, com anel de 2px na cor do fundo. Nunca um ícone genérico de pessoa como avatar de usuário real.

**Foto do Perfil, 96px.** É o único avatar fora dos tamanhos do shadcn e o único `className` de
tamanho permitido nele: `size-24` no `Avatar` e `text-3xl` nas iniciais (`AvatarFallback`). Fica
no topo do card "Seus dados" do Perfil, com os botões à direita:

- **"Trocar foto"** (`outline` `sm`) abre o seletor de arquivo. Aceita **JPG, PNG ou WebP, até
  5 MB**, e a regra fica escrita abaixo dos botões (12, `muted-foreground`). Arquivo fora disso não
  entra, e a mensagem de erro toma o lugar da regra: "Use uma imagem JPG, PNG ou WebP." ou "A
  imagem tem mais de 5 MB. Escolha uma menor."
- **"Remover"** (`ghost` `sm`), só quando há foto: volta às iniciais.
- **Prévia na hora**, no próprio avatar, antes de subir. O **recorte** é o quadrado do centro da
  imagem, em 256 × 256, mostrado redondo; a pessoa não recorta à mão.
- A foto nova, ou a remoção, sobe com o "Salvar" do formulário, como os outros campos; "Cancelar"
  volta à anterior. Salva, ela aparece em todo lugar onde a pessoa aparece: o botão e o cabeçalho
  do menu do usuário, as listas, os cards.

**Anel de atenção.** Enquanto o "Ver como" vale (2.16), o avatar do rodapé da sidebar ganha um
anel de 2px em `warning`, afastado 2px na cor da sidebar (`ring-2 ring-warning ring-offset-2
ring-offset-sidebar`).

## 2.20 Login

Fora do shell, em **duas colunas** *(decisão do usuário, 2026-10-22: o padrão é o do DevTasks,
não mais o card centralizado)*.

```text
+-------------------------------+--------------------------------------+
| [logo branco]                 |                                      |
|                               |   Bem-vindo de volta                 |
|                               |   Entre na sua conta para continuar  |
|   Frase do produto            |                                      |
|   (até duas linhas)           |   E-mail   [__________________]      |
|   Descrição em uma frase      |   Senha       Esqueci minha senha    |
|                               |            [__________________]      |
|                               |   [            Entrar           ]    |
|                               |   Problemas para entrar? Fale com…   |
|                               |--------------------------------------|
|                               | Os negócios por trás…  Quem está ↗   |
|                               | Mais de 20 anos empreendendo, mais…  |
|                               | [‹] [▣ Produto ↗] [▣ Produto ↗] [›]  |
| ✦ recurso  ✦ recurso  ✦ rec.  | Um produto da Ideia Business · …     |
+-------------------------------+--------------------------------------+
```

- **Painel da marca** (esquerda, metade da largura a partir de 1024px): fundo em degradê de 135°
  da `brand` (a primária clara do produto) para ela 25% mais escura. **Sempre colorido, nos dois
  temas**, com texto branco. Logo na versão escura (branca) no canto superior esquerdo, 32px de
  altura. No centro vertical, a **frase do produto** (Vitrine, 36/44/700, até duas linhas) e uma
  descrição (16/24, branco a 85%). No rodapé do painel, até três recursos do produto com o ícone
  `sparkles` (14/500). Sem imagem de fundo, sem ilustração: o degradê é o painel.
- **Coluna do formulário** (direita): fundo `background` do tema; formulário centralizado na
  vertical, até 384px: título "Bem-vindo de volta" (24/600) › "Entre na sua conta para continuar"
  (14 `muted-foreground`) › campo E-mail com `mail` › campo Senha com o link "Esqueci minha senha"
  (`link` `sm`) **à direita do rótulo, na mesma linha**, e o "mostrar senha" dentro do campo ›
  botão `primary` de largura total, no tamanho padrão, como nos blocos de login do shadcn ("Entrar") › linha de apoio (12 `muted-foreground`):
  "Problemas para entrar? Fale com contato@ideiabusiness.com.br".
- **Rodapé** (2.21) **na coluna da direita, embaixo do formulário, e já estendido** *(decisão do
  usuário, 2026-10-27: na largura toda, debaixo das duas colunas, ficou feio)*: produtos à vista,
  carrossel passando, sem a seta. O painel da marca ocupa a altura toda à esquerda; a página só rola
  quando não cabe. **No celular**, o rodapé vem recolhido, com a seta, e abre como folha de baixo,
  para não empurrar o formulário *(D3, decisão do usuário, 2026-10-26)*.
- Enviando: botão desabilitado com Spinner. Erro de credencial: alerta `danger` acima do botão, uma
  frase, sem dizer qual dos dois campos está errado.
- **Abaixo de 1024px:** o painel vira uma faixa no topo, com o logo e a frase; o formulário vem
  abaixo, em largura total. **Abaixo de 640px:** a faixa fica só com o logo.
- Recuperar senha, primeiro acesso e código de verificação usam a mesma estrutura, trocando só o
  conteúdo da coluna do formulário.
- O logo sem nada escrito ao lado. Os recursos são do produto, não da empresa.

## 2.21 Rodapé

Todo sistema tem o mesmo rodapé *(decisão do usuário, 2026-10-22: o do DevTasks ocupava espaço
demais; o padrão passa a ser uma linha, e os produtos da Ideia Business aparecem pela seta)*.

```text
Recolhido (toda tela):
───────────────────────────────────────────────────────────────────────────────────────────────
Um produto da Ideia Business    Razão social · CNPJ       contato@ideiabusiness.com.br   [⌃]

Estendido (clique na seta; no login, já vem assim e sem a seta):
═══════════════════════════════ borda em cima, sombra só para cima ════════════════════════════
Os negócios por trás deste produto                                         Quem está por trás ↗
Mais de 20 anos empreendendo, mais de 500 mil empresas atendidas e uma rede com mais de 5 mil…
[‹]  [▣ IDeia DevTasks ↗]  [▣ IDeia Chat ↗]  [▣ IDeia Signer ↗]  [▣ NF IDeia ↗]  [▣ Polaria ↗]  [›]
Um produto da Ideia Business    Razão social · CNPJ       contato@ideiabusiness.com.br   [⌄]
```

- **Uma linha de 40px** no fim da coluna de conteúdo de **toda** tela, depois da última box. Rola
  com a página; nunca fixa, nunca cobrindo conteúdo. Borda superior em `border`, texto 12 em
  `muted-foreground`, padding 12 × 24.
- Conteúdo, da esquerda para a direita: "Um produto da **Ideia Business**"; a razão social e o CNPJ;
  o e-mail de contato como texto selecionável; e, no canto direito, **a seta para cima**
  (`chevron-up`: botão só de ícone `ghost` `sm`, com `aria-label`, `aria-expanded` e tooltip
  "Produtos da Ideia Business").
- **A seta abre e fecha só no clique** (Enter ou espaço pelo teclado), nunca no hover, com cursor
  de mão; o `globals.css` gerado já põe `cursor: pointer` em todo botão *(decisão do usuário,
  2026-10-26)*. Enquanto aberto, a seta vira `chevron-down`. Fecha pela seta ou com Esc (o foco
  volta para a seta). Clicar fora não fecha: o rodapé é parte da página, e fechar sozinho faria o
  conteúdo pular.
- **Estendido, é o próprio rodapé crescendo**, não um painel flutuante *(decisão do usuário,
  2026-10-26)*. A parte estendida entra **no fluxo da página**, logo acima da linha, na largura do
  rodapé: o rodapé fica mais alto, a página ganha a altura dele e **rola até mostrar o rodapé
  inteiro** (`scrollIntoView`, sem animação para quem pede movimento reduzido). **Nada fica por cima
  do conteúdo** *(decisão do usuário, 2026-10-26: por cima, ele cobria o fim da lista)*. A linha
  continua embaixo, com a seta. Fundo da página (`background`) *(D4)*; borda superior em `border`;
  **sem raio e sem borda nos lados**; **sombra só para cima** (a `shadow-md` do Tailwind,
  invertida); sem véu.
- Dentro, de cima para baixo: o título "Os negócios por trás deste produto" (14/500) com **"Quem
  está por trás ↗"** à direita, na mesma linha, e a frase da empresa (12, uma só) na largura toda;
  depois, os produtos num **carrossel** de **cards finos** *(decisão do usuário, 2026-10-27: a
  1024 × 768, o rodapé aberto ocupava 30% da janela)*: 240 × 54px, e **o card inteiro é o link do
  produto, que abre em outra aba** (cursor de mão, fundo `muted` no hover), com o ícone do logo
  (32px), o nome (14/500) e a descrição (12, `muted-foreground`), uma linha cada, e o
  `external-link` (12, `muted-foreground`) à direita. Sem botão "Conhecer". O leitor de tela ouve
  "(abre em outra aba)" no fim do nome do card. Uma seta em cada ponta do carrossel (`chevron-left`
  e `chevron-right`, botões só de ícone `outline` `sm`, com nome acessível), **sem barra de
  rolagem**, passando sozinho a cada 4 segundos em laço; para enquanto o mouse está em cima ou algo
  dentro dele tem foco, e não passa sozinho para quem pede movimento reduzido *(decisão do
  usuário, 2026-10-22)*. A razão social e o CNPJ só ganham uma linha embaixo dos cards quando a
  linha do rodapé não tem espaço para eles.
- **Os textos e os produtos vêm da API** *(decisões do usuário, 2026-10-28 e 2026-10-29)*:
  `GET https://design-api.ideiabusiness.com.br/api/v1/footer?product=<slug do sistema>`, sem login.
  Nada disso fica escrito no código do sistema.
  - A resposta traz os textos da empresa e os cards. Os textos são o nome da marca, a razão social, o
    CNPJ, o e-mail, o título, a frase e o link do "Quem está por trás", editados no painel. Os cards
    vêm em ordem alfabética, sem o do próprio sistema: slug, nome, texto, URL e ícone.
  - O texto do card é o do cadastro do produto. Card de produto sem endereço sai sem link.
  - **Em SSG, consultando a API 1 ou 2 vezes por dia** *(decisão do usuário, 2026-10-30)*: o rodapé
    sai pronto do build e o sistema só volta à API quando a revalidação vence, a cada 12 ou 24 horas
    (no Next, `fetch` com `next: { revalidate: 43200 }` ou `86400`). Em tela com login, que se monta a
    cada pedido, o `fetch` vem do cache do Next, não da API. Nunca SSR sem cache (uma chamada por
    página), nunca do navegador, e nada de `cache: "no-store"`, `revalidate: 0` ou
    `fetchCache = "force-no-store"` no caminho do rodapé. Uma mudança no painel chega a todos em até
    um dia.
  - Com a API fora, o Next continua servindo o último rodapé que leu (o `fetch` só guarda resposta
    200); sem nenhum guardado, o rodapé não aparece e a página segue.
- **Login:** o rodapé fica **na coluna da direita, embaixo do formulário** (2.20), e **já vem
  estendido**: produtos à vista, carrossel passando, sem a seta *(decisão do usuário, 2026-10-27:
  na largura toda, debaixo das duas colunas, ficou feio)*. É o mesmo componente com `estendido`;
  ali ele faz parte da página e não cobre nada.
- **Celular** (abaixo de 768px): a linha vira duas linhas centralizadas e o CNPJ fica só na parte
  estendida, que vira **folha de baixo** (`Sheet side="bottom"`), com véu, a seta para baixo no
  topo (fecha) e os cards empilhados; fecha pela seta, com Esc ou tocando fora. **No login pelo
  celular, o rodapé vem recolhido, com a seta**, para não empurrar o formulário *(D3, decisão do
  usuário, 2026-10-26)*.
- **Tela de altura cheia:** a linha fica abaixo da área que cresce, e os 40px dela entram na conta.
  Estendido, a área que cresce encolhe para dar lugar a ele (o quadro do kanban fica mais baixo); a
  página continua sem rolar e nada fica coberto.
- Nunca: botão "Conhecer" ou outro link dentro do card do produto (o card é o link); parágrafo
  institucional, carrossel ou cards de produtos no corpo da tela; rodapé fixo; os textos da empresa
  ou a lista de produtos escritos no código (vêm da API); abrir no hover; a parte estendida por cima
  do conteúdo ou com cara de painel flutuante (raio, borda nos lados, fundo de `popover` ou `card`,
  sombra para baixo, véu no desktop); esconder a linha (o CNPJ precisa estar à vista). O que fica
  guardado até a seta é só a parte estendida.

## 2.22 Filtro

Os controles de filtro são os mesmos em toda tela; o que muda é onde ficam (3.5).

| Controle | Quando | Anatomia |
|---|---|---|
| **Select de filtro** | escolha única, até 5 valores (Status, Setor, Origem, Prioridade) | select de 32px com o rótulo e o valor no gatilho: "Status: todos", "Setor: Vendas". Vazio = "todos" |
| **Seletor múltiplo com busca** | mais de 5 valores, ou quando o normal é combinar valores (pessoa, etiqueta, cargo, produto) | gatilho `outline` com o rótulo e o contador ("Pessoa · 2"); aberto: busca no topo, caixas de marcação, opções especiais fixas no alto ("Eu", "Sem responsável"), separador, as demais em ordem alfabética; rodapé com "n marcadas" e "Limpar". Ativo: borda na `primary` e o contador |
| **Período** | qualquer filtro por data | um botão `outline` com `calendar` e o que vale ("Últimos 30 dias", "01/10 a 22/10/2026"); aberto: atalhos à esquerda (7 dias, 30 dias, 90 dias, Mês atual, Mês anterior, Este ano, 12 meses) e "De" e "Até" digitáveis à direita; aplica ao mudar |
| **Chip de alternância** | atalho liga/desliga que combina com os outros ("Só o que é meu", "Ocultar concluídos", "Compacto") | `Toggle` `outline` de 32px, raio 8; ligado = `primary` cheia (o toggle do shadcn liga em `muted`, sem o contraste de 3:1; ver 4.5). No máximo três por barra |
| **Botão "Filtros"** | os filtros que não cabem à vista | `outline` com `filter` e o contador dos ativos ("Filtros · 2"); abre um popover (folha de baixo no celular) com todos os campos no formato de formulário, em 2 colunas, e "Limpar tudo" no rodapé; aplica ao mudar |
| **Chip removível** | mostrar e tirar um filtro ativo que não está à vista | botão `secondary` `xs` (24px, 12/500) com "Rótulo: valor" e o `x` à direita; o botão inteiro remove, com nome acessível ("Remover filtro Etiqueta: Bloqueada"); a linha termina em "Limpar (n)" |
| **Busca** | texto livre | campo de 32px com `search`, placeholder "Buscar <o quê>", até 320px; limpa pelo "×" dentro do campo |

- **De onde vêm os filtros de uma tabela:** cada coluna de conjunto fechado tem o seu, com o nome da
  coluna no gatilho (2.10). Escolha única até 5 valores; múltipla acima disso ou quando o normal é
  combinar valores, como Pessoa *(decisão do usuário, 2026-10-26)*.
- Todo controle de filtro mostra **o rótulo e o valor** no próprio gatilho; nunca só o valor.
- Vazio significa "todos": o gatilho diz "Status: todos", não fica em branco.
- **Filtro ativo:** borda na `primary` e, no seletor múltiplo e em "Filtros", o contador (badge na
  `primary`); **o texto do gatilho fica em `foreground`** *(decisão do usuário, 2026-10-26)*: texto
  na `primary` fica abaixo de 4,5:1 no escuro, e a borda só precisa de 3:1. Não está à vista: aparece
  na linha de chips.
- Aplica ao mudar. Busca e filtro que vão ao servidor esperam 300ms. Sem botão "Aplicar".
- Exemplo vivo dos seis controles na página do guia, seção 3.5.

## 2.23 Abas

O `Tabs` do shadcn com `variant="line"`, como vem *(decisão do usuário, 2026-10-26)*: lista de 32px
sem fundo, 4px entre as abas, rótulo 14/500 em `foreground` a 60% (`muted-foreground` no escuro), a
aba ativa em `foreground` com um sublinhado de 2px em `foreground`. Ícone opcional de 16px à
esquerda do rótulo. Nada de cor da primária, fundo ou borda por `className`.

| | Abas (`variant="line"`) | Controle segmentado (`variant="default"`) |
|---|---|---|
| Para quê | trocar de visão: cada aba tem o seu conteúdo | trocar o recorte ou o agrupamento do mesmo conteúdo (Dia · Semana · Mês) |
| Onde | no topo do card, antes dos filtros (2.24) | junto do que ele muda, dentro do conteúdo (o cabeçalho de um gráfico) |
| Quantas | 2 a 6, rótulo de uma ou duas palavras | 2 a 4, rótulo de uma palavra |
| Desenho | sem fundo; a ativa sublinhada | trilho em `muted`, a ativa em `background` com sombra leve |

- No controle segmentado, o rótulo inativo fica sobre o trilho `muted` (em `muted-foreground` no
  escuro): os neutros do tema precisam dar 4,5:1 nesse par (1.2).
- Os dois são o mesmo componente, com a mesma semântica: `tablist` com nome (`aria-label`:
  "Visão"), `tab` com `aria-selected` e `aria-controls`, `tabpanel` ligado à aba.
- **Teclado**, o do Base UI: Tab entra na aba ativa; as setas movem o foco entre as abas e voltam ao
  início no fim; Home e End vão às pontas; Enter ou Espaço abrem a aba (`activateOnFocus` desligado,
  como vem: trocar de aba pode ir ao servidor). Tab de novo segue adiante: os filtros, no card de
  relatório, ou o painel.
- O painel recebe foco (o Base UI dá `tabIndex` 0 ao painel aberto) e o `TabsContent` do shadcn vem
  com `outline-none`: o anel de foco do guia entra no `tabs.tsx` (nível 3, 4.5), senão quem usa o
  teclado perde o foco de vista.
- A aba aberta vive na URL (`?visao=pessoas`), como os filtros (3.5). Sem nada na URL, a primeira.
- As abas não quebram linha: sem espaço, a lista rola na horizontal dentro do card. Nunca mais de
  uma linha de abas nem abas dentro de abas. Uma visão só não vira aba.
- Aba não é navegação: trocar de tela é o menu (3.2), e as seções de uma área (as configurações:
  Tags, Campos, SLA, Webhooks) vão no segundo menu (2.27). Lista ou Kanban e Compacto são modo de
  exibição, na barra de ferramentas (3.5), e não abas.

## 2.24 Card de relatório

O relatório é **um card autossuficiente** *(decisão do usuário, 2026-10-26)*: tudo o que muda o que
ele mostra mora dentro dele. Por isso entra em qualquer tela (a tela Relatórios, o detalhe de um
produto, a página de uma equipe) sem depender de barra de ações (3.3).

```text
+------------------------------------------------------------+
| Produtos   Pessoas   Equipe                        [ação]  |  abas (2.23)
| ‾‾‾‾‾‾‾‾                                                   |
| [Últimos 30 dias ▾]  [Produto: todos ▾]  ◌                 |  filtros do card
|                                                            |
| Andamento por produto                                      |  título da visão
| 31 produtos · 13 com entrega vencida                       |  recorte e contagem
| ...lista, gráfico ou tabela...                             |  conteúdo
+------------------------------------------------------------+
```

De cima para baixo, com os 16px do `Card` entre as partes:
1. **Abas** (2.23): as visões do relatório. Uma visão só: sem abas, e o título da visão abre o
   card. Ação do card inteiro (exportar, por exemplo) à direita das abas.
2. **Filtros do card**, logo abaixo das abas: o período (2.22) e o que muda o recorte (produto,
   fila, pessoa), nos controles de 32px. Aparecem só os que valem para a aba aberta; o período vale
   para todas e não muda ao trocar de aba. Até três à vista, o resto em "Filtros" (3.5).
3. **Conteúdo** da aba: título da visão (16/500) e descrição (14 `muted-foreground`) com o recorte e
   a contagem, depois a lista, o gráfico ou a tabela.

Estados, todos dentro do card, com as abas e os filtros sempre usáveis:
- **Primeira carga**, e aba aberta pela primeira vez: Skeleton no formato do conteúdo (2.11).
- **Mudou um filtro, ou voltou a uma aba já vista:** os dados ficam e o Spinner aparece no fim da
  linha de filtros.
- **Erro ao carregar:** o estado de erro no lugar do conteúdo, com "Tentar de novo" (2.12).
- **Nada no recorte:** estado vazio ("Nenhuma entrega no período"), com "Limpar filtros" quando há
  filtro além do período.
- Releitura automática: só os números mudam (3.8).

Estado na URL:
- Aba, período e filtros vivem na URL (`?visao=pessoas&p=90d&produto=ideia-chat`): o link abre o
  mesmo recorte, e o voltar do navegador desfaz a última troca. Vazio = a primeira aba e o padrão.
- **Com mais de um card de relatório na tela, cada um usa um prefixo** (`entregas.visao`,
  `conversas.p`), para um não mexer no outro. Um só na tela: sem prefixo.
- Trocar de empresa zera tudo (3.5).

- No celular a linha de filtros quebra linha; as abas não: rolam na horizontal dentro do card.
- Dashboard não usa card de relatório: mostra recortes fixos (3.1). Quem precisa filtrar abre um
  relatório.

## 2.25 Troca de empresa

No topo da sidebar, **logo abaixo do logo do produto**, o seletor da empresa em que a pessoa está
trabalhando *(decisão do usuário, 2026-10-26: o topo tem duas linhas; o logo é a marca do produto e o
seletor é o contexto)*. É o `TeamSwitcher` do bloco `sidebar-07` do shadcn.

```text
┌──────────────────────────────┐
│ [logo do produto]            │  48px · logo de 32px de altura
│ [EE] Empresa Exemplo       ⇕ │  48px · SidebarMenuButton size="lg"
│      12.345.678/0001-90      │
├──────────────────────────────┤
│ GRUPO                        │
```

- **Botão de 48px** (`SidebarMenuButton size="lg"`): à esquerda, o **avatar da empresa**, um quadrado
  de 32px com raio 8, fundo `sidebar-primary` e as iniciais (12/500) em `sidebar-primary-foreground`
  (o logo da empresa, quando ela tem um); ao lado, o **nome** (14/500) e, abaixo, o **CNPJ** (12, na
  mesma cor, como no `TeamSwitcher`: em `muted-foreground`, sobre o fundo do botão aberto, o escuro
  fica abaixo de 4,5:1), os dois cortados com reticências; à direita, `chevrons-up-down`. O quadrado
  distingue a empresa da pessoa, que tem avatar redondo (2.19).
- **Três modos**, pelo que a pessoa alcança:

| Modo | Quem | Como é |
|---|---|---|
| **Uma empresa só** | trabalha numa empresa | o mesmo bloco, **sem a seta e sem menu**. Não é botão: não há o que clicar |
| **Lista** | trabalha em duas ou mais | menu suspenso (2.14) ao lado do botão (embaixo, no celular): rótulo "Empresas", uma linha por empresa (quadrado de 24px com borda, nome) e a ativa marcada com `check` à direita |
| **Busca** | alcança todas as empresas (o Sysadmin) | popover com o campo "Buscar empresa" no topo (nome, razão social ou CNPJ), a lista que o servidor devolve (nome e CNPJ), a ativa marcada, e **"Ver todas as empresas"** no fim, fora da lista, que abre a tela de empresas |

- **Por que a busca é popover, e não menu:** campo de texto dentro de menu do Base UI não recebe o que
  se digita (o menu usa as teclas para pular até o item pela primeira letra). Então o modo busca é um
  `Popover` com o `Command` dentro, ancorado no mesmo botão, como o seletor múltiplo (2.22).
- **Busca no servidor:** espera 300ms depois de parar de digitar (3.5). Primeira carga com skeleton de
  3 linhas; enquanto a lista nova vem, a anterior fica e o Spinner aparece no rótulo "Empresas"
  (2.11). Sem resultado: "Nenhuma empresa encontrada". Erro: o estado vazio de erro com "Tentar de
  novo" (2.12). A consulta só roda com o popover aberto.
- **Sidebar recolhida:** só o avatar da empresa (o botão encolhe para 32px, como no shadcn), com
  tooltip com o nome; o botão tem nome acessível ("Trocar de empresa: Empresa Exemplo"). A linha
  continua com 48px, para o topo não mudar de altura (2.15).
- **Trocar de empresa:** o menu fecha e o botão mostra o Spinner no lugar da seta até o servidor
  confirmar. Depois, **a tela remonta limpa**: a mesma tela, sem filtro, busca, página nem linha
  aberta (3.5, 3.6); num detalhe, volta para a lista, porque o item era da outra empresa. Um toast
  avisa: **"Você está em Lumen Engenharia"** (2.7). Se falhar, toast de erro e a empresa não muda.
  Escolher a empresa que já está ativa só fecha o menu.
- **Fora da empresa principal** *(decisão do usuário, 2026-10-30)*: quem alcança todas as empresas (o
  modo busca) tem uma **empresa principal**, a casa do produto (nos sistemas da IDeia, a Rede Ideia).
  Enquanto está em qualquer outra, uma **faixa fixa** acima do header diz onde a pessoa está e dá o
  caminho de volta. É a mesma faixa do "Ver como" (2.16), com outro ícone e outro botão:

```text
+------------+------------------------------------------------------------------+
| [Logo]     | Você está em Lumen Engenharia      [Voltar para Empresa Exemplo] |  faixa, 40px
| [LE] Lumen⇕+------------------------------------------------------------------+
|            | [≡] | Grupo › Tela atual                                  [sino] |  header
|            |  +------------------------------------------------------------+  |
|            |  | box                                                        |  |
+------------+------------------------------------------------------------------+
```

- A faixa tem 40px, fundo `warning` a 12% sobre o `background`, texto em `warning-strong`, borda de
  baixo em `warning` a 30%, o ícone `building-2` (o mesmo do seletor), a frase "Você está em **Lumen
  Engenharia**" e, à direita, **"Voltar para Empresa Exemplo"** (`outline` `sm`, ícone `arrow-left`,
  com o nome da empresa principal; no celular, só o ícone, com tooltip). Sem "×": a faixa só sai
  quando a pessoa volta, pelo botão ou pelo seletor. `role="status"`.
- **O botão é uma troca de empresa como outra qualquer:** o Spinner no lugar do ícone até o servidor
  confirmar, a tela remonta limpa e o toast avisa. A faixa é do shell, não da tela: não remonta, some
  porque a condição deixou de valer.
- Fica na largura da coluna de conteúdo, acima do header e do segundo menu (2.27); as telas de altura
  cheia descontam os 40px (3.3). Com o "Ver como" ligado ao mesmo tempo, uma faixa embaixo da outra,
  a do "Ver como" primeiro.
- **Não aparece** para quem troca entre as próprias empresas (modo lista): são todas dela, e o seletor
  já diz qual está ativa. Nem na área de administração (2.30), que vale para todas as empresas.
- **Teclado:** Enter, espaço ou seta para baixo abrem; no menu, setas, Home e End; no modo busca, o
  foco vai para o campo e as setas andam pela lista; Enter escolhe; Esc fecha e devolve o foco ao
  botão.
- **Na área de administração** (2.30), o seletor dá lugar ao bloco fixo "Administração · Todas as
  empresas", com a mesma altura: a área vale para todas as empresas.
- Nunca: o seletor no header ou no menu do usuário; o nome do produto ao lado do logo ou no lugar do
  CNPJ (o logo já diz qual é o produto); trocar de empresa sem remontar a tela; um menu sem busca para
  quem alcança todas as empresas; a faixa "Você está em …" para quem troca entre as próprias empresas,
  ou com "×".

## 2.26 Kanban

**Todo kanban de todo produto segue isto** *(decisão do usuário, 2026-10-26)*. O kanban é uma tela
de altura cheia (3.1): ocupa a janela, **a página não rola**, o quadro rola na horizontal e cada
coluna rola na vertical, com o cabeçalho da coluna parado.

```text
┌ header ──────────────────────────────────────────────────────────────────┐
├ card ────────────────────────────────────────────────────────────────────┤
│ [Buscar…] [Status ▾] [Produto ▾] [Pessoa ▾] [Filtros]     [+ Nova tarefa] │  barra (3.5)
│ [Só o que é meu] [Ocultar concluídas] [≡|▦] [Compacto]     [Ordenar ▾]    │
│ ┌ ● Entrada   11 ┐ ┌ ● Backlog   14 ┐ ┌ ● Refinamento  9 ┐ ┌ ● Em exe     │  cabeçalho parado
│ │ ┌────────────┐ │ │ ┌────────────┐ │ │ ┌──────────────┐ │ │ ┌──────      │
│ │ │ card       │ │ │ │ card       │ │ │ │ card         │ │ │ │ card       │  cada coluna rola
│ │ └────────────┘ │ │ └────────────┘ │ │ └──────────────┘ │ │ └──────      │
│ │       ⋮        │ │       ⋮        │ │        ⋮         │ │              │
│ └────────────────┘ └────────────────┘ └──────────────────┘ └              │
│ ◄━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━►                                 │  barra horizontal à vista
│ 72 tarefas                                                                │
├ rodapé ──────────────────────────────────────────────────────────────────┤
```

**Altura.** O card vai do header até o rodapé: altura = janela − header (64px; 48 com a sidebar
recolhida) − rodapé (40px) − respiros (os 24px abaixo do card; 16 no celular) − a faixa do "Ver
como" (40px, quando ligada, 2.16). Não se calcula na mão: quando a tela é de altura cheia, a coluna
de conteúdo do shell (2.15) passa a ter a altura da janela, e cada nível até a coluna (conteúdo,
card, quadro, coluna) cresce com `flex-1` e `min-h-0`. Janela muito baixa: a área tem no mínimo
560px, e só então a página rola.

**Quadro.**
- As colunas lado a lado, com 12px entre elas e **largura mínima de 288px** (`w-72`, a do
  DevTasks); quando todas cabem, dividem a largura.
- Rola na horizontal (`overflow-x-auto`) **com a barra à vista**: 10px, polegar arredondado no token
  `input` (3:1 contra o card), nas medidas do `ScrollBar` do shadcn. A coluna cortada na borda do
  card é o outro sinal de que há mais.
- Vai de borda a borda do card (sem os 16px laterais); a primeira coluna alinha com a barra de
  ferramentas.
- **Celular** *(decisão do usuário, 2026-10-26)*: cerca de 1,5 coluna à vista, quase 2. Cada coluna
  tem 60% da largura do quadro e a próxima aparece pela metade, para mostrar que rola; ao soltar, o
  quadro encaixa no começo de uma coluna. A altura segue a mesma regra.

**Coluna.**
- Fundo `muted`, raio 11 (o do card), 8px de respiro e 8px entre os cards.
- **Cabeçalho parado**, fora da rolagem: bolinha de 10px na cor do estado, nome (14/500) e contador
  (pílula 12/500 em `card`), que conta o que está no quadro depois dos filtros.
- **Lista com rolagem própria** (`overflow-y-auto` com `min-h-0`): só ela rola.
- **Coluna vazia:** caixa tracejada (borda `input`) com "Arraste tarefas para cá" (12,
  `muted-foreground`).
- Com um card em cima, pronto para soltar: anel de 2px em `ring` por dentro da coluna.

**Card da tarefa.** O `Card size="sm"` do shadcn (12px de respiro), de cima para baixo:
1. **Código** em mono (12, `muted-foreground`) e o "…" à direita (`ghost` `icon-sm`, com nome
   acessível "Ações de CHAT-0B2DE2" e tooltip).
2. **Título** (14/500) em **até 2 linhas**, cortado com reticências. É um botão: abre a tarefa.
3. **Badges** (2.5): tipo, produto e "Bloqueada", quando for o caso.
4. **Progresso** das subtarefas, quando há: o `Progress` do shadcn (4px) com "2/11" ao lado.
5. **Prazo:** badge com relógio, vencida em `danger`, até 7 dias em `warning`, depois em `success`;
   sem prazo, neutra. Concluída não mostra prazo.
6. **Responsável:** avatar de 24px e o nome, cortado; sem ninguém, "Sem responsável" em
   `muted-foreground`.
- Bloqueada: além do badge, borda esquerda de 3px em `danger`.

**Mover.**
- **Arrastar e soltar** entre colunas: o card arrastado fica a 40% de opacidade; ao soltar, a
  tarefa entra no topo da coluna nova e o toast avisa "Movida para Revisão", com **Desfazer**, que
  devolve a coluna e a posição (2.7). Perto da borda, o quadro e a coluna rolam sozinhos.
- **"Mover para ›" no "…" do card**, para quem usa teclado (e no celular): submenu com as outras
  colunas (2.14). Depois de mover, o quadro rola até o card e o foco volta ao "…" dele, na coluna
  nova.
- O servidor recusou: o card volta para onde estava e o toast de erro avisa.
- Reordenar dentro da coluna é opcional; quem faz usa `@dnd-kit` com o `KeyboardSensor`, como o
  DevTasks, e mantém o "Mover para".

**Modo compacto** ("Compacto", na barra de ferramentas): o card fica com código, título e
responsável (e "Bloqueada", quando for o caso), no mesmo `Card size="sm"`; cabem quase o dobro de
tarefas na coluna. Vive na URL, como os filtros.

**Barra de ferramentas** (3.5) *(decisão do usuário, 2026-10-26)*: à esquerda, a busca, até três
filtros, "Filtros", os chips de alternância, "Lista/Kanban" e "Compacto"; à direita, só "Ordenar" e
"Nova tarefa". No celular: a busca, "Filtros" e o "+"; o modo de exibição vai para o fim da folha
de "Filtros".

**Estados.**
- Primeira carga: as colunas com o cabeçalho e dois cards em Skeleton cada uma; o contador mostra
  "–" (2.11).
- Nada no quadro inteiro com os filtros: o estado vazio (2.12) no lugar do quadro, com "Limpar
  filtros". Coluna sem nada: a caixa "Arraste tarefas para cá".
- Erro ao carregar: o estado de erro no lugar do quadro, com "Tentar de novo".
- A contagem ("72 tarefas") fica numa linha no pé do card.
- A visão em lista ("Lista", na barra) é a tabela de dados (2.10), com paginação; nela a página
  volta a rolar.

Nunca: a página rolando junto com o quadro; o cabeçalho da coluna rolando com os cards; coluna com a
altura do conteúdo, esticando a página; a barra horizontal escondida; mover só arrastando.

## 2.27 Segundo menu

Quando um item do menu reúne várias **seções que são telas próprias**, cada uma com a sua listagem
ou o seu formulário, elas vão num segundo menu *(decisão do usuário, 2026-10-26)*. O caso típico
são as configurações da empresa: Tags, Campos personalizados, Respostas rápidas, SLA, API Keys,
Webhooks. Trocar de seção é trocar de tela, por isso não são abas (2.23).

```text
+------------+-------------------------------------------------------------+
| [Logo]     | [≡] | Configurações da empresa › Geral › Tags [?] [✨] [🔔] |
| [EE] Emp. ⇕+---------------+---------------------------------------------+
|            | ATENDIMENTO   |  +---------------------------------------+  |
| PLATAFORMA |  [Tags]       |  | Tags                     [+ Nova tag] |  |
|  Item      |   Campos      |  | As tags da empresa e quantos contatos |  |
| CONFIG.    |   Respostas   |  | [Buscar por nome]                     |  |
|  Filas     | REGRAS        |  | Tag ↑               Contatos          |  |
| [Geral]    |   SLA         |  | ● VIP               12               …|  |
|            | INTEGRAÇÕES   |  +---------------------------------------+  |
|            |   API Keys    |                                             |
|            |   Webhooks    |  rodapé                                     |
+------------+---------------+---------------------------------------------+
   sidebar     segundo menu     conteúdo
```

- **Onde:** abaixo do header, à esquerda do conteúdo, até o fim da janela. O header fica igual ao
  das outras telas *(decisão do usuário, 2026-10-26: o segundo menu começa abaixo do header)*. A
  coluna fica parada enquanto o conteúdo rola (`sticky`) e rola sozinha se as seções não couberem.
  O rodapé (2.21) fica na coluna do conteúdo, à direita dela.
- **Desenho:** 224px (`w-56`), fundo `muted`, borda à direita em `border`, padding 8. Itens de 32px
  (a altura padrão, 1.5), rótulo 14 e ícone de 16 opcional, raio 8. Com mais de 6 seções, elas
  entram em **grupos** com rótulo (12/500, `muted-foreground`), como os da sidebar.
- **A cor:** no escuro, o `muted` fica um tom mais claro que a sidebar (`#1f1f1f` ao lado de
  `#171717`), como pediu o usuário ("uma cor mais clara do que a navbar"). No claro, a sidebar já
  é branca e não há tom mais claro: o `muted` é o cinza leve que separa as duas colunas.
- **Ativo:** o item da sidebar (o "Geral") **continua ativo**, em `primary` cheia, em qualquer
  seção *(decisão do usuário, 2026-10-26)*. No segundo menu, a seção aberta fica **destacada de
  leve**: fundo `card`, contorno `edge` e texto 500, sem a primária, para ficar claro qual é o nível
  principal. Hover: fundo `card` a 50%.
- **Cada seção é uma tela:** URL própria (`/configuracoes/tags`; o item sem seção abre a primeira),
  e o breadcrumb ganha o terceiro nível, "Grupo › Item › Seção", com o item como link para a
  primeira seção (2.17). Voltar do navegador volta para a seção anterior; recarregar mantém a seção.
- **Conteúdo da seção: a largura toda que sobra**, na listagem e no formulário *(decisão do usuário,
  2026-10-27: com o formulário até 720px sobrava um vazio à direita; a de Tags, na largura toda,
  ficou melhor)*. Listagem: card com a tabela e o "Novo…" no canto do card (2.1). Formulário: cards
  na mesma largura, campos em 2 colunas (3.4) e o "Salvar" no rodapé do último card. Dentro de uma
  seção, abas (2.23) só para visões da mesma coisa.
- **Abaixo de 1024px:** o segundo menu vira um **Select** "Seção" no topo do conteúdo, antes da
  primeira box, com os mesmos grupos; escolher navega para a seção.
- **Semântica e teclado:** `nav` com nome ("Seções de Geral") e links, com `aria-current="page"` na
  seção aberta. O Tab passa pelos links. Não é `tablist` nem tem setas.
- **Permissão:** seção sem permissão não aparece; grupo sem seção visível some com o rótulo, como
  no menu (3.2). O servidor revalida.
- Nunca: abas para trocar de seção; segundo menu dentro de um card ou com título próprio (o nome é o
  breadcrumb); mais de um nível no segundo menu; segundo menu com uma seção só; a primária no item
  ativo do segundo menu.

## 2.28 Passo a passo da tela e ajuda

Cada tela pode ter um **passo a passo**: o sistema escurece a página e destaca uma parte por vez (a
busca e os filtros, o "Novo…", uma coluna), com um cartão que diz o que se faz ali. Ele **começa por
convite**, nunca sozinho, e se revê pelo **botão de ajuda** do header *(decisões do usuário,
2026-10-26)*.

**O botão de ajuda.** Botão só de ícone no header (`circle-question-mark`, `ghost` `icon-sm`, a altura dos outros
botões do header, tooltip "Ajuda"), à direita, na ordem **? · ✨ · sino** (2.15). Abre um menu suspenso (2.14) alinhado à
direita:

1. **Passo a passo desta tela** (`route`). Na tela sem passo a passo, desabilitado, com "Esta tela
   não tem passo a passo" embaixo do rótulo (12, `muted-foreground`).
2. Só se o produto tiver, depois de um separador: **Central de ajuda** (`book-open`, abre em outra
   aba, com `external-link` à direita) e **Falar com o suporte** (`life-buoy`).

**O convite.** Na primeira vez que a pessoa abre uma tela com passo a passo, um cartão sai do "?":

```text
                                         [?] [✨] [🔔]
                            +-------------------------+
                            | Conheça esta tela       |
                            | Um passo a passo de 4   |
                            | passos pelo que dá para |
                            | fazer aqui.             |
                            |  [Agora não]  [Começar] |
                            +-------------------------+
```

- **Quando:** depois que a tela carrega (sem skeleton), sem modal nem outro flutuante aberto, e só
  se sobrarem pelo menos 2 passos visíveis nesta largura de tela.
- **Desenho:** o `PopoverContent` do shadcn como vem (288px, fundo `popover`, contorno, sombra
  média, raio 8; 1.5), ancorado no "?": título "Conheça esta tela" (14/500), uma frase com o número
  de passos (14, `muted-foreground`) e, à direita, "Agora não" (`ghost` `sm`) e "Começar" (padrão
  `sm`).
- **Não rouba o foco:** quem está digitando continua digitando. Ele é anunciado (`aria-live`
  educado) e, no HTML, vem logo depois do "?", então o Tab chega nele.
- **Fecha** com "Agora não", com Esc ou ao clicar fora, e qualquer um deles vale como "Agora não":
  **um convite só por tela**, que não volta. O passo a passo continua no "?". O "?" não ganha ponto
  nem contador.
- **Guardado por pessoa, no servidor** (não no navegador, para não repetir em outro computador): por
  tela e versão do passo a passo, `convidado`, `visto` ou `concluído`. Quando a tela muda a ponto de
  o passo a passo mudar, sobe a versão e o convite volta uma vez.

**O passo a passo.**

```text
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   ← véu preto a 50%
 ░░ +------------------------------------------+ ░░
 ░░ | [Buscar] [Status ▾] [Responsável ▾]       | ░░   ← a parte destacada, sem véu
 ░░ +------------------------------------------+ ░░
 ░░     +-------------------------------------+   ░░
 ░░     | Filtros                      2 de 4 |   ░░
 ░░     | Escolha o que aparece na lista: o   |   ░░
 ░░     | status e quem é o responsável.      |   ░░
 ░░     | [Pular]           [Voltar] [Próximo]|   ░░
 ░░     +-------------------------------------+   ░░
```

- **De 3 a 5 passos**, cada um numa parte que a pessoa vai usar: a busca e os filtros, o "Novo…",
  uma coluna que pede explicação, o "…" das ações. Nada do shell (menu, header, sino): o passo a
  passo é da tela. **O último passo destaca o "?"**: "Para rever este passo a passo, é aqui.", com
  "Concluir".
- **Véu** preto a 50% nos dois temas, sem desfoque, com o recorte na parte destacada (o raio dela e
  4px de folga). A parte destacada não responde a clique enquanto o passo a passo está aberto; clicar
  no véu vale como "Pular".
- **Cartão:** o mesmo `PopoverContent` do convite. Em cima, o título (14/500, até 3 palavras: o nome
  da parte) e, à direita, "2 de 4" (12, `muted-foreground`); a frase (14, `muted-foreground`, até
  120 caracteres, com verbo: o que se faz ali); embaixo, **"Pular"** (`ghost` `sm`) à esquerda e,
  à direita, "Voltar" (`outline` `sm`, não aparece no primeiro passo) e "Próximo" (padrão `sm`; no
  último, "Concluir", e o "Pular" sai).
- **Posição:** abaixo ou acima da parte destacada, onde couber; a página rola até ela, sem animação
  para quem pede movimento reduzido (1.7). Passo cuja parte não está na tela (escondida no celular,
  sem permissão, lista vazia) é pulado. No celular, o cartão tem a largura da tela menos 32px.
- **Teclado:** o cartão é um `dialog` com `aria-labelledby` e `aria-describedby`; o foco vai para
  "Próximo" e fica preso no cartão; ← e → trocam de passo; Esc é "Pular". Ao sair, o foco volta
  para onde estava antes de começar.
- **Começar de novo:** pelo "?" › "Passo a passo desta tela", ou pela sugestão do assistente (2.29),
  sempre do primeiro passo.
- **Texto** em i18n, nos três idiomas (3.14). Cada passo se prende à tela por um atributo
  (`data-tour="filtros"`), nunca por classe CSS.
- **Biblioteca:** **driver.js** (MIT, sem dependências; serve em React, Next e nos projetos em
  Tailwind 3). O shadcn não tem passo a passo, e Shepherd e Intro.js são AGPL. O cartão recebe as
  classes do `PopoverContent` e os botões as do `Button` (`buttonVariants`), para seguir o tema e as
  medidas sem valor à mão (exemplo na Parte 4).
- Nunca: começar sozinho; mais de um convite por tela, ou ponto e contador no "?"; mais de 5 passos;
  explicar o menu ou o header; cartão sem "Pular"; passo preso a classe CSS; o mesmo cartão fora do
  passo a passo (dica é tooltip, 2.8; aviso é alerta, 2.6).

## 2.29 Assistente de IA

Os produtos com IA têm um assistente interno: tira dúvidas sobre a tela, resume, busca e, quando o
produto permite, faz tarefas no sistema. Ele mora num **painel encaixado à direita**, nunca num
balão flutuante *(decisão do usuário, 2026-10-26)*: por cima, cobriria o fim da lista, o canto dos
toasts e, no atendimento, o botão de enviar, o mesmo problema que tirou o rodapé de cima do conteúdo.

```text
+------------+-------------------------------------+---------------------+
| [Logo]     | [≡] | Grupo › Tela    [?] [✨] [🔔] | ✨ Assistente [✎][×]|
| [EE] Emp. ⇕+-------------------------------------+---------------------+
|            |  +-------------------------------+  | Nesta tela:         |
| GRUPO      |  | box (encolhe; nada fica       |  | Contatos         [×]|
|  Item      |  | coberto)                      |  |                     |
|  Item      |  +-------------------------------+  | Pergunte sobre esta |
|            |  +-------------------------------+  | tela ou peça uma    |
|            |  | box                           |  | tarefa.             |
|            |  +-------------------------------+  | [Como importo…?   ] |
|            |                                     | [Quem está sem tag?]|
|            |                                     | [Fazer o passo a…  ]|
|            |                                     +---------------------+
|            |                                     | Pergunte ou peça…   |
|            |                                     |                [↑]  |
|            | rodapé                              | A IA pode errar…    |
+------------+-------------------------------------+---------------------+
```

**Abrir e fechar**
- O botão **✨** (`sparkles`, `ghost` `icon-sm`, a altura dos outros botões do header) fica no header, entre o "?" e o sino (2.15),
  com tooltip "Assistente" (ou o nome da IA do produto), `aria-expanded` e `aria-controls`. Abre e
  fecha o painel; o "×" do painel e o Esc (com o foco dentro dele) também fecham, e o foco volta ao
  ✨. Ao abrir, o foco vai para o campo de mensagem. Só no clique: nunca abre sozinho, no hover ou
  arrastando.
- Só existe nos produtos com IA. Aberto ou fechado fica guardado por pessoa; a conversa **continua
  ao trocar de tela**, porque o painel é do shell, não da tela.

**O painel**
- À direita, **384px** (`w-96`), do topo ao fim da janela, fundo `sidebar` e borda à esquerda, como
  o painel da direita (2.15), cujo lugar ele usa: aberto, toma o lugar do painel da tela (os dados
  do contato, no atendimento), que volta quando ele fecha. **O conteúdo encolhe**, como com a
  sidebar: nada fica coberto.
- **Sem espaço**, abaixo de 1024px ou quando a coluna de conteúdo ficaria com menos de 640px (com o
  segundo menu, 2.27, por exemplo), ele abre por cima, como **folha da direita** com véu; fecha com
  o "×", com Esc ou tocando fora. No celular, a folha ocupa a tela toda.
- **Cabeçalho** (64px, com a borda de baixo na linha do header): ✨ e o nome (14/500) à esquerda;
  à direita, **Nova conversa** (`square-pen`) e **Fechar** (`x`), botões só de ícone `ghost` `sm`
  com tooltip. Produto que guarda o histórico põe **Conversas anteriores** (`history`) antes deles.
- **Contexto:** logo abaixo, "Nesta tela: **Contatos**" (12, `muted-foreground`), com o registro
  aberto quando há ("Atendimento #1234"). O assistente usa a tela e o registro como contexto; o
  "×" da linha tira o contexto desta conversa.

**A conversa** (componentes `message-scroller`, `message` e `bubble` do shadcn)
- **Sem conversa:** uma frase do que ele faz ("Pergunte sobre esta tela ou peça uma tarefa.") e de 2
  a 4 **sugestões da tela**, botões `outline` `sm`, um por linha, com texto de uma linha. Se a tela
  tem passo a passo (2.28), uma delas é "Fazer o passo a passo desta tela".
- **Mensagem da pessoa:** balão à direita, `Message align="end"` com `Bubble variant="muted"`, até 80%
  da largura (o `Bubble` como vem).
- **Resposta:** sem balão (`Bubble variant="ghost"`), na largura toda, 14/20, com Markdown seguro (negrito, listas, links em
  `text-link`, código em `font-mono`); nunca HTML vindo do modelo. Embaixo, **Copiar** (`copy`),
  **Útil** (`thumbs-up`) e **Não útil** (`thumbs-down`), botões só de ícone `ghost` `icon-xs`, com
  tooltip; o escolhido fica marcado (`aria-pressed`).
- **Enquanto responde:** "Pensando…" com o efeito `shimmer` do shadcn (parado para quem pede
  movimento reduzido), depois o texto chegando. O botão de enviar vira **Parar** (`square`). A
  lista acompanha a resposta enquanto a pessoa está no fim; se ela rolar para cima, para de
  acompanhar e aparece o botão de ir ao fim (`MessageScrollerButton`).
- **Erro:** dentro da conversa, logo abaixo da pergunta, `Bubble variant="destructive"` com "Não
  consegui responder agora." e **Tentar de novo** (`outline` `sm`). Nunca toast.

**Ações no sistema** (padrão Confirmation do shadcn)
- Tudo o que o assistente for **mudar** (criar, editar, enviar, encerrar, excluir) aparece antes
  como um cartão na conversa: `Item variant="outline" size="sm"`, o ícone da ação, a pergunta
  ("Criar a tag **VIP**?"), o que muda numa frase e, à direita, **Cancelar** (`outline` `sm`) e
  **Confirmar** (padrão `sm`). Ação destrutiva: o botão `destructive` e a consequência na frase
  (3.10).
- Depois da escolha, o cartão vira uma linha com o resultado ("Tag VIP criada.", com **Ver** quando
  há registro, ou "Cancelado."). Ler, buscar e resumir não pedem confirmação.
- **Permissões:** o assistente só vê e faz o que a pessoa pode; o servidor revalida, como em toda
  ação. No "Ver como" (2.16) ele é a pessoa escolhida, e a auditoria registra quem fez ("Marcos
  Silva, vendo como Ana Ribeiro, pelo assistente").

**O campo de mensagem** (padrão Prompt Input do shadcn)
- `InputGroup` com `InputGroupTextarea` e, embaixo (`InputGroupAddon align="block-end"`), o botão de
  enviar à direita: `InputGroupButton` só de ícone (`arrow-up`, `aria-label` "Enviar"), desabilitado
  com o campo vazio. Anexo (`paperclip`) só se o produto aceitar.
- Placeholder "Pergunte ou peça algo…"; cresce de 1 a 6 linhas e depois rola. **Enter envia,
  Shift+Enter quebra a linha.**
- Embaixo, "A IA pode errar. Confira o que for importante." (12, `muted-foreground`, centralizado).

**Quando não resolve:** o assistente oferece **Falar com o suporte**, o mesmo destino da Ajuda
(2.28), levando a tela e a conversa.

- Responde no idioma da interface; os textos fixos do painel e as sugestões vêm do i18n (3.14).
- Nunca: balão flutuante ou janela por cima do conteúdo no desktop; abrir sozinho; mudar algo sem
  a confirmação; HTML da resposta inserido na página; um assistente montado dentro da tela.

## 2.30 Área de administração

O que é da IDeia, e não de uma empresa cliente, mora na área de administração *(decisão do usuário,
2026-10-27)*:
- as empresas que usam o sistema;
- os produtos, com logo e cores;
- as pessoas, com os seus papéis.

Só o Sysadmin entra. A área se distingue do resto do sistema pela cor da sidebar, e a identidade do
produto não muda.

```text
+--------------+-----------------------------------------------------+
| [Logo]       | [≡] | Administração › Empresas       [?] [✨] [🔔]  |
| [🛡] Adminis- +-----------------------------------------------------+
|     tração   |  +-----------------------------------------------+  |
|  Todas as e. |  | [Buscar empresa] [Status ▾]   [+ Nova empresa] |  |
| CADASTROS    |  | Empresa            CNPJ          Produtos      |  |
| [Empresas]   |  | [EE] Empresa Ex.   12.345.678/…  [◼] [◼]       |  |
|  Produtos    |  +-----------------------------------------------+  |
| ACESSO       |                                                     |
|  Usuários    |                                                     |
|--------------|                                                     |
| ↶ Sair da a. |                                                     |
| [MS] Marcos ⇕|  rodapé                                             |
+--------------+-----------------------------------------------------+
  a sidebar no tom suave da primária; o resto do shell não muda
```

- **Quem entra:** só quem está como **Sysadmin** (2.16).
  - Com outro papel, ou no "Ver como", a entrada não aparece.
  - A URL da área leva ao início, sem dizer que a área existe.
  - O servidor revalida em toda chamada: quem não é Sysadmin recebe 404.
- **A entrada:** um item fixo no **pé da sidebar, acima do menu do usuário** *(decisão do usuário,
  2026-10-27)*, com o ícone `shield` e o texto "Administração".
  - É um item como os do menu, separado dos grupos pela borda de cima do rodapé.
  - Fica à vista em qualquer tela, longe dos itens do dia a dia e perto de quem a pessoa é.
  - Na sidebar recolhida, só o ícone, com tooltip.
- **A cor:** a sidebar inteira (fundo, hover e bordas) ganha **um tom suave da primária do produto**
  *(decisão do usuário, 2026-10-27: mudar a cor sem mudar a identidade)*. Os tokens:

  | Token | Claro | Escuro |
  |---|---|---|
  | `sidebar-admin` (fundo) | primária a 8% sobre a `sidebar` | 14% |
  | `sidebar-admin-accent` (hover) | 14% | 22% |
  | `sidebar-admin-border` | primária a 20% sobre a `border` | 30% |

  - O item ativo continua na `primary` cheia, e o logo é o do produto: muda o tom, não a marca.
  - O header, o conteúdo e o rodapé não mudam.
  - O build confere o contraste em todo produto: texto 4,5:1 e item ativo 3:1.
- **O topo:** o logo continua. No lugar da troca de empresa (2.25) fica o bloco fixo
  **"Administração · Todas as empresas"**, com um quadrado de 32px em `primary` e o ícone `shield`.
  Não é botão, porque a área vale para todas as empresas.
- **O menu:** só os itens da administração, em grupos como os do sistema (3.2): **Cadastros**
  (Empresas, Produtos) e **Acesso** (Usuários). Nenhum item do sistema da empresa aparece aqui.
- **A saída:** dentro da área, a entrada vira **"Sair da administração"** (`undo-2`). Ela volta para a
  tela em que a pessoa estava antes de entrar; sem tela anterior, para o início.
- **URL e breadcrumb:**
  - Cada tela tem URL própria: `/admin/empresas`, `/admin/produtos/ideia-vault`.
  - O breadcrumb é "Administração › Empresas".
  - No detalhe, "Administração › Produtos › Ideia Vault", com o item como link (2.17).
- **As telas** usam os mesmos tipos de tela do sistema (3.1): listagem com o "Novo…" no canto do card
  e formulário em cards.
  - **Empresas:** listagem; criar e editar em modal.
  - **Produtos:** listagem com o logo e as cores, primária e secundária, em amostras com o hex. Aqui
    a cor é dado, como a cor de uma tag. O cadastro é uma tela de formulário com identificação,
    logos para o tema claro e o escuro, e cores com prévia e aviso de contraste.
  - **Usuários:** listagem com os papéis e "Editar papéis" em modal. Ninguém tira o próprio papel de
    Sysadmin.
- **Celular:** a sidebar vira gaveta, também no tom da área.
- **No código:** o layout da área marca `data-area="admin"`.
  - O globals.css de cada produto (get_tokens) já traz os `--sidebar-admin*` e a regra
    `:root:has([data-area="admin"])`, que troca `--sidebar`, `--sidebar-accent` e `--sidebar-border`.
  - A Sidebar do shadcn não muda, e a gaveta do celular, que abre fora do layout, também pega o tom.
- **Nunca:**
  - outra cor para marcar a área, como vermelho, amarelo de alerta ou o cinza de outro produto;
  - a entrada no meio dos grupos do menu;
  - itens do sistema da empresa dentro da área;
  - a entrada à vista para quem não está como Sysadmin;
  - o seletor de empresa dentro da área.

---

# Parte 3 — Pattern Library

## 3.1 Tipos de tela

| Tipo | Estrutura |
|---|---|
| **Lista** (a maioria) | card com a tabela de dados, com o "Novo…" no canto superior direito do card; criar e editar em modal. Lista que depende de uma escolha (a pessoa, a fila): listagem em duas etapas (3.18) |
| **Dashboard** | grade de KPIs › cards com gráficos. **Sem filtro nem período** *(decisão do usuário, 2026-10-26)*: o recorte é fixo e vai na descrição de cada card ("Últimos 30 dias", "Agora"); KPI compara com o recorte anterior do mesmo tamanho. Dashboard com filtro é relatório |
| **Relatório** | um card de relatório (2.24) por assunto: abas, filtros e conteúdo dentro do card |
| **Detalhe** | cards por assunto (dados, histórico, anexos), com as ações do registro (Editar, "…") no cabeçalho do primeiro card; ou painel da direita quando a lista fica à vista |
| **Altura cheia** (atendimento, chat, kanban) | a área vai do header até o rodapé, com a altura da janela: **a página não rola**, só as partes dela (no kanban, o quadro na horizontal e cada coluna na vertical, 2.26). Altura = janela − header − rodapé − respiros (− as faixas do "Ver como" e da empresa, quando ligadas: 2.16 e 2.25); mínimo de 560px, abaixo disso a página rola |
| **Configuração** | cards por grupo de opções; switch para o que salva sozinho, formulário com "Salvar" para o resto. **Sem listagem nem tabela** (Perfil, Geral): **centralizada, até 720px** (`mx-auto w-full max-w-180`); com tabela, a largura toda, para a tabela não ficar apertada *(decisão do usuário, 2026-10-26)*. **Com várias seções que são telas próprias** (Tags, Campos personalizados, SLA, Webhooks): segundo menu (2.27), cada seção com a sua URL, **na largura toda que sobra, também as de formulário**; nunca abas *(decisões do usuário, 2026-10-26 e 2026-10-27)* |
| **Login e recuperação** | fora do shell, duas colunas: painel da marca e formulário (2.20) |

Em todas dentro do shell, o conteúdo começa logo abaixo do header, na primeira box, sem barra de
ações (3.3).

## 3.2 Navegação e menu

- Cada item do menu é uma tela. Os itens entram em **grupos** pelo que são (o que se usa no dia a
  dia; o que a empresa configura; o que só a administração alcança), não pela permissão.
- Item só aparece para quem tem permissão; grupo sem item visível some com o rótulo. A visibilidade
  é dado do menu, não condição espalhada pela tela, e o servidor revalida toda permissão.
- **O menu é o do papel ativo.** Quem tem mais de um papel troca no menu do usuário (2.16), e o menu,
  as telas e as permissões passam a ser os do papel novo.
- **O que é da IDeia, e não da empresa cliente** (as empresas, os produtos, os papéis das pessoas),
  não entra nos grupos do menu. Fica na **área de administração** (2.30), com entrada fixa no pé da
  sidebar e só para quem está como Sysadmin.
- Item ativo pela rota atual. Contadores (não lidos, pendências) na pílula do item.
- **Topo da sidebar em duas linhas:** o logo do produto, que leva ao início, e logo abaixo o seletor
  da empresa ativa (componente Troca de empresa) *(decisão do usuário, 2026-10-26)*. O logo diz
  qual é o produto; o seletor diz em que empresa a pessoa está. O menu e as permissões são os da
  empresa ativa.
- **Trocar de empresa remonta a tela limpa:** a mesma tela, sem filtro, busca, página nem linha
  aberta; num detalhe, volta para a lista. Um toast avisa "Você está em …". Quem alcança todas as
  empresas e saiu da principal vê a faixa "Você está em …" acima do header, com o botão de voltar
  (2.25).
- Item com subitens abre em sanfona dentro do grupo, um nível só. Item cujas seções são telas
  próprias de uma mesma área (as configurações: Tags, Campos, SLA, Webhooks) não usa subitens: abre
  o **segundo menu** (2.27), e o item fica ativo em qualquer seção.
- Nada do usuário (perfil, preferências, idioma, tema, sair) no menu principal: tudo no menu do
  usuário.
- A tela não tem título: o breadcrumb é o nome dela. Tela nova = um item no menu + o nome no
  breadcrumb.

## 3.3 Topo do conteúdo

**Não existe barra de ações** *(decisão do usuário, 2026-10-26)*. O topo da tela é o header e, logo
abaixo, a primeira box. O que ficava entre os dois passou para dentro do card a que pertence.

- **Header:** só recolher, breadcrumb, indicadores de estado, ajuda (?), assistente (✨) e sino (2.15).
  Nenhuma ação da tela.
- **Primeira box logo abaixo do header**, sem título de tela nem frase solta: o nome da tela é o
  breadcrumb, e o que explica o conteúdo vai na descrição da box.

| O que ficava na barra de ações | Onde fica agora |
|---|---|
| "Novo…" | no card da lista que ele alimenta, no canto superior direito, na altura padrão, como o resto da barra (2.1) |
| "Atualizar" e "Atualizado às" | não existem: os dados se atualizam sozinhos (3.8) |
| visão e período de um relatório | nas abas e na linha de filtros do card de relatório (2.24) |
| período de um dashboard | não existe: dashboard mostra um recorte fixo, dito em cada card (3.1) |
| a escolha de que a tela depende (a pessoa, a fila) | na primeira etapa da listagem em duas etapas (3.18) |
| "Salvar" de formulário em tela própria | no rodapé do último card (3.4) |
| ações de um registro (Editar, "…") | no cabeçalho do card do detalhe, à direita |

- Ação que depende de permissão entra só com ela; sem permissão, o card fica sem o botão.
- Ação que parece valer para a tela inteira pertence a algum card. Se não pertence a nenhum, falta
  o card.

## 3.4 Formulários

- **Criar e editar são o mesmo formulário**, com os campos preenchidos na edição.
- **Em modal, por padrão, até 8 campos** (recomendação, não limite). Formulário maior pode ser tela
  própria, com os cards por grupo de campos e "Cancelar" e "Salvar" no rodapé do último card (não
  há barra de ações, 3.3).
- Layout: 2 colunas no desktop, 1 no celular; campo longo (observações, endereço) ocupa a linha.
  Rótulo acima do campo. 20px entre campos (o `FieldGroup` do shadcn).
- Ordem dos campos: do mais importante ao menos; o que identifica (nome) primeiro; o opcional por
  último.
- **Validação:** no envio, e a partir daí a cada mudança do campo que falhou. Erro embaixo do campo,
  com o que fazer. O foco vai ao primeiro campo com erro.
- **Recusa do servidor:** alerta `danger` acima do rodapé, uma frase, sem fechar o modal.
- **Rodapé:** "Cancelar" (`ghost`) e "Salvar" (`primary`), à direita. Salvando: botão desabilitado
  com Spinner. Sucesso: fecha e mostra toast ("Fila criada").
- Fechar com alteração não salva pergunta antes ("Descartar alterações?").
- Formato de data, número e moeda segue o idioma do usuário (3.14).
- Nunca campos sem rótulo, formulário sem feedback de erro, ou "Salvar" sem estado de carregamento.

## 3.5 Filtros: escopo, modo de exibição e filtro do conjunto

Cada filtro tem um nível, e cada nível tem um lugar *(decisão do usuário, 2026-10-22; a validar com
os analistas na página de testes)*.

| Nível | O que é | Onde fica | Exemplos |
|---|---|---|---|
| **Escopo do card** | muda do que o card trata | topo do próprio card: abas e, logo abaixo, a linha de filtros (2.24); ou a primeira etapa da listagem em duas etapas (3.18) | as visões de um relatório (Produtos, Pessoas, Equipe); o período e o produto do relatório; a pessoa cujo acesso se edita |
| **Modo de exibição** | muda como o mesmo conjunto aparece | barra de ferramentas da box, lado direito; no kanban, só Ordenar fica à direita (barra do kanban, abaixo) | Lista ou Kanban; Ordenar; Compacto; Colunas |
| **Filtro do conjunto** | reduz o que a box mostra | barra de ferramentas da box, lado esquerdo | busca; Status; Produto; Pessoa; "Só o que é meu" |

**Escopo dentro do card, não numa barra da tela** *(decisão do usuário, 2026-10-26)*. Não há barra
de ações (3.3). Num relatório, as visões são abas (2.23) no topo do card, e o período e os filtros
que mudam o recorte ficam logo abaixo delas (2.24). Tela que depende de uma escolha (a pessoa, a
fila) começa listando as opções: é a listagem em duas etapas (3.18). Nada de título na tela nem frase
explicativa no header: isso vai para a descrição da box. **Dashboard não tem filtro nem período**
(3.1): quem precisa filtrar abre um relatório.

**Barra de ferramentas da box, em até duas linhas.**
1. Primeira linha: a busca e **no máximo três filtros à vista**, os mais usados daquela tela. Os
   outros ficam no botão "Filtros", no fim da linha. Card sem título: o "Novo…" fecha a linha, no
   canto superior direito (2.1).
2. Segunda linha, só quando existe: à esquerda os chips de alternância, no máximo três; à direita o
   modo de exibição (Ordenar, Lista ou Kanban, Compacto, Colunas).
3. Linha de chips removíveis: só aparece quando há filtro ativo que não está à vista, com
   "Limpar (n)" no fim.
4. A contagem ("23 tickets") vai para o rodapé da tabela ou para a descrição da box, nunca para o
   título.

**Barra do kanban** (2.26) *(decisão do usuário, 2026-10-26)*: à esquerda, a busca, até três
filtros, "Filtros", os chips de alternância, "Lista/Kanban" e "Compacto"; à direita, só "Ordenar" e
"Nova tarefa". Na primeira linha, "Filtros" vem logo depois dos filtros à vista e "Nova tarefa"
fecha a linha; na segunda, "Lista/Kanban" e "Compacto" vêm depois dos chips, e "Ordenar" fica
sozinho à direita. Vale também para a visão em lista da mesma tela, que usa a mesma barra.

**Comportamento.**
- Filtro, busca, ordenação, aba e período **vivem na URL**: sobrevivem a recarregar a página, dão
  para compartilhar e voltam no histórico do navegador. Trocar de empresa zera tudo.
- Aplica ao mudar. O que vai ao servidor espera 300ms. Enquanto recarrega, os dados ficam e o
  Spinner aparece na barra (2.11).
- Filtro ativo sempre pode ser visto e removido sem abrir o painel: pelo gatilho, pela linha de
  chips ou por "Limpar".
- Padrão da tela ("Só o que é meu" ligado para quem atende) não é filtro escondido: aparece ligado
  no chip.
- **Celular:** a barra de ferramentas recolhe para a busca e o botão "Filtros", que abre uma folha
  de baixo com todos os campos, inclusive os que estavam à vista e os chips de alternância; o modo
  de exibição vai para o fim da folha.
- Os controles estão no componente 2.22. Exemplo vivo do card de relatório e do kanban na página do
  guia, seção 3.5; o da listagem em duas etapas, na seção 3.18.

## 3.6 Tabelas e listas

- Toda listagem é tabela de dados (2.10): mesma barra de ferramentas, mesmo "…", mesmo rodapé.
- **Toda listagem tem o padrão completo** *(decisão do usuário, 2026-10-26)*: busca, colunas
  ordenáveis, paginação, "…" de ações e os estados (skeleton, vazio, erro).
- **Toda coluna de valor único é ordenável**, inclusive telefone, e-mail e código. Não ordenam a
  coluna de ações, a de seleção, coluna com vários valores na célula (etiquetas, avatares) e texto
  livre longo (descrição, observações).
- **Coluna cujo valor vem de um conjunto fechado** (Status, Setor, Origem, Prioridade, Tipo…) **vira
  filtro** na barra de ferramentas: escolha única até 5 valores; múltipla acima disso ou quando o
  normal é combinar valores, como Pessoa. Com mais de três, os excedentes vão para "Filtros" (3.5).
- Tela que depende de uma escolha (a pessoa, a fila) começa listando as opções: é a listagem em duas
  etapas (3.18).
- Cards no lugar de tabela só quando o item é visual (um modelo, um anúncio) e tem no máximo 4
  informações; a grade de cards segue os mesmos estados (skeleton, vazio, erro) e tem a mesma busca,
  ordem e filtros na barra.
- Busca, filtro e ordenação ficam na URL ou no estado da tela e sobrevivem a recarregar a página.
- Trocar de empresa ou de contexto remonta a tela limpa (busca, página e linha aberta zeradas).

## 3.7 Feedback: qual componente para cada situação

| Situação | Componente | Onde |
|---|---|---|
| Erro de um campo | mensagem do campo | abaixo do campo |
| Recusa do servidor num formulário | alerta `danger` | acima do rodapé do formulário |
| Erro de uma ação fora de formulário | alerta `danger` | no card da ação; se não há onde, toast de erro |
| Erro ao carregar uma lista | estado vazio com "Tentar de novo" | dentro da box |
| Deu certo, passageiro | toast `success` | canto inferior direito |
| Deu certo, precisa ficar | alerta `success` | no card |
| Consequência que a pessoa precisa saber | alerta `warning` | onde a ação acontece |
| Contexto neutro | alerta `info` | no topo do card |
| Condição que vale enquanto dura | indicador de estado (neutro, `role="status"`) | junto do que descreve |
| Processo longo | Spinner com texto curto ("Enviando 3 de 10") | no lugar da ação |
| Notificação do sistema | o sino (3.11) e, se acabou de chegar, toast do tipo dela com "Ver" | header |
| Dado novo no servidor | nada: a tela relê sozinha, sem Spinner e sem mudar de lugar (3.8) | — |

## 3.8 Carregamento

- Primeira carga de qualquer coisa: Skeleton no formato. Recarga porque a pessoa mudou o que pediu
  (busca, filtro, ordenação, aba): Spinner, dados mantidos. Releitura em segundo plano: nada.
- **Os dados se atualizam sozinhos** *(decisão do usuário, 2026-10-26)*: por tempo real quando o
  servidor avisa, ou relendo ao voltar o foco da janela e em intervalo (o `refetchOnWindowFocus` e
  o `refetchInterval` do TanStack Query). Sem Skeleton, sem Spinner e **sem mudar a página de
  lugar**: rolagem, foco, linha aberta e página da tabela ficam onde estão.
- **Não existe botão "Atualizar"** em nenhuma tela, nem o "Atualizado às". "Tentar de novo"
  continua nos estados de erro (2.12), porque é outra coisa: a leitura falhou.
- Releitura em segundo plano que falha não avisa nada: os dados ficam e a próxima tenta de novo.
- Botão que dispara chamada: desabilitado com Spinner até a resposta.
- Nenhuma tela sem estado de carregamento quando há chamada ao servidor.

## 3.9 Estados vazios e de erro

Sempre dentro da box, no formato do 2.12. Primeiro uso convida a agir; filtro sem resultado oferece
limpar; erro oferece tentar de novo. Nunca a box some: o estado toma o lugar do conteúdo.

## 3.10 Ações destrutivas

- Excluir, desativar, encerrar, remover acesso: item por último no "…", depois do separador, em
  `danger`.
- Confirmação em diálogo (2.13): pergunta no título, consequência em uma frase, botão `danger` com
  o verbo e o objeto ("Excluir fila"). O botão principal de uma confirmação destrutiva nunca é o
  foco inicial.
- O que dá para desfazer não confirma: faz e oferece "Desfazer" no toast por 6 segundos.
- Depois: toast de sucesso, a lista atualiza, o foco volta a um lugar razoável (a linha seguinte ou
  a barra de ferramentas).

## 3.11 Notificações (o sino)

- Botão só de ícone no header, com o contador de não lidas na pílula `primary`.
- Abre um popover de 360px (`w-90`; no celular, uma folha) com a lista: ícone do tipo (`success`,
  `info`, `warning`, `danger`), título de uma linha, hora relativa ("há 5 min"), e a ação "Ver"
  quando há destino. Não lida tem fundo `muted` leve. Vazio: "Nenhuma notificação."
- **Cabeçalho do popover:** o título "Notificações" à esquerda e, à direita, duas ações:
  **"Marcar todas como lidas"** (`ghost` `sm`, desabilitada quando não há não lidas) e o **botão de
  configurações** (`settings`, `ghost` `icon-sm`, tooltip "Configurar notificações"). Ele fecha o
  popover e abre o modal de preferências; ao fechar o modal, o foco volta ao sino.
- A que acabou de chegar também aparece como toast do tipo dela, com "Ver".

**Preferências de notificação.** São **de cada pessoa, não da empresa**, e o modal do sino cuida
**só das notificações do app** *(decisão do usuário, 2026-10-26)*:

```text
Preferências de notificação                                          [×]
São suas: valem só para você, em qualquer dispositivo.

Como avisar
  No sino                     a lista, o contador e o aviso na tela   [■ ]
  Som                         um toque curto quando chega             [■ ]
  Notificação do navegador    aparece com a aba em segundo plano      [ □]
Avisar sobre
  Novas conversas · Tarefas atribuídas a mim · Menções                [■ ]
Notificações por e-mail ficam no seu perfil.
------------------------------------------------------------------ [Fechar]
```

- Modal padrão (384px, 2.13) em dois grupos com legenda: os **canais** (no sino, som, notificação
  do navegador) e os **tipos de aviso** (novas conversas, tarefas atribuídas a mim, menções). Cada
  linha tem rótulo, uma frase de descrição e um **switch que salva na hora** (2.4), com o toast
  "Preferência salva"; se falhar, o switch volta e o toast é de erro.
- O tipo decide se a notificação existe; o canal, onde ela aparece. Desligar "No sino" tira a lista
  e o toast; o som e o navegador seguem os switches deles.
- **Notificação do navegador:** ligar o switch pede a permissão do navegador, e o pedido sai do
  próprio clique (o navegador recusa o pedido que não nasce de um gesto). Recusada ou bloqueada, o
  switch fica desligado e desabilitado, com um alerta `warning` dizendo como liberar nas
  configurações do navegador. Sem suporte, o switch fica desabilitado e a descrição diz por quê.
- **Rodapé só com "Fechar"**: não há "Salvar", porque cada switch já salvou. Acima do rodapé, a
  linha "Notificações por e-mail ficam no **seu perfil**", com o link para o Perfil.
- **O e-mail fica só no Perfil**: um switch "Notificações por e-mail", ligado por padrão, e nada
  mais sobre notificação ali. O card "Notificações" de Configurações › Geral deixa de existir: era
  da empresa e passou a ser de cada pessoa.

## 3.12 Responsividade

- **Mobile-first.** Pontos de quebra da janela: 640, 768 e 1024px. Abaixo de 768 a sidebar vira
  gaveta; o painel da direita só existe a partir de 1024. O segundo menu (2.27) vira um Select
  abaixo de 1024; o assistente de IA (2.29) vira folha abaixo de 1024 ou quando o conteúdo ficaria
  com menos de 640px.
- **Dentro do shell, o componente mede o contêiner**, não a janela: a sidebar e o painel tiram
  512px da largura, e um arranjo pela janela fica errado. Grades, tabelas, paginação e barras mudam
  de arranjo pela largura do elemento em volta.
- A página nunca rola para o lado. Tabela que não cabe rola dentro do card; antes disso, esconde
  colunas secundárias.
- Modal ocupa a largura no celular; formulário longo vira folha de baixo.
- Toque: alvo mínimo de 24 × 24px (WCAG 2.5.8). Todo controle do shadcn cumpre (o menor, `xs`, tem
  24px; o checkbox tem área de clique maior que o desenho). Controle não cresce no celular: só o
  texto do campo passa a 16px, para o iPhone não ampliar a tela.

## 3.13 Tema

Ver 1.6. Resumo: os dois temas, escolha no menu do usuário, guardada por usuário, inicial claro
ou do sistema, sem cor fixa em tela nenhuma.

## 3.14 Internacionalização (i18n)

- **Todo sistema nasce preparado para três idiomas: pt-BR (padrão), en e es.** Nenhum texto fixo
  no código: rótulo, mensagem, placeholder, tooltip, título e texto de e-mail vêm de dicionário por
  idioma, com chave por contexto. Ícone e cor não substituem texto.
- A troca fica no **menu do usuário** (2.16), em sigla, e vale na hora, sem recarregar. A escolha é
  guardada por usuário; sem escolha, o idioma do navegador se for um dos três, senão pt-BR.
- Data, hora, número e moeda são formatados pela localidade escolhida: `22/10/2026` e `R$ 1.234,56`
  em pt-BR; `10/22/2026` e `R$1,234.56` em en; `22/10/2026` e `R$ 1.234,56` em es. A moeda é a do
  dado, não a do idioma.
- Texto cresce até 30% de um idioma para outro: nenhum rótulo com largura fixa, nenhum botão que
  corte texto. Plural e gênero vêm do dicionário, nunca de concatenação.
- Texto que vem do banco (nome de fila, mensagem de cliente) fica como está; só a interface traduz.

## 3.15 Acessibilidade

- Contraste mínimo (1.2). Foco visível em todo controle: a borda vira `ring` e ganha um anel de 3px
  em `ring` a 50%, colado ao controle (o foco do shadcn, sem edição).
- Tudo opera por teclado: Tab na ordem visual, Enter e Espaço ativam, Esc fecha, setas navegam em
  menu e tabela.
- Todo controle tem nome acessível: rótulo ligado ao campo; `aria-label` em botão só de ícone;
  tabela com cabeçalho; imagem informativa com `alt`, decorativa com `alt` vazio.
- Alerta tem `role="alert"`; indicador de estado, `role="status"`; toast é anunciado.
- Cor nunca é o único sinal: status tem ícone e texto; erro tem mensagem; gráfico tem rótulo.
- Movimento respeita a preferência do sistema. Nada pisca.
- Nunca o atributo `title`. Nunca `tabindex` positivo. Nunca foco preso fora de um modal.

## 3.16 Texto da interface

As IAs tendem a escrever demais. Aqui, não.

- **Uma frase por aviso, alerta, toast, descrição ou estado vazio.** Se precisa de duas, a segunda
  é um link "Saiba mais".
- **Título de toast: até 5 palavras.** Título de modal: até 6. Rótulo de botão: 1 a 3.
- **O texto é o que a pessoa precisa para decidir**, não tudo o que é verdade sobre o assunto.
- **Botão é verbo + objeto:** "Salvar", "Excluir fila", "Nova fila", "Tentar de novo". Nunca "OK",
  "Sim", "Confirmar", "Clique aqui", "Prosseguir".
- **Erro diz o que aconteceu e o que fazer:** "Não foi possível salvar. Tente de novo." Nunca
  código, stack, nome de tabela ou "erro inesperado".
- Sem "Por favor", sem "Ops", sem exclamação, sem ponto de interrogação fora de confirmação.
  Sem "Você" quando dá para omitir. Sem ponto final em rótulo e título; com ponto final em frase.
- Voz ativa, presente, direta: "A fila recebe conversas" e não "As conversas serão recebidas".
- Nome das coisas pelo que a pessoa reconhece ("Notificações"), não pelo que o sistema faz
  ("Configuração de webhook").
- Maiúscula só na primeira palavra ("Nova fila", não "Nova Fila").

Glossário dos rótulos padrão (usar sempre estes, nos três idiomas):

| pt-BR | en | es |
|---|---|---|
| Salvar | Save | Guardar |
| Cancelar | Cancel | Cancelar |
| Fechar | Close | Cerrar |
| Excluir | Delete | Eliminar |
| Editar | Edit | Editar |
| Novo / Nova … | New … | Nuevo / Nueva … |
| Atualizar (nunca botão de tela: 3.8) | Refresh | Actualizar |
| Buscar | Search | Buscar |
| Filtrar | Filter | Filtrar |
| Limpar filtros | Clear filters | Limpiar filtros |
| Carregar mais | Load more | Cargar más |
| Tentar de novo | Try again | Intentar de nuevo |
| Desfazer | Undo | Deshacer |
| Ver | View | Ver |
| Entrar | Sign in | Iniciar sesión |
| Sair | Sign out | Cerrar sesión |
| Perfil | Profile | Perfil |
| Configurações | Settings | Configuración |
| Idioma | Language | Idioma |
| Tema · Claro · Escuro | Theme · Light · Dark | Tema · Claro · Oscuro |
| Ações | Actions | Acciones |
| Opcional | Optional | Opcional |
| Nenhum resultado | No results | Sin resultados |
| Carregando | Loading | Cargando |
| Bem-vindo de volta | Welcome back | Bienvenido de nuevo |
| Esqueci minha senha | Forgot my password | Olvidé mi contraseña |
| Filtros · Limpar tudo | Filters · Clear all | Filtros · Limpiar todo |
| Todos · Período · Ordenar · Compacto | All · Period · Sort · Compact | Todos · Período · Ordenar · Compacto |
| Problemas para entrar? | Trouble signing in? | ¿Problemas para entrar? |

## 3.17 O que nunca fazer

- Cor fixa na tela (hexadecimal, nome de cor ou paleta da biblioteca): só tokens.
- Título ou subtítulo na tela: o nome dela é o breadcrumb.
- Menu, header ou painel lateral montado dentro da tela: são do shell.
- Ação ou filtro no header, ou numa barra solta entre o header e a primeira box: vai no card a que
  pertence (3.3).
- Mais de um botão `primary` no mesmo contexto.
- Botão só de ícone sem `aria-label` e tooltip. Atributo `title` em qualquer lugar.
- Texto "Carregando…" ou spinner no lugar de um componente que ainda não carregou: é Skeleton.
- Aviso escrito à mão com texto colorido: é alerta. Ícone ou cor escolhidos pela tela num alerta
  com tipo. Quinto tipo de alerta.
- Tabela solta sem barra de ferramentas, estados e "…" de ações. Botões soltos na linha.
- Formulário sem feedback de erro, chamada ao servidor sem estado de carregamento.
- Opacidade em texto de descrição ou de erro.
- Fonte, ícone ou tamanho fora do guia. Emoji como ícone.
- Texto fixo no código: tudo vem de dicionário. Bandeira como idioma.
- Sombra em box. Raio diferente de 8, 12 ou redondo.
- "Sim" e "Não" numa confirmação. "OK" num botão. Frase explicando o sistema inteiro num toast.
- Valor aleatório ou hora atual no primeiro render (quebra a hidratação e o Skeleton).
- Decidir o que renderizar pelo tema: tudo é token.
- Botão "Atualizar" ou "Atualizado às": os dados se atualizam sozinhos (3.8).
- Filtro ou período num dashboard: dashboard com filtro é relatório (3.1).
- Coluna de valor único que não ordena, ou coluna de conjunto fechado sem o seu filtro (2.10).
- Balão flutuante (de IA, ajuda ou chat) ou janela por cima do conteúdo: o assistente é um painel
  encaixado à direita (2.29), e a ajuda é o "?" do header (2.28).
- Passo a passo que começa sozinho, ou convite que volta depois de "Agora não" (2.28).
- Abas para trocar de seção das configurações: é o segundo menu (2.27).
- Assistente que muda algo no sistema sem o cartão de confirmação (2.29).
- Itens da administração (empresas clientes, produtos, papéis) no meio dos grupos do menu, ou a
  área de administração com outra cor que não o tom da primária (2.30).
- Trocar de papel pelo "Ver como", ou o "Ver como" para quem não está como Sysadmin (2.16).
- Tela que depende de uma escolha abrindo num seletor vazio ("Escolha uma pessoa"): ela começa
  listando as opções (3.18). Esc para voltar da segunda etapa.

## 3.18 Listagem em duas etapas

Tela que depende de uma escolha (a pessoa, a fila, a empresa…) **começa listando as opções**, com o
padrão completo de listagem, e não com um seletor vazio no topo *(decisão do usuário, 2026-10-26)*.
É o que substitui o antigo "filtro inicial": não há barra de ações (3.3), e o escopo mora no card
(3.5). Ao escolher, **o mesmo card desliza** para a segunda etapa, já filtrada pela escolha.

```text
Etapa 1: as opções                               Etapa 2: a escolha (?pessoa=u2)
+--------------------------------------------+   +--------------------------------------------+
| [Buscar pessoa]  [Cargo ▾]                 |   | ← Pessoas                                  |
|                                            |   | Repositórios de Ana Ribeiro                |
| Nome ↑        Cargo     Repos.             |   | 8 com acesso · 24 no catálogo              |
| Ana Ribeiro   Atendente   8  Ver acessos › | → | [Filtrar por nome] [Origem ▾] [Acesso ▾]   |
| Bruno Cardoso Desenv.     5  Ver acessos › |   | Repositório ↑           Origem   Acesso    |
| 1-10 de 24         ‹ Página 1 de 3 ›       |   | ideia-chat              GitHub     [●]     |
+--------------------------------------------+   +--------------------------------------------+
```

**Etapa 1, as opções.** Uma tabela de dados completa (2.10): busca, colunas ordenáveis, um filtro por
coluna de conjunto fechado, paginação e estados. A última coluna é a ação que leva à etapa 2: um
botão `ghost` `sm` com o verbo e `chevron-right` ("Ver acessos ›"), o único botão da linha, com o
nome da opção no nome acessível ("Ver acessos de Ana Ribeiro"). A linha inteira também abre a etapa
2. Se a linha tiver outras ações, elas ficam no "…" ao lado.

**Etapa 2, a escolha.** O mesmo card, de cima para baixo:
1. O botão **"← Pessoas"**: `ghost` `sm`, `arrow-left`, o nome da etapa 1 no plural.
2. O título (16/500) **com o nome escolhido** ("Repositórios de Ana Ribeiro") e a descrição com a
   contagem.
3. A barra de ferramentas e a tabela da etapa, também no padrão completo (2.10).

**Ida e volta.**
- **Desliza em 200ms**, como a folha lateral (1.7): ao ir, a etapa 1 sai pela esquerda e a 2 entra
  pela direita; ao voltar, o contrário. Com movimento reduzido, troca sem animação.
- **Volta só pelo botão "← Pessoas" e pelo voltar do navegador** *(decisão do usuário,
  2026-10-26)*. O Esc não volta: ele fecha camadas (modal, menu, popover), e a etapa 2 não é camada.
- **Estado na URL:** a escolha entra como parâmetro (`?pessoa=u2`) com uma entrada nova no
  histórico; o link abre direto na etapa 2. A busca, os filtros, a ordem e a página da etapa 1
  continuam na URL enquanto a etapa 2 está aberta, e os da etapa 2 têm nomes próprios (`rq`,
  `rpage`, `rsort`), para uma etapa não apagar a outra. Voltar tira só os da etapa 2.
- **A volta encontra a etapa 1 como ficou:** a mesma busca, os mesmos filtros, a mesma ordem e a
  mesma página, sem Skeleton de novo (a etapa 1 continua montada, escondida).
- **Foco:** ao ir, vai ao título da etapa 2 (`tabIndex={-1}`); ao voltar, à ação da linha de origem.
  Se a linha não está mais na página, à busca da etapa 1.
- **Breadcrumb com o terceiro nível** *(decisão do usuário, 2026-10-26)*: "Configurações da empresa ›
  Acesso a projetos › Ana Ribeiro". O nível do meio é link para a etapa 1, como na tela de detalhe
  (2.17), e o título da aba do navegador acompanha o último nível.
- Escolha que não existe mais (o link de alguém que saiu): a etapa 2 diz isso no título ("Pessoa não
  encontrada"), sem tabela, com o "← Pessoas".
- Trocar de empresa zera tudo e volta à etapa 1 (3.2).

**Quando não usar.** Escolha que só recorta um conjunto que faz sentido inteiro (Status, Produto) é
filtro (3.5). Visão de um relatório é aba (2.23). Um registro com várias partes é tela de detalhe
(3.1).

---

# Parte 4 — Implementação de referência: shadcn/ui + Tailwind

A equipe padronizou também a stack do front *(decisão do usuário, 2026-10-22)*. Projeto novo nasce
nela; projeto antigo migra quando tocar na tela. As partes 1 a 3 continuam valendo para qualquer
stack; esta parte diz como elas viram código nesta. O `docs/DESIGN.md` local de um projeto nesta
stack só descreve o que é específico dele (rotas, NAV, nomes de arquivos); o mapa é este.

## 4.1 A stack

| Camada | Padrão |
|---|---|
| Framework | Next.js (App Router) com React 19 e TypeScript. App sem servidor próprio: Vite + React |
| CSS | Tailwind CSS 4 |
| Componentes | shadcn/ui pelo CLI atual, **estilo `base-nova`** (primitivos **Base UI**), copiados para `components/ui/`, com as medidas que vêm (1.5). Composição pelo prop `render`, nunca `asChild`. O `radix-nova` (ideia-renewal, primitivos Radix) tem as mesmas medidas e compõe pelo `asChild`, que é o do Radix (4.5) |
| Ícones | `lucide-react` (importar sem o sufixo `Icon`) |
| Tema | `next-themes`, classe `dark` no `<html>` |
| Formulários | `react-hook-form` + `zod` + a família `Field` do shadcn, por `Controller` |
| Tabelas | `@tanstack/react-table` v9 pelo guia Data Table do shadcn |
| Fontes | Roboto e Roboto Mono por `next/font/google` (no Vite, `@fontsource-variable/roboto` e `@fontsource-variable/roboto-mono`) |
| Classes | `cn()` de `@/lib/utils` |
| i18n | `next-intl` no Next; `i18next` + `react-i18next` no Vite *(proposta, a confirmar)* |
| Documentação | sempre a da versão Base UI: `https://ui.shadcn.com/docs/components/base/<componente>` |

Instalar um componente: `pnpm dlx shadcn@latest add <componente>`. Procurar antes de criar:
`pnpm dlx shadcn@latest search @shadcn -q <termo>`. Ver um bloco: `pnpm dlx shadcn@latest view sidebar-07`.

## 4.2 Tokens: `app/globals.css`

Os valores são os da Parte 1. **Por produto mudam só `--primary`, `--primary-foreground`, `--ring`,
`--sidebar-primary` e `--brand`**; todo o resto é copiado igual. O `danger` do guia é o
`destructive` do shadcn: não renomear.

```css
/* Rede Ideia — gerado pelo ideia-design-system a partir de tokens/. Não edite à mão: mude o token e gere de novo. */
@import "tailwindcss";
@import "shadcn/tailwind.css";
@custom-variant dark (&:is(.dark *));

:root {
  --background: #f8fafc;  --foreground: #0f172a;
  --card: #ffffff;  --card-foreground: #0f172a;
  --popover: #ffffff;  --popover-foreground: #0f172a;
  --primary: #153261;  --primary-foreground: #ffffff;   /* só isto muda por produto (com --ring, --sidebar-primary e --brand) */
  --link: #153261;   /* texto de link (variante link do Button): a primária; no escuro, mais clara, com 4,5:1 (D18) */
  --brand: #153261;   /* a primária clara, fixa nos dois temas: só o painel do login */
  --secondary: #f1f5f9;  --secondary-foreground: #0f172a;
  --muted: #f1f5f9;  --muted-foreground: #475569;
  --accent: #f1f5f9;  --accent-foreground: #0f172a;
  --destructive: #b91c1c;  --destructive-foreground: #ffffff;  --destructive-strong: #991b1b;   /* = danger do guia; -strong = texto e ícone sobre superfície tingida */
  --success: #15803d;  --success-foreground: #ffffff;  --success-strong: #166534;   /* -strong: texto e ícone sobre a tinta (badge, alerta) */
  --warning: #b45309;  --warning-foreground: #ffffff;  --warning-strong: #92400e;
  --info: #0369a1;  --info-foreground: #ffffff;  --info-strong: #075985;
  --border: #e2e8f0;  --input: #8592a6;  --ring: #153261;
  --sidebar: #ffffff;  --sidebar-foreground: #0f172a;
  --sidebar-primary: #153261;  --sidebar-primary-foreground: #ffffff;   /* item ativo, cheio */
  --sidebar-accent: #f1f5f9;  --sidebar-accent-foreground: #0f172a;   /* hover */
  --sidebar-border: #e2e8f0;  --sidebar-ring: #153261;
  --sidebar-admin: #eceff2;  --sidebar-admin-accent: #dee2e9;  --sidebar-admin-border: #b9c4d3;   /* área de administração (2.30): a sidebar no tom suave da primária */
  --radius: 0.5rem;   /* 8px = rounded-lg (controles); a escala do shadcn multiplica: md ×0,8 (itens de menu), xl ×1,4 (card, modal) */
}
.dark {
  --background: #171717;  --foreground: #e5e5e5;
  --card: #262626;  --card-foreground: #e5e5e5;
  --popover: #262626;  --popover-foreground: #e5e5e5;
  --primary: #2e6cd2;  --primary-foreground: #ffffff;   /* só isto muda por produto (com --ring, --sidebar-primary e --brand) */
  --link: #608fdd;   /* texto de link (variante link do Button): a primária; no escuro, mais clara, com 4,5:1 (D18) */
  --brand: #153261;   /* a primária clara, fixa nos dois temas: só o painel do login */
  --secondary: #404040;  --secondary-foreground: #e5e5e5;
  --muted: #1f1f1f;  --muted-foreground: #a8a8a8;
  --accent: #1f1f1f;  --accent-foreground: #e5e5e5;
  --destructive: #f87171;  --destructive-foreground: #171717;  --destructive-strong: #fca5a5;   /* = danger do guia; -strong = texto e ícone sobre superfície tingida */
  --success: #4ade80;  --success-foreground: #171717;  --success-strong: #86efac;   /* -strong: texto e ícone sobre a tinta (badge, alerta) */
  --warning: #fbbf24;  --warning-foreground: #171717;  --warning-strong: #fcd34d;
  --info: #38bdf8;  --info-foreground: #171717;  --info-strong: #7dd3fc;
  --border: #404040;  --input: #737373;  --ring: #2e6cd2;
  --sidebar: #171717;  --sidebar-foreground: #e5e5e5;
  --sidebar-primary: #2e6cd2;  --sidebar-primary-foreground: #ffffff;   /* item ativo, cheio */
  --sidebar-accent: #1f1f1f;  --sidebar-accent-foreground: #e5e5e5;   /* hover */
  --sidebar-border: #404040;  --sidebar-ring: #2e6cd2;
  --sidebar-admin: #1a2331;  --sidebar-admin-accent: #1c2a40;  --sidebar-admin-border: #3b4d6c;   /* área de administração (2.30): a sidebar no tom suave da primária */
}
/* Área de administração (2.30): com ela na tela, a sidebar inteira (também a do celular, que abre fora do layout) fica no
   tom suave da primária. Marque o layout da área com data-area="admin"; a Sidebar do shadcn só lê --sidebar-*. */
:root:has([data-area="admin"]) {
  --sidebar: var(--sidebar-admin);  --sidebar-accent: var(--sidebar-admin-accent);  --sidebar-border: var(--sidebar-admin-border);
}
/* O shadcn/tailwind.css só traz animações e variantes data-*: as cores, a fonte e a escala de raio se registram aqui. */
@theme inline {
  --font-sans: var(--font-roboto), system-ui, sans-serif;
  --font-mono: var(--font-roboto-mono), ui-monospace, monospace;
  --font-heading: var(--font-sans);
  --color-background: var(--background);  --color-foreground: var(--foreground);
  --color-card: var(--card);  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);  --color-primary-foreground: var(--primary-foreground);
  --color-link: var(--link);
  --color-brand: var(--brand);
  --color-secondary: var(--secondary);  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);  --color-destructive-foreground: var(--destructive-foreground);  --color-destructive-strong: var(--destructive-strong);
  --color-success: var(--success);  --color-success-foreground: var(--success-foreground);  --color-success-strong: var(--success-strong);
  --color-warning: var(--warning);  --color-warning-foreground: var(--warning-foreground);  --color-warning-strong: var(--warning-strong);
  --color-info: var(--info);  --color-info-foreground: var(--info-foreground);  --color-info-strong: var(--info-strong);
  --color-border: var(--border);  --color-input: var(--input);  --color-ring: var(--ring);
  --color-sidebar: var(--sidebar);  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);  --color-sidebar-ring: var(--sidebar-ring);
  --color-sidebar-admin: var(--sidebar-admin);  --color-sidebar-admin-accent: var(--sidebar-admin-accent);  --color-sidebar-admin-border: var(--sidebar-admin-border);
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}
/* O que o shadcn init põe no globals.css: sem isto, a borda sai na cor do texto e o body fica sem o fundo do tema. */
@layer base {
  * { @apply border-border outline-ring/50; }
  body { @apply bg-background text-foreground; }
  button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; }
}
```

O arquivo acima é gerado pelo build a partir de `packages/tokens/base.json` e das cores da Rede Ideia no cadastro do painel, lidas da API dos produtos; cada produto tem o seu em `apps/site/dist/css/<slug>.css`.

- O `@theme inline` registra as cores, a fonte e a escala de raio. **O `shadcn/tailwind.css` não
  registra nenhuma delas** (só as animações e as variantes `data-*`): sem esse bloco, `bg-primary` e
  `rounded-xl` não existem.
- `--radius: 0.5rem` é o raio dos controles (`rounded-lg`, 8px); a escala do shadcn multiplica:
  `rounded-md` 6px (itens de menu), `rounded-xl` 11px (card, modal). Não use outro `rounded-*` em
  superfície.
- `--chart-1` a `--chart-5` ainda não saem do build: até lá, gráfico usa a primária e as semânticas
  (no TODO).
- O `layout.tsx` carrega as fontes e monta os providers:

```tsx
// app/layout.tsx
import { Roboto, Roboto_Mono } from "next/font/google";
const roboto = Roboto({ subsets: ["latin"], variable: "--font-roboto" });
const robotoMono = Roboto_Mono({ subsets: ["latin"], variable: "--font-roboto-mono" });

<html lang="pt-BR" suppressHydrationWarning className={cn("font-sans", roboto.variable, robotoMono.variable)}>
  <body className="min-h-dvh antialiased">
    <ThemeProvider attribute="class" defaultTheme="light" enableSystem={false} disableTransitionOnChange>
      <TooltipProvider>
        {children}
        <Toaster />   {/* dentro do TooltipProvider: o X de fechar tem dica */}
      </TooltipProvider>
    </ThemeProvider>
  </body>
</html>
```

## 4.3 Mapa: componente do guia → shadcn

| Guia | shadcn | Como |
|---|---|---|
| 2.1 Botão | `Button` | `variant`: `default` (= primary), `secondary`, `outline`, `ghost`, `link`, `destructive` (= danger). `size`: `xs` (24), `sm` (28), `default` (32), `lg` (36), `icon-xs`, `icon-sm`, `icon`, `icon-lg`; não existe `xl`. `destructive` com `text-destructive-strong` e `link` com `text-link` no `cva` (nível 3, contraste). Ícone com `data-icon="inline-start"` |
| 2.2 Campo | `Field`, `FieldLabel`, `Input` / `Textarea`, `FieldDescription`, `FieldError`; ícone por `InputGroup` + `InputGroupAddon` | sempre por `Controller`; nunca o conjunto antigo `Form`/`FormField` |
| 2.3 Select, combobox, data | `Select`; `Combobox` acima de 8 opções; data = campo digitável + `Calendar` (`captionLayout="dropdown"`) num `Popover` | |
| 2.4 Checkbox, rádio, switch | `Checkbox`, `RadioGroup`, `Switch` | |
| 2.5 Badge | `Badge` | variantes `success`, `warning`, `info` e `danger` (tingidas a 12%, texto em `text-*-strong`) adicionadas no `cva` do `badge.tsx` (nível 3) |
| 2.6 Alerta | `Alert` + `AlertDescription` | variantes `success`, `warning`, `info` no `cva` do `alert.tsx`, com o ícone fixo por variante e texto em `text-*-strong`; a tela não passa ícone |
| 2.7 Toast | `Toast` (Base UI) por `@/lib/toast` | `toast.success/error/info/warning(título, { description, action })`; `<Toaster />` no layout, dentro do `TooltipProvider`; 6 s |
| 2.8 Tooltip | `Tooltip`, `TooltipTrigger render={…}`, `TooltipContent` | `TooltipProvider` na raiz; atalho em `Kbd` |
| 2.9 Card, KPI | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | KPI: `CardTitle className="text-3xl font-bold tabular-nums"` |
| 2.10 Tabela | `Table` + TanStack v9, com os reutilizáveis do guia (`data-table-column-header`, `-pagination`, `-view-options`, `-row-actions`) e o `filtro-de-coluna` (`Select` até 5 valores; `Popover` + `Command` acima) | um `DataTable` por tela, dentro de `Card`; `DataTableColumnHeader` em toda coluna de valor único, `enableSorting: false` nas outras; `aria-sort` no `TableHead`; ordem e filtros por `useSearchParams` |
| 2.11 Skeleton, Spinner | `Skeleton`, `Spinner` | Spinner com `data-icon="inline-start"` em botão |
| 2.12 Vazio | `Empty`, `EmptyHeader`, `EmptyMedia variant="icon"`, `EmptyTitle`, `EmptyDescription`, `EmptyContent` | |
| 2.13 Modal | `Dialog` (formulário), `AlertDialog` (confirmação) | largura pelo `DialogContent`: padrão (384), `className="sm:max-w-lg"` (512) ou `"sm:max-w-2xl"` (672); `DialogClose render={<Button variant="ghost" />}` para Cancelar |
| 2.14 Menu suspenso | `DropdownMenu` | `DropdownMenuItem variant="destructive"` por último |
| 2.15 Shell | `Sidebar` no bloco `sidebar-07` (`SidebarProvider`, `AppSidebar collapsible="icon"`, `SidebarInset`), `Breadcrumb`, `Separator`, `SidebarTrigger`; painel da direita = `Sidebar collapsible="none"` (bloco `sidebar-15`) | item ativo cheio: no `sidebar.tsx`, o `SidebarMenuButton` ativo usa `bg-sidebar-primary text-sidebar-primary-foreground` (nível 3) |
| 2.16 Menu do usuário | `DropdownMenu` no `SidebarFooter` (o `NavUser` do bloco), `ToggleGroup` para idioma e tema; trocar de papel = `DropdownMenuSub` com `DropdownMenuRadioGroup` | o papel ativo vem da sessão; trocar invalida as consultas e remonta a tela |
| 2.17 Breadcrumb · 2.18 Paginação · 2.19 Avatar | `Breadcrumb` · `DataTablePagination` · `Avatar` + `AvatarFallback` | |
| 2.20 Login | grid de duas colunas com `Field`, `InputGroup`, `Button`; na linha de baixo do grid, o `Footer estendido` (2.21) nas duas colunas | painel em `bg-[linear-gradient(135deg,var(--brand),…)]` |
| 2.22 Filtro | `Select`; seletor múltiplo = `Popover` + `Command` (`CommandInput`, `CommandList`, `CommandItem` com `Checkbox`); período = `Popover` com `ToggleGroup` vertical e dois campos de data; chip de alternância = `Toggle variant="outline"` (ligado em `primary`: nível 3, 4.5); "Filtros" = `Button` + `Popover` (no celular `Sheet side="bottom"`); chip removível = `Button variant="secondary" size="xs"` com `X` em `data-icon="inline-end"` | estado na URL por `useSearchParams` |
| 2.21 Rodapé | componente próprio `components/shell/footer.tsx`: a linha, a seta e a parte estendida com os produtos. Desktop: `Collapsible` com o próprio `footer` no `render` e o `CollapsibleContent` no fluxo, acima da linha: o rodapé cresce e a página rola até ele (`scrollIntoView`), nada por cima do conteúdo; borda e sombra só em cima, sem véu; abre só no clique (sem `onMouseEnter`); clicar fora não fecha. Celular: `Sheet side="bottom"`. Login: prop `estendido`, no fluxo e sem a seta. O carrossel é o `Carousel` do shadcn (embla) com `embla-carousel-autoplay` | `pnpm dlx shadcn@latest add collapsible sheet carousel` e `pnpm add embla-carousel-autoplay` |
| 2.23 Abas | `Tabs`, `TabsList variant="line"`, `TabsTrigger`, `TabsContent`; controle segmentado = o mesmo `TabsList` com `variant="default"` | `pnpm dlx shadcn@latest add tabs`; anel de foco no `TabsContent` (nível 3, 4.5); a aba na URL por `useSearchParams` |
| 2.24 Card de relatório | componente próprio `components/relatorio/card-de-relatorio.tsx`: `Card` › `Tabs className="contents"` › `CardHeader` com o `TabsList` (e `CardAction`) › `CardContent` com os filtros do 2.22 › `TabsContent` com o conteúdo | estado por `useSearchParams` com prefixo quando há mais de um na tela; dados por `useQuery` com `refetchInterval` |
| 2.25 Troca de empresa | `SidebarMenuButton size="lg"` no `SidebarHeader`, abaixo do logo (o `TeamSwitcher` do bloco `sidebar-07`); lista = `DropdownMenu`; busca = `Popover` + `Command` (`shouldFilter={false}`, quem filtra é o servidor) e "Ver todas as empresas" fora do `Command`, um `Link` com `buttonVariants`; uma empresa só = o mesmo bloco num `div`, sem seta | campo dentro de menu do Base UI não recebe o que se digita: por isso a busca é `Popover` |
| 3.11 Notificações | `Popover` (`PopoverTitle`) no sino, com `Button` `ghost` `sm` e `icon-sm` no cabeçalho; preferências em `Dialog` com `FieldSet`, `FieldLegend variant="label"`, `Field orientation="horizontal"` e `Switch`; `DialogFooter showCloseButton` | a permissão do navegador é pedida no clique do switch; aviso de bloqueio em `Alert variant="warning"` |
| 2.26 Kanban | componente próprio `components/kanban/quadro.tsx`: `Card` (`data-altura="cheia"`, `flex-1 min-h-0`) › barra (2.22, `Toggle`, `ToggleGroup`) › quadro em `grid grid-flow-col` com `overflow-x-auto` › coluna com cabeçalho parado e lista em `overflow-y-auto`; card da tarefa = `Card size="sm"` com `Badge`, `Progress` e `Avatar size="sm"`; "…" = `DropdownMenu` com `DropdownMenuSub` "Mover para"; arrastar e soltar nativo do HTML | `pnpm dlx shadcn@latest add progress toggle toggle-group`; no shell, `SidebarInset` com `has-data-[altura=cheia]:h-svh` e o conteúdo com `min-h-0`; barra horizontal à vista com `[&::-webkit-scrollbar]:h-2.5` e polegar em `bg-input` |
| 2.27 Segundo menu | `nav` próprio no layout da área (`app/(painel)/configuracoes/layout.tsx`): links com `buttonVariants({ variant: "ghost" })`, `w-full justify-start`; ativo `bg-card ring-1 ring-foreground/10 font-medium` e `aria-current="page"`; abaixo de `lg`, `Select` com `SelectGroup` e `SelectLabel` | cada seção é uma rota; o `SidebarMenuButton` do item fica ativo por prefixo (`pathname.startsWith`); no shell, o contêiner do conteúdo perde o padding com `has-[[data-slot=segundo-menu]]:p-0` |
| 2.28 Passo a passo e ajuda | "?" = `DropdownMenu` com `Button variant="ghost" size="icon-sm"` + `Tooltip`; convite = `Popover` controlado com `PopoverContent anchor={botao}` (`PopoverHeader`, `PopoverTitle`, `PopoverDescription`); passo a passo = **driver.js**, com o cartão nas classes do `PopoverContent` e os botões em `buttonVariants` pelo `onPopoverRender` | `pnpm add driver.js`; `@import "driver.js/dist/driver.css" layer(base);` no `globals.css`; partes marcadas com `data-tour`; estado por pessoa no servidor |
| 2.29 Assistente de IA | `MessageScroller`, `Message`, `Bubble` (`muted` para a pessoa, `ghost` para a resposta, `destructive` para o erro), padrão Prompt Input (`InputGroup` + `InputGroupTextarea` + `InputGroupButton`), padrão Confirmation (`Item variant="outline" size="sm"` + `ItemActions`); encaixado = `aside` `w-96` no lugar do painel da direita; sem espaço, `Sheet side="right"` | `pnpm dlx shadcn@latest add message-scroller message bubble input-group item sheet`; conversa pelo `useChat` do AI SDK, ferramentas que mudam algo com `needsApproval`; `shimmer` do shadcn no "Pensando…" |
| 2.30 Área de administração | rotas em `app/(admin)/admin/…` com layout próprio: `data-area="admin"` num elemento do layout, `TeamSwitcher` trocado pelo bloco fixo, `NavMain` com os itens da área; entrada = `SidebarMenuButton` no `SidebarFooter`, acima do `NavUser` | o `globals.css` gerado já troca `--sidebar`, `--sidebar-accent` e `--sidebar-border` por `:root:has([data-area="admin"])`; o layout confere o papel no servidor (`notFound()`) |
| 3.18 Listagem em duas etapas | um `Card` com as duas etapas no mesmo `CardContent`: a etapa 1 é um `DataTable` com a ação `Button variant="ghost" size="sm"` e `ChevronRight`; a etapa 2, `CardHeader` com o `Button` "← Pessoas" (`ArrowLeft`) e o título com `tabIndex={-1}`; o terceiro nível no `Breadcrumb` do shell (`BreadcrumbLink` para a etapa 1) | escolha por `useSearchParams` (`?pessoa=`) com `router.push`; deslizar com `transition-[translate,visibility] duration-200`, `starting:` e `motion-reduce:transition-none`; `inert` na etapa escondida |

## 4.4 Exemplos

Exemplos de código para a stack padrão. Cada arquivo em `examples/` é o trecho canônico do componente; o guia único os inclui aqui.

### Botão

```tsx
import { Plus } from "lucide-react";
import { Button, buttonVariants } from "@/components/ui/button";
import { Spinner } from "@/components/ui/spinner";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";

// tamanhos do shadcn: xs 24 · sm 28 · default 32 · lg 36 (não existe xl); nunca h-*/px-* por className
// "Novo…": no canto superior direito do card que ele alimenta, o único default (= primary) do card,
// no tamanho padrão: a mesma altura da busca, dos filtros e dos outros botões da barra (nada de lg).
// Abaixo de 40rem de card vira só ícone, com aria-label e tooltip. Não existe botão "Atualizar" (3.8).
// components/botao-novo.tsx; o Card (ou o contêiner da tabela) leva className="@container/card"
export function BotaoNovo({ rotulo, onClick }: { rotulo: string; onClick: () => void }) {
  return (
    <>
      <Button className="hidden @min-[40rem]/card:inline-flex" onClick={onClick}><Plus data-icon="inline-start" />{rotulo}</Button>
      <Tooltip>
        <TooltipTrigger render={<Button size="icon" aria-label={rotulo} className="@min-[40rem]/card:hidden" onClick={onClick} />}><Plus /></TooltipTrigger>
        <TooltipContent>{rotulo}</TooltipContent>
      </Tooltip>
    </>
  );
}

// salvando: desabilitado, Spinner no lugar do ícone, rótulo mantido
<Button type="submit" disabled={isPending}>
  {isPending && <Spinner data-icon="inline-start" />}
  Salvar
</Button>

// link com cara de botão: nunca <Link> dentro de <Button>
<Link href="/contatos" className={buttonVariants({ variant: "outline" })}>Contatos</Link>
```

### Botão só de ícone e tooltip

```tsx
import { Ellipsis } from "lucide-react";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";

// botão só de ícone: aria-label E Tooltip com o mesmo texto; nunca o atributo title
<Tooltip>
  <TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Ações" />}>
    <Ellipsis />
  </TooltipTrigger>
  <TooltipContent>Ações</TooltipContent>
</Tooltip>

// atalho na dica
<TooltipContent>Recolher menu <Kbd>Ctrl B</Kbd></TooltipContent>

// botão desabilitado não dispara a dica: envolva num span
<TooltipTrigger render={<span className="inline-block w-fit" />}>
  <Button disabled>Transferir</Button>
</TooltipTrigger>
```

### Campo

```tsx
import { Controller } from "react-hook-form";
import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/ui/input-group";

// sempre por Controller + família Field; nunca o conjunto antigo Form/FormField/FormItem
<Controller
  name="name"
  control={form.control}
  render={({ field, fieldState }) => (
    <Field data-invalid={fieldState.invalid}>
      <FieldLabel htmlFor="queue-name">Nome</FieldLabel>
      <Input {...field} id="queue-name" aria-invalid={fieldState.invalid} />
      <FieldDescription>Como aparece para o cliente.</FieldDescription>
      {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
    </Field>
  )}
/>

// campo com ícone
<Field>
  <FieldLabel htmlFor="email">E-mail</FieldLabel>
  <InputGroup>
    <InputGroupInput id="email" type="email" placeholder="nome@empresa.com.br" />
    <InputGroupAddon><Mail /></InputGroupAddon>
  </InputGroup>
</Field>

// data: digitável dd/mm/aaaa + Calendar num Popover, mês e ano em dropdown (captionLayout="dropdown")
<CampoDeData value={field.value} onChange={field.onChange} anoMin={2021} anoMax={2036} />
```

### Badge

```tsx
import { CircleCheck, CircleX } from "lucide-react";
import { Badge } from "@/components/ui/badge";

// variantes success, warning, info e danger adicionadas no cva do badge.tsx — nível 3:
//   success: "bg-success/12 text-success-strong"  ·  danger: "bg-destructive/12 text-destructive-strong"  (texto no tom -strong, guia 1.2)
<Badge variant="success"><CircleCheck data-icon="inline-start" />Ativa</Badge>
<Badge variant="danger"><CircleX data-icon="inline-start" />Inativa</Badge>
<Badge variant="secondary">Neutro</Badge>
<Badge>Primária</Badge>
```

### Alerta

```tsx
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";

// variantes success, warning e info no cva do alert.tsx, ícone fixo por variante; a tela não passa ícone
//   ex.: warning: "border-warning/30 bg-warning/8 text-warning-strong [&>svg]:text-warning-strong"
<Alert variant="destructive"><AlertDescription>{excluir.error.message}</AlertDescription></Alert>
<Alert variant="warning"><AlertDescription>Desativar a fila devolve as conversas para a triagem.</AlertDescription></Alert>
<Alert variant="info"><AlertDescription>Os contadores atualizam a cada 5 minutos.</AlertDescription></Alert>

// manchete só quando precisa
<Alert variant="destructive">
  <AlertTitle>Conexão perdida</AlertTitle>
  <AlertDescription>Reconectando. As mensagens enviadas agora ficam na fila.</AlertDescription>
</Alert>

// indicador de estado (não é alerta): variante default, role="status", ícone próprio
<Alert role="status" className="bg-muted"><Lock /><AlertDescription>Nota interna: o cliente não vê.</AlertDescription></Alert>
```

### Toast

```ts
import { toast } from "@/lib/toast";   // o nosso, nunca o componente: tipo como método, action, prioridade

toast.success("Fila criada", { description: "Retenção já recebe conversas." });
toast.error("Não foi possível salvar", { description: "Tente de novo." });
toast.info("Nova conversa atribuída", { action: { label: "Ver", onClick: () => router.push(href) } });
toast.success("Contato excluído", { action: { label: "Desfazer", onClick: desfazer } });

// <Toaster /> no app/layout.tsx, dentro do TooltipProvider; timeout padrão 6 s (0 = até fechar)
```

### Card e KPI

```tsx
import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card";

// a box, como o shadcn entrega: bg-card, contorno ring-foreground/10, rounded-xl, padding 16, sem sombra.
// Nada fica solto fora de uma. Não passe padding, raio nem borda por className.
<Card>
  <CardHeader>
    <CardTitle>Horário de atendimento</CardTitle>
    <CardDescription>Fora do horário, as conversas ficam na triagem.</CardDescription>
  </CardHeader>
  <CardContent>…</CardContent>
  <CardFooter className="justify-end gap-2">
    <Button variant="ghost">Cancelar</Button>
    <Button>Salvar</Button>
  </CardFooter>
</Card>

// KPI
<Card>
  <CardHeader>
    <CardDescription>Conversas hoje</CardDescription>
    <CardTitle className="text-3xl font-bold tabular-nums">148</CardTitle>
  </CardHeader>
</Card>

// KPI de dashboard: o recorte é fixo e dito no card, sem filtro de período (3.1); a variação compara
// com o recorte anterior do mesmo tamanho
<Card>
  <CardHeader>
    <CardDescription>Conversas</CardDescription>
    <CardTitle className="text-3xl font-bold tabular-nums">4.812</CardTitle>
    <CardAction><Badge variant="success"><TrendingUp data-icon="inline-start" />+12%</Badge></CardAction>
  </CardHeader>
  <CardContent><p className="text-xs text-muted-foreground">Últimos 30 dias, contra os 30 anteriores</p></CardContent>
</Card>
```

### Tabela de dados

```tsx
// app/(painel)/filas/
//   page.tsx                 "use client": busca os dados e renderiza <DataTable /> dentro do Card
//   columns.tsx              as colunas: toda coluna de valor único ordena; a de conjunto fechado diz o seu filtro
//   data-table.tsx           o <DataTable /> desta tela: barra de ferramentas, Table, paginação
//   data-table-features.ts   tableFeatures(): só os recursos que esta tabela usa (TanStack v9)
// components/ (compartilhados, do guia Data Table do shadcn):
//   data-table-column-header.tsx · data-table-pagination.tsx · data-table-view-options.tsx · data-table-row-actions.tsx
//   filtro-de-coluna.tsx     o filtro de uma coluna de conjunto fechado: Select até 5 valores, seletor múltiplo acima

<Card className="@container/card">
  <CardContent>
    <DataTable
      columns={columns}
      data={filas.data ?? []}
      isLoading={filas.isLoading}     // primeira carga: linhas de Skeleton
      isFetching={filas.isFetching}   // busca, filtro ou ordem: Spinner na barra, dados mantidos
      opcoes={{ atendente: pessoas }} // opções que vêm do servidor; as fixas moram na coluna
      // card sem título: o "Novo…" fecha a primeira linha da barra de ferramentas, à direita (2.1)
      toolbarEnd={<BotaoNovo rotulo="Nova fila" onClick={() => setEditando("novo")} />}
    />
  </CardContent>
</Card>

// ---- columns.tsx: toda coluna de valor único ordena (2.10), inclusive telefone, e-mail e código.
// Não ordenam: ações, seleção, vários valores na célula sem um número natural (etiquetas), texto livre longo.
const SETORES = [{ value: "suporte", label: "Suporte" }, { value: "vendas", label: "Vendas" }, { value: "financeiro", label: "Financeiro" }, { value: "retencao", label: "Retenção" }];
const STATUS = [{ value: "ativa", label: "Ativa" }, { value: "inativa", label: "Inativa" }];
const ORDEM_DO_STATUS: Record<string, number> = { ativa: 0, inativa: 1 };   // pela ordem do conjunto, não pelo alfabeto

export const columns = columnHelper.columns([
  columnHelper.accessor("nome", {
    header: ({ column }) => <DataTableColumnHeader column={column} title="Nome" />,
    sortFn: "textoPtBr", enableHiding: false,
    cell: ({ row }) => <NomeDaFila fila={row.original} />,
  }),
  // conjunto fechado: a coluna declara o filtro; 4 valores = escolha única (2.22)
  columnHelper.accessor("setor", {
    header: ({ column }) => <DataTableColumnHeader column={column} title="Setor" />,
    sortFn: "textoPtBr", cell: ({ getValue }) => NOME_DO_SETOR[getValue()],
    meta: { label: "Setor", className: "hidden @md/data-table:table-cell", filtro: { param: "setor", opcoes: SETORES } },
  }),
  // vários valores na célula (avatares) com um número natural: ordena pela quantidade.
  // Pessoa é conjunto fechado em que o normal é combinar: seletor múltiplo, com as opções do servidor
  columnHelper.accessor((fila) => fila.atendentes.length, {
    id: "atendentes",
    header: ({ column }) => <DataTableColumnHeader column={column} title="Atendentes" />,
    sortFn: "basic", cell: ({ row }) => <Avatares pessoas={row.original.atendentes} />,
    meta: { label: "Atendentes", className: "hidden @lg/data-table:table-cell", filtro: { param: "atendente", multiplo: true } },
  }),
  columnHelper.accessor("emEspera", {
    header: ({ column }) => <DataTableColumnHeader column={column} title="Em espera" className="justify-end" />,
    sortFn: "basic", cell: ({ getValue }) => <div className="text-right tabular-nums">{getValue()}</div>,
  }),
  columnHelper.accessor((fila) => ORDEM_DO_STATUS[fila.status], {
    id: "status",
    header: ({ column }) => <DataTableColumnHeader column={column} title="Status" />,
    sortFn: "basic", cell: ({ row }) => <StatusDaFila status={row.original.status} />,   // Badge com ícone (2.5)
    meta: { label: "Status", filtro: { param: "status", opcoes: STATUS } },
  }),
  columnHelper.display({ id: "acoes", enableSorting: false, enableHiding: false, cell: ({ row }) => <AcoesDaFila fila={row.original} /> }),
]);

// ---- data-table.tsx: ordem e filtros vivem na URL (3.5); a barra nasce das colunas
export function DataTable<TData extends { id: string }>({ columns, data, isLoading, isFetching, opcoes = {}, toolbarEnd }: DataTableProps<TData>) {
  const url = useUrlDaTela();                           // ler(k) e mudar(patch) sobre useSearchParams + router.push
  const [id = "nome", sentido = "asc"] = (url.ler("ordem") ?? "").split(".").filter(Boolean);
  const table = useTable({
    features, data, columns, getRowId: (row) => row.id,
    state: { sorting: [{ id, desc: sentido === "desc" }], globalFilter: url.ler("q") ?? "" },
    // um clique ordena crescente, outro decrescente; vazio = a ordem de abertura; mudar a ordem volta à página 1
    onSortingChange: (u) => {
      const [s] = functionalUpdate(u, [{ id, desc: sentido === "desc" }]);
      url.mudar({ ordem: !s || (s.id === "nome" && !s.desc) ? undefined : `${s.id}.${s.desc ? "desc" : "asc"}`, pagina: undefined });
    },
  });
  // um filtro por coluna de conjunto fechado; até três à vista, o resto em "Filtros" (3.5)
  const filtros = table.getAllLeafColumns().map((c) => c.columnDef.meta?.filtro).filter(Boolean);

  return (
    // o container da tabela mede a si mesmo: colunas secundárias por @container, nunca por sm:/md:
    <div className="@container/data-table flex flex-col gap-4">
      <div className="flex flex-wrap items-center gap-2">
        <Busca valor={url.ler("q")} onChange={(q) => url.mudar({ q, pagina: undefined }, { replace: true })} />
        {filtros.slice(0, 3).map((f) => (
          <FiltroDeColuna key={f.param} titulo={rotuloDe(f)} opcoes={f.opcoes ?? opcoes[f.param] ?? []} multiplo={f.multiplo}
            valor={url.ler(f.param)} onChange={(v) => url.mudar({ [f.param]: v, pagina: undefined })} />
        ))}
        {filtros.length > 3 && <BotaoFiltros filtros={filtros.slice(3)} />}
        {isFetching && <Spinner aria-label="Carregando" />}
        <div className="ml-auto flex items-center gap-2">
          <DataTableViewOptions table={table} className="hidden @3xl/data-table:flex" />
          {toolbarEnd}
        </div>
      </div>
      <Table>
        <TableHeader>
          {table.getHeaderGroups().map((grupo) => (
            <TableRow key={grupo.id}>
              {grupo.headers.map((h) => {
                const ordem = h.column.getIsSorted();
                // aria-sort acompanha: ascending/descending na ordenada, none nas outras ordenáveis, nada nas demais
                const ariaSort = !h.column.getCanSort() ? undefined : ordem === "asc" ? "ascending" : ordem === "desc" ? "descending" : "none";
                return <TableHead key={h.id} aria-sort={ariaSort} className={h.column.columnDef.meta?.className}>{flexRender(h.column.columnDef.header, h.getContext())}</TableHead>;
              })}
            </TableRow>
          ))}
        </TableHeader>
        {/* corpo: Skeleton na primeira carga, linhas, ou o Empty dentro do card (2.12) */}
      </Table>
      <DataTablePagination table={table} />
    </div>
  );
}

// ---- components/filtro-de-coluna.tsx: até 5 valores, escolha única; acima disso, ou quando o normal é
// combinar valores (Pessoa, Etiquetas), o seletor múltiplo com busca do 2.22 (Popover + Command)
export function FiltroDeColuna({ titulo, opcoes, multiplo, valor, onChange }: FiltroDeColunaProps) {
  if (!multiplo && opcoes.length <= 5) {
    return (
      <Select items={[{ value: null, label: "todos" }, ...opcoes]} value={valor ?? null} onValueChange={(v) => onChange(v ?? undefined)}>
        <SelectTrigger aria-label={titulo} className={cn(valor && "border-primary")}>
          <span className="text-muted-foreground">{titulo}:</span><SelectValue />
        </SelectTrigger>
        <SelectContent>{/* "todos" e as opções */}</SelectContent>
      </Select>
    );
  }
  return <SeletorMultiplo titulo={titulo} opcoes={opcoes} marcados={valor?.split(",") ?? []} onChange={(v) => onChange(v.join(",") || undefined)} />;
}
```

### Skeleton e Spinner

```tsx
import { Skeleton } from "@/components/ui/skeleton";
import { Spinner } from "@/components/ui/spinner";

// primeira carga: o formato do conteúdo final, larguras fixas (nunca Math.random())
{Array.from({ length: 5 }).map((_, i) => (
  <div key={i} className="flex gap-4">
    <Skeleton className="h-4 flex-1" /><Skeleton className="h-4 w-24" /><Skeleton className="h-4 w-16" />
  </div>
))}

// ação em andamento
<Button disabled={isPending}>{isPending && <Spinner data-icon="inline-start" />}Carregar mais</Button>
```

### Estado vazio

```tsx
import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "@/components/ui/empty";

<Empty>
  <EmptyHeader>
    <EmptyMedia variant="icon"><Users /></EmptyMedia>
    <EmptyTitle>Nenhum contato ainda</EmptyTitle>
    <EmptyDescription>Cadastre o primeiro para começar.</EmptyDescription>
  </EmptyHeader>
  <EmptyContent>
    <Button><Plus data-icon="inline-start" />Novo contato</Button>
  </EmptyContent>
</Empty>

// erro ao carregar: o mesmo Empty com CircleAlert e "Tentar de novo" (refetch)
```

### Modal e confirmação

```tsx
import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@/components/ui/dialog";

// o gatilho é o "Novo…" no canto superior direito do card da lista (2.1); o foco volta a ele ao fechar
<CardAction><BotaoNovo rotulo="Nova fila" onClick={() => setOpen(true)} /></CardAction>

<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent className="sm:max-w-lg">   {/* 512px: formulário em duas colunas; o padrão do shadcn tem 384 */}
    <DialogHeader>
      <DialogTitle>Nova fila</DialogTitle>
      <DialogDescription>Defina quem atende e como as conversas são distribuídas.</DialogDescription>
    </DialogHeader>
    {/* o mesmo componente cria e edita; a key remonta o form limpo a cada abertura */}
    <form id="queue-form" key={item?.id ?? "new"} onSubmit={form.handleSubmit(onSubmit)} className="grid gap-4 sm:grid-cols-2">
      …Controllers…
    </form>
    {form.formState.errors.root && (
      <Alert variant="destructive"><AlertDescription>{form.formState.errors.root.message}</AlertDescription></Alert>
    )}
    <DialogFooter>
      <DialogClose render={<Button variant="ghost" />}>Cancelar</DialogClose>
      <Button type="submit" form="queue-form" disabled={form.formState.isSubmitting}>
        {form.formState.isSubmitting && <Spinner data-icon="inline-start" />}Salvar
      </Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

// confirmação destrutiva: AlertDialog, pergunta no título, consequência de uma frase, verbo + objeto
<AlertDialogFooter>
  <AlertDialogCancel>Cancelar</AlertDialogCancel>
  <AlertDialogAction render={<Button variant="destructive" />} onClick={excluir}>Excluir fila</AlertDialogAction>
</AlertDialogFooter>
```

### Menu suspenso (ações da linha)

```tsx
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
import { DataTableRowActions } from "@/components/data-table-row-actions";   // o "…": ghost icon-sm, aria-label e Tooltip

<DropdownMenu>
  <DropdownMenuTrigger render={<DataTableRowActions />} />
  <DropdownMenuContent align="end">
    <DropdownMenuItem onClick={() => editar(row)}><Pencil />Editar</DropdownMenuItem>
    <DropdownMenuItem onClick={() => desativar(row)}><Power />Desativar</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive" onClick={() => setConfirmar(row)}><Trash2 />Excluir…</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

### Shell e item do menu

```tsx
// components/shell/shell.tsx — bloco sidebar-07 (menu) + sidebar-15 (painel da direita)
<SidebarProvider>
  <AppSidebar />                       {/* Sidebar collapsible="icon": logo, grupos do NAV, NavUser no footer */}
  <SidebarInset>                       {/* o <main> da tela */}
    <header className="flex h-16 shrink-0 items-center gap-2 px-6">
      <SidebarTrigger />               {/* com Tooltip "Recolher menu" + <Kbd>Ctrl B</Kbd> */}
      <Separator orientation="vertical" className="h-4" />
      <h1 className="sr-only">{tela.label}</h1>
      <Breadcrumb>…Grupo › Tela…</Breadcrumb>
      <div className="ml-auto flex items-center gap-2">
        {/* indicadores de estado, depois ? · ✨ · sino (2.28, 2.29, 3.11); nada mais */}
        <Ajuda /><AssistenteBotao /><Notificacoes />
      </div>
    </header>
    {/* sem barra de ações (3.3): a primeira box vem logo abaixo do header; o "Novo…" mora no card */}
    {/* com segundo menu (2.27), o layout da área encosta no header e na sidebar: sem o padding daqui */}
    <div className="flex flex-1 flex-col gap-4 px-6 pb-6 has-[[data-slot=segundo-menu]]:p-0">{children}</div>
    <Footer />                         {/* 2.21: uma linha */}
  </SidebarInset>
  <ShellToolbar />                     {/* Sidebar collapsible="none", só de lg para cima; com o assistente (2.29) aberto, dá lugar a ele */}
</SidebarProvider>

// cabeçalho da sidebar (app-sidebar.tsx): duas linhas de 48px, abertas e recolhidas (o topo não muda de altura)
<SidebarHeader>
  <div className="flex h-12 items-center px-2 group-data-[collapsible=icon]:px-0">
    <Link href="/painel" className="flex items-center rounded-md">
      {/* logo completo e ícone com a mesma altura: h-8 (32px) nos dois; versão clara ou escura pelo tema */}
      <ProductLogo variant="completo" className="h-8 w-auto group-data-[collapsible=icon]:hidden" />
      <ProductLogo variant="icone" className="hidden size-8 group-data-[collapsible=icon]:block" />
    </Link>
  </div>
  <div className="flex h-12 items-center">
    <CompanySwitcher {...empresa} />   {/* Troca de empresa: recolhida, o botão encolhe para 32px e a linha fica */}
  </div>
</SidebarHeader>

// item do menu (nav-main.tsx). Ativo CHEIO: no sidebar.tsx o SidebarMenuButton ativo usa
// data-[active=true]:bg-sidebar-primary data-[active=true]:text-sidebar-primary-foreground (nível 3)
<SidebarMenuItem>
  <SidebarMenuButton render={<Link href={item.href} />} isActive={pathname === item.href} tooltip={item.label}>
    <item.icon /><span>{item.label}</span>
  </SidebarMenuButton>
  {item.count > 0 && <SidebarMenuBadge>{item.count}</SidebarMenuBadge>}
</SidebarMenuItem>
```

### Menu do usuário, idioma e tema

```tsx
// nav-user.tsx, no SidebarFooter: o botão (avatar, nome, e-mail, ChevronsUpDown) abre um DropdownMenu
<DropdownMenuContent side={isMobile ? "bottom" : "right"} align="end" className="w-64">
  <DropdownMenuLabel>{/* avatar, nome, e-mail; e "Papel: Sysadmin" só para quem tem um papel */}</DropdownMenuLabel>
  {podeTrocar && <TrocarDePapel />}   {/* quem tem mais de um papel, fora do "Ver como" */}
  <DropdownMenuSeparator />
  <DropdownMenuItem><User />Perfil</DropdownMenuItem>
  <DropdownMenuItem><Settings />Configurações</DropdownMenuItem>
  {ehSysadmin && <DropdownMenuItem><Eye />Ver como…</DropdownMenuItem>}   {/* busca, faixa e volta: ver-como.tsx */}
  <DropdownMenuSeparator />
  <LanguageMenuGroup />   {/* linha "Idioma" + ToggleGroup PT · EN · ES, Tooltip com o nome do idioma */}
  <ThemeMenuGroup />      {/* linha "Tema" + ToggleGroup Sol · Lua */}
  <DropdownMenuSeparator />
  <DropdownMenuItem onClick={sair}><LogOut />Sair</DropdownMenuItem>
</DropdownMenuContent>

// ThemeMenuGroup: o ToggleGroup não é item de menu, então trocar não fecha o menu
const { resolvedTheme, setTheme } = useTheme();
<DropdownMenuGroup className="flex items-center justify-between gap-4 pr-1.5">
  <DropdownMenuLabel>Tema</DropdownMenuLabel>
  <ToggleGroup variant="outline" size="sm" value={[resolvedTheme ?? "light"]}
    onValueChange={(v) => setTheme(v[0] ?? resolvedTheme)}>
    <ToggleGroupItem value="light" aria-label="Claro"><Sun /></ToggleGroupItem>
    <ToggleGroupItem value="dark" aria-label="Escuro"><Moon /></ToggleGroupItem>
  </ToggleGroup>
</DropdownMenuGroup>

// TrocarDePapel (2.16): a linha do papel abre o submenu; o ícone de troca fica no lugar da seta. Escolher fecha o menu,
// grava o papel ativo na sessão (fica até trocar de novo) e remonta a tela; sem a tela no papel novo, vai ao início.
const { papel, papeis, trocarPapel } = useSessao();   // papeis: os da pessoa que entrou; o Sysadmin tem todos
const PAPEIS = { sysadmin: "Sysadmin", dev: "Dev", suporte: "Suporte" } as const;
const PODE_VER = { sysadmin: "Tudo, com a administração e o Ver como", dev: "Tarefas, relatórios e acesso a projetos", suporte: "Contatos, filas, tarefas e relatórios" } as const;

<DropdownMenuSub>
  {/* o SubTrigger sempre põe a seta (ChevronRight) por último: a classe a esconde, sem editar o componente */}
  <DropdownMenuSubTrigger className="[&>svg:last-child]:hidden">
    <IdCard />
    <span className="text-muted-foreground">Papel:</span> <span className="font-medium">{PAPEIS[papel]}</span>
    <ArrowLeftRight className="ml-auto text-muted-foreground" />
  </DropdownMenuSubTrigger>
  <DropdownMenuSubContent className="w-60">
    <DropdownMenuGroup>
      <DropdownMenuLabel>Trocar de papel</DropdownMenuLabel>
      <DropdownMenuRadioGroup value={papel} onValueChange={async (novo) => {
        if (novo === papel) return;
        await trocarPapel(novo);                 // servidor: valida que a pessoa tem o papel e registra na auditoria
        queryClient.invalidateQueries();         // os dados passam a ser os do papel novo
        if (!podeVerTela(pathname, novo)) router.replace("/painel");
        toast.info(`Agora você está como ${PAPEIS[novo]}`);
      }}>
        {papeis.map((p) => (
          <DropdownMenuRadioItem key={p} value={p}>
            <span className="grid">{PAPEIS[p]}<span className="text-xs text-muted-foreground">{PODE_VER[p]}</span></span>
          </DropdownMenuRadioItem>
        ))}
      </DropdownMenuRadioGroup>
    </DropdownMenuGroup>
  </DropdownMenuSubContent>
</DropdownMenuSub>
```

### Login

```tsx
// app/(auth)/login/page.tsx — fora do shell: duas colunas e, debaixo delas, o rodapé na largura toda, já estendido
{/* minmax(0,1fr): com 1fr, o carrossel do rodapé alarga a coluna e a página rola de lado */}
<main className="grid min-h-dvh grid-rows-[auto_1fr_auto] lg:grid-cols-[minmax(0,1fr)_minmax(0,1fr)] lg:grid-rows-[1fr_auto]">
  {/* painel da marca: sempre colorido, nos dois temas (--brand = primária clara); texto branco */}
  <section className="flex flex-col justify-between gap-6 bg-[linear-gradient(135deg,var(--brand),color-mix(in_srgb,var(--brand)_75%,black))] p-6 text-white lg:row-span-2 lg:p-12">
    {/* unoptimized: o logo vai direto do CDN para o navegador; o otimizador da Vercel entra no uso cobrado (1.1) */}
    <Image src={logo.escura} alt="IDeia DevTasks" width={480} height={217} priority unoptimized className="h-8 w-auto self-start" />
    <div className="hidden max-w-md sm:block">
      <h1 className="text-4xl font-bold leading-[44px]">Gestão de tasks para times ágeis</h1>
      <p className="mt-3 text-base text-white/85">Crie tickets com ajuda de IA, acompanhe o progresso no kanban e mantenha seu time alinhado.</p>
    </div>
    <ul className="hidden flex-wrap gap-x-6 gap-y-2 text-sm font-medium lg:flex">
      <li className="flex items-center gap-1.5"><Sparkles className="size-3.6" />Chat IA integrado</li>
      <li className="flex items-center gap-1.5"><Sparkles className="size-3.6" />Kanban configurável</li>
      <li className="flex items-center gap-1.5"><Sparkles className="size-3.6" />SLA automático</li>
    </ul>
  </section>

  {/* coluna do formulário: no tema */}
  <section className="flex flex-col p-6 lg:p-12">
    <form onSubmit={…} className="m-auto grid w-full max-w-sm gap-4">
      <div>
        <h2 className="text-2xl font-semibold">Bem-vindo de volta</h2>
        <p className="text-sm text-muted-foreground">Entre na sua conta para continuar</p>
      </div>
      <Field>…E-mail: InputGroup com <Mail />…</Field>
      <Field>
        <div className="flex items-center justify-between">
          <FieldLabel htmlFor="password">Senha</FieldLabel>
          <Link href="/esqueci-minha-senha" className={buttonVariants({ variant: "link", size: "sm" })}>Esqueci minha senha</Link>
        </div>
        <InputGroup>…senha + botão só de ícone "Mostrar senha"…</InputGroup>
      </Field>
      {erro && <Alert variant="destructive"><AlertDescription>E-mail ou senha incorretos.</AlertDescription></Alert>}
      <Button type="submit" className="w-full" disabled={isPending}>
        {isPending && <Spinner data-icon="inline-start" />}Entrar
      </Button>
      <p className="text-xs text-muted-foreground">Problemas para entrar? Fale com contato@ideiabusiness.com.br.</p>
    </form>
  </section>

  {/* rodapé (2.21) na coluna da direita, embaixo do formulário: estendido, produtos à vista e sem a seta
      (decisão do usuário, 2026-10-27: na largura toda, debaixo das duas colunas, ficou feio).
      No celular o Footer ignora o estendido e fica recolhido com a seta, para não empurrar o formulário */}
  <Footer estendido className="lg:col-start-2" />
</main>
```

### Filtro

```tsx
// seletor múltiplo com busca: Popover + Command; "Eu" fixo no alto; contador no gatilho; aplica ao mudar.
// Ativo: borda na primary e o contador (Badge na primary); o texto fica em foreground (contraste no escuro)
<Popover>
  <PopoverTrigger render={<Button variant="outline" className={cn(marcados.length > 0 && "border-primary")} />}>
    Pessoa{marcados.length > 0 && <Badge>{marcados.length}</Badge>}
    <ChevronDown data-icon="inline-end" />
  </PopoverTrigger>
  <PopoverContent className="w-72 p-0" align="start">
    <Command>
      <CommandInput placeholder="Buscar pessoa" />
      <CommandList>
        <CommandEmpty>Nenhum resultado</CommandEmpty>
        <CommandGroup>
          <CommandItem onSelect={() => alternar("eu")}><Checkbox checked={tem("eu")} />Eu</CommandItem>
          <CommandItem onSelect={() => alternar("sem")}><Checkbox checked={tem("sem")} />Sem dev e sem bola</CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup>
          {pessoas.map((p) => (
            <CommandItem key={p.id} value={p.nome} onSelect={() => alternar(p.id)}><Checkbox checked={tem(p.id)} />{p.nome}</CommandItem>
          ))}
        </CommandGroup>
      </CommandList>
      <div className="flex items-center justify-between border-t px-3 py-2 text-xs text-muted-foreground">
        <span>{marcados.length} marcada(s)</span>
        <Button variant="link" size="sm" onClick={limpar}>Limpar</Button>
      </div>
    </Command>
  </PopoverContent>
</Popover>

// período: um botão só, de 32px, na linha de filtros do card de relatório (2.24); atalhos à esquerda,
// De e Até à direita; aplica ao mudar. Dashboard não tem período (3.1)
<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    <CalendarIcon data-icon="inline-start" />{rotuloDoPeriodo}<ChevronDown data-icon="inline-end" />
  </PopoverTrigger>
  <PopoverContent className="grid w-[440px] grid-cols-[140px_1fr] gap-3 p-3" align="start">
    <ToggleGroup orientation="vertical" value={[atalho]} onValueChange={([v]) => v && aplicarAtalho(v)}>
      {ATALHOS.map((a) => <ToggleGroupItem key={a.id} value={a.id} className="justify-start">{a.rotulo}</ToggleGroupItem>)}
    </ToggleGroup>
    <div className="grid gap-3">
      <CampoDeData label="De" value={de} onChange={setDe} />
      <CampoDeData label="Até" value={ate} onChange={setAte} />
    </div>
  </PopoverContent>
</Popover>

// chip de alternância (ligado = primária cheia) e chip removível com o "×" nomeado
// (o Toggle ligado em bg-primary vem do toggle.tsx, nível 3: o muted do shadcn não tem contraste)
<Toggle variant="outline" pressed={soMeu} onPressedChange={setSoMeu}>Só o que é meu</Toggle>
<Button variant="secondary" size="xs" aria-label="Remover filtro Etiqueta: Bloqueada" onClick={() => remover("etiqueta")}>
  Etiqueta: Bloqueada<X data-icon="inline-end" />
</Button>

// "Filtros · n": Popover no desktop, Sheet side="bottom" no celular, campos em 2 colunas, "Limpar tudo" no rodapé
<Button variant="outline" className={cn(ativos > 0 && "border-primary")} onClick={abrirFiltros}><Filter data-icon="inline-start" />Filtros{ativos > 0 && <Badge>{ativos}</Badge>}</Button>

// estado na URL (Next): tudo o que filtra entra em searchParams e sobrevive a recarregar a página
const params = useSearchParams(); const router = useRouter();
function setFiltro(chave: string, valor?: string) {
  const q = new URLSearchParams(params); valor ? q.set(chave, valor) : q.delete(chave);
  router.replace("?" + q.toString());
}
```

### Rodapé

```tsx
// lib/rodape.ts — só servidor, em SSG: os textos da empresa e os cards vêm da API do guia, lida 1 ou 2 vezes por dia
const API = "https://design-api.ideiabusiness.com.br/api/v1";
export interface Rodape {
  company: { brandName: string; legalName: string; cnpj: string; email: string; title: string; tagline: string; aboutUrl: string };
  products: { slug: string; name: string; description: string; url: string | null; icon: string | null }[];
}
export async function getRodape(): Promise<Rodape | null> {
  try {
    // ?product= o slug deste sistema no guia (list_products): o card dele fica de fora
    const res = await fetch(`${API}/footer?product=ideia-chat`, { next: { revalidate: 43200 } });
    if (!res.ok) return null;                    // só a resposta 200 entra no cache do fetch
    return (await res.json()).data ?? null;
  } catch {
    return null;                                 // API fora e nada guardado: a página segue sem o rodapé
  }
}
// no layout (servidor): const rodape = await getRodape(); … {rodape && <Footer rodape={rodape} />}

// components/shell/footer.tsx — uma linha; a seta, só no clique, estende o próprio rodapé com os produtos,
// no fluxo da página: o rodapé cresce, a página rola até ele e nada fica por cima do conteúdo
// pnpm dlx shadcn@latest add collapsible sheet carousel · pnpm add embla-carousel-autoplay
// sombra só para cima: a shadow-md do Tailwind, invertida
const SOMBRA_CIMA = "shadow-[0_-4px_6px_-1px_rgb(0_0_0/0.1),0_-2px_4px_-2px_rgb(0_0_0/0.1)]";
type Empresa = Rodape["company"];
type Produto = Rodape["products"][number];
const razaoECnpj = (e: Empresa) => `${e.legalName} · CNPJ ${e.cnpj}`;

export function Footer({ rodape, estendido = false, className }: { rodape: Rodape; estendido?: boolean; className?: string }) {
  const { company: empresa, products: produtos } = rodape;
  const isMobile = useIsMobile();          // < 768px: o hook do sidebar do shadcn (hooks/use-mobile.ts)
  const fixo = estendido && !isMobile;     // login no desktop: já vem estendido, sem a seta
  const reduzido = useMediaQuery("(prefers-reduced-motion: reduce)");
  const [open, setOpen] = useState(false);
  const footer = useRef<HTMLElement>(null);
  const seta = useRef<HTMLButtonElement>(null);
  const nomeDaSeta = `Produtos da ${empresa.brandName}`;

  // desktop: ao abrir, a página rola até mostrar o rodapé inteiro (em tela de altura cheia, a área que cresce encolhe)
  useEffect(() => {
    if (open && !isMobile && !fixo) requestAnimationFrame(() => footer.current?.scrollIntoView({ block: "end", behavior: reduzido ? "auto" : "smooth" }));
  }, [open, isMobile, fixo, reduzido]);

  // desktop: Esc, com o foco no rodapé, fecha e devolve o foco à seta. Clicar fora não fecha: o rodapé é parte da página.
  // No celular, quem cuida é o Sheet.
  const onKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === "Escape" && open && !isMobile) { setOpen(false); seta.current?.focus(); }
  };

  if (fixo) {
    // login: a parte estendida faz parte da página (no fluxo), com a linha embaixo e sem a seta
    return (
      <footer className={cn("min-w-0 border-t bg-background px-6 pt-4", SOMBRA_CIMA, className)}>
        <Produtos empresa={empresa} produtos={produtos} />
        <Linha empresa={empresa} />
      </footer>
    );
  }

  return (
    // só no clique: nada de onMouseEnter/onMouseLeave. O cursor de mão vem do globals.css (button { cursor: pointer })
    <Collapsible open={open && !isMobile} onOpenChange={setOpen}
      render={<footer ref={footer} onKeyDown={onKeyDown} className={cn("mt-4 flex min-w-0 flex-col border-t px-6", open && !isMobile && cn("bg-background", SOMBRA_CIMA), className)} />}>
      <Linha empresa={empresa}>
        <Tooltip>
          <TooltipTrigger render={<CollapsibleTrigger ref={seta} render={<Button variant="ghost" size="icon-sm" aria-label={nomeDaSeta} />} />}>
            {open ? <ChevronDown /> : <ChevronUp />}
          </TooltipTrigger>
          <TooltipContent>{nomeDaSeta}</TooltipContent>
        </Tooltip>
      </Linha>
      {/* desktop: a parte estendida entra no fluxo: o rodapé fica mais alto e a página rola até ele; nada por cima do
          conteúdo. Depois da seta no HTML (o Tab entra nos produtos), acima da linha na tela (order-first).
          Fundo da página; borda só em cima; sem raio; sombra só para cima; sem véu */}
      <CollapsibleContent className="order-first pt-4">
        <Produtos empresa={empresa} produtos={produtos} />
      </CollapsibleContent>
      {/* celular: folha de baixo com véu e os cards empilhados; fecha pela seta, com Esc ou tocando fora */}
      <Sheet open={open && isMobile} onOpenChange={setOpen}>
        <SheetContent side="bottom" showCloseButton={false} finalFocus={seta} aria-label={nomeDaSeta}
          className="max-h-[85dvh] overflow-y-auto">
          <div className="p-4"><Produtos empresa={empresa} produtos={produtos} empilhado onClose={() => setOpen(false)} /></div>
        </SheetContent>
      </Sheet>
    </Collapsible>
  );
}

function Linha({ empresa, children }: { empresa: Empresa; children?: React.ReactNode }) {
  return (
    <div className="flex min-h-10 flex-wrap items-center justify-center gap-x-4 gap-y-1 py-3 text-xs text-muted-foreground md:justify-between">
      <span>Um produto da <span className="font-medium text-foreground">{empresa.brandName}</span></span>
      <span className="hidden md:inline">{razaoECnpj(empresa)}</span>
      <span className="flex items-center gap-2"><span className="select-all">{empresa.email}</span>{children}</span>
    </div>
  );
}

const QuemEstaPorTras = ({ href }: { href: string }) => (
  <a href={href} target="_blank" rel="noreferrer" className={buttonVariants({ variant: "link", size: "sm" })}>
    Quem está por trás <ExternalLink /><span className="sr-only"> (abre em outra aba)</span>
  </a>
);

function Produtos({ empresa, produtos, empilhado = false, onClose }: { empresa: Empresa; produtos: Produto[]; empilhado?: boolean; onClose?: () => void }) {
  const reduzido = useMediaQuery("(prefers-reduced-motion: reduce)");
  // card fino (240 × 54): o card inteiro é o link e abre em outra aba; sem "Conhecer" (decisão do usuário, 2026-10-27).
  // Produto sem endereço no cadastro: o card sai sem link
  const card = (p: Produto) => {
    const conteudo = (
      <>
        {p.icon && <Image src={p.icon} alt="" width={32} height={32} unoptimized className="row-span-2 rounded-lg" />}
        <span className="truncate text-sm font-medium">{p.name}</span>
        {p.url && <ExternalLink className="row-span-2 col-start-3 row-start-1 size-3 text-muted-foreground" />}
        <span className="col-start-2 truncate text-xs text-muted-foreground">{p.description}</span>
      </>
    );
    const classes = "relative grid grid-cols-[32px_minmax(0,1fr)_12px] items-center gap-x-3 rounded-lg border bg-card px-3 py-2";
    return p.url
      ? <a href={p.url} target="_blank" rel="noreferrer" className={cn(classes, "transition-colors hover:bg-muted")}>{conteudo}<span className="sr-only"> (abre em outra aba)</span></a>
      : <div className={classes}>{conteudo}</div>;
  };
  return (
    // grid-cols-[minmax(0,1fr)]: uma coluna "auto" cresce até caber o carrossel inteiro numa linha
    <section aria-label={`Produtos da ${empresa.brandName}`} className="grid grid-cols-[minmax(0,1fr)] gap-2 py-3 text-sm">
      {/* título e "Quem está por trás" (no celular, o fechar) na mesma linha; a frase embaixo, na largura toda */}
      <div className="grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-4">
        <h2 className="font-medium">{empresa.title}</h2>
        {onClose
          ? <Button variant="ghost" size="icon-sm" aria-label="Fechar" onClick={onClose}><ChevronDown /></Button>
          : <QuemEstaPorTras href={empresa.aboutUrl} />}
        <p className="col-span-2 text-xs text-muted-foreground">{empresa.tagline}</p>
      </div>
      {empilhado ? (
        <ul className="grid gap-3">{produtos.map((p) => <li key={p.slug}>{card(p)}</li>)}</ul>
      ) : (
        // Carousel do shadcn (embla) + autoplay: passa a cada 4 s em laço, para com o mouse em cima ou foco
        // dentro, sem barra de rolagem; com movimento reduzido, sem o plugin (não passa sozinho)
        <Carousel opts={{ align: "start", loop: true }} className="px-10"
                  plugins={reduzido ? [] : [Autoplay({ delay: 4000, stopOnMouseEnter: true, stopOnFocusIn: true, stopOnInteraction: false })]}>
          <CarouselContent className="-ml-3">
            {produtos.map((p) => <CarouselItem key={p.slug} className="basis-60 pl-3">{card(p)}</CarouselItem>)}
          </CarouselContent>
          {/* as setas para dentro do px-10: no base-nova elas nascem em -left-12/-right-12 e passariam da tela */}
          <CarouselPrevious aria-label="Anterior" className="left-0" />
          <CarouselNext aria-label="Próximo" className="right-0" />
        </Carousel>
      )}
      {/* no celular (folha), embaixo dos cards: "Quem está por trás" e o CNPJ, que a linha não mostra */}
      {empilhado && (
        <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
          <QuemEstaPorTras href={empresa.aboutUrl} />
          <span className="text-xs text-muted-foreground">{razaoECnpj(empresa)}</span>
        </div>
      )}
    </section>
  );
}
```

### Abas

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";

// Abas (2.23): o Tabs do shadcn com variant="line", como vem: lista de 32px sem fundo, rótulo 14/500,
// a ativa em foreground com o sublinhado de 2px. Nada de h-*, px-*, cor ou borda por className.
// Teclado do Base UI: setas movem o foco (voltam ao início), Home e End, Enter ou Espaço abrem a aba.
// A aba vive na URL (setFiltro do 2.22); sem nada na URL, a primeira.
<Tabs value={visao} onValueChange={(v) => setFiltro("visao", v === "produtos" ? undefined : v)}>
  <TabsList variant="line" aria-label="Visão">
    <TabsTrigger value="produtos">Produtos</TabsTrigger>
    <TabsTrigger value="pessoas">Pessoas</TabsTrigger>
    <TabsTrigger value="equipe">Equipe</TabsTrigger>
  </TabsList>
  <TabsContent value="produtos">…</TabsContent>
  <TabsContent value="pessoas">…</TabsContent>
  <TabsContent value="equipe">…</TabsContent>
</Tabs>

// controle segmentado: o mesmo Tabs com variant="default" (trilho em muted, a ativa em background),
// junto do que ele muda: o agrupamento do mesmo gráfico. className="contents" deixa o cabeçalho e o
// conteúdo como filhos do Card, com o espaço dele
<Card>
  <Tabs value={agrupar} onValueChange={setAgrupar} className="contents">
    <CardHeader>
      <CardTitle>Entregas</CardTitle>
      <CardDescription>Toda a equipe, nos últimos 90 dias.</CardDescription>
      <CardAction>
        <TabsList aria-label="Agrupar por">
          <TabsTrigger value="dia">Dia</TabsTrigger>
          <TabsTrigger value="semana">Semana</TabsTrigger>
          <TabsTrigger value="mes">Mês</TabsTrigger>
        </TabsList>
      </CardAction>
    </CardHeader>
    <CardContent><TabsContent value={agrupar}><GraficoDeEntregas agrupar={agrupar} /></TabsContent></CardContent>
  </Tabs>
</Card>

// components/ui/tabs.tsx, nível 3 (4.5): o painel recebe foco (tabIndex 0 do Base UI) e o shadcn tira
// o contorno; o anel de foco do guia volta no TabsContent
function TabsContent({ className, ...props }: TabsPrimitive.Panel.Props) {
  return (
    <TabsPrimitive.Panel
      data-slot="tabs-content"
      className={cn("flex-1 rounded-md text-sm outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", className)}
      {...props}
    />
  );
}
```

### Card de relatório

```tsx
// components/relatorio/card-de-relatorio.tsx: o relatório como um card autossuficiente (2.24).
// Abas no topo, filtros logo abaixo, conteúdo embaixo. Entra em qualquer tela; nada fora do card.
"use client";
import { useQuery } from "@tanstack/react-query";
import { useRouter, useSearchParams } from "next/navigation";
import { Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
import { Spinner } from "@/components/ui/spinner";

export type Visao<D> = {
  id: string; rotulo: string;
  filtros?: string[];                              // os filtros que valem nesta aba (o período vale em todas)
  carregar: (recorte: Recorte) => Promise<D>;
  titulo: string; descricao: (dados: D) => string; // "31 produtos · 13 com entrega vencida"
  Esqueleto: React.ComponentType;                  // Skeleton no formato do conteúdo
  Conteudo: React.ComponentType<{ dados: D }>;
};

// estado na URL; com mais de um card na tela, cada um tem o seu prefixo ("entregas.visao", "entregas.p")
function useUrlDoCard(prefixo?: string) {
  const params = useSearchParams(); const router = useRouter();
  const chave = (k: string) => (prefixo ? `${prefixo}.${k}` : k);
  return {
    ler: (k: string) => params.get(chave(k)) ?? undefined,
    mudar(patch: Record<string, string | undefined>) {
      const q = new URLSearchParams(params);
      for (const [k, v] of Object.entries(patch)) v ? q.set(chave(k), v) : q.delete(chave(k));
      router.push("?" + q.toString(), { scroll: false });   // push: o voltar do navegador desfaz a troca
    },
  };
}

export function CardDeRelatorio({ prefixo, visoes, acao }: { prefixo?: string; visoes: Visao<any>[]; acao?: React.ReactNode }) {
  const url = useUrlDoCard(prefixo);
  const visao = visoes.find((v) => v.id === url.ler("visao")) ?? visoes[0];
  const recorte = { ...periodoDaUrl(url.ler), produto: url.ler("produto") };   // vazio = padrão ("Últimos 30 dias", todos)
  const consulta = useQuery({
    queryKey: ["relatorio", prefixo, visao.id, recorte],
    queryFn: () => visao.carregar(recorte),
    // mudou só o filtro: os dados ficam e o Spinner aparece; aba vista pela primeira vez: Skeleton
    placeholderData: (anterior, q) => (q?.queryKey[2] === visao.id ? anterior : undefined),
    refetchInterval: 60_000,                       // atualiza sozinho (3.8): sem Spinner, sem mudar de lugar
  });

  return (
    <Card>
      {/* className="contents": cabeçalho, filtros e painel ficam filhos do Card, com os 16px dele */}
      <Tabs value={visao.id} onValueChange={(v) => url.mudar({ visao: v === visoes[0].id ? undefined : v })} className="contents">
        {visoes.length > 1 && (
          <CardHeader>
            <div className="overflow-x-auto">       {/* abas não quebram linha: rolam dentro do card */}
              <TabsList variant="line" aria-label="Visão">
                {visoes.map((v) => <TabsTrigger key={v.id} value={v.id}>{v.rotulo}</TabsTrigger>)}
              </TabsList>
            </div>
            {acao && <CardAction>{acao}</CardAction>}
          </CardHeader>
        )}
        <CardContent className="flex flex-wrap items-center gap-2">
          <FiltroDePeriodo valor={recorte} onChange={(p) => url.mudar(periodoParaUrl(p))} />   {/* 2.22, 32px */}
          {visao.filtros?.includes("produto") && (
            <SelectDeFiltro rotulo="Produto" valor={recorte.produto} opcoes={produtos} onChange={(v) => url.mudar({ produto: v })} />
          )}
          {consulta.isFetching && consulta.isPlaceholderData && <Spinner aria-label="Carregando" />}
        </CardContent>
        <TabsContent value={visao.id}>
          <CardContent className="grid gap-4">
            {/* erro: o Empty com circle-alert e "Tentar de novo" (2.12), dentro do card */}
            {consulta.isError && !consulta.data ? (
              <ErroAoCarregar onRetry={() => consulta.refetch()} />
            ) : !consulta.data ? (
              <visao.Esqueleto />
            ) : (
              <>
                <div className="grid gap-1">
                  <CardTitle>{visao.titulo}</CardTitle>
                  <CardDescription>{visao.descricao(consulta.data)}</CardDescription>
                </div>
                <visao.Conteudo dados={consulta.data} />
              </>
            )}
          </CardContent>
        </TabsContent>
      </Tabs>
    </Card>
  );
}

// uso: um card na tela Relatórios (sem prefixo); dois no detalhe de um produto, cada um com o seu
<CardDeRelatorio visoes={[porProduto, porPessoa, daEquipe]} />
<CardDeRelatorio prefixo="entregas" visoes={[entregasDoProduto]} />
<CardDeRelatorio prefixo="conversas" visoes={[conversasPorFila, conversasPorCanal]} />
```

### Troca de empresa: seletor e faixa "Você está em …"

```tsx
// components/shell/company-switcher.tsx: o TeamSwitcher do bloco sidebar-07, no SidebarHeader, logo abaixo do logo
// Três modos: uma empresa só (sem seta e sem menu), lista (DropdownMenu) e busca (Popover + Command, quem alcança todas)
// No fim, a faixa "Você está em …" de quem alcança todas e saiu da empresa principal (faixa-da-empresa.tsx)
type Empresa = { id: string; nome: string; cnpj: string };

function Identidade({ empresa }: { empresa: Empresa }) {
  return (
    <>
      <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-xs font-medium text-sidebar-primary-foreground">
        {iniciais(empresa.nome)}
      </div>
      <div className="grid flex-1 text-left text-sm leading-tight">
        <span className="truncate font-medium">{empresa.nome}</span>
        <span className="truncate text-xs">{empresa.cnpj}</span>
      </div>
    </>
  );
}

export function CompanySwitcher({ ativa, empresas, podeTodas, trocando, onTrocar }: Props) {
  const { isMobile } = useSidebar();
  const lado = isMobile ? "bottom" : "right";
  const [aberto, setAberto] = useState(false);
  // consulta no servidor com 300ms de espera, keepPreviousData e enabled: aberto && podeTodas
  const { texto, setTexto, resultado, buscando } = useBuscaDeEmpresas(aberto && podeTodas);

  // uma empresa só: o mesmo bloco, sem seta e sem menu. Um div, não um botão: não há o que clicar
  if (!podeTodas && empresas.length < 2) {
    return (
      <SidebarMenu>
        <SidebarMenuItem>
          <div className="flex h-12 w-full items-center gap-2 overflow-hidden rounded-md p-2 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-0!">
            <Identidade empresa={ativa} />
          </div>
        </SidebarMenuItem>
      </SidebarMenu>
    );
  }

  const gatilho = (
    // tooltip: o SidebarMenuButton só mostra com a sidebar recolhida (só o avatar à vista), como nos itens do menu
    <SidebarMenuButton size="lg" tooltip={ativa.nome} aria-busy={trocando}
      className="data-popup-open:bg-sidebar-accent data-popup-open:text-sidebar-accent-foreground" />
  );
  const miolo = (
    <>
      <Identidade empresa={ativa} />
      {trocando ? <Spinner className="ml-auto" /> : <ChevronsUpDown className="ml-auto" />}
    </>
  );

  // lista: as empresas da pessoa, a ativa com o Check
  if (!podeTodas) {
    return (
      <SidebarMenu>
        <SidebarMenuItem>
          <DropdownMenu>
            <DropdownMenuTrigger disabled={trocando} render={gatilho}>{miolo}</DropdownMenuTrigger>
            <DropdownMenuContent className="min-w-56" align="start" side={lado} sideOffset={4}>
              <DropdownMenuGroup>
                <DropdownMenuLabel>Empresas</DropdownMenuLabel>
                {empresas.map((e) => (
                  <DropdownMenuItem key={e.id} className="gap-2 p-2" onClick={() => e.id !== ativa.id && onTrocar(e.id)}>
                    <div className="flex size-6 items-center justify-center rounded-md border text-xs">{iniciais(e.nome)}</div>
                    <span className="truncate">{e.nome}</span>
                    {e.id === ativa.id && <Check className="ml-auto" />}
                  </DropdownMenuItem>
                ))}
              </DropdownMenuGroup>
            </DropdownMenuContent>
          </DropdownMenu>
        </SidebarMenuItem>
      </SidebarMenu>
    );
  }

  // busca (quem alcança todas). Popover, e não DropdownMenu: campo dentro de menu do Base UI não recebe o que se
  // digita (o typeahead do menu engole as teclas). Com o popover fechado, a consulta não roda
  return (
    <SidebarMenu>
      <SidebarMenuItem>
        <Popover open={aberto} onOpenChange={setAberto}>
          <PopoverTrigger disabled={trocando} render={gatilho}>{miolo}</PopoverTrigger>
          <PopoverContent className="w-72 gap-0 p-1" align="start" side={lado} sideOffset={4}>
            {/* shouldFilter={false}: quem filtra é o servidor (nome, razão social ou CNPJ), 300ms depois de parar de digitar */}
            <Command shouldFilter={false} label="Trocar de empresa" className="p-0">
              <CommandInput value={texto} onValueChange={setTexto} placeholder="Buscar empresa" aria-label="Buscar empresa" />
              <CommandList>
                {/* primeira carga: Skeleton de 3 linhas; erro: Empty com "Tentar de novo"; nada: Empty "Nenhuma empresa encontrada" */}
                <CommandGroup heading={<span className="flex items-center gap-2">Empresas{buscando && <Spinner className="size-3" />}</span>}>
                  {resultado.map((e) => (
                    <CommandItem key={e.id} value={e.id} aria-checked={e.id === ativa.id} data-checked={e.id === ativa.id || undefined}
                      onSelect={() => { setAberto(false); if (e.id !== ativa.id) onTrocar(e.id); }} className="gap-2 p-2">
                      <div className="flex size-6 items-center justify-center rounded-md border text-xs">{iniciais(e.nome)}</div>
                      <div className="grid min-w-0"><span className="truncate">{e.nome}</span><span className="text-xs">{e.cnpj}</span></div>
                    </CommandItem>
                  ))}
                </CommandGroup>
              </CommandList>
            </Command>
            <Separator className="my-1" />
            {/* fora do Command: não entra nas setas da busca. Link de verdade, com buttonVariants */}
            <Link href="/admin/empresas" onClick={() => setAberto(false)} className={cn(buttonVariants({ variant: "ghost" }), "w-full justify-start")}>
              <Building2 data-icon="inline-start" />Ver todas as empresas
            </Link>
          </PopoverContent>
        </Popover>
      </SidebarMenuItem>
    </SidebarMenu>
  );
}

// quem troca é o Shell: o servidor confirma, a tela remonta limpa e o toast avisa
async function trocar(id: string) {
  await switchCompany(id);                                   // server action: troca a empresa da sessão
  router.replace(rotaDaLista(pathname));                     // a mesma tela, sem query; num detalhe, a lista
  router.refresh();                                          // e o conteúdo vive sob key={empresaAtiva.id}: remonta
  toast.info(`Você está em ${empresas.find((e) => e.id === id)?.nome}`);
}

// components/shell/faixa-da-empresa.tsx — "Você está em …" (2.25): a mesma Faixa do "Ver como" (ver-como.tsx), com
// building-2 e "Voltar para …". A decisão é pura e só usa o que o servidor disse: quem alcança todas, a ativa com nome
// e a empresa principal marcada (sem ela, a faixa cala: não há o que dizer nem para onde voltar)
export function decidirFaixa(sessao: { podeTodas: boolean; ativa: Empresa | null; principal: Empresa | null }) {
  const { podeTodas, ativa, principal } = sessao;
  if (!podeTodas || !ativa || !principal || ativa.id === principal.id) return null;
  return { empresa: ativa.nome, principal };
}

export function FaixaDaEmpresa({ empresa, principal, voltando, onVoltar }: {
  empresa: string; principal: Empresa; voltando: boolean; onVoltar: (id: string) => void;
}) {
  return (
    <Faixa icone={Building2} acao={{ rotulo: `Voltar para ${principal.nome}`, icone: ArrowLeft }} aguardando={voltando} onAcao={() => onVoltar(principal.id)}>
      Você está em <span className="font-medium">{empresa}</span>
    </Faixa>
  );
}

// shell.tsx — fora da key da tela (a faixa é do shell: não remonta, some quando a condição deixa de valer) e fora da
// área de administração (2.30). Com o "Ver como" ligado, as duas no mesmo sticky, a do "Ver como" primeiro (ver-como.tsx)
const faixaDaEmpresa = naAdministracao ? null : decidirFaixa({ podeTodas, ativa: empresaAtiva, principal: empresaPrincipal });
```

### Notificações: o sino e as preferências

```tsx
// components/shell/notificacoes.tsx — o sino (3.11). Referência: ideiachat, components/shell/notificacoes.tsx
const [aberto, setAberto] = useState(false);
const [configurando, setConfigurando] = useState(false);

<Popover open={aberto} onOpenChange={setAberto}>
  <Tooltip>
    <TooltipTrigger render={<PopoverTrigger render={gatilho} />} />   {/* Button ghost icon-sm (a altura do SidebarTrigger) + Badge com as não lidas */}
    <TooltipContent>Notificações</TooltipContent>
  </Tooltip>
  <PopoverContent align="end" className="w-90 gap-0 p-0">          {/* 360px; cabeçalho e lista têm o padding deles */}
    <div className="flex items-center gap-1 border-b py-1.5 pr-1.5 pl-3">
      <PopoverTitle className="flex-1">Notificações</PopoverTitle>
      <Button variant="ghost" size="sm" disabled={naoLidas === 0} onClick={marcarTodas}>Marcar todas como lidas</Button>
      <Tooltip>
        {/* o Dialog não abre por cima de um popover aberto: o sino fecha antes */}
        <TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Configurar notificações"
          onClick={() => { setAberto(false); setConfigurando(true); }} />}>
          <Settings />
        </TooltipTrigger>
        <TooltipContent>Configurar notificações</TooltipContent>
      </Tooltip>
    </div>
    <ListaDeNotificacoes />   {/* ícone do tipo, título, hora relativa, "Ver"; não lida em bg-muted */}
  </PopoverContent>
</Popover>
<PreferenciasDeNotificacao open={configurando} onOpenChange={setConfigurando} />

// components/shell/preferencias-de-notificacao.tsx — de cada pessoa, só as do app; cada switch salva na hora
const CANAIS = [
  { id: "sino", rotulo: "No sino", descricao: "A lista e o contador do sino, e um aviso na tela quando chega." },
  { id: "som", rotulo: "Som", descricao: "Um toque curto quando chega uma notificação." },
] as const;
const TIPOS = [
  { id: "conversas", rotulo: "Novas conversas", descricao: "Quando uma conversa entra numa fila sua." },
  { id: "tarefas", rotulo: "Tarefas atribuídas a mim", descricao: "Quando alguém passa uma tarefa para você." },
  { id: "mencoes", rotulo: "Menções", descricao: "Quando alguém cita você com @." },
] as const;

export function PreferenciasDeNotificacao({ open, onOpenChange }: { open: boolean; onOpenChange: (v: boolean) => void }) {
  const prefs = trpc.me.notificacoes.useQuery();   // do usuário, não da empresa
  const salvar = useSalvarPreferencia();            // otimista; se falhar, o switch volta e sai toast.error
  const linha = (p: { id: Preferencia; rotulo: string; descricao: string }) => (
    <LinhaDePreferencia key={p.id} {...p} checked={!!prefs.data?.[p.id]} onCheckedChange={(v) => salvar.mutate({ [p.id]: v })} />
  );
  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent>   {/* o padrão do shadcn, 384px */}
        <DialogHeader>
          <DialogTitle>Preferências de notificação</DialogTitle>
          <DialogDescription>São suas: valem só para você, em qualquer dispositivo. Cada uma salva na hora.</DialogDescription>
        </DialogHeader>
        <FieldSet>
          <FieldLegend variant="label">Como avisar</FieldLegend>
          <FieldGroup>
            {CANAIS.map(linha)}
            <NotificacaoDoNavegador ligada={!!prefs.data?.navegador} onChange={(navegador) => salvar.mutate({ navegador })} />
          </FieldGroup>
        </FieldSet>
        <FieldSet>
          <FieldLegend variant="label">Avisar sobre</FieldLegend>
          <FieldGroup>{TIPOS.map(linha)}</FieldGroup>
        </FieldSet>
        <p className="text-sm text-muted-foreground">
          Notificações por e-mail ficam no{" "}
          <Link href="/perfil" className="underline underline-offset-4 hover:text-foreground" onClick={() => onOpenChange(false)}>seu perfil</Link>.
        </p>
        <DialogFooter showCloseButton />   {/* só "Fechar": cada switch já salvou */}
      </DialogContent>
    </Dialog>
  );
}

function LinhaDePreferencia({ id, rotulo, descricao, ...props }: { id: string; rotulo: string; descricao: string } & React.ComponentProps<typeof Switch>) {
  return (
    <Field orientation="horizontal">
      <FieldContent>
        <FieldLabel htmlFor={`pref-${id}`}>{rotulo}</FieldLabel>
        <FieldDescription>{descricao}</FieldDescription>
      </FieldContent>
      <Switch id={`pref-${id}`} {...props} />
    </Field>
  );
}

// o pedido de permissão sai do clique no switch: o navegador recusa o pedido que não nasce de um gesto
function NotificacaoDoNavegador({ ligada, onChange }: { ligada: boolean; onChange: (v: boolean) => void }) {
  const [permissao, setPermissao] = useState<NotificationPermission | "sem-suporte">("default");
  useEffect(() => setPermissao("Notification" in window ? Notification.permission : "sem-suporte"), []);   // só no cliente
  const mudar = async (v: boolean) => {
    if (v && permissao !== "granted") {
      const resposta = await Notification.requestPermission();
      setPermissao(resposta);
      if (resposta !== "granted") return;
    }
    onChange(v);
  };
  return (
    <>
      <LinhaDePreferencia id="navegador" rotulo="Notificação do navegador"
        descricao={permissao === "sem-suporte" ? "Este navegador não mostra notificações." : "Aparece mesmo com a aba em segundo plano. O navegador pede a sua permissão."}
        checked={ligada && permissao === "granted"} disabled={permissao === "denied" || permissao === "sem-suporte"} onCheckedChange={mudar} />
      {permissao === "denied" && (
        <Alert variant="warning">
          <AlertDescription>O navegador bloqueou as notificações deste site. Libere nas configurações do navegador para recebê-las.</AlertDescription>
        </Alert>
      )}
    </>
  );
}
```

### Perfil: tela centralizada e foto

```tsx
// app/(app)/perfil/page.tsx — configuração sem tabela: centralizada, até 720px (3.1, D11). Geral segue igual.
<div className="mx-auto flex w-full max-w-180 flex-col gap-4">   {/* max-w-180 = 720px; com tabela, sem o max-w */}
  <Card className="@container/dados">
    <CardHeader>
      <CardTitle>Seus dados</CardTitle>
      <CardDescription>Como você aparece para a equipe.</CardDescription>
    </CardHeader>
    <CardContent className="flex flex-col gap-6">
      <Controller name="foto" control={form.control}
        render={({ field }) => <FotoDoPerfil nome={form.watch("nome")} foto={field.value} onChange={field.onChange} />} />
      <form id="perfil-form" onSubmit={form.handleSubmit(salvar)} className="grid gap-4 @md/dados:grid-cols-2">…Controllers…</form>
    </CardContent>
    <CardFooter className="justify-end gap-2">…Cancelar · Salvar (a foto sobe junto)…</CardFooter>
  </Card>
  <Card>
    <CardHeader><CardTitle>Notificações</CardTitle><CardDescription>Salva na hora.</CardDescription></CardHeader>
    <CardContent>
      {/* só o e-mail; as do app ficam no sino (3.11) */}
      <Field orientation="horizontal">
        <FieldContent>
          <FieldLabel htmlFor="email-notif">Notificações por e-mail</FieldLabel>
          <FieldDescription>Os avisos também chegam em {usuario.email}.</FieldDescription>
        </FieldContent>
        <Switch id="email-notif" checked={prefs.email ?? true} onCheckedChange={(email) => salvar.mutate({ email })} />
      </Field>
    </CardContent>
  </Card>
</div>

// components/perfil/foto-do-perfil.tsx — 96px: o único avatar fora dos tamanhos do shadcn (2.19)
const TIPOS = ["image/jpeg", "image/png", "image/webp"];
const MAXIMO = 5 * 1024 * 1024;

export function FotoDoPerfil({ nome, foto, onChange }: { nome: string; foto: string | null; onChange: (v: string | null) => void }) {
  const arquivo = useRef<HTMLInputElement>(null);
  const [erro, setErro] = useState<string | null>(null);
  const escolher = async (file?: File) => {
    if (!file) return;
    if (!TIPOS.includes(file.type)) return setErro("Use uma imagem JPG, PNG ou WebP.");
    if (file.size > MAXIMO) return setErro("A imagem tem mais de 5 MB. Escolha uma menor.");
    setErro(null);
    onChange(await recortarQuadrado(file, 256));   // a prévia é local; sobe no "Salvar"
  };
  return (
    <div className="flex items-center gap-4">
      <Avatar className="size-24">
        {foto && <AvatarImage src={foto} alt="" />}
        <AvatarFallback className="text-3xl">{iniciais(nome)}</AvatarFallback>
      </Avatar>
      <div className="flex min-w-0 flex-col gap-2">
        <div className="flex gap-2">
          <Button variant="outline" size="sm" onClick={() => arquivo.current?.click()}>Trocar foto</Button>
          {foto && <Button variant="ghost" size="sm" onClick={() => onChange(null)}>Remover</Button>}
        </div>
        {erro ? <FieldError>{erro}</FieldError> : <FieldDescription>JPG, PNG ou WebP, até 5 MB. Aparece redonda.</FieldDescription>}
        <input ref={arquivo} type="file" accept={TIPOS.join(",")} hidden
          onChange={(e) => { void escolher(e.target.files?.[0]); e.target.value = ""; }} />
      </div>
    </div>
  );
}

// lib/recortar-quadrado.ts — o quadrado do centro, no tamanho pedido; o avatar mostra redondo
export async function recortarQuadrado(file: File, lado: number): Promise<string> {
  const img = await createImageBitmap(file);
  const s = Math.min(img.width, img.height);
  const canvas = document.createElement("canvas");
  canvas.width = canvas.height = lado;
  canvas.getContext("2d")!.drawImage(img, (img.width - s) / 2, (img.height - s) / 2, s, s, 0, 0, lado, lado);
  return canvas.toDataURL("image/webp", 0.85);
}
```

### Ver como (Sysadmin): item, busca e faixa

```tsx
// nav-user.tsx — "Ver como…" depois de Configurações, só para o Sysadmin (2.16, D12); com o modo ligado, "Voltar"
const { usuario, quemEntrou, vendoComo, comecar, voltar } = useSessao();   // usuario = quem o sistema está sendo agora
const PAPEL = { sysadmin: "Sysadmin", membro: "Membro" } as const;

<DropdownMenuLabel className="flex items-center gap-2 font-normal">
  <UserAvatar user={usuario} />
  <span className="grid min-w-0 text-left text-sm">
    <span className="truncate font-medium">{usuario.nome}</span>
    <span className="truncate text-xs text-muted-foreground">{usuario.email}</span>
    <span className="text-xs text-muted-foreground">Papel: <span className="font-medium text-foreground">{PAPEL[usuario.papel]}</span></span>
  </span>
</DropdownMenuLabel>
<DropdownMenuSeparator />
<DropdownMenuItem render={<Link href="/perfil" />}><User />Perfil</DropdownMenuItem>
<DropdownMenuItem render={<Link href="/configuracoes" />}><Settings />Configurações</DropdownMenuItem>
{vendoComo
  ? <DropdownMenuItem onClick={voltar}><Undo2 />Voltar ao meu usuário</DropdownMenuItem>
  : quemEntrou.papel === "sysadmin" && <DropdownMenuItem onClick={() => setBuscando(true)}><Eye />Ver como…</DropdownMenuItem>}

// o avatar do rodapé da sidebar, com o anel de atenção enquanto o modo vale (2.19)
<Avatar className={cn(vendoComo && "ring-2 ring-warning ring-offset-2 ring-offset-sidebar")}>…</Avatar>

// ver-como-dialog.tsx — a busca fica num Dialog, fora do menu (campo dentro de menu do Base UI não recebe o que se digita)
<Dialog open={buscando} onOpenChange={setBuscando}>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Ver como</DialogTitle>
      <DialogDescription>O menu e as telas passam a ser os da pessoa escolhida. O que você fizer fica registrado no seu nome.</DialogDescription>
    </DialogHeader>
    <Command className="rounded-lg border">
      <CommandInput placeholder="Buscar por nome ou e-mail" />
      <CommandList>
        <CommandEmpty>Ninguém encontrado.</CommandEmpty>
        {pessoas.filter((p) => p.id !== quemEntrou.id).map((p) => (
          <CommandItem key={p.id} value={`${p.nome} ${p.email}`} onSelect={() => { setBuscando(false); comecar.mutate(p.id); }}>
            <UserAvatar user={p} size="sm" />
            <span className="grid min-w-0">
              <span className="truncate">{p.nome}</span>
              <span className="truncate text-xs text-muted-foreground">{p.email}</span>
            </span>
            <span className="ml-auto text-xs text-muted-foreground">{PAPEL[p.papel]}</span>
          </CommandItem>
        ))}
      </CommandList>
    </Command>
  </DialogContent>
</Dialog>
// comecar e voltar: a sessão no servidor passa a ter as duas pessoas; ao voltar, queryClient.clear() e a tela remonta.
// "Sair" encerra a sessão e o modo junto: quem entra de novo entra como si mesmo.

// components/shell/faixa.tsx — a faixa do shell: no SidebarInset, antes do header, na largura da coluna de conteúdo.
// Serve ao "Ver como" (2.16) e à troca de empresa (2.25, troca-de-empresa.tsx): a mesma faixa, com outro ícone e outro botão
export function Faixa({ icone: Icone, acao, onAcao, aguardando, children }: {
  icone: LucideIcon; acao: { rotulo: string; icone: LucideIcon }; onAcao: () => void; aguardando?: boolean; children: ReactNode;
}) {
  const isMobile = useIsMobile();
  const IconeDaAcao = acao.icone;
  return (
    <div role="status" className="flex h-10 items-center gap-2 border-b border-warning/30 bg-warning/12 px-6 text-sm text-warning-strong">
      <Icone className="shrink-0" />
      <span className="min-w-0 flex-1 truncate">{children}</span>
      {isMobile ? (
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label={acao.rotulo} disabled={aguardando} onClick={onAcao} />}>
            {aguardando ? <Spinner /> : <IconeDaAcao />}
          </TooltipTrigger>
          <TooltipContent>{acao.rotulo}</TooltipContent>
        </Tooltip>
      ) : (
        <Button variant="outline" size="sm" disabled={aguardando} onClick={onAcao}>
          {aguardando ? <Spinner data-icon="inline-start" /> : <IconeDaAcao data-icon="inline-start" />}{acao.rotulo}
        </Button>
      )}
    </div>
  );
}

// components/shell/faixa-ver-como.tsx
export function FaixaVerComo({ nome, onVoltar }: { nome: string; onVoltar: () => void }) {
  return (
    <Faixa icone={Eye} acao={{ rotulo: "Voltar ao meu usuário", icone: Undo2 }} onAcao={onVoltar}>
      Você está vendo como <span className="font-medium">{nome}</span>
    </Faixa>
  );
}

// shell.tsx — as faixas antes do header, num só sticky com o fundo opaco por baixo da tinta (o conteúdo rola por trás).
// Com as duas ligadas, uma embaixo da outra: a do "Ver como" primeiro, depois a da empresa (2.25)
<SidebarInset>
  {(vendoComo || faixaDaEmpresa) && (
    <div className="sticky top-0 z-20 bg-background">
      {vendoComo && <FaixaVerComo nome={usuario.nome} onVoltar={voltar} />}
      {faixaDaEmpresa && <FaixaDaEmpresa {...faixaDaEmpresa} voltando={trocando} onVoltar={trocar} />}
    </div>
  )}
  <header …>
```

### Kanban: altura cheia, quadro e card da tarefa

```tsx
// components/kanban/quadro.tsx: o kanban de altura cheia (2.26). Todo kanban de todo produto segue isto.
// A página não rola; o quadro rola na horizontal, com a barra à vista, e cada coluna na vertical, com o cabeçalho parado.
"use client";
import { useEffect, useState } from "react";
import { Ban, Clock, List, MoveRight, Pencil, Plus, SquareKanban, Trash2, User } from "lucide-react";
import { Avatar, AvatarFallback } from "@/components/ui/avatar";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Card, CardAction, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import {
  DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator,
  DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
import { Progress } from "@/components/ui/progress";
import { Toggle } from "@/components/ui/toggle";
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
import { DataTableRowActions } from "@/components/data-table-row-actions";   // o "…" da tabela: ghost icon-sm, aria-label e Tooltip
import { toast } from "@/lib/toast";
import { cn } from "@/lib/utils";

export type Coluna = { id: string; nome: string; cor: string };   // cor: um token ("var(--info)") ou a cor do banco
export type Tarefa = {
  id: string; codigo: string; titulo: string; status: string; tipo: string; produto: string;
  bloqueada: boolean; subtarefas: [feitas: number, total: number]; prazo?: Prazo; responsavel?: Pessoa;
};

// 1. altura cheia (3.1): no shell (2.15), o SidebarInset passa a ter a altura da janela quando a tela pede.
//    A faixa do "Ver como", o header e o rodapé ficam com a altura deles; o conteúdo leva o resto.
<SidebarInset className="has-data-[altura=cheia]:h-svh has-data-[altura=cheia]:min-h-140">   {/* 560px no mínimo */}
  {/* …faixa do Ver como, header… */}
  <div className="flex min-h-0 flex-1 flex-col gap-4 px-6 pb-6">{children}</div>              {/* min-h-0: o card encolhe */}
  <Footer />
</SidebarInset>

// 2. a tela: o card ocupa o que sobra; dentro dele, a barra (3.5), o quadro e a contagem
export function TelaKanban({ colunas, tarefas, compacto, ...barra }: TelaKanbanProps) {
  const mover = useMover(colunas);
  return (
    <Card data-altura="cheia" className="@container min-h-0 flex-1">   {/* layout, não tamanho: o Card fica como vem */}
      <CardContent className="flex min-h-0 flex-1 flex-col gap-4">
        <BarraDoQuadro compacto={compacto} {...barra} />
        <Quadro colunas={colunas} tarefas={tarefas} compacto={compacto} onMover={mover} />
        <p className="text-xs text-muted-foreground">{tarefas.length} tarefas</p>
      </CardContent>
    </Card>
  );
}

// 3. a barra (D1): à esquerda a busca, até três filtros, "Filtros", os chips, Lista/Kanban e Compacto;
//    à direita só Ordenar e "Nova tarefa". No celular: busca, "Filtros" e o "+"; o resto vai para o fim da folha.
function BarraDoQuadro({ visao, compacto, soMeu, ocultar, mudar, onNova }: BarraProps) {
  return (
    <div className="grid gap-2">
      <div className="flex flex-wrap items-center gap-2">
        <BuscaDaBox placeholder="Buscar por título ou código" />
        <SelectDeFiltro rotulo="Status" /><SelectDeFiltro rotulo="Produto" /><FiltroDePessoa />   {/* 2.22 */}
        <BotaoFiltros />
        <Button className="ml-auto" onClick={onNova}><Plus data-icon="inline-start" />Nova tarefa</Button>
      </div>
      <div className="flex flex-wrap items-center gap-2">
        <Toggle variant="outline" pressed={soMeu} onPressedChange={(v) => mudar({ meu: v })}><User />Só o que é meu</Toggle>
        <Toggle variant="outline" pressed={ocultar} onPressedChange={(v) => mudar({ ocultar: v })}>Ocultar concluídas</Toggle>
        <ToggleGroup variant="outline" aria-label="Exibição" value={[visao]} onValueChange={([v]) => v && mudar({ visao: v })}>
          <ToggleGroupItem value="lista" aria-label="Lista"><List /></ToggleGroupItem>        {/* com Tooltip (2.8) */}
          <ToggleGroupItem value="kanban" aria-label="Kanban"><SquareKanban /></ToggleGroupItem>
        </ToggleGroup>
        <Toggle variant="outline" pressed={compacto} onPressedChange={(v) => mudar({ compacto: v })}>Compacto</Toggle>
        <SelectDeOrdem className="ml-auto" />
      </div>
    </div>
  );
}

// 4. o quadro: de borda a borda do card, rola na horizontal com a barra à vista (10px, polegar em input, 3:1);
//    no contêiner estreito (celular), cada coluna tem 60% da largura: cerca de 1,5 coluna à vista, com encaixe
function Quadro({ colunas, tarefas, compacto, onMover }: QuadroProps) {
  const [arrastando, setArrastando] = useState<string | null>(null);
  const [sobre, setSobre] = useState<string | null>(null);
  return (
    <div role="region" aria-label="Quadro de tarefas" className={cn(
      "-mx-4 grid min-h-0 flex-1 auto-cols-[minmax(18rem,1fr)] grid-flow-col grid-rows-[minmax(0,1fr)] gap-3 overflow-x-auto overflow-y-hidden px-4 pb-2 scroll-px-4",
      "@max-2xl:auto-cols-[60%] @max-2xl:snap-x @max-2xl:snap-mandatory",
      "[&::-webkit-scrollbar]:h-2.5 [&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:border [&::-webkit-scrollbar-thumb]:border-card [&::-webkit-scrollbar-thumb]:bg-input",
    )}>
      {colunas.map((c) => {
        const itens = tarefas.filter((t) => t.status === c.id);
        return (
          <section key={c.id} data-coluna={c.id} aria-labelledby={`coluna-${c.id}`}
            onDragOver={(e) => { if (!arrastando) return; e.preventDefault(); e.dataTransfer.dropEffect = "move"; setSobre(c.id); }}
            onDragLeave={(e) => { if (!e.currentTarget.contains(e.relatedTarget as Node)) setSobre(null); }}
            onDrop={(e) => {
              e.preventDefault(); setSobre(null);
              const t = tarefas.find((x) => x.id === e.dataTransfer.getData("text/plain"));
              if (t) onMover(t, c.id);
            }}
            className={cn("flex min-h-0 snap-start flex-col gap-2 rounded-xl bg-muted p-2", sobre === c.id && "ring-2 ring-ring ring-inset")}>
            {/* cabeçalho parado: fica fora da lista que rola */}
            <h2 id={`coluna-${c.id}`} className="flex shrink-0 items-center gap-2 px-1.5 py-1 text-sm font-medium">
              <span aria-hidden className="size-2.5 shrink-0 rounded-full" style={{ background: c.cor }} />
              {c.nome}
              <Badge variant="outline" className="ml-auto bg-card tabular-nums">{itens.length}</Badge>
            </h2>
            <div className="grid min-h-0 flex-1 content-start gap-2 overflow-y-auto">   {/* só a lista rola */}
              {itens.length ? itens.map((t) => (
                <CartaoDaTarefa key={t.id} tarefa={t} colunas={colunas} compacto={compacto}
                  arrastando={arrastando === t.id} onArrastar={setArrastando} onMover={onMover} />
              )) : (
                <p className="rounded-lg border border-dashed border-input px-3 py-6 text-center text-xs text-muted-foreground">
                  Arraste tarefas para cá
                </p>
              )}
            </div>
          </section>
        );
      })}
    </div>
  );
}

// 5. o card da tarefa: o Card size="sm" (12px), arrastável. Tudo o que o arrastar faz também está no "…"
function CartaoDaTarefa({ tarefa: t, colunas, compacto, arrastando, onArrastar, onMover }: CartaoProps) {
  const [feitas, total] = t.subtarefas;
  return (
    <Card size="sm" data-tarefa={t.id} draggable
      onDragStart={(e) => { e.dataTransfer.setData("text/plain", t.id); e.dataTransfer.effectAllowed = "move"; onArrastar(t.id); }}
      onDragEnd={() => onArrastar(null)}
      className={cn("cursor-grab active:cursor-grabbing", arrastando && "opacity-40", t.bloqueada && "border-l-3 border-l-destructive")}>
      <CardHeader>
        <span className="font-mono text-xs text-muted-foreground">{t.codigo}</span>
        <CardAction>
          <DropdownMenu>
            <DropdownMenuTrigger render={<DataTableRowActions label={`Ações de ${t.codigo}`} />} />
            <DropdownMenuContent align="end">
              <DropdownMenuItem onClick={() => abrir(t)}><Pencil />Editar</DropdownMenuItem>
              <DropdownMenuSub>   {/* o caminho de quem usa teclado, e do celular */}
                <DropdownMenuSubTrigger><MoveRight />Mover para</DropdownMenuSubTrigger>
                <DropdownMenuSubContent>
                  {colunas.filter((c) => c.id !== t.status).map((c) => (
                    <DropdownMenuItem key={c.id} onClick={() => onMover(t, c.id, { foco: true })}>{c.nome}</DropdownMenuItem>
                  ))}
                </DropdownMenuSubContent>
              </DropdownMenuSub>
              <DropdownMenuItem onClick={() => bloquear(t)}><Ban />{t.bloqueada ? "Desbloquear" : "Marcar como bloqueada"}</DropdownMenuItem>
              <DropdownMenuSeparator />
              <DropdownMenuItem variant="destructive" onClick={() => excluir(t)}><Trash2 />Excluir…</DropdownMenuItem>
            </DropdownMenuContent>
          </DropdownMenu>
        </CardAction>
        <CardTitle>   {/* 14/500 no size="sm"; até 2 linhas */}
          <button type="button" className="line-clamp-2 text-left hover:underline" onClick={() => abrir(t)}>{t.titulo}</button>
        </CardTitle>
      </CardHeader>
      <CardContent className="grid gap-2">
        {!compacto && (
          <>
            <div className="flex flex-wrap items-center gap-2">
              <Badge variant={t.tipo === "bug" ? "danger" : t.tipo === "melhoria" ? "info" : "secondary"}>{rotuloDoTipo(t.tipo)}</Badge>
              <ProdutoChip slug={t.produto} />
              {t.bloqueada && <Badge variant="danger"><Ban data-icon="inline-start" />Bloqueada</Badge>}
            </div>
            {total > 0 && (
              <div className="flex items-center gap-2">
                <Progress value={(feitas / total) * 100} aria-label={`${feitas} de ${total} subtarefas`} className="flex-1" />
                <span className="text-xs tabular-nums text-muted-foreground">{feitas}/{total}</span>
              </div>
            )}
            {t.prazo && <Badge variant={t.prazo.tom} className="justify-self-start"><Clock data-icon="inline-start" />{t.prazo.rotulo}</Badge>}
          </>
        )}
        {compacto && t.bloqueada && <Badge variant="danger" className="justify-self-start"><Ban data-icon="inline-start" />Bloqueada</Badge>}
        <div className="flex min-w-0 items-center gap-2">
          {t.responsavel ? (
            <><Avatar size="sm"><AvatarFallback>{t.responsavel.iniciais}</AvatarFallback></Avatar><span className="truncate text-xs">{t.responsavel.nome}</span></>
          ) : <span className="text-xs text-muted-foreground">Sem responsável</span>}
        </div>
      </CardContent>
    </Card>
  );
}

// 6. mover: otimista, no topo da coluna nova, com "Desfazer"; o servidor recusou, o card volta e o toast avisa.
//    Depois de mover, o quadro e a coluna rolam até o card (a página não), e pelo teclado o foco volta ao "…" dele:
//    o Base UI devolve o foco ao gatilho do menu, que saiu da coluna antiga junto com o card.
function useMover(colunas: Coluna[]) {
  const mutacao = useMoverTarefa();             // useMutation: onMutate põe a tarefa no topo da coluna; onError desfaz
  const [movida, setMovida] = useState<{ id: string; para: string; foco: boolean } | null>(null);
  useEffect(() => {                             // depois de cada render, até o card aparecer na coluna nova
    if (!movida) return;
    const el = document.querySelector<HTMLElement>(`[data-coluna="${movida.para}"] [data-tarefa="${movida.id}"]`);
    if (!el) return;
    el.scrollIntoView({ block: "nearest", inline: "nearest" });
    if (movida.foco) el.querySelector<HTMLElement>("[data-slot=card-action] button")?.focus();
    setMovida(null);
  });
  function mover(t: Tarefa, para: string, { foco = false } = {}) {
    const de = t.status;
    mutacao.mutate({ id: t.id, status: para }, {
      onSuccess: () => toast.success(`Movida para ${colunas.find((c) => c.id === para)?.nome}`, {
        description: t.codigo,
        action: { label: "Desfazer", onClick: () => mutacao.mutate({ id: t.id, status: de }) },   // volta coluna e posição
      }),
      onError: () => toast.error("Não foi possível mover. Tente de novo."),
    });
    setMovida({ id: t.id, para, foco });
  }
  return mover;
}
```

### Listagem em duas etapas

```tsx
// app/(painel)/acesso/page.tsx: listagem em duas etapas (3.18). Um card só: a etapa 1 lista as pessoas e a
// etapa 2 é a tabela de repositórios da escolhida. A escolha mora na URL (?pessoa=). A etapa 1 continua
// montada, escondida: a volta a encontra como ficou (busca, filtros, ordem e página), sem Skeleton de novo.
"use client";
import { useEffect, useRef, useState } from "react";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
import { ArrowLeft, ChevronRight } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
import { useTerceiroNivel } from "@/components/shell/breadcrumb";
import { cn } from "@/lib/utils";

// os parâmetros da etapa 2 têm nome próprio: voltar tira só estes, e os da etapa 1 (q, cargo, ordem, pagina) ficam
const DA_ETAPA_2 = ["pessoa", "rq", "origem", "acesso", "rordem", "rpagina"];

export default function AcessoAProjetos() {
  const params = useSearchParams(); const router = useRouter(); const pathname = usePathname();
  const pessoaId = params.get("pessoa");
  const pessoa = usePessoa(pessoaId);                    // useQuery; null = não existe mais
  const [saindo, setSaindo] = useState<string | null>(null);
  const mostrada = pessoaId ?? saindo;                   // a etapa 2 fica na tela enquanto desliza para fora
  const titulo = useRef<HTMLHeadingElement>(null);
  const anterior = useRef(pessoaId);

  const semEtapa2 = () => { const q = new URLSearchParams(params); DA_ETAPA_2.forEach((k) => q.delete(k)); return q; };
  // push nos dois sentidos: o voltar do navegador desfaz a ida, e o link abre direto na etapa 2
  const ir = (id: string) => { const q = new URLSearchParams(params); q.set("pessoa", id); router.push(`${pathname}?${q}`, { scroll: false }); };
  const voltar = () => router.push(`${pathname}?${semEtapa2()}`, { scroll: false });

  // breadcrumb com o terceiro nível: "Configurações da empresa › Acesso a projetos › Ana Ribeiro";
  // o nível do meio vira link para a etapa 1, e o título da aba acompanha
  useTerceiroNivel(pessoaId ? { rotulo: pessoa?.nome ?? "…", href: `${pathname}?${semEtapa2()}` } : null);

  // foco nos dois sentidos, também pelo voltar e pelo avançar do navegador (quem muda é a URL).
  // Sem Esc: ele fecha camadas, e a etapa 2 não é camada (D9)
  useEffect(() => {
    const de = anterior.current; anterior.current = pessoaId;
    if (de === pessoaId) return;
    if (pessoaId) { titulo.current?.focus(); return; }
    setSaindo(de);
    // volta à ação da linha de origem; se ela não está mais na página, à busca da etapa 1
    (document.querySelector<HTMLElement>(`[data-pessoa="${de}"]`) ?? document.getElementById("busca-pessoas"))?.focus();
    const t = setTimeout(() => setSaindo(null), 200);
    return () => clearTimeout(t);
  }, [pessoaId]);

  // desliza em 200ms (1.7): quem sai vai para o lado, fora do fluxo, e some no fim (visibility muda no fim da
  // transição); quem entra parte do lado (@starting-style). Movimento reduzido: troca sem animação.
  const painel = "min-w-0 transition-[translate,visibility] duration-200 ease-out motion-reduce:transition-none";
  const fora = "invisible absolute inset-x-0 top-0";
  return (
    <Card>
      <CardContent className="relative overflow-x-clip">
        <section aria-label="Pessoas" inert={!!pessoaId} className={cn(painel, pessoaId ? `${fora} -translate-x-full` : "starting:-translate-x-full")}>
          {/* a tabela de dados completa (2.10): busca (id="busca-pessoas"), Nome, E-mail, Cargo e
              "Repositórios com acesso" ordenáveis, filtro Cargo (8 valores: seletor múltiplo), paginação */}
          <TabelaDePessoas
            acao={(p) => (
              // o único botão da linha; o nome da pessoa vai no nome acessível. A linha inteira também abre
              <Button variant="ghost" size="sm" data-pessoa={p.id} aria-label={`Ver acessos de ${p.nome}`} onClick={() => ir(p.id)}>
                Ver acessos<ChevronRight data-icon="inline-end" />
              </Button>
            )}
            onLinha={(p) => ir(p.id)}
          />
        </section>

        {mostrada && (
          <section inert={!pessoaId} className={cn(painel, pessoaId ? "starting:translate-x-full" : `${fora} translate-x-full`)}>
            <CardHeader className="px-0">
              <Button variant="ghost" size="sm" className="justify-self-start" aria-label="Voltar para Pessoas" onClick={voltar}>
                <ArrowLeft data-icon="inline-start" />Pessoas
              </Button>
              {/* o título recebe o foco ao chegar; o anel aparece só se a ida foi pelo teclado (:focus-visible) */}
              <CardTitle><h2 ref={titulo} tabIndex={-1}>{pessoa === null ? "Pessoa não encontrada" : `Repositórios de ${pessoa?.nome ?? "…"}`}</h2></CardTitle>
              <CardDescription>{pessoa === null ? "Ela pode ter saído da empresa. Volte e escolha outra." : `${pessoa?.comAcesso ?? "…"} com acesso · ${catalogo} no catálogo`}</CardDescription>
            </CardHeader>
            {/* a tabela da escolha, também completa, com os parâmetros próprios (rq, origem, acesso, rordem, rpagina) */}
            {pessoa && <RepositoriosDaPessoa key={pessoa.id} pessoa={pessoa} />}
          </section>
        )}
      </CardContent>
    </Card>
  );
}

// components/shell/breadcrumb.tsx: o shell monta "Grupo › Tela › Escolha"; com o terceiro nível, a tela é link
export function BreadcrumbDoShell({ grupo, tela, terceiro }: { grupo?: string; tela: string; terceiro: Nivel | null }) {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        {grupo && <><BreadcrumbItem className="hidden @2xl/header:block">{grupo}</BreadcrumbItem><BreadcrumbSeparator className="hidden @2xl/header:block" /></>}
        <BreadcrumbItem>{terceiro ? <BreadcrumbLink render={<Link href={terceiro.href} />}>{tela}</BreadcrumbLink> : <BreadcrumbPage>{tela}</BreadcrumbPage>}</BreadcrumbItem>
        {terceiro && <><BreadcrumbSeparator /><BreadcrumbItem><BreadcrumbPage className="truncate">{terceiro.rotulo}</BreadcrumbPage></BreadcrumbItem></>}
      </BreadcrumbList>
    </Breadcrumb>
  );
}
```

### Segundo menu

```tsx
// app/(painel)/configuracoes/layout.tsx — o segundo menu (2.27): as seções da área, abaixo do header.
// Cada seção é uma rota (/configuracoes/tags); o "Geral" da sidebar continua ativo em qualquer uma
// (no nav-main, isActive={pathname.startsWith("/configuracoes")}). O breadcrumb do shell ganha o
// terceiro nível: "Configurações da empresa › Geral › Tags", com "Geral" como link para a primeira.
const SECOES = [
  { grupo: "Atendimento", itens: [
    { href: "/configuracoes/tags", rotulo: "Tags" },
    { href: "/configuracoes/campos-personalizados", rotulo: "Campos personalizados" },
    { href: "/configuracoes/respostas-rapidas", rotulo: "Respostas rápidas" },
  ] },
  { grupo: "Regras", itens: [
    { href: "/configuracoes/identificacao", rotulo: "Identificação" },
    { href: "/configuracoes/sla", rotulo: "SLA" },
  ] },
  { grupo: "Integrações", itens: [
    { href: "/configuracoes/api-keys", rotulo: "API Keys" },
    { href: "/configuracoes/webhooks", rotulo: "Webhooks" },
  ] },
] as const;   // seção sem permissão sai daqui (e o grupo vazio some), como no menu (3.2)

export default function ConfiguracoesLayout({ children }: { children: React.ReactNode }) {
  return (
    // encosta na sidebar e no header: no shell.tsx, o contêiner do conteúdo perde o padding com
    // has-[[data-slot=segundo-menu]]:p-0, e o padding volta aqui, só na coluna do conteúdo
    <div className="flex flex-1">
      <SegundoMenu rotulo="Seções de Geral" />
      <div className="flex min-w-0 flex-1 flex-col gap-4 px-6 pb-6 lg:pt-4">
        <SeletorDeSecao />   {/* abaixo de 1024px, no lugar do segundo menu */}
        {children}           {/* a seção, na largura toda: listagem (card + tabela + "Nova tag") ou formulário (cards, campos em 2 colunas) */}
      </div>
    </div>
  );
}

// 224px, fundo muted, borda à direita; parado enquanto o conteúdo rola (sticky abaixo do header de 64px)
function SegundoMenu({ rotulo }: { rotulo: string }) {
  const pathname = usePathname();
  return (
    <nav data-slot="segundo-menu" aria-label={rotulo}
      className="sticky top-16 hidden max-h-[calc(100svh-(--spacing(16)))] w-56 shrink-0 flex-col gap-1 self-start overflow-y-auto border-r bg-muted p-2 lg:flex">
      {SECOES.map((g) => (
        <div key={g.grupo} role="group" aria-labelledby={`sm-${g.grupo}`} className="flex flex-col gap-1">
          <div id={`sm-${g.grupo}`} className="px-2 pt-2 pb-1 text-xs font-medium text-muted-foreground">{g.grupo}</div>
          {g.itens.map((s) => {
            const ativa = pathname === s.href;
            return (
              // a altura e o padding vêm do Button (variant ghost, size padrão: 32px); o ativo é leve,
              // em card com o contorno edge, sem a primária (ela fica no "Geral" da sidebar)
              <Link key={s.href} href={s.href} aria-current={ativa ? "page" : undefined}
                className={cn(buttonVariants({ variant: "ghost" }), "w-full justify-start font-normal hover:bg-card/50",
                  ativa && "bg-card font-medium ring-1 ring-foreground/10 hover:bg-card")}>
                {s.rotulo}
              </Link>
            );
          })}
        </div>
      ))}
    </nav>
  );
}

// abaixo de 1024px: um Select "Seção" com os mesmos grupos; escolher navega
function SeletorDeSecao() {
  const pathname = usePathname();
  const router = useRouter();
  const itens = SECOES.flatMap((g) => g.itens.map((s) => ({ value: s.href, label: s.rotulo })));
  return (
    <Field className="lg:hidden">
      <FieldLabel htmlFor="secao">Seção</FieldLabel>
      <Select items={itens} value={pathname} onValueChange={(href) => href && router.push(href)}>
        <SelectTrigger id="secao" className="w-full"><SelectValue /></SelectTrigger>
        <SelectContent>
          {SECOES.map((g) => (
            <SelectGroup key={g.grupo}>
              <SelectLabel>{g.grupo}</SelectLabel>
              {g.itens.map((s) => <SelectItem key={s.href} value={s.href}>{s.rotulo}</SelectItem>)}
            </SelectGroup>
          ))}
        </SelectContent>
      </Select>
    </Field>
  );
}

// app/(painel)/configuracoes/page.tsx — o item sem seção abre a primeira
export default function Configuracoes() { redirect("/configuracoes/tags"); }
```

### Passo a passo da tela e ajuda

```tsx
// Passo a passo da tela e ajuda (2.28). driver.js (MIT): pnpm add driver.js
// No globals.css, o css dele entra numa camada abaixo dos utilitários, para as classes do guia valerem:
//   @import "driver.js/dist/driver.css" layer(base);

// app/(painel)/contatos/passo-a-passo.ts — mora com a tela: de 3 a 5 passos, presos por data-tour,
// textos do i18n. Mudou a tela a ponto de o passo a passo mudar: sobe a versão (o convite volta uma vez).
export const passoAPassoContatos: PassoAPasso = {
  id: "contatos", versao: 1, passos: [
    { tour: "busca", titulo: "tour.contatos.busca.titulo", texto: "tour.contatos.busca.texto" },
    { tour: "filtros", titulo: "tour.contatos.filtros.titulo", texto: "tour.contatos.filtros.texto" },
    { tour: "novo", titulo: "tour.contatos.novo.titulo", texto: "tour.contatos.novo.texto" },
    { tour: "acoes", titulo: "tour.contatos.acoes.titulo", texto: "tour.contatos.acoes.texto" },
    // o último é sempre o "?": "Para rever este passo a passo, é aqui."
    { tour: "ajuda", titulo: "tour.rever.titulo", texto: "tour.rever.texto" },
  ],
};
// na tela: <Card data-tour="busca">…  <Button data-tour="novo">…   e o registro no shell:
useRegistrarPassoAPasso(passoAPassoContatos);

// components/shell/passo-a-passo.ts — o cartão é o PopoverContent e os botões são o Button: as classes
// vêm deles (popoverClasses é a string do PopoverContent; buttonVariants, a do Button), sem valor à mão.
// Vale para o driver.js 1.10: o clique dos botões depende das classes driver-popover-*-btn (somar, nunca trocar).
export function comecarPassoAPasso(p: PassoAPasso, t: T, aoSair: (estado: "visto" | "concluido") => void) {
  const reduzido = matchMedia("(prefers-reduced-motion: reduce)").matches;
  const visiveis = p.passos.filter((s) => document.querySelector(`[data-tour="${s.tour}"]`)?.checkVisibility()); // fora da tela: pula
  const voltarPara = document.activeElement as HTMLElement | null;
  const botao = (b: HTMLButtonElement, doDriver: string, classes: string, rotulo: string, mostrar: boolean) => {
    b.className = cn(doDriver, classes); b.textContent = rotulo; b.style.display = mostrar ? "" : "none";
  };
  const d = driver({
    steps: visiveis.map((s) => ({ element: `[data-tour="${s.tour}"]`, popover: { title: t(s.titulo), description: t(s.texto) } })),
    animate: !reduzido, smoothScroll: !reduzido, duration: 200,
    overlayColor: "black", overlayOpacity: 0.5,     // véu preto a 50%, sem desfoque
    stagePadding: 4, stageRadius: 8, popoverOffset: 8,   // o recorte: 4px de folga e o raio da box; o cartão a 8px
    disableActiveInteraction: true,                  // a parte destacada não responde a clique
    allowKeyboardControl: true,                      // ← e → trocam de passo; Esc é "Pular" (o driver prende o Tab no cartão)
    showProgress: true, progressText: t("tour.progresso"),   // "{{current}} de {{total}}"
    nextBtnText: t("common.next"), prevBtnText: t("tour.voltar"), doneBtnText: t("tour.concluir"),
    onHighlightStarted: (el) => {
      // o driver marca a parte com aria-haspopup/aria-expanded/aria-controls, que não valem num div (o axe acusa);
      // o cartão já é o dialog. Ele devolve os valores de antes ao sair do passo.
      if (el) queueMicrotask(() => ["aria-haspopup", "aria-expanded", "aria-controls"].forEach((a) => el.removeAttribute(a)));
    },
    onPopoverRender: (pop, { state }) => {
      const ultimo = state.activeIndex === visiveis.length - 1;
      pop.wrapper.classList.add(...popoverClasses.split(" "));
      // [Filtros ………… 2 de 4] no topo; embaixo [Pular] à esquerda e [Voltar] [Próximo] à direita
      const topo = document.createElement("div");
      topo.className = "flex items-baseline gap-2";
      pop.title.before(topo);
      topo.append(pop.title, pop.progress);
      pop.title.className = "driver-popover-title flex-1 font-medium";
      pop.progress.className = "driver-popover-progress-text text-xs text-muted-foreground";
      pop.description.className = "driver-popover-description text-muted-foreground";
      botao(pop.closeButton, "driver-popover-close-btn", buttonVariants({ variant: "ghost", size: "sm" }), t("tour.pular"), !ultimo);   // o "×" vira "Pular"
      botao(pop.previousButton, "driver-popover-prev-btn", buttonVariants({ variant: "outline", size: "sm" }), t("tour.voltar"), state.activeIndex! > 0);
      botao(pop.nextButton, "driver-popover-next-btn", buttonVariants({ size: "sm" }), ultimo ? t("tour.concluir") : t("common.next"), true);
      pop.closeButton.removeAttribute("aria-label");
      pop.footer.className = "driver-popover-footer flex items-center gap-2";
      pop.footerButtons.className = "driver-popover-navigation-btns ml-auto flex gap-2";
      pop.footer.prepend(pop.closeButton);
      // o driver foca o primeiro botão logo depois deste gancho (agora o "Pular"); o foco vai para "Próximo" em seguida
      queueMicrotask(() => { if (pop.nextButton.isConnected) pop.nextButton.focus({ preventScroll: true }); });
    },
    // no onDestroyed o estado do driver já foi zerado (isLastStep() dá sempre false): use o índice e o motivo
    onDestroyed: (_el, _passo, { index, reason }) => {
      aoSair(reason === "done" || index === visiveis.length - 1 ? "concluido" : "visto");
      setTimeout(() => voltarPara?.focus(), 0);
    },
  });
  d.drive();
}

// components/shell/ajuda.tsx — o "?" do header, antes do ✨ e do sino (2.15)
export function Ajuda() {
  const t = useT();
  const botao = useRef<HTMLButtonElement>(null);
  const tela = usePassoAPassoDaTela();               // o registrado pela tela atual, ou null
  const estado = trpc.me.passoAPasso.useQuery();     // por pessoa, no servidor: { "contatos@1": "convidado" | "visto" | "concluido" }
  const marcar = trpc.me.marcarPassoAPasso.useMutation();
  const carregada = useTelaCarregada();              // sem skeleton na tela
  const ocupada = useAlgumFlutuanteAberto();         // modal, menu ou popover aberto
  const chave = tela && `${tela.id}@${tela.versao}`;
  const convidar = !!chave && estado.isSuccess && !estado.data[chave] && carregada && !ocupada
    && passosVisiveis(tela) >= 2;                    // no celular, partes escondidas não contam
  const comecar = () => tela && comecarPassoAPasso(tela, t, (e) => marcar.mutate({ chave: chave!, estado: e }));

  return (
    <>
      <DropdownMenu>
        <Tooltip>
          <TooltipTrigger render={<DropdownMenuTrigger render={<Button ref={botao} variant="ghost" size="icon-sm" aria-label={t("ajuda.titulo")} data-tour="ajuda" />} />}>
            <CircleQuestionMark />
          </TooltipTrigger>
          <TooltipContent>{t("ajuda.titulo")}</TooltipContent>
        </Tooltip>
        <DropdownMenuContent align="end" className="w-64">
          <DropdownMenuItem disabled={!tela} onClick={comecar}>
            <Route />
            <span className="flex flex-col">
              {t("ajuda.passoAPasso")}
              {!tela && <span className="text-xs text-muted-foreground">{t("ajuda.semPassoAPasso")}</span>}
            </span>
          </DropdownMenuItem>
          {(produto.centralDeAjuda || produto.suporte) && <DropdownMenuSeparator />}
          {produto.centralDeAjuda && (
            <DropdownMenuItem render={<a href={produto.centralDeAjuda} target="_blank" rel="noopener" />}>
              <BookOpen />{t("ajuda.central")}<ExternalLink className="ml-auto" />
            </DropdownMenuItem>
          )}
          {produto.suporte && <DropdownMenuItem onClick={abrirSuporte}><LifeBuoy />{t("ajuda.suporte")}</DropdownMenuItem>}
        </DropdownMenuContent>
      </DropdownMenu>

      {/* o convite: um por tela e por pessoa; não rouba o foco; fechar de qualquer jeito vale "Agora não" */}
      <Popover open={convidar} onOpenChange={(aberto) => { if (!aberto) marcar.mutate({ chave: chave!, estado: "convidado" }); }}>
        <PopoverContent anchor={botao} align="end" initialFocus={false} aria-live="polite">
          <PopoverHeader>
            <PopoverTitle>{t("tour.convite.titulo")}</PopoverTitle>
            <PopoverDescription>{t("tour.convite.texto", { count: tela?.passos.length ?? 0 })}</PopoverDescription>
          </PopoverHeader>
          <div className="flex justify-end gap-2">
            <Button variant="ghost" size="sm" onClick={() => marcar.mutate({ chave: chave!, estado: "convidado" })}>{t("tour.convite.agoraNao")}</Button>
            <Button size="sm" onClick={() => { marcar.mutate({ chave: chave!, estado: "convidado" }); comecar(); }}>{t("tour.convite.comecar")}</Button>
          </div>
        </PopoverContent>
      </Popover>
    </>
  );
}
```

### Assistente de IA

```tsx
// Assistente de IA (2.29): painel encaixado à direita, no lugar do painel da direita do shell.
// pnpm dlx shadcn@latest add message-scroller message bubble input-group item sheet
// A conversa é do useChat do AI SDK; o servidor revalida as permissões e marca como needsApproval
// toda ferramenta que muda algo no sistema (criar, editar, enviar, encerrar, excluir).

// header (2.15): [?] [✨] [🔔] — o ✨ abre e fecha; o foco volta a ele ao fechar
<Tooltip>
  <TooltipTrigger render={<Button ref={botaoIa} variant="ghost" size="icon-sm" aria-label={t("ia.nome")}
    aria-expanded={aberto} aria-controls="assistente" onClick={alternar} />}>
    <Sparkles />
  </TooltipTrigger>
  <TooltipContent>{t("ia.nome")}</TooltipContent>
</Tooltip>

// shell.tsx — encaixado quando a coluna de conteúdo continua com pelo menos 640px; senão, folha da direita
const encaixado = useMediaQuery("(min-width: 1024px)") && larguraDoConteudo - 384 >= 640;
{aberto && (encaixado
  ? <aside id="assistente" aria-label={t("ia.nome")} className="sticky top-0 flex h-svh w-96 shrink-0 flex-col border-l bg-sidebar">
      <Assistente />   {/* aberto, toma o lugar do painel da tela (os dados do contato), que volta ao fechar */}
    </aside>
  : <Sheet open onOpenChange={(v) => !v && fechar()}>
      <SheetContent id="assistente" side="right" showCloseButton={false} className="w-full gap-0 p-0 sm:max-w-sm">
        <Assistente />
      </SheetContent>
    </Sheet>)}

// components/shell/assistente.tsx
export function Assistente() {
  const t = useT();
  const tela = useTelaAtual();          // { id, nome, registro?, sugestoes, passoAPasso? } — o que a tela registrou
  const [comContexto, setComContexto] = useState(true);
  const { messages, sendMessage, status, stop, regenerate, setMessages, addToolApprovalResponse } = useChat({
    transport: new DefaultChatTransport({ api: "/api/assistente", body: () => (comContexto ? { tela: tela.id, registro: tela.registroId } : {}) }),
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
  });
  return (
    <>
      {/* 64px, com a borda de baixo na linha do header */}
      <div className="flex h-16 shrink-0 items-center gap-2 border-b px-4">
        <Sparkles className="size-4" />
        <span className="flex-1 font-medium">{t("ia.nome")}</span>
        <BotaoDeIcone icone={SquarePen} rotulo={t("ia.novaConversa")} onClick={() => setMessages([])} />
        <BotaoDeIcone icone={X} rotulo={t("common.close")} onClick={fechar} />   {/* Button ghost size="icon-sm" + Tooltip */}
      </div>
      {comContexto && (
        <div className="flex items-center gap-1 px-4 pt-3 text-xs text-muted-foreground">
          {t("ia.nestaTela")} <span className="font-medium text-foreground">{tela.registro ?? tela.nome}</span>
          <Button variant="ghost" size="icon-xs" aria-label={t("ia.tirarContexto")} onClick={() => setComContexto(false)}><X /></Button>
        </div>
      )}
      <MessageScrollerProvider autoScroll>
        <MessageScroller className="min-h-0 flex-1">
          <MessageScrollerViewport>
            <MessageScrollerContent className="gap-4 p-4">
              {messages.length === 0 && (
                <div className="flex flex-col items-start gap-2">
                  <p className="text-muted-foreground">{t("ia.vazio")}</p>   {/* "Pergunte sobre esta tela ou peça uma tarefa." */}
                  {tela.sugestoes.map((s) => <Button key={s} variant="outline" size="sm" onClick={() => sendMessage({ text: s })}>{s}</Button>)}
                  {tela.passoAPasso && <Button variant="outline" size="sm" onClick={() => comecarPassoAPasso(tela.passoAPasso)}>{t("ia.fazerPassoAPasso")}</Button>}
                </div>
              )}
              {messages.map((m) => (
                <MessageScrollerItem key={m.id} messageId={m.id} scrollAnchor={m.role === "user"}>
                  {m.role === "user" ? (
                    <Message align="end"><MessageContent><Bubble variant="muted"><BubbleContent>{textoDe(m)}</BubbleContent></Bubble></MessageContent></Message>
                  ) : (
                    <Message>
                      <MessageContent>
                        {m.parts.map((p, i) => p.type === "text"
                          ? <Bubble key={i} variant="ghost"><BubbleContent><Markdown>{p.text}</Markdown></BubbleContent></Bubble>   // sem HTML do modelo
                          : isToolUIPart(p) && <Ferramenta key={i} parte={p} responder={addToolApprovalResponse} />)}
                      </MessageContent>
                      <MessageFooter><AcoesDaResposta mensagem={m} /></MessageFooter>   {/* Copiar, Útil, Não útil: ghost icon-xs + Tooltip, aria-pressed */}
                    </Message>
                  )}
                </MessageScrollerItem>
              ))}
              {status === "submitted" && <p className="shimmer text-muted-foreground motion-reduce:animate-none">{t("ia.pensando")}</p>}
              {status === "error" && (
                <Bubble variant="destructive"><BubbleContent>
                  {t("ia.erro")} <Button variant="outline" size="sm" onClick={() => regenerate()}>{t("common.tryAgain")}</Button>
                </BubbleContent></Bubble>
              )}
            </MessageScrollerContent>
          </MessageScrollerViewport>
          <MessageScrollerButton />
        </MessageScroller>
      </MessageScrollerProvider>
      <CampoDeMensagem respondendo={status === "submitted" || status === "streaming"} onEnviar={(text) => sendMessage({ text })} onParar={stop} />
    </>
  );
}

// o padrão Confirmation do shadcn: toda mudança no sistema pede o "Confirmar"; depois, vira a linha do resultado
function Ferramenta({ parte, responder }: { parte: ToolUIPart; responder: AddToolApprovalResponse }) {
  const t = useT();
  const acao = ACOES[parte.type];       // { icone, pergunta, descricao, destrutiva }
  if (parte.state === "approval-requested") return (
    <Item variant="outline" size="sm">
      <ItemMedia variant="icon"><acao.icone /></ItemMedia>
      <ItemContent>
        <ItemTitle>{acao.pergunta(parte.input)}</ItemTitle>          {/* "Criar a tag VIP?" */}
        <ItemDescription>{acao.descricao(parte.input)}</ItemDescription>
      </ItemContent>
      <ItemActions>
        <Button variant="outline" size="sm" onClick={() => responder({ id: parte.approval.id, approved: false })}>{t("common.cancel")}</Button>
        <Button variant={acao.destrutiva ? "destructive" : "default"} size="sm" onClick={() => responder({ id: parte.approval.id, approved: true })}>{t("common.confirm")}</Button>
      </ItemActions>
    </Item>
  );
  if (parte.state === "output-available") return <ResultadoDaAcao parte={parte} />;   // "Tag VIP criada." + "Ver"
  if (parte.state === "output-denied") return <p className="text-muted-foreground">{t("ia.cancelado")}</p>;
  return null;
}

// o padrão Prompt Input do shadcn: Enter envia, Shift+Enter quebra a linha; de 1 a 6 linhas e depois rola
function CampoDeMensagem({ respondendo, onEnviar, onParar }: { respondendo: boolean; onEnviar: (t: string) => void; onParar: () => void }) {
  const t = useT();
  const [texto, setTexto] = useState("");
  const form = useRef<HTMLFormElement>(null);
  return (
    <form ref={form} className="shrink-0 px-4 pb-3" onSubmit={(e) => { e.preventDefault(); if (texto.trim() && !respondendo) { onEnviar(texto.trim()); setTexto(""); } }}>
      <InputGroup>
        <InputGroupTextarea autoFocus value={texto} onChange={(e) => setTexto(e.target.value)} className="max-h-36"
          placeholder={t("ia.placeholder")} aria-label={t("ia.mensagem")}
          onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); form.current?.requestSubmit(); } }} />
        <InputGroupAddon align="block-end">
          {respondendo
            ? <InputGroupButton variant="default" size="icon-sm" className="ml-auto" aria-label={t("ia.parar")} onClick={onParar}><Square /></InputGroupButton>
            : <InputGroupButton type="submit" variant="default" size="icon-sm" className="ml-auto" aria-label={t("ia.enviar")} disabled={!texto.trim()}><ArrowUp /></InputGroupButton>}
        </InputGroupAddon>
      </InputGroup>
      <p className="pt-2 text-center text-xs text-muted-foreground">{t("ia.aviso")}</p>   {/* "A IA pode errar. Confira o que for importante." */}
    </form>
  );
}
```

### Área de administração

```tsx
// app/(admin)/admin/layout.tsx — a área de administração (2.30): só para quem está como Sysadmin.
// O data-area="admin" liga o tom da área: o globals.css gerado tem
//   :root:has([data-area="admin"]) { --sidebar: var(--sidebar-admin); --sidebar-accent: …; --sidebar-border: … }
// e vale também para a gaveta do celular, que o Sheet abre fora deste layout. A Sidebar do shadcn não muda.
export default async function AdminLayout({ children }: { children: React.ReactNode }) {
  const sessao = await getSessao();
  if (sessao.vendoComo || sessao.papel !== "sysadmin") notFound();   // a área não existe para os outros
  return (
    <SidebarProvider data-area="admin">
      <AppSidebar area="admin" />
      <SidebarInset>{/* o mesmo header (breadcrumb "Administração › Empresas"), conteúdo e rodapé do shell */}{children}</SidebarInset>
    </SidebarProvider>
  );
}

// app-sidebar.tsx — na área, o topo troca o seletor de empresa pelo bloco fixo e o menu é o da área
const NAV_ADMIN = [
  { grupo: "Cadastros", itens: [{ href: "/admin/empresas", rotulo: "Empresas", icone: Building2 }, { href: "/admin/produtos", rotulo: "Produtos", icone: Package }] },
  { grupo: "Acesso", itens: [{ href: "/admin/usuarios", rotulo: "Usuários", icone: Users }] },
];

<SidebarHeader>
  {/* logo do produto: a mesma linha de 48px */}
  <div className="flex h-12 items-center">
    {area === "admin" ? (
      // o mesmo bloco da Troca de empresa com uma empresa só (troca-de-empresa.tsx): um div, não um botão
      <SidebarMenu><SidebarMenuItem>
        <div className="flex h-12 w-full items-center gap-2 overflow-hidden rounded-md p-2 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-0!">
          <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground"><Shield /></div>
          <div className="grid flex-1 text-left text-sm leading-tight">
            <span className="truncate font-medium">Administração</span>
            <span className="truncate text-xs">Todas as empresas</span>
          </div>
        </div>
      </SidebarMenuItem></SidebarMenu>
    ) : <CompanySwitcher {...empresa} />}
  </div>
</SidebarHeader>
<SidebarContent><NavMain grupos={area === "admin" ? NAV_ADMIN : navDoPapel(papel)} /></SidebarContent>

<SidebarFooter>
  {/* a entrada fixa, acima do usuário: só como Sysadmin e fora do "Ver como"; dentro da área, vira a saída */}
  {podeAdministrar && (
    <SidebarMenu><SidebarMenuItem>
      {area === "admin" ? (
        <SidebarMenuButton render={<Link href={telaDeAntes ?? "/painel"} />} tooltip="Sair da administração">
          <Undo2 /><span>Sair da administração</span>
        </SidebarMenuButton>
      ) : (
        <SidebarMenuButton render={<Link href="/admin/empresas" />} tooltip="Administração">
          <Shield /><span>Administração</span>
        </SidebarMenuButton>
      )}
    </SidebarMenuItem></SidebarMenu>
  )}
  <NavUser />
</SidebarFooter>

// produtos: a cor do produto é dado, não token: a amostra leva a cor no style, com o hex em texto ao lado
<span className="inline-flex items-center gap-2">
  <span aria-hidden className="size-4 rounded-sm ring-1 ring-foreground/10" style={{ background: produto.primaria }} />
  <span className="font-mono text-xs">{produto.primaria}</span>
</span>
```

## 4.5 Personalização em três níveis e cuidados com o CLI

1. **Tokens no `globals.css`:** onde mora a identidade. Trocar `--primary` muda tudo.
2. **`className` por instância**, com `cn(...)`: ajuste pontual num uso.
3. **Editar o arquivo em `components/ui/`:** só para mudar o padrão global, e só nestes casos: as
   variantes novas do Badge e do Alert; o item ativo do Sidebar; o texto do `destructive` do Button
   em `text-destructive-strong`, o do `link` em `text-link` e o Toggle ligado em
   `bg-primary text-primary-foreground` (os três porque o padrão do shadcn não tem o contraste
   mínimo, 1.2); o anel de foco no `TabsContent` (o painel recebe foco e vem com `outline-none`,
   3.15); os textos em pt-BR dos componentes.
   Única medida fora do shadcn: o avatar de 96px da foto do Perfil, por `className` (`size-24`, 2.19).
   `add --overwrite` desfaz: reconciliar à mão e conferir o `git diff`.

**Medidas: as do shadcn.** Altura, padding, raio, peso e tamanho de texto dos componentes ficam como o
CLI entrega (1.5). Nada de `h-10`, `px-4`, `rounded-md` ou `text-base` por `className` para "acertar"
um componente: se a medida parecer errada, quem muda é o guia.

- Nada nosso mora em `components/ui/` nem em `lib/utils.ts` além do que o nível 3 exige; helpers
  próprios vão em `lib/<nome>.ts`.
- `apply --preset` só com `--only theme` ou `--only font`; sem o `--only` ele reinstala os componentes.
- Composição pelo motor do estilo, nunca os dois no mesmo projeto: no `base-nova` (Base UI), o prop `render`, nunca
  `asChild`; no `radix-nova` (Radix), o `asChild`, porque o Radix não tem `render` *(decisão do usuário, 2026-11-04)*.
- Nunca `title`, nunca `<Link>` dentro de `<Button>` (use `buttonVariants` no link), nunca `style` inline fora da cor
  do banco, nunca `onPress`.
- Nenhuma cor em classe (`bg-zinc-900`, `text-emerald-500`, hexadecimal): só os tokens
  (`bg-primary`, `text-success`, `border-border`).
- Dentro do shell, arranjo pela largura do contêiner: `@container/<nome>` e variantes
  `@sm/<nome>:`, `@md/<nome>:` (Tailwind 4), não `sm:`/`md:`.
- Nada sorteado no render (`Math.random()`, `Date.now()`): quebra a hidratação.

## 4.6 Projetos ainda em Tailwind 3 + Radix (DevTasks, Radar RH)

Mesmos tokens, em HSL sem `hsl()` no `index.css` e mapeados no `tailwind.config`
(`primary: "hsl(var(--primary))"`); `asChild` no lugar de `render`; `tailwindcss-animate` para os
flutuantes. Migram para a stack padrão quando a tela for refeita; até lá, seguem as partes 1 a 3
à risca.

Medidas: os componentes deles vêm da versão antiga do shadcn (botão e campo de 40px, `sm` 36, `lg`
44, padding de 16). Para valer a 1.5, edite uma vez o `cva` do `button.tsx` (padrão `h-8 px-2.5`,
`sm` `h-7`, `lg` `h-9`, `icon` `size-8`) e a altura de `input.tsx`, `select.tsx` e `textarea.tsx`
(`h-8 px-2.5`; área de texto `min-h-16`). É a única edição de componente pedida para eles.

---

## Checklist antes de entregar uma tela

- [ ] Está dentro do shell, sem título e sem barra de ações: o nome no breadcrumb, a primeira box logo abaixo do header e o "Novo…" no canto superior direito do card que ele alimenta (3.3).
- [ ] Todo conteúdo está numa box. Nada solto sobre o fundo.
- [ ] Só tokens de cor. Conferida no tema claro e no escuro. Texto de link no token `link`, nunca `primary` como cor de texto (1.2).
- [ ] Um `primary` por contexto. Ícone à esquerda. Botão só de ícone com `aria-label` e tooltip.
- [ ] Toda chamada ao servidor tem Skeleton (primeira carga) ou Spinner (ação), e tem estado vazio e de erro. Os dados se atualizam sozinhos, sem botão "Atualizar" (3.8).
- [ ] Formulário: rótulo em todo campo, erro embaixo do campo, recusa do servidor em alerta, "Cancelar" e "Salvar" no rodapé com carregamento.
- [ ] Tabela com o padrão completo (2.10): busca, toda coluna de valor único ordenável (com `aria-sort`), um filtro por coluna de conjunto fechado (até 5 valores, escolha única; acima disso, múltipla), "…" nas ações, status com ícone e texto, rodapé com paginação, e os estados (skeleton, vazio, erro).
- [ ] Tela que depende de uma escolha começa listando as opções: listagem em duas etapas, com a escolha na URL, a volta pelo botão "← Pessoas" e pelo voltar do navegador (sem Esc), e o terceiro nível no breadcrumb (3.18).
- [ ] Aviso é alerta de um dos quatro tipos, ou toast se é passageiro. Uma frase.
- [ ] Roboto, escala do guia, 14px no corpo. Lucide nos tamanhos do guia. Componentes com as medidas do shadcn, sem `h-*`, `px-*` ou `rounded-*` por cima (1.5). Layout na escala de 4. Box sem sombra.
- [ ] Funciona a 360px sem rolagem lateral; dentro do shell, responde ao contêiner.
- [ ] Teclado: Tab, Enter, Esc. Foco visível. Contraste 4,5:1.
- [ ] Nenhum texto fixo: tudo no dicionário dos três idiomas. Data e número no formato do idioma.
- [ ] Textos: uma frase, verbo no botão, sem "por favor", sem jargão.
- [ ] Rodapé padrão de uma linha no fim da coluna de conteúdo; estendido pela seta, no fluxo da página, nunca por cima do conteúdo (2.21). Os textos e os cards vêm da API em SSG, consultada 1 ou 2 vezes por dia, nunca do navegador.
- [ ] Filtros no lugar certo: escopo no topo do card (abas e filtros do card de relatório, 2.24), modo de exibição à direita da barra de ferramentas, até três filtros à vista e o resto em "Filtros"; tudo na URL (3.5). Dashboard sem filtro; configuração sem tabela centralizada até 720px; kanban e chat em altura cheia (3.1).
- [ ] Configuração com várias seções que são telas próprias: segundo menu abaixo do header, cada seção com a sua URL e o terceiro nível no breadcrumb, na largura toda que sobra (também as de formulário); nunca abas para trocar de seção (2.27).
- [ ] Header à direita na ordem: indicadores, "?" (ajuda), "✨" (assistente, nos produtos com IA) e sino (2.15).
- [ ] Passo a passo só por convite (um por tela, guardado no servidor), de 3 a 5 passos, com "Pular"; o último destaca o "?"; partes marcadas com `data-tour` (2.28).
- [ ] Assistente de IA em painel encaixado à direita, nunca balão flutuante; toda mudança no sistema passa pelo cartão de confirmação (2.29).
- [ ] Menu e permissões pelo papel ativo; quem tem mais de um papel troca pela linha "Papel" do menu do usuário, e a tela remonta limpa (2.16).
- [ ] O que é da IDeia (empresas clientes, produtos, papéis) na área de administração: entrada fixa no pé da sidebar só para o Sysadmin, sidebar no tom `sidebar-admin`, `data-area="admin"` no layout (2.30).
- [ ] Na stack padrão: componentes do shadcn pelo mapa da Parte 4, tokens só no `globals.css`, nenhuma cor em classe.
- [ ] O `DESIGN.md` local do projeto foi consultado para saber qual componente da biblioteca faz cada papel.

---

## API dos produtos

A API do IDeia Design guarda os dados de cada produto: os textos e os cards do rodapé, as cores, os logos e o
`globals.css`. Os sistemas leem dela sem login. Quem escreve é o painel administrativo, e só o Sysadmin entra nele.

- **Endereço:** `https://design-api.ideiabusiness.com.br/api/v1`
- **Contrato:** https://design-api.ideiabusiness.com.br/api-docs (o Swagger, para ler e testar no navegador) e
  https://design-api.ideiabusiness.com.br/api-docs-json (o OpenAPI, para gerar os tipos).
- **Painel:** https://design-admin.ideiabusiness.com.br

## Leitura dos sistemas (sem login)

| Método e caminho | O que devolve |
|---|---|
| `GET /footer?product=<slug>` | O rodapé (2.21): os textos da empresa e os cards dos produtos, em ordem alfabética, sem o card do sistema que pede. Sem `product`, vêm todos |
| `GET /products` | Os produtos que não estão arquivados, em ordem alfabética, com os textos, as cores e os logos. `metadata.total` diz quantos são |
| `GET /products/<slug>` | Um produto |
| `GET /products/<slug>/globals.css` | O `globals.css` do produto (shadcn/ui + Tailwind 4), o mesmo do `get_tokens` do MCP. Vem o arquivo, não JSON |
| `GET /health` | Se a API e o banco respondem: `status` `ok` ou `degraded` |
| `GET /guide/products` | Os produtos no formato do guia, com a cor do logo e as medidas de cada PNG: o que o build do site e o MCP leem. Os sistemas usam `/products` |

- `<slug>` é o do produto no guia (`ideia-chat`, `ideia-devtasks`…): a lista sai de `GET /products` ou do
  `list_products` do MCP. Só letras minúsculas sem acento, números e hífen.
- **Sem login, de qualquer origem:** CORS aberto, só `GET`. Não mande cookie nem `Authorization`.
- **Cache:** `Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=86400`. A borda da Vercel guarda a
  resposta por 5 minutos; passado esse tempo, ainda entrega a anterior por até um dia enquanto busca a nova.
- **Leia em SSG, consultando a API 1 ou 2 vezes por dia** (D38 e D47): a página sai pronta do build e o sistema só
  volta à API quando a revalidação vence, a cada 12 ou 24 horas (no Next, `fetch` com `next: { revalidate: 43200 }`
  ou `86400`). Em tela com login, que se monta a cada pedido, o `fetch` vem do cache do Next, não da API. Nunca SSR
  sem cache (uma chamada por página), nunca do navegador, e nada de `cache: "no-store"`, `revalidate: 0` ou
  `fetchCache = "force-no-store"` nesse caminho. Uma mudança no painel chega a todos os sistemas em até um dia.
- **Com a API fora,** o sistema segue com a última resposta boa: o `fetch` do Next só guarda resposta 200. Sem nenhuma
  guardada, o que depende dela não aparece (o rodapé, por exemplo) e a página segue. A API nunca derruba uma tela.
- **Produto arquivado** (D37): sai de `/products` e do rodapé, e `/products/<slug>` responde 404. As URLs dos logos
  dele continuam no ar.
- **Logos:** use a URL que a API devolve. Ela traz o `?v=` da versão atual, e um logo trocado chega com uma URL nova,
  sem esperar cache. Em `logos` só estão as variantes que o produto tem (1.1). Na tela, `<img>` ou
  `<Image unoptimized>`: o arquivo vai direto para o navegador, sem passar pelo otimizador de imagens.
- **Cores:** ficam compiladas no `globals.css` de cada sistema, e a API não muda a cor de um sistema que já está no ar.
  Depois de uma troca de cor no painel, o sistema baixa o `globals.css` de novo.
- **O guia também lê daqui.** O build do site lê os produtos da API, e o painel pede um build novo a cada escrita: uma
  cor, um texto ou um logo trocado no painel chega ao guia, à /live e ao MCP em cerca de um minuto.

### O rodapé: `GET /footer?product=ideia-chat`

| Campo | O que é |
|---|---|
| `company.brandName` | O nome da marca: "Um produto da …" e o nome da seta, "Produtos da …" |
| `company.legalName`, `company.cnpj` | A razão social e o CNPJ, com a máscara, na linha do rodapé |
| `company.email` | O e-mail de contato, na linha do rodapé |
| `company.title`, `company.tagline` | O título e a frase da parte estendida |
| `company.aboutUrl` | Para onde o "Quem está por trás" leva |
| `products[].slug`, `products[].name` | O produto do card |
| `products[].description` | O texto do card: o do rodapé no cadastro do produto; vazio, o do login |
| `products[].url` | O endereço do produto; `null`, o card sai sem link |
| `products[].icon` | O ícone claro (o logo claro, se o produto não tem ícone); `null`, sem imagem |

```json
{
  "success": true,
  "data": {
    "company": {
      "brandName": "Ideia Business",
      "legalName": "Ideia Business Soluções Tecnológicas LTDA",
      "cnpj": "30.082.914/0001-00",
      "email": "contato@ideiabusiness.com.br",
      "title": "Os negócios por trás deste produto",
      "tagline": "Mais de 20 anos empreendendo, mais de 500 mil empresas atendidas e uma rede com mais de 5 mil contadores.",
      "aboutUrl": "https://ideiabusiness.com.br"
    },
    "products": [
      {
        "slug": "ideia-devtasks",
        "name": "IDeia DevTasks",
        "description": "Crie tickets com ajuda de IA e acompanhe o time no kanban.",
        "url": null,
        "icon": "https://cdn.ideiabusiness.com.br/logos/ideia-devtasks/ideia-devtasks-icone-clara.png?v=7832ddae0d57"
      }
    ]
  },
  "metadata": { "timestamp": "2026-10-29T22:43:16.710Z", "version": "v1" }
}
```

### Um produto: `GET /products/ideia-chat`

| Campo | O que é |
|---|---|
| `slug` | Fixo: não muda depois de criado. É também o nome dos arquivos dos logos |
| `name` | O nome do produto |
| `family` | `ideia` ou `propria` (1.1) |
| `pitch`, `description` | O título e o texto do painel do login (2.20) |
| `footerDescription` | O texto do card do rodapé (2.21); vazio, vale o `description` |
| `siteUrl` | O endereço do produto, para onde o card do rodapé leva; `null` quando não tem |
| `showInFooter` | Se o card do produto aparece no rodapé dos outros sistemas |
| `colors.primary` | A primária de cada tema e o texto sobre ela: `light`, `lightForeground`, `dark` e `darkForeground` (1.2) |
| `colors.brand` | A primária clara, fixa nos dois temas: só o painel do login (2.20) |
| `colors.link` | O texto de link de cada tema, `light` e `dark` (1.2) |
| `logos` | A URL de cada PNG que existe: `clara`, `escura`, `icone-clara` e `icone-escura` (1.1) |

```json
{
  "success": true,
  "data": {
    "slug": "ideia-chat",
    "name": "IDeia Chat",
    "family": "propria",
    "pitch": "Atendimento multicanal pelo WhatsApp",
    "description": "Filas, SLA e dashboards para o seu time atender melhor.",
    "footerDescription": "Atendimento multicanal pelo WhatsApp, com filas, SLA e dashboards.",
    "siteUrl": null,
    "showInFooter": true,
    "colors": {
      "primary": { "light": "#265e9f", "lightForeground": "#ffffff", "dark": "#2e71c0", "darkForeground": "#ffffff" },
      "brand": "#265e9f",
      "link": { "light": "#265e9f", "dark": "#5c90ce" }
    },
    "logos": {
      "clara": "https://cdn.ideiabusiness.com.br/logos/ideia-chat/ideia-chat-clara.png?v=985d0c40f5c8",
      "escura": "https://cdn.ideiabusiness.com.br/logos/ideia-chat/ideia-chat-escura.png?v=1096dde5c415",
      "icone-clara": "https://cdn.ideiabusiness.com.br/logos/ideia-chat/ideia-chat-icone-clara.png?v=19c9a6d7496c",
      "icone-escura": "https://cdn.ideiabusiness.com.br/logos/ideia-chat/ideia-chat-icone-escura.png?v=251c730a4a82"
    }
  },
  "metadata": { "timestamp": "2026-10-29T22:47:50.483Z", "version": "v1" }
}
```

## O envelope e os erros

Toda resposta em JSON vem no mesmo envelope: `success`, `data` (ou `error`, quando falha) e `metadata`, com
`timestamp`, `version` e, nas listas, `total`. Só o `globals.css` vem como arquivo.

```json
{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Produto não encontrado: nao-existe"
  },
  "metadata": {
    "timestamp": "2026-10-29T22:47:50.675Z",
    "version": "v1"
  }
}
```

| Status | `error.code` | Quando |
|---|---|---|
| 404 | `PRODUCT_NOT_FOUND` | O slug não existe ou o produto está arquivado |
| 404 | `ROUTE_NOT_FOUND` | O caminho não existe |
| 422 | `VALIDATION_ERROR` | Parâmetro inválido; `error.details` traz cada campo, com `path` e `message` |
| 500 | `INTERNAL_ERROR`, `FOOTER_NOT_CONFIGURED` | Falha da API: siga com a última resposta boa |

As rotas do painel respondem também 401 (sem sessão), 403 (sem o papel Sysadmin), 409 `SLUG_TAKEN` e 422
`CONTRAST_FAILED` ou `LOGO_INVALID`. A lista completa está no contrato.

## O painel (com login)

Só o painel administrativo escreve, e só o Sysadmin entra nele (D34). Nele ficam **Cadastros › Produtos** (cadastrar,
editar os textos, as cores e o rodapé de cada produto, arquivar) e **Configurações › Rodapé** (os textos da empresa).
Os sistemas de produto nunca chamam estas rotas.

| Método e caminho | O que faz |
|---|---|
| `POST /auth/login` | Entra com e-mail e senha e recebe o token (JWT) |
| `POST /auth/github` | Entra pelo GitHub: só quem é da organização Ideia-Business e está cadastrado como Sysadmin |
| `GET /auth/me`, `POST /auth/logout` | Quem está na sessão; sair |
| `GET /admin/products` | A lista, com busca (`search`), família (`family`), situação (`status`: `ativos`, `arquivados` ou `todos`), rodapé (`footer`) e em revisão (`review`) |
| `POST /admin/products` | Cadastra um produto. O que faltar das cores sai da receita do guia (1.2) |
| `GET /admin/products/<slug>`, `PATCH /admin/products/<slug>` | Lê o produto, com as cores e os logos; edita só os campos enviados |
| `POST /admin/products/<slug>/archive`, `POST /admin/products/<slug>/restore` | Arquiva (D37) e tira do arquivo |
| `POST /admin/products/<slug>/logos/<variante>/uploads` | Assina o envio de um logo: o navegador sobe o PNG direto no armazenamento, num link que vale 5 minutos |
| `POST /admin/products/<slug>/logos/<variante>` | Confere o arquivo enviado e publica como versão nova: a URL fixa troca e o cache do CDN é limpo |
| `POST /admin/products/<slug>/logos/<variante>/versions/<n>/restore` | Volta o logo para uma versão guardada |
| `POST /admin/colors/derive` | Sugere a primária clara, a escura e o texto sobre elas a partir de uma cor, com o contraste do resultado |
| `GET /admin/footer`, `PATCH /admin/footer` | Os textos da empresa no rodapé (D40) |

- **Sessão:** o token vai no cabeçalho `Authorization: Bearer <token>`. No painel, ele fica num cookie httpOnly, e
  quem o manda à API é o servidor do painel (BFF): o navegador nunca o vê. A API lê o usuário no banco a cada pedido,
  e quem é desativado perde o acesso na hora.
- **Contraste:** toda cor salva passa pelas contas do guia (1.2); a que reprova é recusada com 422 `CONTRAST_FAILED`
  e os motivos (D36).
- **Auditoria:** toda escrita grava quem fez, o quê, o antes e o depois.
- **Logos:** PNG com fundo transparente (pelo menos um canto), até 2 MB e 4096 px de lado; o ícone, quadrado, com
  128 px ou mais; o logo completo, com 64 px de altura ou mais (1.1). O que não serve volta com 422 `LOGO_INVALID` e
  os motivos. Cada envio guarda uma versão, e o mesmo arquivo de uma versão antiga volta para ela.

## No código (Next.js, no servidor)

O `lib/ideia-design.ts` abaixo lê o rodapé e o próprio produto em SSG, voltando à API a cada 12 horas. Os tipos
saem do contrato, com o `openapi-typescript` (o comando está no começo do arquivo). O componente do rodapé que recebe
esses dados está no 2.21.

```ts
// lib/ideia-design.ts — só servidor, em SSG: a API do guia é lida 1 ou 2 vezes por dia (D38, D47)
// Os tipos saem do contrato, uma vez e a cada mudança na API:
//   pnpm dlx openapi-typescript https://design-api.ideiabusiness.com.br/api-docs-json -o lib/ideia-design-api.d.ts
import type { components } from "./ideia-design-api";

type Rodape = components["schemas"]["PublicFooter"];
type Produto = components["schemas"]["PublicProduct"];

const API = "https://design-api.ideiabusiness.com.br/api/v1";
const SLUG = "ideia-chat";   // o slug deste sistema no guia (GET /products ou list_products do MCP)

async function ler<T>(caminho: string): Promise<T | null> {
  try {
    // 12 horas (86400: 24); nunca no-store nem revalidate: 0, que chamam a API a cada página
    const res = await fetch(`${API}${caminho}`, { next: { revalidate: 43200 } });
    if (!res.ok) return null;                                  // só a resposta 200 entra no cache: a última boa continua valendo
    return ((await res.json()) as { data?: T }).data ?? null;
  } catch {
    return null;                                               // API fora e nada guardado: a tela segue sem o que dependia dela
  }
}

// o rodapé (2.21): os textos da empresa e os cards, sem o deste sistema
export const getRodape = () => ler<Rodape>(`/footer?product=${SLUG}`);
// este produto: o título e o texto do login (2.20), as cores e as URLs dos logos, com ?v=
export const getProduto = () => ler<Produto>(`/products/${SLUG}`);

// no layout (servidor):
//   const [rodape, produto] = await Promise.all([getRodape(), getProduto()]);
//   … {rodape && <Footer rodape={rodape} />}
```

---

## Histórico e pendências

- 2026-11-04 · v1.12.0 · O MCP aplica o guia num projeto (TODO, Fase 12; D52 a D62): o prompt `aplicar-guia(produto,
  pasta)`, com o questionário de quatro rodadas em caixas de múltipla escolha, o mapeamento de tudo o que vai mudar em
  `docs/adocao-guia-ideia.md` antes de alterar qualquer arquivo, a revisão humana do documento, a base (tokens,
  componentes e shell) antes das telas e uma parte por vez, com o OK de uma pessoa entre elas; "continue de onde parou"
  retoma pelo documento. Três ferramentas novas: `get_roteiro("aplicar-guia")` (o mesmo texto do prompt, para quem não
  consegue começar um prompt), `plano_template` (o modelo do documento) e `check_tela(stack, codigo)`, a conferência
  mecânica do código de uma tela (cor fixa, medida de controle por `className`, `text-primary`, `title`, "Atualizar",
  texto fixo e, na stack padrão, `asChild`). O MCP passa a 12 ferramentas e 3 prompts (`llms.txt`, a página "Para
  devs e IAs", os README do site e de `integration/`); o `CLAUDE-block.md` ganha `check_tela` e `aplicar-guia`. E a skill `aplicar-guia-ideia` (D57): a fonte em
  `integration/skills/`, publicada pelo build em `/skills/aplicar-guia-ideia/SKILL.md`; o `conectar-mcp.sh` a instala em
  `~/.claude/skills/` junto com o token (rodar de novo atualiza). Ela não guarda regra: confere se o MCP responde e segue
  o `get_roteiro("aplicar-guia")`. E a composição pelo motor do estilo (D62, 4.5 e 4.1): `render` no `base-nova`,
  `asChild` no `radix-nova` (o Radix não tem `render`), nunca os dois no mesmo projeto; o `check_tela` recebe o `estilo`.
- 2026-10-30 · v1.11.0 · A faixa "Você está em …" da troca de empresa (D51, o padrão do IdeiaChat): quem alcança todas
  as empresas e sai da empresa principal vê uma faixa fixa acima do header, a mesma do "Ver como" (2.16), com
  `building-2`, o nome da empresa e "Voltar para …" à direita; sem "×". 2.25 (regras, diagrama e "nunca"), 2.16, 3.2 e
  3.3; os exemplos `ver-como.tsx` (a `Faixa` compartilhada) e `troca-de-empresa.tsx` (`decidirFaixa` e
  `FaixaDaEmpresa`); a página do guia e a live (as duas faixas empilhadas: header, segundo menu e assistente descem
  40px por faixa).
- 2026-10-30 · v1.10.1 · O rodapé em SSG (D47): o 2.21, a seção "API dos produtos", os exemplos `api.ts` e
  `rodape.tsx`, o checklist e o MCP (as instruções e a auditoria) passam de "no servidor (SSR ou SSG)" para SSG,
  consultando a API 1 ou 2 vezes por dia (`revalidate` de 12 ou 24 horas). Em tela com login, o `fetch` vem do cache do
  Next; `no-store`, `revalidate: 0` e `fetchCache = "force-no-store"` ficam fora do caminho do rodapé.
- 2026-10-30 · v1.10.0 · O guia lê os produtos da API, e os logos moram no CDN (TODO 10.5, D30, D31):
  - o build lê `GET https://design-api.ideiabusiness.com.br/api/v1/guide/products` e guarda em `dist/products.json`
    (o `--check`, os testes e o MCP leem a cópia; sem a API, o build falha e o site fica na versão anterior). Os JSON
    de `tokens/products/` e o `tokens/produtos.json` saíram do repositório: produto, cor, texto e logo se mudam no
    painel, que pede um build novo do site a cada escrita;
  - os logos vêm de `https://cdn.ideiabusiness.com.br/logos/…`: a página, a /live, o `products.json`, o
    `logos/index.json` (agora com largura e altura, além dos bytes), o `produtos.json` e o MCP (`get_logo_urls`). Os
    endereços antigos, `design.ideiabusiness.com.br/logos/<slug>/<arquivo>`, redirecionam para o CDN (308);
  - 1.1 Marca e logo: as URLs do CDN, a troca sozinha pelo painel e o logo do CDN direto para o navegador (`<img>` ou
    `<Image unoptimized>`, sem copiar o arquivo para o projeto);
  - seção "API dos produtos": a leitura `GET /guide/products` e o fim do "por enquanto, o guia lê do repositório".
- 2026-10-30 · v1.9.1 · O envio de logos pelo painel (TODO 10.3 e 10.4), na seção "API dos produtos": as três rotas
  (assinar o envio, publicar e voltar a uma versão), as regras do arquivo (PNG com fundo transparente, até 2 MB e
  4096 px de lado; ícone quadrado com 128 px ou mais; logo completo com 64 px de altura ou mais) e o erro
  `LOGO_INVALID`. Sai o aviso "Ainda não: o envio de logos".
- 2026-10-29 · v1.9.0 · Pedido do usuário: a documentação da API e o caminho para o painel.
  - Seção nova "API dos produtos" (no fim, depois de "Para devs e IAs"; `get_section("api")` no MCP e `/guia/api.md`):
    o endereço, o contrato (Swagger e OpenAPI), as cinco leituras sem login (rodapé, produtos, um produto, o
    `globals.css` e o health), como ler (no servidor, cache, API fora, arquivado, logos com `?v=`, cores), os campos do
    rodapé e do produto com a resposta real, o envelope e os erros, as rotas do painel e o exemplo novo
    `lib/ideia-design.ts` (`api.ts`), com os tipos gerados do contrato pelo `openapi-typescript`.
  - Página: o botão "Entrar no painel" (`outline`, ícone `log-in`) ao lado da "Demonstração ao vivo", levando ao login
    de design-admin.ideiabusiness.com.br; a seção nova no sumário e no "Ir para".
  - Consertos na página, que ainda falavam do rodapé antigo: a lista do 2.21 vinha do `produtos.json` (desde a v1.8.0
    vem da API); o mapa do shadcn dizia `Popover` no rodapé, no lugar de `Collapsible`, `Sheet` e `Carousel`.
  - `llms.txt` e as instruções do MCP apontam para a API dos produtos.
- 2026-10-29 · v1.8.0 · O rodapé (2.21) passa a ler da API (decisões do usuário D40 a D43):
  `GET https://design-api.ideiabusiness.com.br/api/v1/footer?product=<slug do sistema>`, no servidor, revalidando a
  cada 12 horas (D38). A API entrega os textos da empresa, editados no painel: o nome da marca, a razão social e o
  CNPJ, o e-mail, o título, a frase e o link do "Quem está por trás". Os cards vêm em ordem alfabética, sem o do
  próprio sistema, com o texto do cadastro de cada produto. Nada disso fica mais escrito no código do sistema, e o
  `produtos.json` deixa de ser a fonte do rodapé. Card de produto sem endereço sai sem link. Exemplo `rodape.tsx`
  com a leitura no servidor (`getRodape`) e o componente recebendo os dados; `llms.txt` aponta para a API.
- 2026-10-29 · v1.7.3 · Consertos achados ao montar o painel administrativo com o próprio guia:
  - o `globals.css` gerado de cada produto ganha o bloco base que o `shadcn init` põe
    (`* { @apply border-border outline-ring/50 }` e `body { @apply bg-background text-foreground }`). Sem ele, a borda
    saía na cor do texto (as linhas de tabela e de rodapé ficavam pretas) e, em tela sem fundo próprio, o escuro deixava
    texto claro sobre branco;
  - exemplos `login.tsx` e `rodape.tsx`: as colunas e a seção dos produtos em `minmax(0,1fr)` e as setas do carrossel
    para dentro (`left-0`, `right-0`), que antes faziam a página rolar de lado; e o `<Image unoptimized>` nos logos, que
    vão direto do CDN para o navegador.
- 2026-10-28 · v1.7.2 · O repositório virou monorepo (Fase 10.1, D29 e D30): o guia, a página, a /live e o MCP estão
  em `apps/site`; o `base.json` e as contas do CSS e do contraste, em `packages/tokens`, que a API do painel também
  usa. Nada muda no que o guia diz nem no que o MCP responde, só os caminhos citados em 1.2, 2.21 e 4.2. Comandos
  com pnpm na raiz: `pnpm build:site`, `pnpm check`, `pnpm test`.
- 2026-10-27 · v1.7.1 · Trocar de papel (2.16, decisão do usuário D28): na linha do papel, o ícone de troca
  (`arrow-left-right`) fica no lugar da seta do submenu, à direita, e o ícone da esquerda passa a ser o crachá
  (`id-card`): "Papel: Sysadmin ⇄". No shadcn, `className="[&>svg:last-child]:hidden"` no `DropdownMenuSubTrigger`
  esconde a seta que ele põe por último, sem editar o componente. Guia, exemplo `usuario.tsx`, página e live.
- 2026-10-27 · v1.7.0 · Fase 9: trocar de papel e a área de administração (pedido do usuário; decisões D26 e D27):
  - 2.16 Menu do usuário: quem tem mais de um papel (o Sysadmin tem todos: Sysadmin, Dev, Suporte) troca pela linha
    "⇄ Papel: Sysadmin ›" logo abaixo do cabeçalho, que abre o submenu "Trocar de papel". A tela remonta limpa no papel
    novo, um toast avisa, e o menu e as permissões passam a ser os do papel; sem faixa, porque é a própria pessoa.
  - 2.30 Área de administração (nova): só para quem está como Sysadmin, com a entrada fixa no pé da sidebar, acima do
    usuário. Dentro dela, a sidebar no tom suave da primária (tokens `sidebar-admin`, `sidebar-admin-accent` e
    `sidebar-admin-border`, com o contraste conferido pelo build em todo produto), o bloco "Administração · Todas as
    empresas" no lugar da troca de empresa e só os itens da área (Empresas, Produtos, Usuários). O globals.css de cada
    produto ganhou os tokens e a regra `:root:has([data-area="admin"])`; o `check_globals_css` passa a cobrá-los.
  - Shell, navegação, troca de empresa, checklist, nunca fazer e mapa do shadcn atualizados; exemplos `usuario.tsx`
    (o submenu de papel) e `admin.tsx` (novo); MCP: get_component e o roteiro de auditoria cobrem a 2.30.
  - Página do guia: a troca de papel no 2.16 e a seção 2.30. Live: papéis por pessoa, o menu pelo papel ativo, a troca
    no menu do usuário e a área de administração com as telas de Empresas, Produtos e Usuários (simulação).
- 2026-10-27 · v1.6.1 · Rodapé mais fino e o do login de volta à coluna da direita (decisões do usuário):
  - Login (2.20): o rodapé, ainda estendido, fica na coluna da direita, embaixo do formulário; o painel da marca ocupa a
    altura toda. Na largura toda, debaixo das duas colunas, ficou feio.
  - Rodapé (2.21): cards finos, de 240 × 54px (eram 86), e o card inteiro é o link do produto, que abre em outra aba
    (cursor de mão, fundo `muted` no hover, ↗ discreto à direita, "(abre em outra aba)" para o leitor de tela); sem o
    "Conhecer". "Quem está por trás ↗" sobe para a linha do título (14/500), e a frase fica na largura toda; a linha do
    CNPJ embaixo dos cards só aparece quando a linha do rodapé não tem espaço. A 1024 × 768, o rodapé aberto passou de
    233px (30% da janela) para 191px (25%); a partir de 1280px, para 167px.
- 2026-10-27 · v1.6.0 · Pedido do usuário: a documentação com os estilos do shadcn, o llms.txt e as instruções do MCP
  para os devs.
  - Controles nativos da página e da live no desenho do shadcn (base-nova): a lista dos 31 select da página e dos do
    calendário da live nas cores do popover (no escuro, o Chrome desenhava a lista clara com o texto claro) e, onde o
    navegador deixa (appearance: base-select), o desenho do SelectContent, com o ✓ à direita; checkbox e rádio de 16px
    com a borda input e o marcado em primary; o switch com o trilho e o polegar do shadcn nos dois temas (tokens
    --switch-off, --switch-thumb e --switch-thumb-on no tokens.css), sem o #fff.
  - llms.txt no site (regras para o agente, instruções do MCP e um link por seção), llms-full.txt (o guia inteiro) e uma
    seção por arquivo em /guia/<id>.md, gerados pelo build com o mesmo texto do get_section do MCP.
  - "Para devs e IAs" reescrita: o passo a passo do MCP no Claude Code (token no IdeiaVault, conectar-mcp.sh, .mcp.json,
    /mcp, auditar-projeto), os arquivos para IA sem MCP, onde o guia vive e as pendências de marca. A versão do topo e
    do rodapé da página vem do package.json (estava "v1.2" e "Versão 1.1").
  - MCP: a descrição do get_component inclui segundo menu, passo a passo e assistente de IA.
- 2026-10-27 · v1.5.1 · Nas telas com segundo menu (2.27), toda seção usa a largura toda que sobra, também as de
  formulário (decisão do usuário: até 720px sobrava um vazio à direita; a de Tags, na largura toda, ficou melhor). Guia,
  tipos de tela (3.1), checklist, exemplo, página, roteiro de auditoria do MCP e live (Dados da empresa e SLA). O Perfil
  continua centralizado até 720px.
- 2026-10-26 · v1.5.0 · Fase 8: três coisas que o guia não mapeava, com as decisões do usuário D19 a D22:
  - 2.27 Segundo menu: configurações com várias seções que são telas próprias (Tags, Campos, SLA, Webhooks) ganham um
    segundo menu abaixo do header, com o item da sidebar ativo e fundo `muted` (no escuro, mais claro que a sidebar);
    cada seção com a sua URL e o terceiro nível no breadcrumb; abaixo de 1024px, um Select. Abas não trocam de seção.
  - 2.28 Passo a passo da tela e ajuda: o "?" no header (a ordem fica ? · ✨ · sino) abre a Ajuda; o passo a passo só
    começa por convite, um por tela e por pessoa, de 3 a 5 passos com "Pular", e o último aponta o "?". driver.js (MIT).
  - 2.29 Assistente de IA: o ✨ abre um painel encaixado à direita, de 384px, e o conteúdo encolhe; sem espaço, folha.
    Componentes de chat do shadcn; toda mudança no sistema passa por um cartão de confirmação.
  - Botões do header em `icon-sm`, a altura do botão de recolher. Shell, topo do conteúdo, tipos de tela, abas,
    breadcrumb, navegação, responsividade, checklist e "nunca fazer" ajustados; exemplos novos; o roteiro
    `auditar-projeto` do MCP cobre 2.27 a 2.29. Na página, os mocks e o código das três seções, e o "Novo…" no tamanho
    padrão em 2.1, 3.3 e 2.10 (estava `lg`). Na live: Configurações › Geral com sete seções, o "?" com o convite e o
    passo a passo em Contatos, Tarefas e Tags, e o assistente com respostas de exemplo e duas ações com confirmação.
- 2026-10-26 · v1.4.1 · Token do MCP sem variável de ambiente: `conectar-mcp.sh` (servido em
  design.ideiabusiness.com.br) pede o token sem mostrá-lo, testa no servidor e guarda em `~/.config/ideia-design`; o
  `.mcp.json` dos projetos lê pelo `headersHelper` do Claude Code. O token mora no IdeiaVault (projeto Ideia Design System).
- 2026-10-26 · v1.4.0 · MCP pronto para auditar projetos: prompt `auditar-projeto` (no Claude Code,
  `/mcp__ideia-design__auditar-projeto <produto> <pasta>`), um roteiro que só verifica e relata tokens, componentes do
  shadcn, uso nas telas, shell, cada tela e o `DESIGN.md` local; ferramenta `check_globals_css`, que compara o CSS global
  do projeto com os tokens do produto comparando a cor e não o texto (hex, rgb, hsl, oklch e Tailwind 3), mais raio e
  `@theme inline`. O servidor lê a versão do `package.json`. `integration/README.md` reescrito com o passo a passo
  (token no ambiente, `.mcp.json`, `/mcp`, auditoria). Checklist com link, rodapé no fluxo e telas de configuração.
- 2026-10-26 · v1.3.3 · Rodapé estendido no fluxo da página (decisão do usuário: por cima, ele cobria o fim da lista). A
  parte com os produtos entra acima da linha, o rodapé fica mais alto e a página rola até mostrá-lo; nada fica por cima do
  conteúdo. Em tela de altura cheia, a área que cresce encolhe (o quadro do kanban fica mais baixo). Clicar fora não fecha
  mais (fechar sozinho faria o conteúdo pular); fecham a seta e o Esc. No HTML, os produtos vêm depois da seta (o Tab entra
  neles) e aparecem acima da linha pelo CSS. No celular, continua a folha de baixo (D3). Na página, o toast de exemplo do
  shell saiu de cima da seta do rodapé.
- 2026-10-26 · v1.3.2 · Tamanho de controle só por classe, nunca à mão (decisão do usuário): escala única `--size-xs`,
  `--size-sm`, `--size-default`, `--size-lg`, `--size-item` e `--size-sidebar-lg` no `tokens.css`, gerada dos tokens; botão,
  campo, select, toggle, chip, abas e itens de menu e da sidebar da página e da live leem dela. Saíram da página quatro
  `select` com `height:32px` no próprio elemento, uma regra que forçava a altura de um campo e itens de menu com padding à mão.
  O grupo segmentado passa a ter 32px no total (a borda fica dentro).
- 2026-10-26 · v1.3.1 · O "Novo…" volta ao tamanho padrão (32px), a mesma altura da busca, dos filtros e dos outros botões
  da barra: em `lg` ele ficava desalinhado (o usuário reviu a D5). `lg` não se usa mais nas telas. O "Entrar" da página do
  guia também ficou no padrão, como já estava no guia e na live.
- 2026-10-26 · v1.3.0 · Os 14 pontos da revisão do usuário de 2026-10-23 (Fase 7), feitos no guia, nos exemplos, na página
  e na live, e as dúvidas D1 a D18:
  - 7.A: sem barra de ações; a tela começa na primeira box, e 3.3 virou "Topo do conteúdo".
  - 7.1: kanban de altura cheia (componente 2.26): a página não rola, o quadro e cada coluna rolam; 1,5 coluna no celular.
  - 7.2: rodapé abre só no clique e cresce como extensão do próprio rodapé; no login, estendido na largura toda.
  - 7.3: dashboard sem filtro nem período; o recorte vai na descrição de cada card.
  - 7.4: o "Novo…" mora no canto superior direito do card que ele alimenta, em `lg` (36px).
  - 7.5: sem botão "Atualizar": os dados se releem sozinhos, sem Spinner.
  - 7.6: logo da sidebar com 32px aberta e recolhida.
  - 7.7: abas (2.23) e card de relatório (2.24): visões, filtros e conteúdo dentro do card.
  - 7.8: toda listagem com o padrão completo; toda coluna de valor único ordena; coluna de conjunto fechado vira filtro.
  - 7.9: listagem em duas etapas (3.18), no lugar do "filtro inicial".
  - 7.10: preferências de notificação no sino; o e-mail fica no Perfil.
  - 7.11: telas de configuração sem tabela centralizadas até 720px; foto de 96px no Perfil.
  - 7.12: "Ver como" para o Sysadmin, com a faixa de aviso.
  - 7.13: troca de empresa no topo da sidebar (2.25), em duas linhas com o logo.
  - 7.14: escuro em grafite ("Modern Minimal" do tweakcn); primárias escuras recalculadas; o build falha se faltar contraste.
  - D16: borda de campo com 3:1 nos dois temas. D17: filtro ativo com borda e contador, texto na cor normal.
  - D18: token `link` por produto, mais claro no escuro (4,5:1).
  - Página do guia: doctype, idioma e viewport; numeração da Parte 3 corrigida; sem rolagem lateral de 320 a 1440px; axe
    sem violações nos dois temas.
- 2026-10-26 · v1.2.3 · Medidas do shadcn/ui (estilo nova) em todo o guia, por decisão do usuário (D15): controle de 32px
  (`sm` 28, `lg` 36, `xs` 24; não existe `xl`), campo com 10px de padding, item de menu de 28px, card e modal com padding 16,
  raio pela escala do shadcn (8 / 6 / 11px), foco com anel de 3px, título de box 16/500, tooltip sem atraso, véu a 10% com
  desfoque e `shadow-md`. Duas edições de componente por contraste (botão de perigo com texto `-strong`, toggle ligado na
  primária). Corrigido o `globals.css` gerado: o `@theme inline` não registrava as cores nem a escala de raio, e `bg-primary`
  não existia. Apagado o `globals.template.css`, que não era usado. Página e live com as medidas novas.
- 2026-10-23 · v1.2.2 · Demonstração ao vivo em /live. Tokens `-strong` para texto e ícone sobre superfície tingida:
  a auditoria automática mostrou badge de sucesso e de atenção abaixo de 4,5:1 no claro e de perigo no escuro.
- 2026-10-22 · v1.2.1 · Logos e ícones de 33 produtos no repositório (`public/logos/`), servidos em design.ideiabusiness.com.br
  no lugar do statics; `logos/index.json` e `produtos.json` gerados pelo build; produto novo IDeia Resources (só ícone).
- 2026-10-22 · v1.0 · Primeira versão, decidida ponto a ponto com o usuário.
- 2026-10-22 · v1.2 · Filtros: o componente 2.22 e o padrão 3.5 (escopo, modo de exibição e filtro do conjunto), a validar com os analistas.
- 2026-10-22 · v1.1 · Login em duas colunas no padrão do DevTasks; rodapé de uma linha com a seta que sobe os produtos; item
  ativo do menu cheio (nitidez no escuro); Parte 4 com a stack padrão shadcn/ui + Tailwind e exemplos.
- Pendente: versão escura (branca) do logo completo de DEIA, Agenda, Cockpit, Vault e Plure, e do ícone de 16 produtos
  que vieram num arquivo só (conecta-ri, deia, ideia-agenda, ideia-b2b, ideia-client, ideia-cockpit, ideia-devteam,
  ideia-mei, ideia-migrate, ideia-pay, ideia-resources, ideia-sales, ideia-timestamp, ideia-vault, lapidai, plure-registros).
- Pendente: logo completo do IDeia Resources (só existe o ícone).
- Pendente: preencher descrição e URL em `tokens/produtos.json`; revisar a primária de deia, ideia-arsenal, plure-registros
  e ideia-resources; confirmar a biblioteca de i18n (4.1).