Migração · convergência governada

Adoção consciente

Um percurso para substituir desvios legados sem perder função, conteúdo ou regras de negócio.

Family Core → perfil de adoção → produto

contrato

As três camadas protegem a unidade do portfólio sem confundir identidade visual com contexto de negócio.

01

Baluarte Family Core

Foundations, componentes, padrões, shell, acessibilidade e comportamento compartilhados.

balu.css · components.css · patterns.css
02

Perfil de adoção

Inventário, mapa de legado, piloto, métricas e exceções temporárias. Não contém tema visual.

products/<produto>/
03

Produto

Conteúdo, dados e fluxos do domínio construídos com a mesma linguagem da família.

sem overrides de identidade
Regra de fronteira: preservar função e contexto de negócio não significa preservar aparência legada. O destino visual é o Baluarte.

Processo seguro em sete passos

rollout
  1. Inventariar. Registrar foundations, shell, componentes, padrões, qualidade, dívidas e dependências.
  2. Definir a baseline. Capturar o estado atual e os critérios do contrato de família que serão medidos.
  3. Decidir. Classificar cada item como adotar, refinar, promover extensão ou rejeitar.
  4. Atualizar o core. Traduzir a decisão para tokens, APIs e governança do Baluarte antes de qualquer override local.
  5. Pilotar. Consumir o core em uma fatia vertical representativa, pequena, frequente e mensurável.
  6. Validar. Revisar reconhecimento de família, acessibilidade, responsividade, performance e regressão funcional.
  7. Escalar e retirar legado. Expandir por ondas, validar em outro domínio, remover duplicações e registrar exceções restantes.

Trilhas e ondas de adoção

portfólio

A convergência não termina na troca de tema. Cada produto mantém um ledger único para cinco trilhas e avança por evidência. ClickAgents pode iniciar o piloto, mas os demais produtos consomem o Baluarte — nunca uma cópia do CSS do ClickAgents.

TrilhaIncluiProva de conclusão
FoundationsCor, tipo, spacing, shape, elevação, motion e íconesDisplays 28–64/500, títulos 18–24/550, fonte/fallback e zero override
Shell e navegaçãoHeader, sidebar/drawer, spacing, scroll, breakpoints, foco e motionTítulo–item 10px, ícones persistentes no rail, preferências restauradas e reversões aprovadas
Componentes e estadosAnatomia, densidade, hover, foco, loading, empty e errorAPI pública sem dependência do portal
Padrões e domínioComposição, conteúdo, permissões, dados e extensõesVariação de domínio sem identidade paralela
Qualidade e retiradaRegressão, performance, métricas, legado e exceçõesLegado removido ou exceção com prazo
Sequência recomendada: contrato central → piloto ClickAgents → segundo produto de domínio diferente → expansão do portfólio. A segunda adoção prova que a regra pertence à família.

Assinatura obrigatória da família

não negociável
Visual

Mesmas foundations

Tipografia, papéis de cor, forma, elevação, densidade e motion vêm do mesmo núcleo.

Componentes

Mesma anatomia

Estados, espaçamento, foco, acessibilidade e API pertencem ao catálogo compartilhado.

Estrutura

Mesmas receitas

Shell, navegação, painéis e hierarquia escolhem padrões governados, não composições privadas.

Conteúdo

Mesma voz

Rótulos, feedback, erros e orientação seguem princípios editoriais comuns.

Teste de reconhecimento: oculte nome e logo. Uma pessoa que conhece outro produto da família ainda deve reconhecer a mesma origem pela interface.

Matriz de liberdade

fronteiras
Obrigatório em todosPode variar por domínioNão pode variar
Tokens semânticos, tipografia, shape, motion e iconografiaDados, conteúdo, permissões, vocabulário especializadoPaleta principal, foco, status e hierarquia tipográfica
Componentes e estados do catálogoComposição entre padrões aprovadosAnatomia privada do mesmo componente
Shell e receitas responsivas governadasPresença de módulos conforme a tarefaUm shell visual paralelo por produto
Regras de conteúdo e acessibilidadeSequência de fluxo e regras de negócioTom contraditório, atalhos inacessíveis ou feedback inconsistente

Contrato do perfil de adoção

template

O perfil descreve como um produto converge. Ele não funciona como tema, pacote visual ou permissão para redefinir o core.

products/
└── <produto>/
    ├── README.md
    ├── adoption-checklist.md
    ├── legacy-map.md
    └── exceptions.md

/* Produto consome a identidade comum. */
@import "balu.css";
@import "components.css";
@import "patterns.css";

/* Proibido: criar tema visual por produto. */
[data-product="..."] {
  --action: ...;
  --accent: ...;
}
FaçaDocumente inventário, mapeamento, piloto, métricas, dependências e exceções temporárias.
Não façaNão mantenha cores, componentes ou shells locais somente porque já existem.

Checklist de rollout

aceite

Antes

  • Escopo e dono definidos
  • Baseline visual capturada
  • Mapa para o core revisado
  • Fluxo piloto e métricas registrados

Durante

  • Ledger e cinco trilhas atualizados
  • Foundations e componentes compartilhados
  • Temas claro, sistema e escuro
  • Teclado, touch, zoom 400% e mobile
  • Noto local, fallback e scripts suportados
  • Nenhuma identidade visual paralela

Depois

  • Teste de reconhecimento aprovado
  • Auditoria automática aprovada
  • Diff visual e regressão funcional revisados
  • Legado removido ou exceção com prazo