Visão

O modelo

Como se trabalha

A plataforma

Origem e rumo

Decisões

Este repositório
Começar
Aparência

Vale na hora e fica lembrada neste navegador.

A plataforma

16 · Design system

A interface de toda stack segue o design system da Hibex (enterprise-stack-design). Ele está acima do produto: quando algo conflita, o produto se ajusta, e o que falta vira pedido.

Como o design system chega à stack

Como o design system chega à stack: no enterprise-stack-design, na tag de uma versão, o mantenedor roda o atualizador dessa versão contra a stack, que escreve a cópia em vendor/hibex/, commitada, com VERSAO e MANIFESTO, e nunca editada à mão. Dela saem a interface de cada aplicação, cada uma com a sua família de cor, as regras para os agentes, o verificador que roda na CI e a ferramenta de pacotes de pedidos. enterprise-stack-designdesign-system-vX.Y.Zo mantenedor roda, na tag,atualizar.mjs --alvo=<stack>(o atualizador da versão)vendor/hibex/a cópia, commitadaVERSAO · MANIFESTOnunca editada à mãoapp Afamília Xapp Bfamília Ysite estáticofamília Zagentes/AGENTS.mdregras para agentesverificar.mjsna CIpedir.mjspacotes de pedidos

Regras

RegraGarantia
vendor/hibex/ é cópia, nunca editada à mãoGarantia: hook block-vendor-hibex.py + o verificador compara com o MANIFESTO.json
A cópia é feita pelo mantenedor, com o atualizador da própria versão, rodado do repositório do design system na tag; a stack não guarda script de atualizaçãoGarantia: AGENTS.md
Cada aplicação tem uma família de cor, exclusiva dentro do produto, listada em docs/design-system/aplicacoes.md; a Fase 1 a escolhe no guia de adoção do design system, antes de existir a cópia, e a change aparencia confereGarantia: ficha da stack (lacuna app.familia)
O build de cada aplicação entrega só a folha, o script, fontes, ícones, a marca-mãe e a sua famíliaGarantia: build da stack
Fontes servidas pela aplicação (sem CDN)Garantia: design system
Um mapa de estados por produto (docs/design-system/estados.md), e o código o consultaGarantia: design system §3; teste que confere o mapa contra o arquivo
O verificador roda na CI e quebra o build com erro (templates, CSS, JS próprios)Garantia: ci.yml
O que falta vira hibex-pendente: NNNN <assunto> no código + bloco em docs/design-system/pedidos.mdGarantia: verificador conta os pendentes
Aviso de ambiente (LOCAL) em toda publicação fora de produção; nunca nas capturasGarantia: ORG-0023
Antes de qualquer tela: ler vendor/hibex/agentes/AGENTS.mdGarantia: AGENTS.md da stack aponta para ele

Os três caminhos do dia a dia

Três caminhos com o design system. Tela nova ou alterada: se o design system tem a peça, copia-se a estrutura do HTML de referência; se não tem, usa-se a mais próxima, marca-se hibex-pendente e registra-se o pedido; nos dois casos, roda-se o verificador e confere-se nos dois temas, no celular e no desktop. Nova versão do design system: uma change lê o CHANGELOG entre as versões, faz o que "Para os produtos" pede e troca os pendentes atendidos. Enviar pedidos: o agente monta o lote, o pedir.mjs gera o zip, o mantenedor envia e os números voltam para o pedidos.md e para os comentários. tela nova ou alteradao design system tem apeça?sim: copia a estruturado HTML de referência(COMPONENTES.md)não: a peça mais próximahibex-pendente + bloco empedidos.mdverificar.mjsdois temas, celular edesktopnova versão do design systemuma changedesign-system-X-Y-Zler o CHANGELOGentre as versões; fazer o "Para osprodutos"trocar os pendentesque a versão atendeuenviar pedidoso agente monta o loteLEIA-ME + uma pasta por pedidopedir.mjsconfere e gera o zipo mantenedor enviaos números voltampedidos.md e hibex-pendente:NNNN

Documentos da stack

ArquivoConteúdo
docs/design-system/aplicacoes.mdConteúdo: cada aplicação, sua pasta e sua família
docs/design-system/estados.mdConteúdo: palavra de estado → papel de cor
docs/design-system/pedidos.mdConteúdo: um bloco por pedido, com estado (aberto · no pacote · registrado NNNN · atendido em X.Y.Z · recusado)
docs/design-system/aprendizados.mdConteúdo: por que algo destoou e o que levar ao design system

Atualizar é change

Atualizar a cópia nunca é manutenção livre: uma atualização começada direto no código pula a leitura do CHANGELOG.md e as trocas que ele pede. Regra:

  1. o mantenedor faz a cópia da versão nova com o atualizador dela;
  2. o agente abre /opsx:propose design-system-X-Y-Z, lendo todas as versões do CHANGELOG.md entre a antiga e a nova;
  3. a change é dividida se a atualização for grande;
  4. as telas afetadas ganham capturas novas (só elas), e a regressão E2E roda inteira.

A interface nasce no padrão

Adotar o design system depois das telas prontas custa uma change por grupo de telas. No modelo, o design system entra na Fase 2 (change aparencia), antes de qualquer tela de produto: layout, temas, menus, página de erro e aviso de ambiente já no padrão. Cada tela de produto depois disso nasce seguindo o COMPONENTES.md.