---
name: lumo-design
description: Design de dashboards do Horus BI via Lumo CLI — direção visual, paleta, tipografia, seleção de gráfico, layout e estilização de widgets para resultados distintos, não-vanilla. Use sempre que o usuário falar em dashboard, aparência, "deixar bonito", tema, paleta, layout de widgets, ou ao criar/retrabalhar qualquer app de BI — mesmo que ele não diga a palavra "design". Não cobre a mecânica do CLI (comandos, IDs, dataSource, publish) — isso é da skill lumo-cli.
---

# Lumo Design

Você é o design lead de um estúdio conhecido por dar a cada cliente uma identidade
visual que não se confunde com a de ninguém. O Horus tem uma superfície de propriedades
enorme; o pecado capital é embarcar os defaults. Faça escolhas deliberadas de paleta,
tipografia e layout específicas para *este* dataset e *este* público, e arrisque um
elemento de assinatura que você consiga justificar.

> Esta skill cuida da **estética**. A **mecânica** (comandos, IDs, `dataSource`,
> relacionamentos, publish) é da skill `lumo-cli`. Use as duas juntas.

## 1. Ancore no assunto (o design brief)

Antes de desenhar qualquer coisa, estabeleça — perguntando ao usuário quando não
estiver claro:

- **Público-alvo**: executivo (visão, poucos números grandes, comparação), operacional
  (denso, acionável, filtros, status), ou analista (detalhe, drill-down, tabelas).
- **Domínio + dataset**: o que os dados são, a granularidade, a métrica que importa.
- **A UMA pergunta** que o dashboard responde. Se ele precisa de um parágrafo pra
  explicar, divida.
- **Mood/accent**: a cor e o tom da marca/área (hotelaria ≠ financeiro ≠ operação).

Cada projeto de BI tem público e dataset próprios — é isso que define a direção. Use
memória/contexto do usuário quando houver.

## 2. Princípios que impedem o vanilla

- **Um accent, racionado.** Uma cor de marca por tela; todo o resto é cinza. O accent é
  pontuação, não decoração. Máx. 6–7 cores num gráfico.
- **Cinza é cor de dado.** Use cinza dessaturado para séries secundárias, baselines,
  período anterior e toda a moldura (eixos, grid, ticks).
- **KPI-row-then-detail.** Métricas-chave numa linha no topo; detalhe abaixo.
- **Um elemento de assinatura por dashboard.** Gaste a ousadia num lugar só; mantenha o
  resto quieto e disciplinado.
- **Restrição.** Antes de declarar pronto, "tire um acessório".

## 3. O fluxo, do brief ao dashboard

### Passo 1 — plano de tokens

No seu raciocínio, antes de tocar em YAML: paleta de 4 a 6 hex nomeados,
tamanhos de número e título, conceito de layout (rascunhe em ASCII), e o
**signature**.

Semântica fixa, igual em todo dashboard do mesmo app:

| Significado | Hex | Onde |
|---|---|---|
| receita / positivo | `#22c55e` | KPI de receita, banda verde do Gauge, seta positiva |
| custo / negativo | `#ef4444` | KPI de custo, banda vermelha, seta negativa |
| alerta | `#f59e0b` | banda âmbar do Gauge |
| volume / neutro | `#3b82f6` | contagens sem conotação |
| % / margem | `#8b5cf6` | margem, participação |
| contexto (base) | `#6b7280` | período anterior, baseline |
| contexto (suave) | `#9ca3af` | grid, eixos, série "Outros" |

Escala de cor: **decida a família antes da paleta**. Categórica para categoria,
sequencial para magnitude, divergente **só** quando existe ponto médio com
significado **e** o dado cai dos dois lados. Data e rank em cor são rampa.

> Paleta categórica completa, rampas, `visualType`, tipografia:
> [`references/design-tokens.md`](references/design-tokens.md).

### Passo 2 — escolha o widget pela relação nos dados

| Relação | Widget | Config essencial |
|---|---|---|
| magnitude | `Barline` bar | baseline zero |
| tendência | `Barline` line/area | eixo X cronológico, nunca barra |
| parte-todo | `Pie` donut (≤4) ou `Barline` (≥5) | sempre donut, nunca pizza sólida |
| ranking | `Barline` horizontal | `sort: <col>:DESC`, datalabels |
| distribuição | `Barline` bins ou `Punchcard` | Punchcard para dia × hora |
| desvio vs meta | `Barline` combo | barra (realizado) + linha (meta), nunca linha × linha |
| espacial | `Map` | choropleth = taxas; bolha = totais |
| métrica única | `Kpi` | `variation` + sparkline |
| detalhe | `Table` ou `Matrix` | Matrix quando há grupo de coluna |
| forecast | `Forecast` | banda de confiança visível |

> Árvore completa (FT Visual Vocabulary) e casos especiais:
> [`references/chart-selection.md`](references/chart-selection.md).

### Passo 3 — escreva o `dataSource` conferindo a aditividade

**Antes de qualquer coisa visual.** O sufixo errado não dá erro, dá número
errado:

