🎨 Identidade Visual — Livro de Estilo (UX)

A membrana estética do PAEBIRU: o conjunto de regras que garante que toda superfície — CLI, TUI, dashboards, site de documentação, identidade impressa, arte em mídias sociais — fale a mesma língua biológica, fractal e antropofágica do projeto.

Este documento é vinculante para qualquer artefato visual ou textual produzido em nome do PAEBIRU (documentação, screenshots, slides, posts, capas, ícones, mensagens de UI). Em caso de conflito com preferências pessoais, o livro de estilo vence. Em caso de conflito com outro documento, vence a hierarquia canônica do AGENTS.md: dictionary.md > este livro de estilo

RFCs Standards Track.

1. Filosofia & Princípios

1.1 Os três eixos estéticos

Toda decisão de UX no PAEBIRU é atravessada por três eixos co-derivados da Realidade fractal:

1.2 Conexão com os 4 Dogmas

Os dogmas da RFC 050 têm tradução direta em UX. Tratar como restrição arquitetural (recusa automática em revisão):

1. Isolamento Absoluto (Hexagonal) → Cada Bounded Context tem sua própria área visual (TUI tem painéis próprios; dashboard separa Kernel, Biologia, Economia, C.A.P.I.B.A.). Nada cruza a membrana sem um receipt visível (timestamp + assinatura).
2. GALS & Actor-like State → Toda tela tem estado local observável (loading, idle, error) e nunca compartilha estado mutável com outra tela via canal implícito. Use eventos assíncronos, publique-os.
3. Pragmatismo de Hardware (no_std First) → A CLI deve rodar em terminais de 80×24 (TTY legado, terminais seriais de MuleNode). Tabelas, cores e layouts que não cabem em 80×24 são rejeição automática. Prompts devem ser ASCII-puro quando possível (sem glifos Unicode exóticos em entradas de comando).
4. Interoperabilidade Blindada → Logs binários opacos (CBOR) e saída humana (texto) e TUI rica são tratados como três vistas do mesmo receipt. Nada de “modo debug” escondido — é cidadão de primeira classe.

1.3 Soberania visual

• Zero-Trust também é visual: nenhuma fonte externa (CDN de fontes, Google Analytics, tracker de marketing) deve vazar dados do operador. O site paebiru.org é self-hosted, sem CDN de telemetria.
• A textura de fundo da documentação (papiro antropofágico) é asset versionado, não CDN externa.
• Fontes canônicas (Iosevka Nerd Font) carregam via jsDelivr com fallback local documentado em docs/theme/paebiru.css.

2. Identidade Visual

2.1 Paleta de cores (Papiro Antropofágico)

A paleta é biológica-semântica: cada cor carrega um significado operacional, não é decorativa. Reutilize-a em CLI (256-color / 24-bit truecolor), TUI (ratatui), dashboards (Grafana) e site (CSS).

Convenção de uso: use uma cor algedônica por tela. Misturar --algedonia-dor e --algedonia-prazer no mesmo componente é sintoma de falsa dicotomia — o operador precisa saber se está saudável ou não, não ambos ao mesmo tempo.

2.2 Tipografia

Regras:

• Tamanho base: 16 px no site (font-size: 1rem), 14 px no CLI (-C document.body.font_size=14 no helix ou similar).
• Peso: use Regular (400) para corpo; Medium (500) para destaques; Light (300) para citações longas. Bold (700+) é proibido em texto corrido — reserve para cabeçalhos de tabela e labels de campo.
• Glifos Nerd Font ( , , , ) só aparecem em TUI e em logs estruturados, nunca em mensagens de erro humanizadas (onde podem quebrar em terminais sem a fonte).
• Sem itálico decorativo: itálico é reservado para termos em inglês, citations e nomes científicos (ex: Maturidade Causal).

2.3 Iconografia

Os ícones do PAEBIRU seguem três famílias com papéis fixos — não misture:

