# 03 · Tema e marca

Um tema não é uma cor — é um **sistema de decisões encadeadas**. No Fayz você declara três decisões no `app.manifest.json` e o motor de tema do shell deriva a paleta inteira a partir delas. O shell continua o mesmo; só a aparência muda, de forma coerente.

## Passo 1 · Pense no sistema

Antes de editar, escolha três coisas — cada uma cascateia por dezenas de tokens:

- **Cor da marca** → vira `primary`, o anel de foco, um `accent` derivado e (opcionalmente) a barra lateral colorida.
- **Personalidade dos cantos** (o raio) → define botões, cards, inputs e modais de uma vez.
- **Estratégia de modo** → claro, escuro ou seguir o sistema operacional.

Três decisões, não trinta cores. Esse é o ponto de um Design System.

## Passo 2 · Aplique no manifesto

Recém-criado, o app traz `"theme": { "brand": "violet" }`. O bloco aceita três chaves:

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

Parece pouco — e é de propósito. Cada chave é a raiz de uma cadeia. Veja o que ela desdobra.

### Galeria das 7 marcas

Escolher `brand` é escolher uma família inteira. O motor pega o matiz da marca, o aplica em `primary`/`ring` e gira o matiz **−50°** para gerar um `accent` harmônico automaticamente. A tabela abaixo mostra, por marca, o matiz base, o `accent` derivado e onde cada uma brilha:

| Marca | Matiz base (HSL) | Vira `primary`/`ring` | `accent` derivado (matiz −50°) | Personalidade · quando usar |
| --- | --- | --- | --- | --- |
| `blue` | `221 83% 53%` | azul institucional | `171` → ciano-esverdeado | Confiança, corporativo. SaaS B2B, fintech, jurídico. |
| `violet` | `262 83% 58%` | violeta premium | `212` → azul | Neutro-premium, criativo, tech. O padrão do scaffold. |
| `green` | `142 71% 45%` | verde vivo | `92` → verde-limão | Cuidado e crescimento. Saúde, finanças, sustentabilidade. |
| `orange` | `25 95% 53%` | laranja quente | `335` → rosa | Apetite e energia. Food, hospitalidade, varejo. |
| `red` | `0 84% 60%` | vermelho forte | `310` → magenta | Urgência e paixão. Esporte, delivery, promoções (cuidado: convive com o `destructive`). |
| `pink` | `330 81% 60%` | rosa vibrante | `280` → violeta | Lifestyle e expressão. Beleza, moda, D2C jovem. |
| `teal` | `172 66% 50%` | verde-água | `122` → verde | Calma e clareza. Clínicas, wellness, apps de produtividade. |

{% callout type="info" %}
Os HSL acima são **valores representativos** para você raciocinar sobre a família e o `accent` que sai de cada uma — o runtime da plataforma aplica a variante calibrada de cada nome. A regra de derivação (matiz −50°, mesma saturação e luz) é a mesma; o que muda é o ponto exato de partida.
{% /callout %}

### O que cada chave cascateia

| Chave | Valor | O que muda de uma vez |
| --- | --- | --- |
| `brand` | um dos 7 nomes | `primary`, `ring`, `accent` (matiz −50°) e, se você optar, a barra lateral colorida — todos da mesma raiz. |
| `radius` | `none` | Cantos retos — leitura **técnica e densa** (tabelas, back-office). |
| | `sm` | Arredondamento discreto — **sóbrio**, corporativo. |
| | `md` | O meio-termo **equilibrado** — a escolha segura. |
| | `lg` | Cantos generosos — **amigável**, tátil no toque. |
| | `full` | Pílulas e círculos — **lúdico**, consumer. |
| `mode` | `system` | Respeita o SO do usuário — o padrão sensato. |
| | `dark` | Sempre escuro — apps noturnos, backstage, salão à noite. |
| | `light` | Sempre claro — operação diurna, recepção, balcão. |

Repare que `radius` não muda "o botão": muda **botões, cards, inputs e modais** juntos, na mesma proporção. É isso que mantém o app coerente quando você troca uma ponta.

### 3 receitas prontas

Copie, cole no `app.manifest.json` e ajuste o `name`. Cada uma é uma combinação testada de marca + raio + modo para um tipo de negócio:

**Clínica / saúde**

```json
{
  "theme": { "brand": "green", "radius": "md", "mode": "light" }
}
```

