# Global Style Guide IDeia — identidade visual e UX dos SaaS da IDeia (guia, tokens e MCP)

> Guia para agentes de IA, v1.12.0. Documentação para pessoas: https://design.ideiabusiness.com.br · Demonstração ao vivo, com tudo funcionando: https://design.ideiabusiness.com.br/live

## Regras para o agente
- Antes de criar ou alterar uma tela, consulte o guia: pelo MCP (abaixo) ou pelos arquivos deste índice. Cite o número da seção que embasa cada decisão; não invente regra que o guia não tem.
- Precedência: este guia > o docs/DESIGN.md do projeto > o jeito das telas antigas. Mudar uma regra é decisão humana, por PR no repositório Ideia-Business/ideia-design-system.
- Stack padrão: shadcn/ui no estilo nova (base-nova ou radix-nova) + Tailwind 4. Os componentes ficam como o shadcn entrega (medidas, pesos, raio, animações); só se edita o que a seção 4.5 lista.
- Cor só por token: o globals.css do produto (get_tokens). Nenhum hexadecimal, rgb() ou cor da paleta do Tailwind numa tela. Texto de link em text-link, nunca text-primary.
- Tamanho de controle só pela prop size do shadcn (xs, sm, padrão, lg), nunca h-*, px-* ou rounded-* por className. Numa mesma barra, todos os controles na mesma altura.
- Toda tela dentro do shell, sem título nem barra de ações: o nome é o breadcrumb, e o "Novo…" mora no canto do card que ele alimenta.
- Nenhum texto fixo: i18n em pt, en e es. Uma frase, verbo no botão. Teclado, foco visível e contraste de 4,5:1.
- Antes de entregar, passe o checklist (ferramenta checklist do MCP, ou https://design.ideiabusiness.com.br/guia/checklist.md).
- O token do MCP é segredo: nunca o imprima, cole ou grave em arquivo versionado.

## MCP
https://design.ideiabusiness.com.br/mcp — Streamable HTTP, sem sessão. Exige o cabeçalho Authorization: Bearer <MCP_TOKEN> (sem ele, 401).
O token mora no IdeiaVault: organização IdeiaBusiness → projeto Ideia Design System → ambiente prod → MCP_TOKEN.
Claude Code, uma vez por máquina (Linux, macOS ou WSL): sh -c "$(curl -fsSL https://design.ideiabusiness.com.br/conectar-mcp.sh)"
  Pede o token sem mostrá-lo, testa no servidor e guarda em ~/.config/ideia-design (só o usuário lê). Também instala a skill aplicar-guia-ideia em ~/.claude/skills (pedir "aplicar o guia" a carrega; ela segue o roteiro aplicar-guia do MCP).
.mcp.json na raiz do projeto (sem segredo, vai para o git):
  {"mcpServers":{"ideia-design":{"type":"http","url":"https://design.ideiabusiness.com.br/mcp","headersHelper":"${HOME}/.config/ideia-design/mcp-headers"}}}
Conferir: /mcp no Claude Code mostra ideia-design connected, com 12 ferramentas e 3 prompts. Erro 401: rode o conectar-mcp.sh de novo.
Outro cliente MCP (Cursor, claude.ai, …): a mesma URL com o cabeçalho Authorization: Bearer <token>.
Ferramentas:
- list_sections, get_section(id | número | título), search(query): o guia.
- get_component(name): as regras do componente e o código de exemplo shadcn/ui.
- get_tokens(product, format): o globals.css do produto (css), as cores para o Tailwind 3 (tailwind3) ou o JSON. list_products: os produtos.
- check_globals_css(product, css): compara o CSS global de um projeto com os tokens do produto.
- check_tela(stack, estilo, 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, a composição do motor: asChild no base-nova e render num projeto Radix).
- checklist: o checklist antes de entregar. get_logo_urls(product): os logos.
- get_roteiro("aplicar-guia") e plano_template: o roteiro do prompt aplicar-guia (para quem não consegue começar um prompt) e o modelo do documento que ele grava no projeto.
Prompts:
- auditar-projeto(produto, pasta): audita o front inteiro, só verifica e relata. No Claude Code: /mcp__ideia-design__auditar-projeto <produto> <pasta>
- aplicar-guia(produto, pasta): para aplicar o guia em várias telas, por partes. Questionário, mapeamento num documento no projeto (docs/adocao-guia-ideia.md), revisão humana e uma parte por vez, com o OK de uma pessoa entre elas. No Claude Code: /mcp__ideia-design__aplicar-guia <produto> <pasta>
- revisar-tela(tela, produto): revisa uma tela pela descrição ou pelo código.

## Sem MCP
- O guia inteiro num arquivo: https://design.ideiabusiness.com.br/llms-full.txt (o mesmo GLOBAL-STYLE-GUIDE.md que vai na raiz de cada projeto).
- Uma seção por arquivo: os links abaixo.
- API dos produtos, sem login: https://design-api.ideiabusiness.com.br/api/v1 (o rodapé em /footer?product=<slug>, os produtos em /products e /products/<slug>, o globals.css em /products/<slug>/globals.css; o contrato OpenAPI em https://design-api.ideiabusiness.com.br/api-docs-json). Como usar: https://design.ideiabusiness.com.br/guia/api.md
- No guia: as cores de cada produto em https://design.ideiabusiness.com.br/tokens/products.json · os logos em https://design.ideiabusiness.com.br/logos/index.json

## Seções
### Início
- [Como usar este guia](https://design.ideiabusiness.com.br/guia/como-usar.md): Para quem é o guia, escopo, neutralidade de stack, precedência e as quatro partes.
- [Princípios](https://design.ideiabusiness.com.br/guia/principios.md): Os dez princípios: mesma experiência em todos os produtos, menos é mais, tudo em box, feedback, mobile-first, acessibilidade, texto curto, dois temas, três idiomas.

### Parte 1 · Estilo
- [1.1 Marca e logo](https://design.ideiabusiness.com.br/guia/style/marca-e-logo.md): Cada produto tem o seu logo e a sua cor primária. Os logos oficiais ficam no CDN da IDeia e se enviam pelo painel, neste padrão de caminho:
- [1.2 Cores](https://design.ideiabusiness.com.br/guia/style/cores.md): 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.
- [1.3 Tipografia](https://design.ideiabusiness.com.br/guia/style/tipografia.md): 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…
- [1.4 Ícones](https://design.ideiabusiness.com.br/guia/style/icones.md): Biblioteca: Lucide, em todos os produtos (existe para web, React, Vue, Svelte, Flutter e SVG
- [1.5 Espaçamento, tamanhos, raio e elevação](https://design.ideiabusiness.com.br/guia/style/espaco-raio-elevacao.md): Os componentes têm as medidas do shadcn/ui (estilo nova), sem edição: controle de 32px, sm 28, lg 36, xs 24. O layout da tela usa a escala de 4px: 4, 8, 12, 16, 24, 32, 48.
- [1.6 Tema claro e escuro](https://design.ideiabusiness.com.br/guia/style/tema.md): Os dois temas são obrigatórios em todo sistema. Toda tela é feita e conferida nos dois.
- [1.7 Movimento](https://design.ideiabusiness.com.br/guia/style/movimento.md): Controles (hover, foco, toggle): 150ms. Flutuantes: as animações do shadcn, 100ms (modal, menu, popover, select) e 200ms (folha lateral).

### Parte 2 · UI Kit
- [2.1 Botão](https://design.ideiabusiness.com.br/guia/components/botao.md): Tamanhos do shadcn: xs 24px, sm 28px, padrão 32px, lg 36px (não existe xl). Só de ícone: quadrado na mesma altura.
- [2.2 Campo de texto e área de texto](https://design.ideiabusiness.com.br/guia/components/campo.md): Anatomia, de cima para baixo: rótulo (14/500, sempre ligado ao controle) › controle (32px, borda input, raio 8, 10px de padding) › ajuda (14, muted-foreground) ou erro (14,…
- [2.3 Select, combobox e data](https://design.ideiabusiness.com.br/guia/components/select-combobox-data.md): Select: mesma anatomia do campo, chevron à direita, até 8 opções. Acima disso, combobox
- [2.4 Checkbox, rádio e switch](https://design.ideiabusiness.com.br/guia/components/checkbox-radio-switch.md): Checkbox para escolha múltipla e para 'aceito'. Rótulo à direita, clicável.
- [2.5 Badge](https://design.ideiabusiness.com.br/guia/components/badge.md): Pílula de 20px (raio redondo), 12/500, 2px × 8px de padding, ícone de 12px à esquerda quando há.
- [2.6 Alerta](https://design.ideiabusiness.com.br/guia/components/alerta.md): 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.
- [2.7 Toast](https://design.ideiabusiness.com.br/guia/components/toast.md): Aviso passageiro, no canto inferior direito (no celular, embaixo, largura total).
- [2.8 Tooltip](https://design.ideiabusiness.com.br/guia/components/tooltip.md): Toda dica ao passar o mouse ou focar é tooltip: fundo popover invertido (escuro no claro, claro
- [2.9 Card e box](https://design.ideiabusiness.com.br/guia/components/card.md): A superfície que embala todo conteúdo: fundo card, contorno de 1px em foreground a 10%, raio 11, padding 16, sem sombra.
- [2.10 Tabela de dados](https://design.ideiabusiness.com.br/guia/components/tabela.md): Toda listagem tabular é uma tabela de dados completa: busca, colunas ordenáveis, um filtro por coluna de conjunto fechado, paginação, '…' de ações e os estados.
- [2.11 Skeleton e Spinner](https://design.ideiabusiness.com.br/guia/components/skeleton-spinner.md): Duas situações, um componente cada. Nunca um texto 'Carregando…' solto.
- [2.12 Estado vazio](https://design.ideiabusiness.com.br/guia/components/estado-vazio.md): Dentro da box, centralizado: ícone 16px num quadrado de 32px em muted › título (14/500: 'Nenhum contato ainda') › descrição (14 muted-foreground, uma frase: 'Cadastre o primeiro…
- [2.13 Modal (diálogo)](https://design.ideiabusiness.com.br/guia/components/modal.md): Confirmação (diálogo de alerta): 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…
- [2.14 Menu suspenso (dropdown)](https://design.ideiabusiness.com.br/guia/components/menu-suspenso.md): Flutuante, raio 8, padding 4, itens de 28px com ícone 16px à esquerda, 14/400, raio 6, hover
- [2.15 Shell: sidebar, header e painel da direita](https://design.ideiabusiness.com.br/guia/components/shell.md): Toda tela do sistema vive dentro do shell. A tela não monta menu, header nem painel lateral próprios.
- [2.16 Menu do usuário](https://design.ideiabusiness.com.br/guia/components/menu-do-usuario.md): No rodapé da sidebar, um botão 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. O menu mostra o papel; quem tem mais de um troca por ali (Papel: Sysadmin ⇄). Só o Sysadmin tem o \"Ver como…\", com a faixa de atenção acima do header.
- [2.17 Breadcrumb](https://design.ideiabusiness.com.br/guia/components/breadcrumb.md): 'Grupo › Tela' no header, 14. O grupo em muted-foreground, sem link; a tela em foreground 500. Tela de detalhe: 'Grupo › Lista › Item' com a lista como link. Encurta com…
- [2.18 Paginação](https://design.ideiabusiness.com.br/guia/components/paginacao.md): Rodapé da tabela: 'N de M linhas' à esquerda; à direita, 'Linhas por página' (select sm, 10/25/50), 'Página X de Y' e as setas (outline só de ícone sm, desabilitadas no…
- [2.19 Avatar](https://design.ideiabusiness.com.br/guia/components/avatar.md): 32px (sm 24, lg 40), redondo; 96px só na foto do Perfil. Foto, ou as iniciais sobre a primary. Troca de foto com prévia na hora, recorte redondo, JPG, PNG ou WebP até 5 MB.
- [2.20 Login](https://design.ideiabusiness.com.br/guia/components/login.md): Fora do shell, em duas colunas: o painel da marca na altura toda e, à direita, o formulário com o rodapé embaixo, já estendido com os produtos.
- [2.21 Rodapé](https://design.ideiabusiness.com.br/guia/components/rodape.md): Todo sistema tem o mesmo rodapé: uma linha; a seta, só no clique, estende o próprio rodapé com os produtos da Ideia Business, em cards finos que abrem em outra aba. No login, na coluna da direita, já vem estendido.
- [2.22 Filtro](https://design.ideiabusiness.com.br/guia/components/filtro.md): Os controles de filtro são os mesmos em toda tela; o que muda é onde ficam (3.5).
- [2.23 Abas](https://design.ideiabusiness.com.br/guia/components/abas.md): O Tabs do shadcn com variant=\"line\", como vem: lista de 32px sem fundo, rótulo 14/500, a ativa em foreground com sublinhado de 2px. Abas trocam de visão; o controle segmentado é o mesmo Tabs com variant=\"default\".
- [2.24 Card de relatório](https://design.ideiabusiness.com.br/guia/components/card-de-relatorio.md): O relatório é um card autossuficiente: abas no topo (as visões), filtros logo abaixo (período, produto…), conteúdo embaixo. Estado na URL, com prefixo quando há mais de um na tela.
- [2.25 Troca de empresa](https://design.ideiabusiness.com.br/guia/components/troca-de-empresa.md): No topo da sidebar, logo abaixo do logo do produto, o seletor da empresa em que a pessoa está trabalhando. Quem alcança todas e sai da empresa principal vê a faixa \"Você está em …\" acima do header, com o caminho de volta.
- [2.26 Kanban](https://design.ideiabusiness.com.br/guia/components/kanban.md): Tela de altura cheia: a página não rola; o quadro rola na horizontal, com a barra à vista, e cada coluna rola na vertical, com o cabeçalho parado. Arrastar e soltar, mais \"Mover para\" no \"…\" do card. Todo kanban de todo produto segue isto.
- [2.27 Segundo menu](https://design.ideiabusiness.com.br/guia/components/segundo-menu.md): Quando um item do menu tem seções que são telas próprias (as configurações: Tags, Campos, SLA, Webhooks), elas vão num segundo menu: uma coluna de 224px abaixo do header, à esquerda do conteúdo, em `muted`. O item continua ativo na sidebar; a seção aberta fica destacada de leve. Abaixo de 1024px, vira um Select.
- [2.28 Passo a passo da tela e ajuda](https://design.ideiabusiness.com.br/guia/components/passo-a-passo.md): O botão ? no header abre a Ajuda. Na primeira visita a uma tela com passo a passo, um convite sai dele; o passo a passo nunca começa sozinho. Ele destaca uma parte da tela por vez, com um cartão de título, uma frase, \"2 de 4\", Pular, Voltar e Próximo. driver.js, com o cartão no desenho do Popover.
- [2.29 Assistente de IA](https://design.ideiabusiness.com.br/guia/components/assistente-ia.md): O botão ✨ no header abre o assistente num painel encaixado à direita, de 384px: o conteúdo encolhe e nada fica coberto; sem espaço, vira folha. Sugestões da tela, respostas com copiar e avaliação, e toda mudança no sistema passa por uma confirmação. Componentes de chat do shadcn.
- [2.30 Área de administração](https://design.ideiabusiness.com.br/guia/components/area-admin.md): Só para quem está como Sysadmin. A entrada fica fixa no pé da sidebar, acima do menu do usuário. Dentro da área, a sidebar inteira ganha um tom suave da primária, o seletor de empresa dá lugar ao bloco \"Administração\" e o menu tem só os itens administrativos (empresas, produtos, usuários). A mesma entrada vira \"Sair da administração\".

### Parte 3 · Padrões
- [3.1 Tipos de tela](https://design.ideiabusiness.com.br/guia/patterns/tipos-de-tela.md): Lista (a maioria) · card com a tabela de dados, logo abaixo do header; criar e editar em modal
- [3.2 Navegação e menu](https://design.ideiabusiness.com.br/guia/patterns/navegacao.md): Cada item do menu é uma tela. Os itens entram em grupos pelo que são (o que se usa no dia a
- [3.3 Topo do conteúdo](https://design.ideiabusiness.com.br/guia/patterns/barra-de-acoes.md): Header e, logo abaixo, a primeira box. Não existe barra de ações: o que ficava nela mora no card a que pertence.
- [3.4 Formulários](https://design.ideiabusiness.com.br/guia/patterns/formularios.md): Criar e editar são o mesmo formulário, com os campos preenchidos na edição.
- [3.5 Filtros: escopo, modo de exibição e filtro do conjunto](https://design.ideiabusiness.com.br/guia/patterns/filtros.md): Cada filtro tem um nível, e cada nível tem um lugar.
- [3.6 Tabelas e listas](https://design.ideiabusiness.com.br/guia/patterns/tabelas-e-listas.md): Toda listagem é tabela de dados (2.10), com o padrão completo: busca, colunas ordenáveis, filtro por coluna de conjunto fechado, paginação, '…' e estados.
- [3.7 Feedback: qual componente para cada situação](https://design.ideiabusiness.com.br/guia/patterns/feedback.md): Erro de um campo · mensagem do campo
- [3.8 Carregamento](https://design.ideiabusiness.com.br/guia/patterns/carregamento.md): Primeira carga: Skeleton no formato. Busca, filtro ou ordenação: Spinner, dados mantidos. Releitura automática: nada. Não existe botão Atualizar.
- [3.9 Estados vazios e de erro](https://design.ideiabusiness.com.br/guia/patterns/estados-vazios.md): 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…
- [3.10 Ações destrutivas](https://design.ideiabusiness.com.br/guia/patterns/acoes-destrutivas.md): Excluir, desativar, encerrar, remover acesso: item por último no '…', depois do separador, em
- [3.11 Notificações (o sino)](https://design.ideiabusiness.com.br/guia/patterns/notificacoes.md): Botão só de ícone no header, com o contador de não lidas. O popover tem "Marcar todas como lidas" e o botão de configurações, que abre as preferências de notificação de cada pessoa.
- [3.12 Responsividade](https://design.ideiabusiness.com.br/guia/patterns/responsividade.md): Mobile-first. Pontos de quebra da janela: 640, 768 e 1024px. Abaixo de 768 a sidebar vira
- [3.13 Tema](https://design.ideiabusiness.com.br/guia/patterns/tema.md): 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)](https://design.ideiabusiness.com.br/guia/patterns/i18n.md): Todo sistema nasce preparado para três idiomas: pt-BR (padrão), en e es. Nenhum texto fixo
- [3.15 Acessibilidade](https://design.ideiabusiness.com.br/guia/patterns/acessibilidade.md): 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%, o foco do shadcn.
- [3.16 Texto da interface](https://design.ideiabusiness.com.br/guia/patterns/texto-da-interface.md): As IAs tendem a escrever demais. Aqui, não.
- [3.17 O que nunca fazer](https://design.ideiabusiness.com.br/guia/patterns/nunca-fazer.md): Cor fixa na tela (hexadecimal, nome de cor ou paleta da biblioteca): só tokens.
- [3.18 Listagem em duas etapas](https://design.ideiabusiness.com.br/guia/patterns/duas-etapas.md): Tela que depende de uma escolha começa listando as opções; ao escolher, o mesmo card desliza para a segunda etapa, já filtrada. Volta pelo '← Pessoas' e pelo voltar do navegador, sem Esc; a escolha fica na URL.

### Parte 4 · shadcn/ui + Tailwind
- [4.1 A stack](https://design.ideiabusiness.com.br/guia/stacks/shadcn-tailwind/stack.md): 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…
- [4.2 Tokens: `app/globals.css`](https://design.ideiabusiness.com.br/guia/stacks/shadcn-tailwind/tokens.md): 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…
- [4.3 Mapa: componente do guia → shadcn](https://design.ideiabusiness.com.br/guia/stacks/shadcn-tailwind/mapa.md): 2.1 Botão · Button
- [4.4 Exemplos](https://design.ideiabusiness.com.br/guia/stacks/shadcn-tailwind/exemplos.md): 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.
- [4.5 Personalização em três níveis e cuidados com o CLI](https://design.ideiabusiness.com.br/guia/stacks/shadcn-tailwind/cuidados.md): Nada nosso mora em components/ui/ nem em lib/utils.ts além do que o nível 3 exige; helpers
- [4.6 Projetos ainda em Tailwind 3 + Radix (DevTasks, Radar RH)](https://design.ideiabusiness.com.br/guia/stacks/tailwind3-radix.md): 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.…

### Fim
- [Checklist antes de entregar uma tela](https://design.ideiabusiness.com.br/guia/checklist.md): A tela só está pronta quando passa em todos os itens.
- [API dos produtos](https://design.ideiabusiness.com.br/guia/api.md): De onde os sistemas leem, sem login, o rodapé, as cores, os logos e o globals.css de cada produto, e o que o painel escreve. Endereços, campos, cache, erros e o código no Next.