1. Membrana (Bounded Contexts) — ícone quadrado com borda dupla representando permeabilidade seletiva. Cor base: --membrana.
2. Fluxo (CausalBlock, plasmídeo) — seta orgânica com curvatura fractal. Cor base: --correnteza.
3. Algedonia (sensor) — bulbo cromático com saturação variável (verde → âmbar → vermelho). Animação: pulsa 1 Hz em --correnteza, 4 Hz em --algedonia-dor.

Em ambientes onde ícones não são possíveis (TTY 80×24, terminais seriais LoRa), use glifos Unicode 24-BIT bem definidos como fallback: ● (membrana), ▶ (fluxo), ▲ (algedonia-dor), ▼ (algedonia-prazer), ◆ (manguezal), ■ (oceano), ○ (nascente). Veja tabela em §4.

2.4 Logomarca

A logomarca canônica é paebiru-logo-1024.png. Respeite a zona de respiro mínima de 1× a altura do glifo “p” ao redor. Não distorça proporções, não troque cores, não sobreponha fundos de baixo contraste. Para variantes em theme-color HTML (<meta name="theme-color">), use #ffffff no modo claro e #1a1c22 no modo escuro (já configurado em docs/theme/index.hbs).

3. Tom de Voz & Linguagem

3.1 Princípios editoriais

A voz do PAEBIRU é técnica, calorosa e direta. Cada palavra deve servir a um dos três objetivos:

1. Orientar o operador na próxima ação concreta.
2. Contextualizar a mensagem dentro da metáfora biológica.
3. Honrar o vocabulário do Dicionário.

3.2 Vocabulário canônico (pt-BR)

Use sempre a forma canônica do Dicionário. Em caso de dúvida, a forma errada vira anti-padrão:

3.3 Estrutura de mensagens de erro

Toda mensagem de erro em qualquer superfície (CLI, TUI, API, log) deve seguir a tríade Causa → Consequência → Caminho:

[COMPONENTE] <causa observável em uma linha>.
↳ Consequência: <o que o sistema fez em resposta>.
↳ Caminho:      <próxima ação ou link ao runbook>.

Exemplo bom (TUI do paebiru-node):

[KERNEL]  Backpressure no GossipSub fanout (fila: 9 124 / 8 192).
↳ Consequência: Publicação de plasmídeo enfileirada; receipt atrasado ~3 s.
↳ Caminho:      R007 · Saturação XDP — `paebiru peer prune --stale 30m`.

Exemplo ruim:

Erro: algo deu errado. Tente novamente.

3.4 Mensagens de sucesso

Sucesso também comunica. Use a forma <verbo no particípio> + receipt>:

[CAPIBA]  CausalBlock `b3:9f…2a` indexado no Manguezal.
           Receipt: dr://2026-06-07T11:42Z#7c1f   maturidade=4   µJ=12.4

O receipt sempre carrega: URI do DRE, maturidade causal (numérica inteira ≥ 0), e custo no LandauerLedger (µJ).

4. CLI & TUI

4.1 Estrutura de comando

A paebiru-cli (Forge CLI, em apps/cli) usa clap e segue a convenção <verbo> <substantivo> [--flags].

Regras:

• Verbos canônicos (use exatamente estes): init, start, stop, status, list, show, add, remove, prune, rotate, quench (Veto Algedônico explícito), migrate (Oceano), flash (HAL).
• Substantivos canônicos: node, peer, plasmid, receipt, ledger, block, key, attestation, quarantine, mesh.
• Sub-comandos aninhados apenas quando o substantivo tem ciclo de vida próprio: paebiru plasmid build, paebiru plasmid test, paebiru plasmid publish.

4.2 Saída padrão (stdout)

• Modo --human (default em TTY, off em pipe): cores, tabelas ASCII, spinner durante ingestão.
• Modo --json (default em pipe/CI): uma linha JSON por evento, esquema em crates/api/....
• Modo --cbor (interop binária): receptor de stream opaco para outros nós. Veja WASI-PAEBIRU ABI.
• Sem --quiet/--verbose binários: use --log-level trace|debug|info|warn|error alinhado com RUST_LOG.