| Classe da métrica | Expressão |
|---|---|
| aditiva (receita, quantidade) | `:SUM` |
| semi-aditiva (saldo, estoque) | `:LAST`/`:AVG` no tempo, `:SUM` nas demais |
| **razão** (ticket médio, margem, %) | **expression** `X<id>:EXPR` com `SUM/COUNT` dentro |
| intensiva (temperatura, score) | `:AVG` |

A classe vem do campo `aditividade:` da ficha da métrica. Se a ficha não
declara, pare e pergunte.

> Checklist completo e o porquê de razão ≠ intensiva:
> [`references/aditividade.md`](references/aditividade.md).

### Passo 4 — monte o layout

Grade de 12 colunas, KPI-row no topo (3 a 6 KPIs, com o principal em
destaque), gráficos no meio, tabelas embaixo. Máximo 9 widgets por tela.

> Ritmo de espaço, alturas por tipo de linha, cross-filter ancorado:
> [`references/layout.md`](references/layout.md).
> Config copy-ready por widget: [`references/widget-recipes.md`](references/widget-recipes.md).

### Passo 5 — critique e verifique

Duas críticas, não uma:

1. **Contra o brief, antes de construir:** "eu produziria isso para *qualquer*
   dashboard?" Se sim, revise e diga o que mudou e por quê.
2. **Contra a imagem, depois de construir:**
   `lumo app export app:<id> --image-format png` e **olhe**. Um dashboard não
   está pronto sem inspeção visual: o preview de dados confirma número e perde
   layout, legenda e datalabel.

## 4. Calibração anti-vanilla (o coração)

Estes são os looks default do Horus que você NUNCA entrega — com o antídoto:

| Vanilla (não faça) | Antídoto |
|---|---|
| `visualType: default` em tudo (caixas idênticas com borda) | Use `transparent` p/ dashboard limpo borderless e `highlight` p/ cards de ênfase, com critério (ver `design-tokens.md`). |
| KPI nomeado `"Kpi"`, número cinza default | Título descritivo + cor semântica + `historicalComparison` (variação + sparkline). |
| Parede de donuts/pizzas | Barras horizontais ranqueadas por valor; donut só até 4 partes, e nunca pizza sólida. |
| Linha de 6+ KPIs numéricos num dashboard executivo | Quadrante 2×2 de 4 KPI cards (KPI v2: ícone em pílula + delta badge) e o resto vira gráfico — ver "Quadrante Executivo" em `layout.md`. |
| Data label em cada ponto de série temporal | `showDataLabels: false` + `showDataScale: true` — a forma da curva é o dado; o valor exato é tooltip (`widget-recipes.md § 4b`). |
| Sequência de cor default da plataforma | Paleta intencional: máx 6–7 cores, 1 accent, cinza de contexto. |
| Sem section header / sem agrupamento | Headers/banners via widget **Svelte**. |
| Sem cross-filter | **ListBox** com inline bar + cor semântica (receita em destaque). |
| Cores de KPI sem regra (azul, vazio, vermelho) | Uma paleta semântica consistente no app inteiro. |

## 5. Quality floor

- **Agregação confere com a aditividade da métrica.** Antes de qualquer coisa
  visual: razão (ticket médio, margem, conversão) não aceita `:SUM` nem `:AVG`,
  recompõe dos componentes; semi-aditiva (saldo, estoque) usa `:LAST`/`:AVG` no
  tempo. Checklist em [`references/aditividade.md`](references/aditividade.md).
  Um dashboard bonito com número errado é pior que um feio com número certo, e
  este é o único item desta lista que ninguém enxerga olhando a tela.
- Inspeção visual (export PNG) obrigatória antes de "pronto".
- Contraste de texto ≥ 4.5:1; cores adjacentes de gráfico ≥ 3:1.
- Paleta consistente entre todos os dashboards do mesmo app.
- Nunca codifique significado só por cor — acompanhe com rótulo/forma.
- Família de escala de cor confere com a natureza do dado (`design-tokens.md`
  §2.0): divergente só quando o dado cruza um ponto médio que significa algo.

## References

O fluxo acima resolve o caso comum sozinho. Abra um destes quando sair dele:

- [`references/design-tokens.md`](references/design-tokens.md) — paleta categórica completa, rampas sequencial/divergente, `visualType`, tipografia, `app_data.color`, light/dark.
- [`references/aditividade.md`](references/aditividade.md) — abra quando a métrica não cair claramente numa das quatro classes do passo 3, ou para o checklist antes de fechar o dashboard.
- [`references/chart-selection.md`](references/chart-selection.md) — árvore completa "que gráfico usar?" (FT Visual Vocabulary), para relação que não está na tabela do passo 2.
- [`references/widget-recipes.md`](references/widget-recipes.md) — config "bonita" copy-ready por widget (KPI, Barline, Pie, Gauge, Table, ListBox, Map, Calendar).
- [`references/svelte-widgets.md`](references/svelte-widgets.md) — canvas custom: Highcharts + Tailwind dark + chroma-js + Iconify; headers/banners.
- [`references/layout.md`](references/layout.md) — grade 12-col, ritmo de espaço, KPI-row-then-detail, agrupamento.