Verde comunica cuidado e confiança; `md` equilibra o formal e o acessível; `light` combina com recepção e atendimento diurno.

**Food / comanda noturna**

```json
{
  "theme": { "brand": "orange", "radius": "lg", "mode": "dark" }
}
```

Laranja é apetite e hospitalidade; `lg` deixa os alvos táteis para o toque rápido; `dark` descansa a vista do salão à noite.

**SaaS B2B sóbrio**

```json
{
  "theme": { "brand": "blue", "radius": "sm", "mode": "system" }
}
```

Azul institucional passa segurança; `sm` mantém a densidade profissional; `system` respeita o SO do operador ao longo do dia.

O `name` no topo do manifesto é o nome exibido — troque-o junto com a cor para a mudança de marca ficar completa:

```json
{
  "name": "Minha Clínica",
  "theme": { "brand": "green", "radius": "md", "mode": "light" }
}
```

## Passo 3 · Valide

Edite o bloco, salve e rode o doctor:

```bash
npx @fayz-ai/cli doctor
```

```
⚠ plugins referenced by manifest are resolved by the platform bundle, not public npm packages: dashboard

0 error(s), 1 warning(s)
```

{% callout type="tip" %}
✓ Você deve ver: `0 error(s)` no doctor. O aviso sobre plugins resolvidos pelo bundle da plataforma é esperado em modo mock — não é um erro. O doctor confirma que o manifesto está bem-formado e íntegro antes de a plataforma consumi-lo.
{% /callout %}

## Por baixo do capô

Essas três chaves são a **expressão resumida** de um sistema maior. A partir da sua cor de marca, o motor de tema (`createTheme` / `applyTheme`, em `@fayz-ai/saas`) deriva a cadeia — verificado no código:

| Token derivado | De onde sai |
| --- | --- |
| `primary` | a marca, com `primaryForeground` branco para o contraste sobre o preenchimento. |
| `ring` (foco) | a mesma marca — o anel herda a identidade. |
| `accent` | o matiz da marca girado **−50°** (mesma saturação e luz), um segundo tom harmônico. |
| barra lateral (opcional) | o fundo do rail recebe a marca, texto branco, borda **−12%** de luz, item ativo **−15%**, ícones secundários em `matiz 35% 82%`. |
| neutros, superfícies, semânticas, raio, sombras, tipografia | de um **preset base curado** (o admin clássico), no qual a sua marca se encaixa. |

O `applyTheme` então escreve cada valor como **variável CSS** no documento (`--primary`, `--ring`, `--accent`, `--sidebar`, `--button-radius`, `--font-family`, `--shadow-sm/md/lg`). Sua marca é **uma entrada** num sistema de tokens já consistente.

{% 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 da plataforma.
{% /callout %}

Quer a cadeia inteira — as oito famílias de tokens, o raciocínio de contraste e o fluxo de desenhar o sistema antes de configurar? Está no capítulo [Design System e tema](/pt-BR/docs/apps/temas).

Ver também: a [Referência completa de tokens](/pt-BR/docs/referencia/tokens) — a consulta rápida das famílias e das variáveis CSS que o motor escreve.

## Além das 3 chaves {% badge status="experimental" /%}

O manifesto expõe três decisões hoje, mas o motor por baixo é bem mais rico. Já existem, atrás do runtime da plataforma: **cor livre em HSL** (não só os 7 nomes), **11 famílias de fonte** (de `inter` e `geist` a `outfit` e `manrope`), **níveis de sombra** (`none` → `subtle` → `medium` → `bold`), a barra lateral em modo `brand` ou `neutral`, e **presets** base inteiros. Expor essas famílias no manifesto — sem inflá-lo — é o próximo passo do contrato de tema; o sentido é evolutivo, não pronto.

{% callout type="tip" %}
Dica de fluxo: desenhe o sistema como um **artefato** primeiro. Uma sessão de design com IA gera um `tokens.css` com as famílias completas (marca, tints, tipografia, elevação); o bloco `theme` do manifesto vira a **expressão condensada** desse artefato, e você promove tokens para as costuras de [Personalização](/pt-BR/docs/apps/personalizacao) conforme cresce. O manifesto declara o tema — não é onde você o descobre.
{% /callout %}

---

[← Anterior: 02 · Explorar a anatomia](/pt-BR/docs/tutorial/02-explorar-a-anatomia) · [Próximo: 04 · Adicionar um plugin →](/pt-BR/docs/tutorial/04-adicionar-um-plugin)