4.3 Códigos de saída

Convenção: códigos 1-6 são reservados a causas semanticamente distintas (se uma operação pode falhar por mais de uma razão, o operador precisa de qual é qual). Códigos 64+ seguem o padrão <sysexits.h>.

4.4 TUI (ratatui)

A TUI do paebiru dashboard (apps/cli) ocupa o terminal inteiro em modo claro/escuro. Princípios:

• 3 painéis fixos + 1 barra de status algedônica:
  • Esquerda: topologia de malha (nós + arestas, cores por saúde).
  • Centro: fila de plasmídeos + receipts em trânsito.
  • Direita: telemetria do nó local (CPU, memória, termostato, XDP).
  • Rodapé: barra algedônica global (verde → âmbar → vermelho).
• Navegação: tab/shift+tab cicla painéis; q quita; ? mostra ajuda; r força refresh; j/k rolam listas.
• Frescor mínimo: 1 Hz (modo fino) ou 0.1 Hz (modo grosso), controlado por PAEBIRU_LAYER9_FINE_RESOLUTION_MS / PAEBIRU_LAYER9_COARSE_RESOLUTION_MS.
• TTY 80×24 é o piso absoluto: degrade para paebiru status --human se a TUI não couber.

4.5 Fallback de glifos

Quando a fonte Nerd Font não está disponível, sempre degrade para glifos Unicode 24-BIT imprimíveis em qualquer encoding moderno:

A ordem das colunas é vinculante: documento e CLI usam o mesmo glifo para o mesmo conceito.

5. Observabilidade & Dashboards

5.1 Métricas Prometheus (canônicas)

Regras:

• Unidades SI em minúsculas (seconds, bytes, joules).
• Sem prefixos decimais ambíguos: use micro_joules, não microjoules nem uJ (reservado a humanos).
• Labels de baixa cardinalidade apenas. PeerID vai em log, não em label (cardinality explosion).
• Nomes com pontos são proibidos — paebiru.* em vez de paebiru...

5.2 Painéis Grafana (canônicos)

A coleção paebiru-dashboards (versionada em observability/grafana/) tem sete dashboards canônicos, um por escala fractal:

1. Bit Físico — XDP, NIC, IRQ, jitter de relógio.
2. Neurônio LIF — spikes/segundo por camada SNN, energy budget.
3. Função WASM — throughput de plasmídeo, falhas de MacrophageVM.
4. Plasmídeo — fila, latência de receipt, custo em µJ por gate.
5. Nó ABAPORU — BDI, intenções, crenças, desejo, termostato.
6. LocalSyncDomain — DVV, Maturidade Causal, Pororoca Causal.
7. Malha Global — topologia, peer count, island mode, fork risk.

Cada dashboard tem uma cor de cabeçalho mapeada ao token da paleta (§2.1): Malha Global = --membrana, Plasmídeo = --correnteza, etc.

5.3 Logs estruturados

