Sistema de Design

O que Sistema de Design faz?

A mesma expertise em três estágios. O orquestrador passa o modo explicitamente.

Modo	Quando	Pergunta
PLAN	fase 2 do desenvolvimento de funcionalidades	Quais padrões/abstrações esta funcionalidade deve usar?
BUILD	fase 4 do desenvolvimento de funcionalidades	Aplicar as decisões do PLAN durante a implementação.
REVIEW	fase 5 do desenvolvimento de funcionalidades	A implementação realmente os segue?

Padrão para REVIEW quando o modo não for especificado e existir um diff de branch. Padrão para PLAN quando o modo não for especificado e ainda não houver diff.

Modo PLAN

Antes do código existir. Entradas: brief de refinamento, nó Figma ou screenshot, rotas no escopo.

1. Pesquise na biblioteca de padrões (src/index.ts, src/theme.ts, src/core/) e app-pro-ui por funcionalidades similares.
2. Execute o teste de abstração (abaixo) em cada elemento importante da interface do design.
3. Para cada elemento: deixe local | API PL existente | token/variante | PR PL necessário — com caminhos citados.
4. Sinalize sequenciamento da PL (PR PL antes/paralelo com app-pro-ui) e cópia/assets faltantes.

Se não houver superfície de UI: retorne Não aplicável (sem UI) em uma linha.

Saída: # Sistema de design (PLAN): [funcionalidade] — lista de reuso, alterações prospectivas, sequenciamento. Nenhum diff de branch necessário.

Modo BUILD

Durante a implementação. Entradas: saída do PLAN do sistema de design, arquivos sendo editados.

1. Aplique as decisões do PLAN: use componentes/tokens nomeados da PL; respeite as chamadas "deixar local".
2. Siga a camada de raciocínio abaixo — não recrie looks reutilizáveis no código da funcionalidade.
3. Se o PLAN estiver errado dado o que você aprende enquanto codifica, documente o desvio no resumo da build; não desvie silenciosamente.

Saída: nenhuma, a menos que haja desvio — então anote no resumo da build.

Modo REVIEW

Após a implementação. Escaneie este branch (app-pro-ui ou biblioteca de padrões) em busca de decisões de UI que deveriam estar no sistema de design. Não diga apenas "delete o estilo" ou "use um componente compartilhado". Prefira a menor alteração global na biblioteca de padrões que permita que qualquer funcionalidade faça o mesmo — ou recomende manter a implementação local quando a abstração não for justificada.

Isso não significa que "todos os estilos pertencem à biblioteca de padrões". Decisões repetidas de produto/UX devem ser cada vez mais codificadas no sistema para que construtores individuais não as reinventem. O código da funcionalidade ainda pode compor localmente.

Regra de arquitetura: Decisões visuais reutilizáveis pertencem à biblioteca de padrões. O código da funcionalidade pode usar sx para layout/composição genuinamente local, mas não deve recriar estilos reutilizáveis de componentes, tokens, estados ou padrões de interação. Evite style, CSS customizado e props legadas do sistema MUI quando uma API estabelecida da PL/MUI existir.

Este skill é a camada do DS. Para estrutura de hook/util/grid do app-pro-ui e higiene de código genérica, use o skill refactoring.

Camada de raciocínio

Julgue cada descoberta com estas regras. Elas vêm de anos de comentários de revisão da biblioteca de padrões e app-pro-ui. Prefira uma API existente a uma nova. Mover código para a biblioteca de padrões não é automaticamente uma melhoria.

Teste de abstração

Execute este teste em cada candidato a receita, token ou nova API. Ele é o julgamento principal — a detecção só produz candidatos.

1. Isso é composição local?
2. A mesma receita aparece em outro lugar?
3. O componente já deveria ser dono disso?
4. Mover para a biblioteca de padrões reduziria decisões futuras significativas?
5. Adicionar uma API tornaria a biblioteca de padrões pior?

Similaridade sozinha não justifica abstração. Dois trechos que parecem iguais podem representar conceitos de produto diferentes. Prefira abstrações compartilhadas quando a mesma decisão de produto/UX deve evoluir junta.

sx não é o problema. A questão é onde a decisão de design mora. sx com token do tema é melhor que hex. Uma receita repetida pode pertencer à biblioteca de padrões. Um <Stack sx={{ mt: 2 }}> avulso geralmente não. Se o teste disser que a solução local está correta, omita-a das descobertas — não a liste como Baixa.

1. Use o sistema de design — não reestilize decisões reutilizáveis na funcionalidade

