Arquitetura · Design system
Design system
Fundamentos
O design system do console Superadmin da IconsAI (https://superadmin.iconsai.ai) e dos módulos globais e universais que têm UI. Este é o padrão de toda tela de ferramenta e de observabilidade do ecossistema.
Fonte de verdade: superadmin/docs/DESIGN-SYSTEM-CANONICO.md (regras RB1–RB20 e «Designs canônicos») e o módulo modules/design_system. Os tokens desta página foram lidos do CSS que a produção serve. Nenhum valor foi inventado.
Como uma tela é aprovada
1. A tela é mostrada ao dono na máquina de designs, em https://<app>--<funcionalidade>.design.iconsai.ai/, com o CSS real do aplicativo e dados reais (§18 e §20).
2. O dono aceita ou reprova pelo botão. O aceite vale para o hash exato.
3. Só depois a tela vira código, passa nos testes no servidor e vai ao ar pela fila central.
4. A tela publicada tem de ser idêntica ao hash aceito. Qualquer diferença reprova a entrega.
Mock, imagem estática, Figma, Canva ou tela mostrada dentro de outro sistema não valem como design.
Fundamentos visuais
Largura. Toda tela do Superadmin tem 1600 px de largura útil (ds-largura-pagina). Nenhuma lacuna vazia na lateral.
Título. O título da aba fica à esquerda, com o componente PageHeading: kicker em maiúsculas acima, título grande (titulo-pagina) e o «?» de ajuda ao lado.
Resumo no topo. 100% das abas abrem com um resumo em boxes logo abaixo do título. Todo box tem mini gráfico, é clicável e abre um modal com o detalhe de cada operação (RB20).
Premissas de observabilidade. Toda tela de observabilidade declara o que é medido, de onde vem o dado, quando foi medido e qual decisão o dado permite tomar (RB18).
Cor com significado. Aprovado é verde (ds-positive). Reprovado é vermelho (ds-danger). A cor de ação é ds-brand. Os acentos de ilustração (ds-sun, ds-mint, ds-coral, ds-sky, ds-lilac) nunca carregam texto corrido.
Contraste. Texto com 4,5:1, texto grande e ícone com 3:1, medidos nos dois temas (RB4). Tom sobre tom da mesma família é proibido.
Respiro. Nada sobreposto (RB2). Mínimo de 4 px entre vizinhos e 8 px entre texto e borda (RB3).
Dois temas. Toda tela funciona no claro e no escuro. As cores vêm só dos tokens ds-*; cor escrita à mão é proibida (§19).
Tipografia
Três famílias, todas do Google Fonts:
- Inter (
interface): toda a interface. - Montserrat (
marca): só peças de marca. - IBM Plex Mono (
mono): hash, SHA, e-mail de conta e kicker.
A escala está na aba Typography. O título de página usa 800 clamp(36px, 7vw, 68px)/0.95 com letter-spacing: -0.055em.
Componentes obrigatórios
| Componente | Quando usar | Ferramentas |
|---|---|---|
PageHeading | Em toda aba, como título à esquerda | |
BoxResumo | No resumo do topo; sempre botão, com mini gráfico e modal | |
SystemDialog | Todo modal: abre ao centro, move, redimensiona e fecha por Esc | |
HelpButton | Toda ajuda: «?» dentro de um círculo | |
TabelaCanonica | Toda tabela: ordenável em toda coluna, sem palavra quebrada, data e hora separadas, ações na linha | |
Botao e BotaoIcone | Ações: com ícone e texto; ferramenta só ícone, sem sombra | |
SectionTabs | Abas da tela, cada uma com URL própria |
Iconografia
Botões de ferramenta usam só o ícone, sem sombra e sem enfeite. Ações em modal e em lote usam ícone e texto juntos (RB8). Ícone tem contraste de 3:1 e nome acessível. Ícone de animação só onde o dono aprovou, como no Trainer dashboard.
Wordmark
O wordmark icons.ai é imutável: i em #f97316 (Libre Baskerville 700, 1.55em), cons em branco no escuro, .ai em #ef4444. A cor de marca vive só no wordmark e não entra nos tokens de UI. O conflito de contraste do .ai com a RB4 está registrado para decisão do dono.
Seções desta referência
- Permitido e proibido: as 20 regras RB, cada uma com o certo e o errado.
- Designs canônicos: as telas aceitas pelo dono, com o hash.
- Componentes: cada um com a prévia ao vivo e o exemplo de certo e errado.
Fontes canônicas
Só estas seis famílias podem aparecer nas telas do ecossistema. Todas vêm do Google Fonts e já estão no CSS que a produção serve (--ds-font-*). Qualquer outra fonte é proibida.
| Família | Token | Uso permitido | Pesos | Proibido | Ferramentas |
|---|---|---|---|---|---|
| Inter | --ds-font-interface | Toda a interface: texto, número, tabela, botão, modal | 400, 500, 600, 700, 800 | Trocar por outra sans; usar só para números | |
| Montserrat | --ds-font-marca | Peças de marca e título de entrada | 600, 700 | Texto corrido de interface; tabela | |
| IBM Plex Mono | --ds-font-mono | Hash, SHA, build, e-mail de conta, kicker | 500, 600 | Texto corrido; título | |
| Caveat | --ds-font-manuscrita | Anotação manuscrita em material de marca | 400, 600 | Qualquer tela de ferramenta ou observabilidade | |
| Libre Baskerville | wordmark | Só o «i» do wordmark icons.ai, 700, 1.55em | 700 | Qualquer outro texto | |
| Plus Jakarta Sans | --font-logo | Só «cons» e «.ai» do wordmark icons.ai, 800 (skill logo §2, imutável) | 800 | Título, display ou qualquer texto fora do wordmark |
Escala da interface (Inter)
| Estilo | Tamanho e entrelinha | Peso | Uso | Ferramentas |
|---|---|---|---|---|
titulo-pagina | clamp(36px, 7vw, 68px) / 0,95; tracking −0,055em | 800 | Título da aba (PageHeading), à esquerda | |
h2 | 40px / 1,15 | 600 | Título de seção | |
titulo-modal | 22px / 1,3 | 700 | Título do SystemDialog | |
valor-box | 36px / 1,05 | 800 | Número do box de resumo | |
corpo | 18px / 28px | 400 | Texto corrido | |
label | 14px / 20px | 600 | Rótulo e cabeçalho de tabela | |
caption | 14px / 18px | 500 | Nota de box e legenda | |
mono | 13px / 18px (IBM Plex Mono) | 500 | Hash e SHA |
Regras
- Toda fonte tem fallback declarado:
system-ui, sans-serif,ui-monospace, monospace,Georgia, serifoucursive. - Texto com 4,5:1 e texto grande com 3:1, nos dois temas (RB4).
- Números em colunas usam
font-variant-numeric: tabular-nums. - Proibido: JetBrains Mono, Plus Jakarta Sans fora do wordmark, fonte do sistema sozinha, Arial, Roboto, Space Grotesk, Georgia como texto, serifada em interface, Title Case, letra espaçada em texto corrido.
Cores
Tokens de cor lidos do CSS servido em produção. Cada amostra mostra o valor no tema claro e no escuro.
Componentes
Cada componente com o permitido e o proibido, renderizado com o CSS real do Superadmin.
AnelCapacidade
Cartão de capacidade (disco, memória) em anel com usado e livre, somando 100%, com número e unidade. É um botão: o clique abre o modal com o que ocupa o recurso, ordenado por tamanho.
Botao
Ação de modal e em lote: ícone e texto juntos (RB8), raio ds-radius-botao. Ferramenta de linha (BotaoIcone): só o ícone, sem sombra e sem enfeite, com aria-label. Primária em ds-brand com ds-on-brand; destrutiva em ds-danger.
BoxResumo
Box do resumo no topo da aba. Todo box é um <button>, tem mini gráfico com dado medido e abre um SystemDialog com o detalhe de cada operação contada (RB6, RB7, RB20).
07/11 · sessão 0e4ca3 · 1 entrada · 17:06
04/11 · sessão 3d9732 · 2 entradas · 18:26
Sem gráfico, sem clique, sem modal
EstadoAprovado
Chip de estado. Aprovado em ds-positive; reprovado em ds-danger, com o botão «Corrigir pela GPU MATH» ao lado quando houver correção.
FontesCanonicas
As seis famílias canônicas, cada uma com o uso permitido. Só elas podem aparecer nas telas; qualquer outra fonte reprova o aceite.
HelpButton
Toda ajuda é o «?» centralizado num círculo (ds-radius-ajuda = 50%), com borda e texto em ds-muted, foco em ds-focus-ring e nome acessível que diz do que é a ajuda.
MiniGraficos
Os oito modelos canônicos de mini gráfico (RB24), todos com hover e foco mostrando um mini modal com valor, unidade e data ou categoria (RB23). O modelo é escolhido pelo tipo de dado, e o gráfico fica abaixo do número, na largura toda do box, com ≥ 60% da área útil (RB6).
- Barra empilhada fina49«Gráfico proibido» na captura do dono
- Anel minúsculo3«Proporção errada»: menos de 64 px
- Barras de mesmo tamanho4 e 119Fora de escala (RB26)
- Gráfico no canto82«Ocupação errada»: área vazia ao redor
PageHeading
Título de toda aba do Superadmin, sempre à esquerda, com o kicker em maiúsculas acima e o «?» de ajuda ao lado.
Tokens · Assinaturas de IA
Tokens de IA
✨ Tokens De IA ✨
Centralizado, Title Case, emoji e sem ajuda
PremissasObservabilidade
Faixa obrigatória em toda tela de observabilidade, acima do resumo: o que é medido, a fonte do dado, quando foi medido e qual decisão o dado permite tomar. Dado velho mostra a idade e não se apresenta como atual.
SystemDialog
Todo modal do ecossistema. Abre ao centro, pode ser movido e redimensionado, fecha por Esc e pelo botão «✕» com nome acessível. Véu em ds-overlay.
Órfãos, obsoletos ou mortos há mais de 48 h.
Fonte: inventário do servidor · 07/11/2026 às 20:35 (UTC)
**Status:** `ok` | --- |
Sem rodapé: sem fonte e sem «Fechar» (RB28)
TabelaCanonica
Toda tabela do ecossistema. Toda coluna é ordenável com aria-sort. Nenhuma palavra é quebrada (hyphens: none, identificador com white-space: nowrap). Data e hora ficam em colunas separadas. A coluna «Ferramentas» fica na própria linha, com botões só de ícone; a função de cada ícone aparece em tooltip no hover e no foco, e é o aria-label (RB22). Reprovado em ds-danger, aprovado em ds-positive.
| Ferramentas | |||||
|---|---|---|---|---|---|
| superadmin | Uso dos módulos v8 | 07/11/2026 | 15:34 | aprovado | |
| superadmin | Testes antes do deploy v5 | 07/11/2026 | 14:38 | reprovado |
Permitido e proibido
As 26 regras básicas canônicas (RB1–RB26) de docs/DESIGN-SYSTEM-CANONICO.md, com a data da ordem do dono. Tela que viola qualquer uma é reprovada.
| Regra | Permitido | Proibido | Ferramentas |
|---|---|---|---|
| RB1 Sem traços de IA (13:41) | Texto direto, específico do assunto; frase em caixa de sentença | Texto genérico, travessão em série, Title Case, emoji de enfeite, gradiente ou blob sem função, glassmorphism, grade de três cartões com ícone, número ou depoimento inventado, «lorem», «TODO» | |
| RB2 Sem sobreposição (13:41) | Elementos lado a lado ou empilhados, de 320 a 1920 px, nos dois temas e com zoom de 200% | Qualquer elemento por cima de outro; título estourando o contêiner | |
| RB3 Sem elementos encostados (13:41) | 4 px entre vizinhos e 8 px entre texto e borda, no mínimo | Botão colado em botão; texto encostado na borda; nada cortado | |
| RB4 Sem tom sobre tom (13:41) | Texto 4,5:1; texto grande e ícone 3:1, medidos na camada efetiva e nos dois temas | Texto pouco visível por tom parecido com o fundo | |
| RB5 «?» em círculo (16:52) | HelpButton: «?» centralizado num círculo | «?» em quadrado, em retângulo ou herdado de botão comum | |
| RB6 Mini gráfico ocupa o box (16:52) | Gráfico com ≥ 60% da área útil do box | Gráfico minúsculo com área vazia ao redor | |
| RB7 Box de lista é botão (16:52) | Clique abre SystemDialog com os itens contados | Box de contagem que não abre nada | |
| RB8 Ações por item e em lote (16:52) | Botões por linha e seleção com as mesmas ações, sempre com ícone e texto; irreversível pede confirmação | Checkbox nas linhas no lugar de ferramentas; botão só texto ou só ícone em ação de modal | |
| RB9 Capacidade em anel (16:52) | Disco e memória em anel usado × livre; o clique mostra o que ocupa | Barra ou número solto para capacidade | |
| RB10 Tabela canônica (16:52) | Toda coluna ordenável com aria-sort; sem palavra quebrada; data e hora em colunas separadas; ações na linha | Hifenização; identificador partido; data e hora juntas; tabela sem ordenação | |
| RB11 Infraestrutura por aplicativo (16:52) | Agrupado por aplicativo, com máquina e pasta | Lista solta sem dizer onde está o recurso | |
| RB12 Modal sem Markdown cru (16:52) | Conteúdo renderizado pelo Universal Reader | Asteriscos, crases, «#» ou |--- visíveis | |
| RB13 Termo interno explicado (16:52) | Rótulo que diz o que a coisa é para o dono, ou «?» com a explicação | «ensaio», «run», «snapshot», «fence» soltos | |
| RB14 DoD só com entregas (16:59) | Linhas com prova de entrega | Erro, falha ou pendência no DoD (vão para a aba «Erros») | |
| RB15 DoD em tabela canônica (16:59) | Colunas Aplicativo, Entrega, Data e Hora, ordenáveis | DoD em lista ou cartões soltos | |
| RB16 Resumo do DoD com mini gráficos (16:59) | Cartões por aplicativo e série por período | Resumo só com números | |
| RB17 Modal por linha do DoD (16:59) | Ferramenta que abre o modal com a aba e a URL | Linha sem explicação do que foi entregue | |
| RB18 Observabilidade com premissas (16:59) | Medida, fonte, momento da medição e decisão que o dado permite | Tela sem objetivo, sem premissa e sem tomada de decisão | |
| RB19 Só publica o que está no DoD (16:59) | Cada commit de implementação com linha no DoD | Implementação publicada sem linha no DoD | |
| RB20 Todo box clicável, com modal e mini gráfico (17:30) | 100% dos boxes como botão, com modal do detalhe de cada operação e mini gráfico | Box só com número, sem clique, sem modal ou sem gráfico | |
| RB21 Só fontes canônicas (17:40) | Inter, Montserrat, IBM Plex Mono, Caveat, Libre Baskerville («i» do wordmark) e Plus Jakarta Sans 800 («cons.ai» do wordmark), cada uma no seu uso, com fallback | JetBrains Mono; Plus Jakarta Sans fora do wordmark; Caveat ou Montserrat em interface; serifada em texto de ferramenta | |
| RB22 Ferramentas em ícone com tooltip (17:50) | Toda tabela com a coluna «Ferramentas», botões só de ícone e a função em tooltip no hover e no foco | Tabela sem ferramentas; ícone sem tooltip; ferramenta com texto no lugar do ícone | |
| RB23 Hover em todo gráfico (18:11) | Mini modal no hover e no foco com valor, unidade e data ou categoria | Gráfico sem hover; só o <title> nativo do SVG | |
| RB24 Catálogo de mini gráficos (18:11) | Linha com área, barras verticais, barras horizontais, anel ≥ 64 px, progresso grosso, pontos por dia, bullet, colunas empilhadas 100%; abaixo do número, na largura toda do box | Barra empilhada fina; anel minúsculo; gráfico encolhido no canto; pizza; 3D; mais de 5 cores | |
| RB25 Nenhum modal sem ação (18:11) | Modal só por clique ou tecla; pedido de permissão em faixa dispensável no topo ou nas configurações | Modal ou caixa flutuante que abre sozinha sobre o conteúdo (ex.: pedido de localização) | |
| RB26 Gráfico em escala, que informa, sem box órfão (18:15) | Barras proporcionais ao valor na mesma escala; estado único dito em texto; resumo em linhas completas | Barras de 4 e 119 do mesmo tamanho; barra cheia de um só estado; box sozinho numa linha; «Ver detalhe» no lugar do box-botão | |
| RB27 Toda tabela ordena (18:17) | Toda coluna ordena por clique e teclado, com seta e aria-sort, menos «Ferramentas» | Só uma coluna ordenando; data ordenada como texto | |
| RB28 Modal com cabeçalho e rodapé (18:40) | Cabeçalho fixo com título e «✕»; corpo que rola; rodapé fixo com a fonte do dado e o botão «Fechar» | Modal sem rodapé; fonte dentro do corpo; ação solta no meio do corpo |
Antes de qualquer design ser mostrado ao dono, as RB1–RB28 já têm de estar aplicadas (ordem de 17:50).
Regras do dono ainda sem número RB
| Regra | Permitido | Proibido | Ferramentas |
|---|---|---|---|
| Largura (14:36 e 15:31) | 1600 px em toda tela do Superadmin | Lacuna vazia na lateral; tela mais estreita | |
| Título (15:28) | Título à esquerda | Título centralizado | |
| Hover nos mini gráficos (15:28) | Mini modal no hover explicando o ponto | Gráfico sem leitura do valor | |
| Botões de ferramenta (13:14) | Só ícone, sem sombra e sem enfeite | Botão com sombra, gradiente ou texto decorativo | |
| Cor de estado (15:39) | Aprovado em verde, reprovado em vermelho | Estado sem cor ou com cor trocada | |
| Correção pela GPU MATH (14:38 e 15:39) | Botão «Corrigir pela GPU MATH» onde há reprovação | Reprovação sem caminho de correção | |
| URL por aba (10:25) | Cada aba com URL própria que representa o trabalho | Duas abas com URL parecida; uma tela única para todas as abas | |
| Design real (11:32) | Tela real do app, servida na AWS | Mock, imagem, Artifact ou tela dentro de outro sistema como design para aprovação |
Designs canônicos
Telas aceitas pelo dono pelo botão «Aceitar design» da máquina de designs, em 07/11/2026, com o hash exato. Implementar é reproduzir o hash aceito. Uma reprovação posterior suspende a referência até um novo aceite.
| Tela | Versão | Hash | Aceite (Brasília) | Situação | Ferramentas |
|---|---|---|---|---|---|
| /token, aba «Tokens de IA» (3 + 3) | 4 | d1405fc104fb | 15:34 | vigente; o código no ar regrediu e está sendo restaurado | |
| /sistema?tab=uso, «Uso dos módulos» | 8 | b94861d691c4 | 15:34 | entregue | |
| /deploy?tab=ensaios, «Ensaios» | 3 | 5f2785be2abb | 15:37 | entregue | |
| /deploy?tab=servidores, «Servidores» | 3 | d0e9662a8025 | 15:37 | entregue | |
| /dod?tab=tarefas, «DoD por tarefa» | 2 | 3a949f7ab899 | 15:37 | entregue | |
| Painéis de observabilidade | 1 | 8d1371a7be44 | 14:31 | entregue; a versão 2 foi reprovada | |
| Trainer dashboard, Financeiro | 8 | 9eb9b1b104da | 14:56 | aceito; CSS adaptativo ao app | |
| Trainer dashboard, X-Docctor | 8 | 83a672d320b0 | 14:56 | aceito; CSS adaptativo ao app | |
| Microphone, Disco de voz | 3 | 5d7fc95537f7 | 15:35 | aceito | |
| Rotas, Motores | 2 | d4f0ad71f186 | 14:20 | entregue | |
| Rotas, curadoria D01 | 2 | 9135ee5cd201 | 15:26 | aceito | |
| /dod, cinco abas | 3 | dc9ad831846c | 15:32 | suspenso: o dono reprovou a aba «Definition of Done» às 17:10 | |
| /deploy, «Limpeza 48 h» | 3 | 0bbef19931c0 | 15:35 | suspenso: o dono reprovou às 16:52; versões novas aguardam aceite |
Os comentários completos de cada reprovação estão em superadmin/docs/design-system/DECISOES-DE-DESIGN-DO-DONO-2026-11-07.md.