• Formato: JSON canônico com tracing-subscriber (campos fixos abaixo).
• Campos obrigatórios:
  • ts (ISO-8601 com Z),
  • level (trace|debug|info|warn|error),
  • target (caminho do módulo Rust),
  • node_id (BLAKE3 curto, 16 chars),
  • peer_id (opcional, mesmo formato),
  • scale (1-7, escala fractal),
  • receipt_uri (opcional, dr://…).
• Mensagem humanizada (campo msg) deve respeitar §3.3 (tríade Causa → Consequência → Caminho).

6. Documentação

A documentação segue convenções vinculantes em contributors/writing-docs.md. Resumo das regras de UX documental:

• Caminhos relativos sempre (./../architecture/kernel.md, nunca https://…).
• Metadados em comentários HTML (<!-- title: ... -->), nunca YAML frontmatter (mdBook renderiza YAML como texto visível).
• kebab-case em nomes de arquivo (exceção: rfcNNN_*.md).
• Emoji no início do capítulo funciona como ícone de seção (🌱 chegando, 🔧 operar, 🛠️ contribuir, 📚 referência, 📜 RFCs, 🎨 visuais). Não introduza emojis novos sem atualizar o SUMMARY.md pai.
• Tabelas têm cabeçalho repetido em thead para que o leitor de tela anuncie o contexto.
• Imagens têm alt text descritivo; imagens puramente decorativas usam alt="".
• Mermaid é a fonte canônica de diagramas (vide §4 de writing-docs.md).

7. Acessibilidade & i18n

7.1 Acessibilidade

• Contraste mínimo WCAG AA (4.5:1 para corpo, 3:1 para display) para qualquer par cor-texto da paleta. A combinação --algedonia-prazer sobre --ceu é a única abaixo de AA — use-a apenas em destaques de uma palavra sobre fundo branco, nunca em corpo.
• Modo escuro respeita prefers-color-scheme (já configurado em docs/theme/index.hbs — default_theme = "rust").
• Sem informação veiculada apenas por cor: a barra algedônica da TUI tem padrão textual (OK, STRESS, VETO) além da cor. Ícones algedônicos têm glifo distinto (▼ vs. ▲).
• CLI --human aceita --no-color/NO_COLOR=1 para terminais monocromáticos (MuleNode sobre UART).

7.2 Internacionalização

A hierarquia canônica está em contributors/i18n.md. Em adição:

• Mensagens de UI são extraídas via tr!()/format_message! no crate; chaves em inglês neutro, valores em pt-BR/en-US/es-ES.
• Termos canônicos do Dicionário NUNCA são traduzidos literalmente — preserva-se a forma de origem (ex: “Plasmídeo” em espanhol segue sendo “Plásmido”, nunca “vector de contrato”).
• Glifos algedônicos são universais (cores têm mapeamento documentado em cada idioma).

8. Anti-padrões de UX

Sintomas de fronteira mal colocada, análogos ao anti-padrão “Costura” do Dicionário:

9. Processo de contribuição

9.1 Checklist antes de abrir PR de UI

• A nova cor está na paleta (§2.1)? Se não, abra uma issue em paebiru/paebiru com tag design/colors antes de mergir.
• A nova fonte está em docs/theme/paebiru.css com fallback local?
• O novo verbo CLI está em §4.1? Caso contrário, proponha adendo ao livro de estilo junto com o PR de código.
• As mensagens de erro seguem a tríade Causa → Consequência → Caminho ( §3.3)?
• O glifo algedônico (se aplicável) tem fallback Unicode (§4.5)?
• Métricas Prometheus seguem a convenção de nomenclatura (§5.1)?
• O componente TUI degrada em 80×24 (§4.4)?
• O texto passa em make i18n-check e respeita o Dicionário?

9.2 Versionamento

• Mudanças neste livro de estilo são versionadas em docs/src/brand/style-guide.md e propagadas ao AGENTS.md §1.4 quando alteram um dogma.
• Mudanças vinculantes (paleta, glifos, códigos de saída) exigem uma RFC Standards Track nova, com referência cruzada a este documento. Mudanças editoriais (texto, exemplos) entram direto via PR com label design/editorial.

10. Veja também

• Iconografia — detalhamento das famílias de ícones e glifos.
• Wallpapers — os ativos visuais versionados.
• Dicionário canônico — terminologia usada neste livro de estilo.
• Glossário de UX (internacional) — referência WCAG 2.2 para acessibilidade.
• docs/theme/paebiru.css — a implementação CSS canônica da tipografia e da textura de fundo.
• docs/theme/index.hbs — o template do mdBook com theme-color e prefers-color-scheme.
• Manifesto — a base filosófica (7 teses) que inspira os três eixos estéticos.
• Realidade fractal — as 7 escalas que organizam dashboards e TUI.
• i18n — hierarquia de idiomas e glossário.
• Escrevendo documentação — convenções vinculantes para a documentação transversal.