fayzfayz sdk
PTEN

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.

FamíliaO que decideExemplo (Design System da Fayz)
Marca + tintsa cor-assinatura e suas variações derivadasignite #2FDD4B → deep #119A27, soft #DFFBE3, bg #F2FDF4
Neutrosa escala de cinza que carrega texto e superfíciespaper #FAFAF8 → near-black #0B0F0E (12 degraus)
Secundáriasacentos pontuais, usados com parcimôniayellow #F2DB0F, cyan #17C1EA, coral #FF6B5C
Semântica por modoo mapeamento bg / surface / border / text por temaclaro usa paper + texto escuro; escuro inverte para near-black + texto branco
Tipografiafamílias e hierarquia por pesoOutfit (display), DM Sans (corpo), JetBrains Mono (código)
Espaçamentoa malha que alinha tudograde de 4px (4, 8, 12, 16, 24, 32…)
Radiusa personalidade dos cantosxs 4px → sm 8px → md 14px → lg 22px → pill 9999px
Elevação + motionsombras, o glow-assinatura e o timingshadow-sm → shadow-glow (halo verde); ease-out cubic-bezier(0.22,1,0.36,1), 240ms

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.

Esta própria documentação usa esse sistema: o corpo é Inter, o código é JetBrains Mono, o botão primário tem o glow verde-ignite e o herói carrega a aurora. Um Design System bem feito se aplica igual num painel administrativo e numa página de docs.

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.

A derivação acontece no runtime da plataforma Fayz, que consome o bloco theme para pintar o shell inteiro. Na pré-visualização local do scaffold — hoje uma tela-âncora — a paleta ainda não é aplicada. Por isso este passo se valida pelo doctor (config válida) e o resultado visual completo aparece no runtime. Nunca conte com a marca renderizada no preview local isolado.

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.