Design System e tema

Um tema não é uma cor. É um sistema de decisões encadeadas: você escolhe uma marca, e dela desce uma paleta derivada, uma semântica por modo (claro/escuro), uma tipografia, uma malha de espaçamento, uma escala de raio, uma elevação e um vocabulário de movimento. Trocar "a cor do app" é, na verdade, mexer numa ponta dessa corrente — e o valor de um Design System é justamente garantir que a corrente inteira continue coerente.

No Fayz, o bloco theme do manifesto é a expressão resumida desse sistema. Você declara pouco; o runtime da plataforma preenche o resto de forma consistente. Antes de escrever esse bloco, vale entender o sistema completo que ele resume.

As oito famílias de tokens

Um Design System maduro organiza suas decisões em famílias. Os valores abaixo vêm do Design System oficial da Fayz — servem de exemplo concreto do nível de riqueza que cada família carrega.

Há ainda uma nona peça, opcional mas característica da marca: o vidro fosco (rgba(255,255,255,0.55) + blur 24px) e a aurora — um radial-gradient verde que vaza por trás do herói. São receitas, não cores soltas: cada uma combina fundo, borda, desfoque e brilho num único token nomeado.

De uma cor para um sistema

O ponto do Design System aparece quando você segue uma decisão até o fim. Pegue a marca ignite #2FDD4B:

• Como preenchimento (um botão, um bloco), o verde vivo #2FDD4B funciona com texto quase-preto por cima — o contraste fica alto porque o verde é claro.
• Como texto de link sobre fundo branco, #2FDD4B reprova em contraste. O sistema então usa o deep #119A27 — a mesma marca, escurecida — para o link ficar legível.
• Em modo escuro, a lógica inverte: o fundo vira near-black, o texto vira branco, e o mesmo verde agora brilha mais forte (a aurora ganha opacidade de 0.55 para 0.65).
• Para halos de seleção e hover, entra o soft #DFFBE3; para acentos sutis de superfície no claro, o bg #F2FDF4.

Repare que o raciocínio de contraste e acessibilidade é parte do Design System, não um detalhe posterior. Uma decisão de marca virou quatro tokens com papéis distintos, cada um escolhido para permanecer legível no contexto certo. É por isso que declarar dezenas de cores à mão é frágil — e derivá-las de uma raiz é robusto.

O que o runtime Fayz faz com o seu tema hoje

No manifesto você escreve pouco:

{
  "theme": {
    "brand": "teal",
    "radius": "lg",
    "mode": "system"
  }
}

• brand — a cor da marca. Valores prontos: blue, violet, green, orange, red, pink, teal.
• radius — o arredondamento: none, sm, md, lg, full.
• mode — o modo de cor: light, dark ou system.

Hoje o fayz doctor valida a estrutura do manifesto (a presença e a forma do bloco theme), mas ainda não os valores desses enums — a validação de que brand/radius/mode estão dentro dessas listas está chegando (um fix de SDK está em PR).

A partir daí, o motor de tema do shell (createTheme / applyTheme, em @fayz-ai/saas) faz a derivação. Verificado no código, de uma única cor de marca ele produz:

• primary = a marca, com primaryForeground branco — texto legível sobre o preenchimento colorido.
• ring = a marca — o anel de foco herda a identidade.
• accent = a marca com o matiz girado ~50° (mesma saturação e luz), gerando um segundo tom harmônico automaticamente.
• Uma barra lateral colorida opcional: o motor tinge o fundo do rail com a marca, força texto branco, escurece a borda em ~12% e o item ativo em ~15% de luz, e apaga os ícones secundários (matiz 35% 82%) — tudo derivado da mesma raiz para o texto continuar legível sobre a barra saturada.

Todo o resto — neutros, superfícies, bordas, semânticas de success/warning/destructive, a escala de raio, as sombras e a tipografia — vem de um preset base curado (o padrão é o admin clássico) no qual a sua marca se encaixa. O applyTheme então escreve cada valor como uma variável CSS no documento (--primary, --ring, --accent, --sidebar, --button-radius, --font-family, --shadow-sm/md/lg, e os tokens de vidro como --surface-backdrop-filter). Ou seja: a sua marca é uma entrada num sistema de tokens maior e já consistente — exatamente o modelo de Design System.

Para onde isso caminha Experimental

Hoje o manifesto expõe três decisões (marca, raio, modo). A direção é trazer as famílias mais ricas do Design System oficial — escala tipográfica, elevação, vidro fosco e motion — como costuras de customização, sem inflar o manifesto. Quando você extrapola o que a config resolve, o caminho já existe: os níveis 5–7 da escada em Personalização deixam você registrar tokens e componentes próprios, referenciados como dado, sem forkar o SDK.

Fluxo recomendado: o Design System antes do manifesto

A ordem que funciona melhor é de fora para dentro:

1. Desenhe o sistema como um artefato primeiro — um tokens.css com as oito famílias, do jeito que o Design System da própria Fayz foi montado numa sessão de design com IA. Ter as cores, os tints, a tipografia e a elevação escritos num só lugar força as decisões de contraste antes de qualquer código.
2. Resuma no manifesto — o bloco theme vira a expressão condensada desse artefato: a raiz da marca, a personalidade dos cantos e a estratégia de modo. O runtime deriva o resto na direção que o seu artefato já definiu.
3. Valide com o doctor — e itere no artefato quando precisar de mais riqueza, promovendo tokens para as costuras de personalização conforme cresce.

Assim o manifesto nunca é onde você "descobre" o tema — é onde você o declara, depois de já ter pensado no sistema inteiro.

Ver também: a Referência completa de tokens — a consulta rápida das oito famílias e das variáveis CSS que o runtime escreve.

Próximo: as costuras para ir além da config em Personalização.