# Foundations do E-PROC > Gerado do guide vivo em 2026-07-15. Fonte: `content/9.design-patterns/5.foundations/`. **Resumo** das foundations (regras + boas práticas + escalas). Os **tokens canônicos e o enforcement** por stack vivem na suite **me-foundations** (nuxt/shadcn) — este MD não a substitui. Não editar à mão — re-gerar. ## Geral _Visão geral do sistema de cor — camadas, boas práticas, semânticas e paletas base do EDS._ > Base (Nuxt UI Colors) → Semânticas (Primary, Success, Error…) → Tokens (`--ui-*`) → Componente Use sempre a camada Token em componentes e telas. Nunca HEX ou cor base direta. > **Regra de ouro:** em componente/tela/modal use **token** (`var(--ui-...)`). Nunca hex, nunca cor base, nunca semântica direta. O token resolve light/dark sozinho. **Quando usar:** - Cores base só como ponto de partida para compor semânticas e tokens. - "Nomenclatura oficial da escala do sistema (ex.: `me-brand-500`)." - Consultar a paleta base para achar o tom exato ao mapear uma nova necessidade. - Manter consistência usando apenas as famílias já aprovadas. - Níveis de intensidade da escala para orientar contraste e acessibilidade. **Quando NÃO usar:** - Cores base ou HEX direto em componentes, telas e código final. - Valores HEX soltos, arbitrários ou inventados fora das escalas. - "Associar significado direto à cor base (ex.: \"Red 500 é a cor de erro\")." - Alterar opacidade (alpha) ou criar tons manualmente fora da estrutura. - Pular a hierarquia aplicando cor base sem passar pela camada semântica. O sistema de cor do EDS tem 3 camadas. Cada uma consome a anterior; o componente usa só a última. As cores do ME existem para manter identidade e consistência — da primária aos estados de feedback. Ao construir telas no código ou exportar para o Figma, use apenas os tons documentados nesta página. ## Cores semânticas Sete famílias com papel definido na interface. Cada uma tem escala 50 → 950, variantes alpha, tokens prontos e orientações de uso: | Papel | Para que serve | Página | |-------|----------------|--------| | **Primary** | Identidade da marca e ações principais (CTAs) | Primary | | **Neutral** | Texto, fundos, bordas e estrutura visual | Neutral | | **Secondary** | Apoio visual e hierarquia complementar | Secondary | | **Success** | Confirmações, validações e feedbacks positivos | Success | | **Error** | Falhas, erros críticos e ações destrutivas | Error | | **Warning** | Avisos, pendências e situações de cautela | Warning | | **Info** | Contexto informativo e orientações neutras | Info | Depois das semânticas vêm os Tokens — a camada final consumida pelos componentes. ## Paletas base (Nuxt UI Colors) Matéria-prima crua, escala 50 → 950 (nome · hex · oklch). Não entram direto no componente — alimentam as semânticas. Coleção Figma 0 - Nuxt UI Colors. --- ## Primary _Cores primárias do sistema — ações de destaque e identidade de marca, prontas para temas._ > Esta família parte da paleta ME brand documentada em Colors. No produto, essas cores viram Tokens prontos para uso. **Quando usar:** - Estabelecer e reforçar a identidade da marca ativa em toda a plataforma. - Ações principais (CTAs) e elementos de maior hierarquia. - Aplicar via tokens (`--ui-primary`); ao trocar de tema, muda só a origem. **Quando NÃO usar:** - HEX bruto no componente — quebra tokens e tematização. - Como semântica de erro, sucesso ou atenção. - Opacidade manual — use a variante alpha correspondente. - Misturar famílias base na mesma escala primária. ## Cores padrão A paleta ME brand é a identidade visual central do produto. Escala completa + variantes alpha: ## Tematizações alternativas A primária pode mapear outra família conforme a marca — os nomes (`primary-50`…) não mudam, só a origem. --- ## Neutral _Tons neutros — texto, fundo, borda e hierarquia visual, prontos para temas._ > Esta família parte da paleta Slate documentada em Colors. No produto, viram Tokens de texto, superfície e borda. **Quando usar:** - Texto, fundos, bordas e superfícies em toda a plataforma. - Hierarquia visual — tipografia, divisores, camadas. - Aplicar via tokens; ao trocar de tema, muda só a origem da neutra. **Quando NÃO usar:** - HEX bruto no componente. - Para CTAs principais ou destaque de marca (use Primary). - Opacidade manual — use a variante alpha. - Misturar famílias base na mesma escala neutra. ## Cores padrão A paleta Slate é a base estrutural para texto, fundo e borda. Escala completa + variantes alpha: ## Tematizações alternativas Os nomes (`neutral-50`…) não mudam, só a origem. --- ## Secondary _Cores secundárias — apoio visual e hierarquia complementar, prontas para temas._ > Esta família parte da paleta Blue documentada em Colors. No produto, viram Tokens de apoio. **Quando usar:** - Reforçar hierarquia e complementar a marca ativa. - Tokens de apoio — tags, badges, chips, elementos abaixo da primária. - Aplicar via tokens (`--ui-secondary`). **Quando NÃO usar:** - HEX bruto no componente. - Como CTA principal ou maior destaque (use Primary). - Opacidade manual — use a variante alpha. - Misturar famílias base na mesma escala secundária. ## Cores padrão A paleta Blue é o apoio visual central. Escala completa + variantes alpha: ## Tematizações alternativas Os nomes (`secondary-50`…) não mudam, só a origem. --- ## Success _Família Success — confirmações, validações positivas e feedback de conclusão._ > Esta família parte da paleta Green documentada em Colors. No produto, vira o token `--ui-success`. **Quando usar:** - Conclusão positiva, confirmações e validações. - Tokens de feedback — toasts, badges, alertas, indicadores de operação concluída. - Mapeia sempre para a paleta Green. **Quando NÃO usar:** - HEX bruto no componente. - Para erros, avisos ou informações neutras. - Opacidade manual — use a variante alpha. - Como única indicação — combine com texto ou ícone. ## Cores padrão A paleta Green é a referência de sucesso. Escala completa + variantes alpha: --- ## Error _Família Error — falhas, validações negativas e ações destrutivas._ > Esta família parte da paleta Red documentada em Colors. No produto, vira o token `--ui-error`. **Quando usar:** - Falhas, validações negativas e ações destrutivas. - Tokens de feedback — toasts, badges, alertas, indicadores de falha. - Mapeia sempre para a paleta Red. **Quando NÃO usar:** - HEX bruto no componente. - Para sucessos, avisos leves ou informações neutras. - Opacidade manual — use a variante alpha. - Em situações negativas que não representem falha real. ## Cores padrão A paleta Red é a referência de erro. Escala completa + variantes alpha: --- ## Warning _Família Warning — avisos, pendências e feedback de cautela sem indicar erro grave._ > Esta família parte da paleta Yellow documentada em Colors. No produto, vira o token `--ui-warning`. **Quando usar:** - Avisos, pendências e cautelas que não bloqueiam o fluxo. - Tokens de feedback — toasts, badges, indicadores de atenção moderada. - Mapeia sempre para a paleta Yellow. **Quando NÃO usar:** - HEX bruto no componente. - Para erros graves, sucessos ou informações puramente neutras. - Opacidade manual — use a variante alpha. - Como substituto de Error em problemas que exigem ação imediata. ## Cores padrão A paleta Yellow é a referência de aviso. Escala completa + variantes alpha: --- ## Info _Família Info — contexto, orientações e mensagens informativas sem tom de alerta._ > Esta família parte da paleta Blue documentada em Colors. No produto, vira o token `--ui-info`. **Quando usar:** - Contexto, orientações e mensagens que não exigem ação imediata. - Tokens informativos — banners, toasts de processamento, indicadores de contexto. - Mapeia sempre para a paleta Blue. **Quando NÃO usar:** - HEX bruto no componente. - Para erros, sucessos, avisos ou ações primárias de destaque. - Opacidade manual — use a variante alpha. - Como cor primária da marca — Info tem papel estritamente informativo. ## Cores padrão A paleta Blue é a referência informativa. Escala completa + variantes alpha: --- ## Geral _Visão geral dos tokens — regras de aplicação, famílias, modos claro/escuro e exemplos de uso._ > Não invente variáveis de cor (`--ui-custom`, hex inline, `bg-[#...]`). Use os tokens documentados nas famílias abaixo. > Prefira referenciar o token em vez de repetir a cor. Os componentes do sistema já consomem os tokens por padrão. **Quando usar:** - Definir fundo, texto e bordas com os tokens oficiais das famílias documentadas. - Comunicar sucesso, erro, atenção e informação com os tokens de feedback. - Variantes com transparência (alpha) para overlays, hovers e fundos sutis. - Conferir a família correta antes de passar para o dev. **Quando NÃO usar:** - "Cores digitadas manualmente (`#1052E0`, `rgb(...)`, etc.)." - Tons avulsos de paleta quando já existe um token para aquele papel. - Duplicar estilos de modo escuro quando o token já se adapta sozinho. - Criar tokens novos fora do que está documentado aqui. Os tokens aplicam a identidade no dia a dia — fundo, texto, bordas, marca e alertas — com suporte a claro/escuro. São a camada final: o que o componente realmente consome. Existem para que modo claro, modo escuro, marcas e estados de feedback mudem juntos — sem ajustar cor por cor em cada tela. ## Famílias de tokens | Família | O que cobre | Página | |---------|-------------|--------| | **Marca** | Primária e secundária (ações, identidade) | Marca | | **Feedback** | Sucesso, info, atenção, erro | Feedback | | **Neutro** | Token neutro base | Neutro | | **Texto** | Hierarquia tipográfica | Texto | | **Background** | Fundos — página, cards, overlays | Background | | **Borda** | Divisores e contornos | Borda | ## Regras de aplicação Cada token tem um papel definido. As cores primitivas (Colors) viram paletas semânticas; os tokens são a camada final — a que se usa de fato na tela. No modo claro, marca e feedback costumam usar tons mais escuros; no escuro, tons mais claros. Cada família mostra exatamente qual referência vale em cada combinação. - **Texto:** do mais forte (títulos) ao mais suave (legendas e apoio). - **Background:** do fundo principal ao fundo elevado ou destacado. - **Borda:** padrão para divisões; versão acentuada quando precisar de mais ênfase. - **Marca:** primária para ações principais; secundária para apoio visual. ### Como ler a tabela Cada célula mostra de onde vem a cor do token. Clique nas referências para ir à paleta primitiva ou semântica correspondente em Colors. | O que aparece | Significado | Exemplo | |---------------|-------------|---------| | `UIColors/…` | Tom da paleta base de cores | `UIColors/ME brand/500` | | `primary-*` | Cor semântica da marca | `primary-500` → página Primary | | `neutral-*` | Cor semântica neutra | `neutral-700` → página Neutral | | `alpha/…` | Mesma cor com transparência | `alpha/500-50` → 50% de opacidade | | `White / 000000` | Branco ou preto puro | Usado em fundos e contrastes | - Tokens em 6 famílias — cada uma com bloco sólido e bloco alpha logo abaixo, quando aplicável. - Paleta completa documentada em Colors e nas páginas de cada família. ### Contraste e legibilidade Os pares de texto e fundo foram pensados para manter leitura confortável nos dois modos. Se combinar tokens de formas diferentes das sugeridas, vale testar se o texto continua fácil de ler. - Texto principal sobre fundo padrão; tons mais suaves sobre fundos mais suaves. - Evitar texto muito fraco onde a pessoa precisa decidir algo importante. - Texto invertido e fundo invertido funcionam como par — use-os juntos. - Alertas de erro e sucesso: escolher texto que contraste bem com o fundo do alerta. ### Modo claro e escuro Modo e tema são duas dimensões independentes — entender a diferença evita retrabalho: | Dimensão | O que muda | Quem controla | |----------|-----------|---------------| | **Modo** (claro ↔ escuro) | Todas as famílias de token | Classe `dark` no `` — gerenciada pelo Nuxt Color Mode | | **Tema** (brand A ↔ brand B) | Só a família Marca (`--ui-primary`) | Configuração do tema ativo no `app.config.ts` | **Como funciona na prática:** o sistema injeta a classe `dark` no elemento `` quando o usuário alterna o modo. Cada token CSS tem dois valores declarados — um para light, outro para dark. O browser resolve o valor certo automaticamente. O dev não escreve nenhuma condicional; o designer não precisa duplicar telas — usar o token já cobre os dois modos. As tabelas de cada família mostram as colunas Light e Dark exatamente por isso: para deixar explícito qual primitiva o token aponta em cada modo. ### Trocar de tema A troca de tema afeta somente a família Marca. Texto, fundo, bordas e feedback usam a escala neutra — são os mesmos em qualquer tema. Só `--ui-primary` (e suas variantes alpha) aponta para paletas diferentes conforme a brand configurada. - Configurar o tema correto em `app.config.ts` antes de implementar. - Verificar que `--ui-primary` resolve para a paleta esperada no ambiente de destino. - Demais tokens não precisam de atenção ao trocar de tema. ### Estados interativos Hover, foco e pressed devem usar os tokens previstos para isso — variantes com transparência ou tons um degrau mais forte — em vez de inventar opacidade sobre uma cor fixa. - Hover em ação primária: variantes alpha ou tom mais forte da primária. - Anel de foco: variantes alpha mais suaves da primária. - Desabilitado: texto mais fraco sobre fundo mais neutro. - Selecionado / ativo: fundo acentuado com texto em destaque. ## Exemplos de uso Os componentes do sistema já consomem os tokens por padrão. Quando montar algo customizado, prefira referenciar o token em vez de repetir a cor. ```vue
Conteúdo que se adapta ao modo claro/escuro
Salvar
Estado interativo
``` --- ## Marca _Tokens de marca — primária e secundária para ações e identidade._ > Cada token aponta para uma paleta em Colors. Regras gerais no hub de Tokens. **Quando usar:** - Ações principais e CTAs com `--ui-primary` (ou variantes alpha). - Apoio visual e chips com `--ui-secondary`. - Hover e foco com tokens alpha (`--ui-primary-25`, `--ui-primary-10`). **Quando NÃO usar:** - HEX ou rgb soltos no lugar dos tokens de marca. - Opacidade manual quando já existe token alpha. - Secundária como substituto da primária em ações principais. ## Guia de decisão | Contexto | Token recomendado | |----------|------------------| | CTAs e botões de ação principal | `--ui-primary` | | Fundo sutil de hover / foco sobre primária | `--ui-primary-10` ou `--ui-primary-25` | | Chip, badge e elementos de apoio | `--ui-secondary` | | Fundo sutil de hover / foco sobre secundária | `--ui-secondary-10` ou `--ui-secondary-25` | | Estado pressed / tom mais forte | `--ui-color-primary-600` | ## Pareamentos recomendados | Contexto | Fundo | Texto / ícone | |----------|-------|---------------| | Botão primário (solid) | `--ui-primary` | `--ui-text-inverted` | | Hover de botão outline primary | `--ui-primary-10` | `--ui-primary` | | Chip / badge de marca ativo | `--ui-primary-25` | `--ui-primary` | | Item ativo em navegação | `--ui-primary-10` | `--ui-primary` | | Botão secondary (solid) | `--ui-secondary` | `--ui-text-inverted` | ## Onde aparece | Token | Componentes | |-------|------------| | `--ui-primary` | UButton (color=primary solid), UBadge (color=primary), indicador ativo de UTabs, anel de foco de UInput, NavBar | | `--ui-primary-*` (alpha) | Hover de UButton outline, fundo de chip ativo, anel de foco global | | `--ui-secondary` | UButton (color=secondary), UBadge (color=secondary) | | `--ui-secondary-*` (alpha) | Hover e foco em contextos de secundária | --- ## Feedback _Tokens de feedback — sucesso, info, atenção e erro._ > Cada token aponta para uma paleta em Colors. Regras gerais no hub de Tokens. **Quando usar:** - Sucesso em confirmações e conclusão de fluxos. - Info em banners orientativos e contexto. - Warning em situações que exigem atenção sem bloqueio. - Error em falhas, validação e bloqueios. - Alpha para fundos sutis de alerta e badges. **Quando NÃO usar:** - Cores de feedback fora dos tokens documentados. - Error ou Warning como decoração sem significado. - Misturar famílias de feedback na mesma mensagem. ## Guia de decisão | Quando usar | Token | |-------------|-------| | Ação concluída, fluxo finalizado com sucesso | `--ui-success` | | Contexto informativo, orientação, dica | `--ui-info` | | Atenção necessária — sem bloqueio do fluxo | `--ui-warning` | | Erro, validação falhou, ação bloqueada | `--ui-error` | | Fundo sutil de alerta ou badge de status | versão alpha (`--ui-[estado]-10` / `--ui-[estado]-25`) | ## Pareamentos recomendados Substitua `[estado]` por `success`, `info`, `warning` ou `error` conforme o contexto. | Contexto | Fundo | Texto | |----------|-------|-------| | Badge / chip de status | `--ui-[estado]-25` | `--ui-[estado]` | | Banner / alerta sutil | `--ui-[estado]-10` | `--ui-color-[estado]-600` | | Mensagem de validação inline | — | `--ui-error` | | Ícone de estado em linha de tabela | — | `--ui-[estado]` | ## Status → tom (mapa canônico) Os **status de negócio** do ME mapeiam para os tons de feedback de forma consistente — a mesma cor significa a mesma coisa em qualquer index, documento ou dashboard (*reconhecer, não decorar*). Esta tabela é a **fonte única** desse mapa; o badge sempre carrega o **rótulo textual** (o tom nunca é o único portador de significado — acessibilidade). | Status (exemplos) | Tom | |-------------------|-----| | Rascunho · Neutro | `neutral` | | Em análise · Em aprovação · Em andamento | `info` | | Pendente · Aguardando · A vencer | `warning` | | Aprovado · Concluído · Liberado · Confirmado | `success` | | Recusado · Cancelado · Bloqueado · Com inconsistência | `error` | > Use no Badge de status. O texto do badge é curto (1–2 palavras); o detalhe vai na descrição, não no rótulo. ## Onde aparece | Token | Componentes | |-------|------------| | `--ui-success` | UAlert (color=success), UBadge (color=success), UFormField (mensagem de sucesso) | | `--ui-info` | UAlert (color=info), UBadge (color=info), `::callout` (color=info) | | `--ui-warning` | UAlert (color=warning), UBadge (color=warning), `::callout` (color=warning) | | `--ui-error` | UAlert (color=error), UFormField (erro de validação), UInput (estado de erro), UBadge (color=error) | --- ## Neutro _Token neutro base para componentes sem ênfase de marca ou feedback._ > Para texto, fundo e borda do dia a dia, prefira os tokens das famílias Texto, Background e Borda. **Quando usar:** - Componentes com `color="neutral"` ou equivalente semântico. - Base neutra quando o contexto não exige marca ou feedback. **Quando NÃO usar:** - Substituir `--ui-text` ou `--ui-bg` quando o token específico já existe. - Inventar tons neutros fora do mapeamento. ## Onde aparece | Token | Componentes | |-------|------------| | `--ui-neutral` | UButton (color=neutral), UBadge (color=neutral), base de estados sem ênfase semântica | --- ## Texto _Tokens de texto — hierarquia de leitura do mais forte ao mais suave, incluindo invertido._ > Derivam da escala Neutral. Regras gerais no hub de Tokens. > Os pares são válidos em claro e escuro — cada token resolve automaticamente para a primitiva correta em cada modo. Consulte as páginas de cada família para ver os valores resolvidos. **Quando usar:** - Títulos e ênfase com `--ui-text-highlighted`. - Corpo e labels com `--ui-text`. - Legendas e metadados com `--ui-text-muted` / `--ui-text-dimmed`. - Texto sobre fundos invertidos com `--ui-text-inverted`. **Quando NÃO usar:** - Texto principal com tokens muted/dimmed. - Combinações texto/fundo que prejudiquem contraste. - Opacidade manual no lugar de tokens alpha de texto. ## Guia de decisão | Contexto | Token recomendado | |----------|------------------| | Títulos, headings, ênfase máxima | `--ui-text-highlighted` | | Corpo de texto, labels de formulário | `--ui-text` | | Texto de apoio, subtítulos | `--ui-text-toned` | | Metadados, timestamps, placeholders | `--ui-text-muted` | | Caption, hint, texto auxiliar | `--ui-text-dimmed` | | Texto sobre fundo invertido (tooltip, banner) | `--ui-text-inverted` | ## Pareamentos recomendados | Contexto | Background | Texto | |----------|-----------|-------| | Conteúdo principal | `--ui-bg` | `--ui-text` | | Card / painel | `--ui-bg-elevated` | `--ui-text` | | Metadado em card | `--ui-bg-elevated` | `--ui-text-muted` | | Heading de seção | `--ui-bg` | `--ui-text-highlighted` | | Tooltip / background invertido | `--ui-bg-inverted` | `--ui-text-inverted` | ## Onde aparece | Token | Componentes | |-------|------------| | `--ui-text-highlighted` | UCard (título), UModal (heading), UBreadcrumb (item ativo) | | `--ui-text` | UButton (label), UInput (valor digitado), USelect (valor), UTable (células) | | `--ui-text-toned` | UBadge (outline), UAlert (texto secundário) | | `--ui-text-muted` | UInput (placeholder), UFormField (hint/label), UTable (header), UBreadcrumb | | `--ui-text-dimmed` | UPagination (itens inativos), estados desabilitados globalmente | | `--ui-text-inverted` | Tooltip, UBadge (solid neutro), UButton (primary solid) | --- ## Background _Tokens de background — fundos de página, cards, modais e overlays._ > Derivam da escala Neutral. Regras gerais no hub de Tokens. > Os pares são válidos em claro e escuro — cada token resolve automaticamente para a primitiva correta em cada modo. Consulte as páginas de cada família para ver os valores resolvidos. **Quando usar:** - Fundo principal da página com `--ui-bg`. - Cards e blocos com `--ui-bg-elevated` ou `--ui-bg-muted`. - Destaque estrutural com `--ui-bg-accented`. - Overlays e scrims com tokens alpha (`--ui-bg-90`, `--ui-bg-inverted-80`). **Quando NÃO usar:** - "Fundos avulsos (`#fff`, `gray-100`) fora dos tokens." - Alpha improvisada quando o token alpha já existe. - Background invertido sem par com texto invertido. ## Hierarquia de elevação As superfícies formam uma **escada** — do mais plano (ao fundo) ao mais elevado (mais perto de quem usa). Suba um degrau só quando o conteúdo precisa se separar do que está atrás; não pule degraus. 1. **`--ui-bg`** — base da página, o fundo de tudo. 2. **`--ui-bg-muted`** — apoio sutil sobre a base (sidebar, fundo de seção). 3. **`--ui-bg-elevated`** — conteúdo que "sobe" da base (card, modal, popover, dropdown). 4. **`--ui-bg-accented`** — realce pontual sobre uma superfície (hover de linha, item ativo). 5. **`--ui-bg-inverted`** — alto contraste, fora da escada (tooltip, badge sólido). A elevação vem do **token de superfície + borda + sombra** combinados — nunca de opacidade. ## Guia de decisão | Contexto | Token recomendado | |----------|------------------| | Fundo principal da página | `--ui-bg` | | Sidebar, área de apoio, fundo de seção sutil | `--ui-bg-muted` | | Card, painel, modal, popover | `--ui-bg-elevated` | | Hover de linha ou item, chip/badge ativo | `--ui-bg-accented` | | Tooltip, banner de alto contraste | `--ui-bg-inverted` | | Overlay com transparência | `--ui-bg-75` ou `--ui-bg-90` conforme opacidade desejada | ## Pareamentos recomendados Combinações validadas de background + borda + texto. Evite montar pares fora dessas combinações sem testar contraste. | Contexto | Background | Borda | Texto | |----------|-----------|-------|-------| | Página base | `--ui-bg` | `--ui-border-muted` | `--ui-text` | | Card / painel / modal | `--ui-bg-elevated` | `--ui-border` | `--ui-text` | | Sidebar / área de apoio | `--ui-bg-muted` | `--ui-border-muted` | `--ui-text-muted` | | Hover de linha / item interativo | `--ui-bg-accented` | — | `--ui-text` | | Tooltip / background invertido | `--ui-bg-inverted` | — | `--ui-text-inverted` | ## Onde aparece Alterações nesses tokens afetam diretamente os componentes abaixo — use como referência de impacto antes de propor ajustes. | Token | Componentes | |-------|------------| | `--ui-bg` | UCard (solid), UModal (fundo do conteúdo), base do layout | | `--ui-bg-muted` | UAlert (variant sutil), UInput (desabilitado), UTabs (barra de abas) | | `--ui-bg-elevated` | UCard, UModal (overlay), UPopover, UDropdownMenu, LoginForm | | `--ui-bg-accented` | UTable (zebra / linha expandida), hover global de item interativo | | `--ui-bg-inverted` | Tooltip, UBadge (solid neutro) | --- ## Borda _Tokens de borda — divisores e contornos que delimitam e reforçam hierarquia._ > Derivam da escala Neutral. Regras gerais no hub de Tokens. > Os pares são válidos em claro e escuro — cada token resolve automaticamente para a primitiva correta em cada modo. Consulte as páginas de cada família para ver os valores resolvidos. **Quando usar:** - Divisores e contornos padrão com `--ui-border`. - Separadores discretos com `--ui-border-muted`. - Ênfase estrutural com `--ui-border-accented`. - Contornos em superfícies invertidas com `--ui-border-inverted`. **Quando NÃO usar:** - Bordas com cor fixa fora dos tokens. - `border-accented` em excesso — dilui a hierarquia. - Borda como único indicador de estado (prefira tokens de feedback). ## Tokens Esta família não possui variantes alpha documentadas. ## Guia de decisão | Contexto | Token recomendado | |----------|------------------| | Separador discreto, divisor interno em lista densa | `--ui-border-muted` | | Contorno padrão de card, input, container | `--ui-border` | | Hover de card, item selecionado, ênfase estrutural | `--ui-border-accented` | | Contorno em background invertido (tooltip, banner) | `--ui-border-inverted` | ## Pareamentos recomendados | Contexto | Background | Borda | |----------|-----------|-------| | Card / painel padrão | `--ui-bg-elevated` | `--ui-border` | | Separador de linha em tabela ou lista | — | `--ui-border-muted` | | Card ou container com hover / foco | `--ui-bg-elevated` | `--ui-border-accented` | | Elemento em background invertido | `--ui-bg-inverted` | `--ui-border-inverted` | | Sidebar / área de apoio | `--ui-bg-muted` | `--ui-border-muted` | ## Onde aparece | Token | Componentes | |-------|------------| | `--ui-border-muted` | UTable (separadores de linha), UTabs (underline), Forehead | | `--ui-border` | UCard, UInput, USelect, UTextarea, UModal (divisores internos), CriterionInput | | `--ui-border-accented` | UInput (foco), UButton (outline hover), UCard (hover) | | `--ui-border-inverted` | Elementos sobre background invertido — Tooltip, banner | --- ## Charts _Tokens de cor das séries de gráfico — paleta categórica de 10 cores (--chart-1 a --chart-10), não-semântica, com light/dark automático._ > Paleta **categórica** para **diferenciar séries** de um gráfico — **não** carrega significado. Reserve as cores semânticas (success/warning/error/info) para **status**: ver Feedback. Regras gerais no hub de Tokens. **Quando usar:** - Diferenciar séries num mesmo gráfico (linhas, barras, fatias) com --chart-1…10. - UI de dado customizada via var(--chart-1) ou utilitários bg-/text-/fill-/stroke-. - Sobrescrever a paleta de um chart — sempre mantendo-se nos --chart-*. **Quando NÃO usar:** - "Cor de série para comunicar status (verde=ok, vermelho=erro) — use os tokens de feedback." - "HEX cru no lugar dos tokens --chart-*." - "Mais de ~10 séries coloridas — o olho não diferencia; prefira Top N + \"Outros\"." ## Tokens Tom **600 no light**, **400 no dark** — troca automática com o tema. ## Como usar A atribuição é **automática**: cada série recebe `--chart-1`, `--chart-2`… em ordem, alternando quente/frio para máxima distinção com 2–4 séries. Os tokens só entram à mão em UI customizada (`var(--chart-1)` ou utilitários `bg-`/`text-`/`fill-`/`stroke-`) ou ao sobrescrever a paleta de um chart — sempre nos `--chart-*` (continuam acessíveis e sensíveis ao tema). **Acessibilidade:** cor é indício **secundário** — combine sempre com rótulo/marcador direto (Yellow no branco e o par quente×frio podem convergir para daltonismo). Se remover a cor torna o gráfico ilegível, adicione rótulo, marcador ou padrão. --- ## Typography _A tipografia organiza a leitura e cria hierarquia visual nas interfaces. Esta página reúne os estilos, tamanhos e regras aprovadas para uso consistente._ > Não aplique fonte, tamanho ou peso manualmente — como Arial, Inter avulso, `15px` ou `font-weight: 550`. Use os estilos de texto documentados na seção Fontes. > As cores utilizadas na tipografia são as cores definidas em Tokens › Texto. > Aplique os estilos de texto do sistema — não redimensione ou mude peso manualmente em camadas soltas. **Quando usar:** - Aplicar os estilos tipográficos definidos pelo sistema ao criar interfaces no Figma ou no código. - Utilizar estilos de texto conforme sua finalidade (títulos, corpo, labels, destaques). - Combinar tamanho e peso seguindo a hierarquia documentada. - Consultar esta referência para manter consistência entre design e desenvolvimento. **Quando NÃO usar:** - Criar tamanhos ou pesos personalizados fora dos estilos aprovados. - Utilizar fontes diferentes da família tipográfica definida pelo sistema. - Misturar estilos de forma inconsistente quando já existe um padrão. - Utilizar itálico ou peso excessivo para substituir hierarquia visual. ## Fontes Biblioteca oficial de estilos tipográficos utilizados no sistema. ## Regras de aplicação Cada estilo possui tamanhos e alturas de linha definidos. Utilize o peso conforme a função do texto. A aplicação segue regras específicas de cada interface e componente, garantindo consistência e hierarquia visual. ## Exemplos de uso Os componentes do sistema já consomem a escala tipográfica. Quando montar algo customizado, combine tamanho e peso dos tokens documentados. ```vue

