# 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ília | O que decide | Exemplo (Design System da Fayz) |
| --- | --- | --- |
| **Marca + tints** | a cor-assinatura e suas variações derivadas | `ignite #2FDD4B` → `deep #119A27`, `soft #DFFBE3`, `bg #F2FDF4` |
| **Neutros** | a escala de cinza que carrega texto e superfícies | `paper #FAFAF8` → `near-black #0B0F0E` (12 degraus) |
| **Secundárias** | acentos pontuais, usados com parcimônia | `yellow #F2DB0F`, `cyan #17C1EA`, `coral #FF6B5C` |
| **Semântica por modo** | o mapeamento bg / surface / border / text por tema | claro usa `paper` + texto escuro; escuro inverte para `near-black` + texto branco |
| **Tipografia** | famílias e hierarquia por peso | `Outfit` (display), `DM Sans` (corpo), `JetBrains Mono` (código) |
| **Espaçamento** | a malha que alinha tudo | grade de **4px** (4, 8, 12, 16, 24, 32…) |
| **Radius** | a personalidade dos cantos | `xs 4px` → `sm 8px` → `md 14px` → `lg 22px` → `pill 9999px` |
| **Elevação + motion** | sombras, o glow-assinatura e o timing | `shadow-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.

{% callout type="tip" %}
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.
{% /callout %}

## 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:

```json
{
  "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.

{% callout type="info" %}
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.
{% /callout %}

## Para onde isso caminha {% badge status="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](/pt-BR/docs/apps/personalizacao) 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](/pt-BR/docs/referencia/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](/pt-BR/docs/apps/personalizacao).