• Prefira componentes estabelecidos da biblioteca de padrões para padrões reutilizáveis de produto (CardWithAction mesmo sem ação, CardCTAFeatured como um card composto, DetailPanelToggle). Não reconstrua esses a partir de Card puro.
• Prefira primitivas de composição do MUI como Stack/Grid em vez de CSS de layout customizado quando o layout for local.
• Use primitivas de layout e padrões estabelecidos antes de inventar geometria local.
• Coloque cores reutilizáveis, sombras e tratamentos de marketing/AI em pattern-library/src/theme.ts como tokens modelados pelo palette (primary.main, ai.gradient.start). Prefira um token ou theme.shadows em vez de hex, fills ou sombras hardcoded quando o valor for uma decisão de produto.
• Use sx, não as props de estilo legadas do MUI. Não adicione props nomeadas de estilo em componentes compartilhados para contornar isso. sx local é aceitável quando é composição, não um look reutilizável.
• Se uma funcionalidade precisar de um novo look que outras superfícies compartilharão (mídia em destaque, sobreposição expansível, superfícies invertidas/de marketing), adicione um padrão ou prop na biblioteca de padrões.

2. Mantenha os componentes compartilhados genéricos

• Não introduza padding, sidenav ou alterações de gráfico específicos de funcionalidade em componentes compartilhados como Card, PageSection ou exports públicos de index.ts. Escope protótipos; reverta arquivos não relacionados. Altere o item, não a estrutura, quando apenas o item estiver errado.
• Nomeie props para reuso (footerDescription, não um rótulo de uma funcionalidade). Comportamento extra é opcional (números de linha, vírgulas em um textarea).
• Prefira variantes de tema e args do Storybook em vez de JSX bifurcado (verificações variant === "marketing").
• Não exporte gráficos ou outros internos da biblioteca de padrões se os apps não os consumirem.
• A longo prazo, envolva uma superfície em um tema (por exemplo, marketing) em vez de passar props visuais avulsas por cada página.

3. QA visual nas bordas

• Verifique cantos arredondados, cards de altura igual, texto quebrado órfão, colapso do FAB móvel, z-index vs. drawers/modais e se um controle ainda funciona em fundo branco.
• Pergunte se um espaçamento especial é necessário ou se os estilos padrão já correspondem a outros modais/páginas. Não adicione padding a um cabeçalho compartilhado para alinhar com um vizinho desalinhado — corrija o vizinho.

4. Questione o requisito de design

Antes de adicionar uma capacidade ao DS para suportar um design incomum, determine se o próprio design deveria se conformar a um comportamento de sistema estabelecido. Não expanda o sistema de design meramente para codificar um requisito avulso questionável.

5. Resista à superfície de API desnecessária

Toda abstração proposta do DS deve justificar a superfície de API que adiciona. Mover código para a biblioteca de padrões não é automaticamente uma melhoria. Configuração que não melhora a experiência é custo de manutenção.

Mantenha apenas a higiene da arquitetura do DS: wrappers desnecessários que interferem na composição, estilização duplicada, complexidade de API de componente e lógica específica de funcionalidade em primitivas compartilhadas. Achate Boxes aninhados quando eles atrapalharem a composição com Stack/sx. Use shorthand do tema (background.main) em vez de useTheme para tokens simples.

6. Envie com a superfície relacionada

• Uma alteração na biblioteca de padrões que os apps devem consumir precisa de um PR correspondente em app-pro-ui ou moz-ui e uma maneira de verificá-lo (amplify/domain ou equivalente).
• Confirme a versão/convenção de pacote atual do repositório consumidor (package.json, lockfile ou docs de instalação) antes de recomendar como fazer o bump. Não assuma um estilo de pin.
• Não mescle uma primitiva compartilhada até que o PR do app consumidor esteja pronto.

Quando invocado (modo REVIEW)

Copie e acompanhe:

Progresso da Revisão:
- [ ] Diff deste branch contra a base de merge
- [ ] Coletar candidatos (não conclusões)
- [ ] Agrupar por intenção (mesma decisão, não mesmo código)
- [ ] Executar o teste de abstração
- [ ] Pesquisar na biblioteca de padrões por um lar existente
- [ ] Recomendar a menor alteração — incluindo manter local / nenhuma alteração do DS
- [ ] Relatar descobertas; não implemente a menos que solicitado

Encontrar trabalho não é obrigatório. Se o diff for apropriadamente local, diga isso e pare.

Passo 1: Escaneie o branch

Inspecione este branch vs sua base de merge. Detecte o branch padrão (git symbolic-ref refs/remotes/origin/HEAD ou origin/main, depois main). Execute a partir do repositório que tem as alterações (app-pro-ui ou biblioteca de padrões).

DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/@@')
DEFAULT=${DEFAULT:-origin/main}
git merge-base "$DEFAULT" HEAD
git diff $(git merge-base "$DEFAULT" HEAD)...HEAD -- '*.tsx' '*.ts' '*.jsx' '*.js' '*.css' '*.scss'
git diff --name-only $(git merge-base "$DEFAULT" HEAD)...HEAD

Pesquise linhas adicionadas em busca de candidatos:

Estilização

• style=
• sx=
• styled(
• css\`` /css(`
• makeStyles / createStyles / withStyles
• #hex, rgb(, rgba(, px hardcoded (investigue; não classifique automaticamente)
• Props Box legadas: display=, alignItems=, justifyContent=, flexDirection=

UI reinventada ou desviada

• Card puro onde um padrão de card estabelecido (CardWithAction, CardCTAFeatured) se encaixa
• Controles de expansão customizados em vez de DetailPanelToggle
• CSS de layout customizado onde Stack/Grid comporia localmente
• Geometria de página inventada onde primitivas de layout ou padrões já definem largura
• Sombras hardcoded em vez de theme.shadows quando a sombra for um look compartilhado
• Novos exports públicos ou edições de tema que só servem uma funcionalidade

Em seguida, abra cada hit e leia o JSX ao redor para entender a intenção. Também capture objetos sx atribuídos antes do JSX, tags <style> e folhas de estilo importadas.

Ignore .cursor/, node_modules/, .next/. Inclua código de funcionalidade, components/ compartilhados, Storybook e src/theme.ts.

Passo 2: Detecte, depois julgue

A detecção é uma heurística. A classificação acontece após o teste de abstração.

Detector	Tratar como	Exemplos
style= / styled( / css / novo .css	Vazamento candidato	<Card style={{ flexBasis: "50%" }}>
Valores visuais hardcoded que parecem codificar decisões do sistema de design, especialmente cor, espaçamento, tipografia, raio, sombra e dimensões repetidas	Token candidato	color: "#002F50"; investigue px antes de tratar como vazamento
sx={{ ... }} usando chaves do tema	Receita candidata	sx={{ mt: 3, width: "100%" }}
Props legadas do sistema Box	Legado candidato	<Box display="flex" alignItems="center">
Componente PL existente não usado	Solução de sistema existente candidata	tabela não envolvida em CardWithAction
Edição específica de funcionalidade em um componente compartilhado	Vazamento de escopo candidato	padding em CardHeader para corresponder a uma história
Prop ou export de uma funcionalidade	API não genérica candidata	prop de footer nomeada para funcionalidade; exportando gráficos não usados

Investigue antes de classificar valores hardcoded. Casos locais legítimos incluem dimensões calculadas, geometria de gráficos, internos de ícone/canvas, bordas, layouts virtualizados e restrições intrínsecas de componentes.

Exceções de último recurso (documente o porquê; não invente uma primitiva):

• Internos de terceiros / canvas / gráficos que não podem usar props da biblioteca de padrões
• Layout de impressão/PDF sem primitiva de relatório existente e verdadeiramente avulso
• Arquivos apenas de protótipo que não são exportados da biblioteca de padrões

Candidatos que passam no teste de abstração como composição local não são descobertas. Coloque-os sob Não promover apenas se eles pudessem ser confundidos com lacunas. Caso contrário, omita-os.

Passo 3: Agrupe por intenção

Agrupe hits que expressam a mesma decisão, não o mesmo CSS ou marcação de aparência similar.

Intenções típicas: cor/ênfase, receita de espaçamento/alinhamento, tipografia, estrutura de componente, estado de interação, padrão de funcionalidade (banner, cabeçalho de página, CTA de card, status), API genérica vs. de uma funcionalidade, escopo de protótipo, requisito de design questionável.

Um agrupamento → uma recomendação. Prefira uma recomendação forte a várias variantes menores da mesma descoberta.

Passo 4: Pesquise primeiro na biblioteca de padrões

Pesquise o repositório irmão biblioteca de padrões antes de propor algo novo. Cite caminhos.

1. Exports públicos — pattern-library/src/index.ts
2. Tokens e padrões globais — pattern-library/src/theme.ts
3. Props/variantes de componentes em pattern-library/src/core/
4. Usos existentes do mesmo componente no app-pro-ui que já evitam o vazamento

Precedente para absorver UI no DS (cite estes; não copie internos para app-pro-ui):

• Prop semântica: Typography lineClamp — pattern-library/src/core/Typography/Typography.tsx
• Prop semântica: Button aiGlow — `pattern-library/src/core/Button/Button.t

…

[truncado para tradução]