Título de página

Título de seção

Corpo de texto — padrão do sistema.

Label ou metadado Ênfase editorial ``` --- ## Spacing _Os espaçamentos ajudam a estruturar conteúdos e manter a leitura mais confortável. Esta página reúne as regras e escalas oficiais do sistema._ > Não use espaçamentos soltos — como `13px`, `gap-[7px]` ou `margin: 17px`. Use os tokens da escala spacing documentados abaixo. > Prefira tokens com valores inteiros e valide com o time o uso de valores fracionados apenas quando necessário. **Quando usar:** - Aplicar padding, margin e gap seguindo a escala definida pelo sistema. - Priorizar a escala padrão antes de recorrer a ajustes específicos. - Manter consistência de espaçamento entre componentes e seções similares. - Seguir esta referência para preservar ritmo e hierarquia visual. **Quando NÃO usar:** - Utilizar valores fora da escala definida. - Aplicar espaçamentos diferentes sem uma necessidade clara. - Misturar padrões de espaçamento na mesma interface. - Utilizar espaçamentos que prejudiquem a hierarquia da interface. ## Spacing Escala oficial de espaçamento utilizada para definir margens, paddings e gaps de forma consistente. ## Regras de aplicação Cada espaçamento segue uma escala baseada em múltiplos de 4px, garantindo consistência e previsibilidade. A escala acompanha a estrutura da interface, começando em grupos internos de componentes e aumentando conforme os elementos se agrupam em blocos e seções maiores. ## Exemplos de uso ```vue
...
...
``` --- ## Border Radius _Os cantos arredondados ajudam a definir a identidade visual e a hierarquia dos componentes. Esta página reúne as escalas e diretrizes oficiais do sistema._ > Não aplique valores personalizados de border-radius. Prefira sempre a escala documentada do sistema. > As cores utilizadas no border radius são as cores definidas em Tokens › Borda. > Utilize os valores de arredondamento definidos pelo sistema e evite aplicar medidas manuais fora da escala oficial. **Quando usar:** - Aplicar border radius seguindo a escala definida pelo sistema. - Utilizar os arredondamentos oficiais para manter consistência visual. - Manter consistência de arredondamento entre componentes semelhantes. - Aplicar arredondamentos proporcionais ao contexto do componente. **Quando NÃO usar:** - Utilizar valores fora da escala oficial. - Aplicar arredondamentos sem contexto ou necessidade clara. - Misturar diferentes padrões de radius na mesma interface. - Utilizar cantos que comprometam legibilidade ou consistência visual. ## Border Radius Escala oficial de border radius utilizada para definir cantos arredondados de forma consistente. ## Regras de aplicação Cada valor de arredondamento segue uma escala fixa para garantir consistência visual entre interfaces e componentes. ## Exemplos de uso ```vue
...
...
``` --- ## Shadows & Elevation _Sombras e elevação ajudam a criar profundidade, hierarquia e destaque visual na interface. Esta página reúne as escalas e diretrizes oficiais do sistema._ > Não aplique sombras personalizadas. Prefira sempre a escala documentada do sistema. > Utilize os valores de sombra e de foco definidos pelo sistema e evite aplicar efeitos manuais fora da escala oficial. **Quando usar:** - Aplicar sombras seguindo os níveis definidos pelo sistema. - Utilizar sombras para reforçar hierarquia e destaque visual. - Manter consistência entre componentes com o mesmo nível de profundidade. - Aplicar sombras proporcionais ao contexto do componente. - Utilizar sombras para indicar sobreposição, foco ou interação. **Quando NÃO usar:** - Utilizar sombras fora da escala oficial. - Aplicar sombras sem necessidade ou significado visual. - Misturar diferentes níveis de sombra sem critério. - Utilizar sombras excessivas que prejudiquem legibilidade ou contraste. ## Shadows & Elevation Duas famílias: Shadow / drop shadow (profundidade e elevação, escala `2xs → 2xl`) e Focus (anel de foco por estado). A cor base das sombras é preto (`#000000`) com a opacidade indicada. O anel de foco usa `2px` do fundo (`--ui-bg`) + `4px` da cor do estado. ## Regras de aplicação Cada nível de sombra segue uma escala padronizada para criar profundidade, reforçar hierarquia e garantir consistência visual entre interfaces e componentes. O foco usa sempre o anel de 2 camadas (gap do fundo + cor do estado), garantindo visibilidade em qualquer superfície. ## Exemplos de uso ```vue
Card normal
Dropdown / Popover
Modal / Drawer
Overlay global
``` --- ## Breakpoints _Use breakpoints para orientar mudanças de layout em diferentes larguras de tela, mantendo a interface consistente, legível e responsiva._ > Evite definir breakpoints ou tamanhos de tela arbitrários. Utilize os padrões e dimensões aprovados pelo sistema. > Cuidado com as siglas iguais. Confirme a tabela correta antes de aplicar a medida na interface. > Mobile não é "encolher o desktop" — é **recolher zonas e priorizar a ação primária**. A página adapta a estrutura (viewport `sm`/`md`/`lg`); o conteúdo interno continua limitado pelos tokens de largura. **Quando usar:** - Tokens de responsividade (sm, md, lg…) só para estruturar colunas e a adaptação da página em diferentes telas. - Tokens de largura (3xs a 7xl) para limitar elementos internos — cards, modais, seções. - "Resoluções de desktop padrão (ex.: 1440×800) como referência principal de projeto." - Consultar esta doc para alinhar proporções e limites entre design e engenharia. - Separar a lógica de adaptação da tela das regras que limitam o conteúdo interno. **Quando NÃO usar:** - "Criar pontos de quebra manuais (ex.: 900px) ou medidas fixas fora das escalas oficiais." - "Confundir escalas: tokens de mesmo nome (ex.: `sm`) têm valores/funções diferentes para tela e componente." - Projetar pensando só em telas grandes, sem prever a quebra em telas menores. - "Inverter as lógicas: token de conteúdo ditando regra de tela, ou vice-versa." - Forçar medidas estáticas; confie no comportamento dinâmico da estrutura. ## Breakpoints Referência oficial das escalas de adaptação de tela e limites de conteúdo, que possuem medidas distintas. ## Regras de aplicação A implementação separa a adaptação da tela (responsividade) das regras que limitam a largura máxima do conteúdo. - **Layouts divididos:** acomodam menus e conteúdo lado a lado quando há espaço. - **Avisos e diálogos:** mantêm largura menor para prender a atenção. - **Limites de conteúdo:** impedem perda de legibilidade em telas muito largas. - **Resolução base (Figma):** ao exportar telas, use sempre 1440×800. ## Comportamento responsivo Os tokens acima dizem **quando** a tela quebra; o **como cada peça se adapta** mora na página do próprio componente (lente UI) — esta Foundation só dá o princípio e aponta onde está cada detalhe. Onde a adaptação de cada peça é documentada: | Peça | Documentação | |------|--------------| | **Subheader** (título + CTAs) | Componentes › Subheader | | **Filter Bar** (persistente) e **Filter Search** (overlay) | Componentes › Filter Bar · Filter Search | | **Tabela** / Lista / Cards | Componentes › Table | | **Modal** e overlays | Componentes › Modal | | **Sidebar** (vira drawer) e composição da página | Padrões › Estrutura de Index · Estrutura de Documento | | **Serviços** (Genius · Chat · Carrinho) | os respectivos padrões | | **Interação** (alvos de toque ≥ 44px, nada dependente de hover) | Foundations › Acessibilidade | ## Exemplos de uso ```vue
...
...
``` --- ## Icons _Ícones ajudam a comunicar ações, estados e navegação de forma rápida e consistente. Esta página reúne os tamanhos, padrões e biblioteca oficial._ > Não aplique ícones personalizados ou fora da biblioteca documentada. Prefira sempre os padrões do sistema. > Utilize apenas a biblioteca Lucide para aplicação de ícones no sistema. **Quando usar:** - Utilizar os ícones oficiais definidos pelo sistema. - Aplicar tamanhos consistentes conforme o contexto da interface. - Reforçar ações, navegação e feedbacks visuais. - Manter o mesmo padrão de ícones entre componentes semelhantes. - Consultar o catálogo oficial antes de adicionar novos ícones. **Quando NÃO usar:** - Misturar diferentes estilos de ícones na mesma interface. - Utilizar tamanhos arbitrários fora dos padrões definidos. - Criar ou editar ícones manualmente sem necessidade. - Ícones decorativos que prejudiquem a hierarquia visual. - Aplicar ícones sem contexto ou significado claro. ## Catálogo Biblioteca oficial de ícones utilizada no sistema, com tamanhos padronizados e catálogo para consulta. ## Regras de aplicação Os ícones devem complementar a interface e reforçar o significado das ações, sem substituir textos importantes. Em ações de tabela, mantenha alinhamento e posicionamento consistentes. ## Exemplos de uso ```vue ``` --- ## Illustrations _Ilustrações padronizadas no Design System, com tamanhos fixos, critérios de uso e catálogo de contextos para aplicação._ > Não use imagens stock, fotos genéricas ou SVGs fora do Foundations. Use apenas as ilustrações desta página — token `sm` (76px), `md` (108px) ou `lg` (142px). > Escolha o contexto no catálogo da seção Referências — não desenhe ilustrações avulsas. Se o contexto não existir, solicite ao design. **Quando usar:** - "Empty states — listas, tabelas e áreas sem registros." - "Tabelas e grids — células/áreas vazias com mensagem de ausência, erro ou orientação." - "Cards — dashboards e blocos informativos sem dados." - "Widgets — dashboards e componentes compactos, respeitando espaço e hierarquia." - "Telas de erro — 404, falhas de carregamento, permissões, conteúdo indisponível." **Quando NÃO usar:** - Fotos, ilustrações stock ou SVGs exportados manualmente. - Redimensionar fora de 76px / 108px / 142px (área do token). - Alterar cores da paleta das ilustrações manualmente. - Usar ilustração sem mensagem — ela complementa, não substitui texto. - Movimentar elementos e transformar em uma nova ilustração. ## Componente Use o componente `EdsIllustration` para aplicar ilustrações padronizadas — combina background com padrão de pontos, ilustração de contexto e badge opcional. ## Referências As ilustrações estão disponíveis em três tamanhos fixos: `sm`, `md` e `lg`. Use os controles para visualizar, ampliar ou baixar o SVG. ## Regras de aplicação Cada ilustração deve acompanhar uma mensagem clara — título, descrição ou ação — e usar o tamanho de token adequado ao componente. - **Empty states:** `md` ou `lg` com título e CTA abaixo. - **Tabelas e grids:** `sm` ou `md` centralizado na área vazia. - **Widgets compactos:** `sm` para não competir com o conteúdo. - Manter a paleta me-brand + slate intacta — sem ajustes manuais de cor. - Se o contexto não existir no catálogo, solicitar ao design antes de improvisar. ## Exemplos de uso ```vue ``` --- ## Brand _Logos, marcas e assinaturas oficiais do ME para garantir consistência visual em produtos, materiais internos e comunicações._ > Não recrie logos, favicons ou sufixos manualmente. Use esta página ou importe do Foundations no Figma — proporções e cores são fixas. > Precisa de sufixo customizado, fundo arco-íris ou badge quadrada? Use sempre o Configurador — o catálogo traz bases e presets, não todas as combinações. **Quando usar:** - "ME Logo Default — fundos claros, páginas institucionais, comunicações padrão." - "ME Logo Primary — quando houver necessidade de reforço visual da marca." - "ME Monograma — espaços reduzidos, ícones, favicons, aplicações compactas." - "Versões com sufixo — quando o produto exigir identificação específica." - "Logo em negativo — fundos escuros ou coloridos, com contraste adequado." **Quando NÃO usar:** - Recriar a marca manualmente — use sempre os arquivos oficiais. - Alterar cores ou proporções — mantenha escala, paleta e composição. - Aplicar efeitos (sombra, contorno, gradiente, blur…). - Usar versões antigas ou não aprovadas. - Combinar a marca com elementos não previstos. Use sempre os arquivos oficiais da marca, respeitando proporção, cor, contraste, área de proteção e contexto. Não altere, redesenhe ou combine logos manualmente. ## Configurador de marca Use a pré-visualização para validar contraste, fundo, variação e tamanho antes de aplicar o logo na interface. ## Referência Assets oficiais da marca ME, organizados por família, variação e contexto. Pesquise, filtre, visualize ou copie o asset. ## Regras de aplicação | Família | Uso típico | Onde personalizar | |---------|-----------|-------------------| | ME-logo | Identidade principal em headers, login e apps | Configurador — cor, badge quadrada, fundo | | Sufix-maker | Novos produtos: me.[nome] | Configurador — sufixo livre e cores | | Favicon | Abas, PWA e app icon | Configurador — px fixo por tamanho sm/md/lg | | topme. | Submarca em campanhas e materiais | Configurador — layout e cores | | DiverseME | Diversidade e inclusão — Logo, Texto ou Coração | Configurador — variantes e fundo arco-íris | | Corações em Ação | Iniciativa social — coração + texto | Configurador — layout e cor do conteúdo | Tamanhos de exportação | Token | Preview | PNG | Quando usar | |-------|---------|-----|-------------| | `sm` | 48 px | @1x | Nav compacta, chips, UI densa | | `md` | 80 px | @2x | Headers, cards, documentação | | `lg` | 128 px | @3x | Hero, apresentações, destaque | ## Exemplos de uso ```vue ``` --- ## Voz e conteúdo _Como o ME escreve — voz, mensagens e nomenclatura. Texto é UX._ O texto é parte da interface — um rótulo ou mensagem mal escrita custa mais que um pixel torto. Esta é a régua de como o ME escreve. O vocabulário (os termos exatos) fica no Glossário. ## Princípios - **Fale como o usuário fala** — termos do dia a dia de compras, não jargão interno ou técnico. - **Lidere pela ação** — diga o que a pessoa faz ("Enviar para aprovação"), não o que o sistema fez ("Submissão efetuada"). - **Curto e claro** — uma ideia por frase; corte a palavra que não muda o sentido. - **PT-BR, sentence case** — só a primeira maiúscula; nunca UPPERCASE em rótulo. ## Mensagens | Tipo | Como escrever | |------|---------------| | **Erro** | O que aconteceu **+ como resolver**, sem culpar o usuário — *"Não foi possível salvar. Verifique a conexão."* | | **Sucesso** | Confirme o resultado e ofereça o próximo passo — *"Pedido criado. Ver pedido →"* | | **Vazio** | Diga o que apareceria ali + o CTA para criar o primeiro item | Qual mecanismo usar (toast efêmero vs alert persistente vs modal) → ver Feedback & Overlays. ## Idioma e i18n PT-BR sentence case é a **voz padrão** do guide — mas o ME é multilíngue. O EletroDS troca o idioma por usuário (en-US · pt-BR · pt-PT · es-ES/MX · fr-CA/FR) pelo `LocalePicker` / `setupI18n` do pacote `@mercadoeletronico/eds-next`; e telas de questionário suportam **idioma por campo** (o conteúdo respondido em locales diferentes). - **Nunca cravar string solta** — todo rótulo/mensagem é uma chave de i18n. A régua de voz vale para o PT-BR; as traduções seguem a mesma intenção (ação, clareza, sentence case na língua). - **Idioma por campo** quando o conteúdo é preenchido por quem responde em idiomas distintos (ex.: perguntas de cotação) — disponível como recurso no Compositor (Formulário → "Idioma por campo"). - O idioma ativo da página (`lang`) é também critério de Acessibilidade. ## Labeling A régua única de como nomear ações e entidades no ME. Padrões e componentes seguem isto — não redefina rótulo caso a caso. ### Nomenclatura de ações | Convenção | Quando | Exemplo | |-----------|--------|---------| | **"Novo X"** | cadastro de uma **entidade** nova (registro mestre) | *"Novo fornecedor", "Novo usuário"* | | **"Adicionar X"** | inserir um **item existente** num contêiner/lista | *"Adicionar item", "Adicionar fornecedor à cotação"* | | **"Gerar X"** | **derivar** um documento de outro, dentro de um fluxo | *"Gerar Pré-Pedido", "Gerar Cotação"* | | **"Novo documento → Tipo"** | split de procurement: o clique cria o tipo padrão, o caret revela os tipos | *Requisição · Cotação · Pedido · Leilão* | | **Verbo no infinitivo** | toda ação de comando | *"Editar", "Excluir", "Filtrar"* — nunca "Editando"/"Edição" | Distinguir **Criar** (permanente) × **Adicionar** (contextual) × **Gerar** (fluxo) previne ação equivocada. ### Rótulos de ação — verbo + entidade explícita | ✅ Bom | ❌ Ruim | |--------|---------| | Ver requisição | Ver | | Abrir detalhes do fornecedor | Abrir | | Consultar contrato | Detalhes | | Visualizar documento de transação | Visualizar | - **Verbo + a entidade explícita** — não deixe o objeto implícito quando o contexto não basta. - **Consistência** entre listagem ↔ header do documento ↔ ações contextuais — o mesmo objeto, o mesmo nome. - **Reflita a profundidade** real (leitura resumida × detalhada). O vocabulário completo (Subheader, Forehead, Filter bar, ações…) está no Glossário. --- ## Acessibilidade _Como o ME garante que a interface funcione para todos — teclado, foco, contraste, leitores de tela e alvos de toque._ Acessibilidade não é uma camada extra — é a interface funcionando para todo mundo, inclusive quem navega por teclado, usa leitor de tela ou tem baixa visão. A meta do ME é [WCAG 2.1 nível AA](https://www.w3.org/WAI/WCAG21/quickref/). Como os componentes vêm de EletroDS → Nuxt UI, boa parte do trabalho já vem pronta — o cuidado está em **como você os compõe e escreve**. ## Princípios - **Tudo pelo teclado** — toda ação alcançável no mouse também no teclado (Tab, Enter/Espaço, Esc). Nada de armadilha de foco. - **Foco sempre visível** — nunca remova o anel de foco; use o token de foco do DS. Quem navega por teclado precisa ver onde está. - **Ordem que faz sentido** — a ordem de foco segue a leitura (cima→baixo, esquerda→direita). Não force com `tabindex` positivo. - **Cor nunca sozinha** — status, erro e seleção precisam de texto ou ícone além da cor (ver Badge). - **Semântica antes de ARIA** — use o elemento certo (`button`, `nav`, heading real). ARIA só quando não há equivalente nativo. ## Teclado e foco A ação destrutiva e o overlay são onde mais se erra: - Modal prende o foco enquanto aberto, fecha no `Esc` e devolve o foco ao gatilho ao fechar. - DropdownMenu e Tabs navegam por setas; o item ativo é anunciado. - Ícone-só (kebab, ações da linha) precisa de rótulo acessível (`aria-label`) — ver Button bar. ## Contraste - Texto normal: **4.5:1**; texto grande (≥ 24px ou ≥ 19px bold) e ícones/bordas significativas: **3:1**. - Use os tokens de cor — eles já são calibrados. Nunca HEX cru, que escapa do contraste validado. - Estado desabilitado é exceção de contraste, mas não deve ser o único sinal de "indisponível". ## Leitores de tela - Toda imagem informativa tem texto alternativo; a decorativa é marcada como tal (não captura foco). - Título de seção é **heading real** na ordem certa (h1 → h2 → h3), não texto grande em negrito — é como o leitor monta o índice da página (ver Card). - Conteúdo que muda sem recarregar (filtro aplicado, Toast) é anunciado por região viva. ## Formulários - Todo campo tem **rótulo visível** associado — placeholder não é rótulo. Ver FormField. - Erro é descrito em **texto** (não só borda vermelha) e ligado ao campo, para o leitor de tela ler junto. - Campo obrigatório é sinalizado de forma textual, não só pelo asterisco de cor. ## Alvos de toque e movimento - Alvo mínimo de **44×44px** em telas de toque; espaçamento suficiente entre ações. - Respeite `prefers-reduced-motion` — anime com moderação e ofereça alternativa estática. --- ## Motion _Como o movimento funciona no ME — durações, curvas, onde usar e o respeito a "reduzir movimento". Funcional, nunca decorativo._ > Movimento no ME é **funcional**: confirma uma ação, orienta de onde algo veio / para onde vai, ou mostra progresso. Nunca é enfeite. Na dúvida, menos. ## Princípios - **Rápido e discreto** — a transição não pode atrasar a tarefa; o usuário mal a percebe conscientemente. - **Com propósito** — anima só o que comunica (estado, entrada/saída, progresso). Sem movimento autônomo (parallax, auto-play, loop decorativo). - **Consistente** — a mesma ação anima do mesmo jeito em qualquer tela. ## Durações As transições do guide ficam em ~150–300 ms — a UI gira em torno de **200 ms**: | Faixa | Quando | |-------|--------| | **~150 ms** | micro-feedback: hover, foco, troca de cor de um controle | | **~200 ms** (padrão) | a maioria das transições — cor (`transition-colors`), `transform`, realces | | **~300 ms** | superfícies maiores entrando/saindo: drawer, modal, sheet, popover | Acima de ~300 ms o movimento começa a "pesar"; abaixo de ~100 ms some sem comunicar. ## Curvas (easing) - **`ease-out`** para entradas (algo aparecendo / expandindo) — começa rápido e desacelera. - **`ease`** para transições simples de estado/cor. - Evite `linear` (mecânico) e `ease-in` isolado em entradas (parece travar no início). ## Onde usar - **`transition-colors`** — hover, foco, estado ativo/selecionado (o caso mais comum). - **`transform`** (translate/scale) — movimento e abertura de painéis; mais barato que animar o layout. - **`opacity`** — fade de overlays e de conteúdo que entra. - **`animate-spin`** — spinner de loading. **`animate-pulse`** — skeleton. - Gráficos: a série não-selecionada perde opacidade (não some) — mantém o contexto. ## Reduzir movimento (acessibilidade) O guide respeita **`prefers-reduced-motion: reduce`** globalmente: transições e animações caem para ~0 e loops/auto-play se desligam. Quem ativa "reduzir movimento" no sistema mantém a UI 100% funcional, sem animação. Nunca dependa do movimento para transmitir informação — ele é sempre **reforço**, não o canal. Ver Acessibilidade. --- ## Estados _Vocabulário canônico de estados — interação (hover, foco, selecionado, desabilitado) e dados (carregando, vazio, erro) — e como o ME expressa cada um._ > Esta é a **referência única** dos estados. Cada componente documenta os seus em detalhe — aqui ficam o **vocabulário**, a regra de como o ME expressa cada estado e o link para onde ele se aplica. Princípio que atravessa tudo: **estado é reforço** — cor nunca sozinha (combine com ícone/rótulo/posição) e movimento é só apoio. > **Cor nunca sozinha.** Selecionado, erro, sucesso etc. sempre combinam cor **+** ícone/rótulo/posição — quem não distingue a cor (daltonismo, baixo contraste) ainda lê o estado. **Foco sempre visível.** **Reduzir movimento:** as transições de estado respeitam `prefers-reduced-motion` (Motion). ## Estados de interação Como um elemento responde ao usuário. Valem em qualquer controle (botão, linha, campo, aba, card). | Estado | O que é | Como o ME expressa | Onde | |--------|---------|--------------------|------| | **Default** | Repouso, sem interação | Superfície e texto base (Tokens) | qualquer elemento | | **Hover** | Cursor sobre o elemento | Leve mudança de superfície (`--ui-bg-accented`) + cursor; transição ~150 ms (Motion) | linhas, itens, botões | | **Foco** | Alcançado por teclado/leitor | **Anel de foco visível** — nunca remover; é requisito de acessibilidade (Acessibilidade) | todo controle interativo | | **Ativo / Selecionado** | Item escolhido / em seleção | Borda/superfície primária (ex.: `ring-primary`); em lote, badge "N selecionados" na Filter Bar | linhas, abas, cards, Checkbox | | **Desabilitado** | Indisponível no contexto | Opacidade reduzida + cursor `not-allowed` + fora da ordem de foco; **explique o porquê** quando não for óbvio | botões (Button), campos, CTAs | ## Estados de dados (assíncrono) Como a tela se comporta enquanto/depois de carregar dados. Prioridade de exibição: **carregando → erro → vazio → conteúdo**. O componente não faz fetch — quem controla esses estados é o squad consumidor. | Estado | O que é | Como o ME expressa | Onde | |--------|---------|--------------------|------| | **Carregando** | Aguardando os dados | **Skeleton** no lugar do conteúdo (respeita as dimensões) ou Spinner sem porcentagem | index, charts, cards | | **Vazio** | Sem dados / sem resultados | **Empty State**: ícone + mensagem contextual + saída clara (CTA primário ou "Limpar filtros") | Views, listas, charts | | **Erro** | Falha ao carregar | **Alert** persistente, com ação de tentar de novo | index, charts, formulários | ---