diff --git a/docs/plans/graficos-dados-instagram-ui-design.html b/docs/plans/graficos-dados-instagram-ui-design.html new file mode 100644 index 00000000..b00e1f2b --- /dev/null +++ b/docs/plans/graficos-dados-instagram-ui-design.html @@ -0,0 +1,631 @@ + + + + + + + Design — Gráficos de dados para Instagram + + + +
+
+
+ Gate visual · template v1 + Instagram feed + Stories +
+

Gráficos claros, sóbrios e prontos para a comunicação

+

A superfície desenhada é a imagem exportada — não uma tela de app. Os dados abaixo são deliberadamente genéricos; as peças fixam hierarquia, grid, tratamento de marca e limites do gerador.

+
+ +
+
+
+

CENA 01 · PADRÃO

+

Feed 4:5 · ranking em barras horizontais

+
+
+ 1080 × 1350 + Escala de visualização: 55% +
+
+ +
+
+
+
+
+
+

Exemplo de comparação

+

Um território concentra o maior resultado do período

+

Valores ilustrativos para demonstrar ordem, proporção e destaque.

+ + + +
+

Fonte: fonte informada pela pessoa · período de exemplo
Nota: valores ilustrativos, sem unidade real.

+
+ +
JORGE SOLLA
MANDATO DEPUTADO FEDERAL
+
+
+
+ NEEDS ASSET · LOGO OFICIAL +
+
+
+ + +
+
+ +
+
+
+

CENA 02 · SISTEMA

+

Quatro relações, um mesmo template

+
+

Grid, tipografia, rodapé e uso de cor permanecem. Só o corpo do gráfico muda conforme a relação entre os dados.

+
+ +
+
+
+
Comparação

Um grupo aparece à frente

Ranking com valores ilustrativos.

+
+
Grupo A
+
Grupo B
+
Grupo C
+
Grupo D
+
+
Fonte: exemploJORGE SOLLA
+
+

Barra · ranking

Categorias longas, leitura direta.

+
+ +
+
+
Poucos períodos

O resultado cresce no período

Quatro momentos ilustrativos.

+
+
P1
P2
P3
P4
+
+
Fonte: exemploJORGE SOLLA
+
+

Coluna · tempo curto

Poucos períodos, base comum em zero.

+
+ +
+
+
Série de tempo

A tendência se mantém ao longo do tempo

Até sete pontos, com rótulo no fim.

+
+ + + + + 72 + +
+
Fonte: exemploJORGE SOLLA
+
+

Linha · série temporal

Tendência contínua, ponto final destacado.

+
+ +
+
+
Número-âncora

Um número sustenta a mensagem

Sem gráfico quando há uma única medida.

+
72

unidades no período de exemplo

+
Fonte: exemploJORGE SOLLA
+
+

Número-âncora

Um valor grande + frase que explica.

+
+
+
+ +
+
+
+

CENA 03 · ADAPTAÇÃO

+

Stories 9:16 · conteúdo dentro da área segura

+
+ 1080 × 1920 · escala 32,5% +
+ +
+
+
+ 250 px · evitar conteúdo essencial + 250 px · evitar conteúdo essencial +
+
+

Exemplo de comparação

+

Um território concentra o maior resultado

+

Valores ilustrativos para demonstrar hierarquia e proporção.

+
+
Território A
84
+
Território B
68
+
Território C
53
+
Território D
41
+
Território E
29
+
+
+
Fonte: fonte informada · valores ilustrativos.
+
JORGE SOLLA
+
+
+ NEEDS ASSET · LOGO OFICIAL +
+
+ +
+
+

TOPO · 250 PX

+

Faixa reservada para chrome do Instagram, avatar e contexto. Nenhuma manchete, valor ou fonte entra aqui.

+
+
+

BASE · 250 PX

+

Faixa reservada para resposta, CTA e controles. O rodapé da peça termina acima dela.

+
+
+

MESMO SISTEMA, MAIS RESPIRO

+

A adaptação não estica o feed. Ela recompõe a hierarquia vertical, reduz um ponto do ranking e mantém título, rótulos, fonte e marca integralmente legíveis na zona central.

+
+
+
+
+ +
+
+

CENAS 04–05 · FAIL-CLOSED

+

Quando o dado não permite uma peça correta

+

Estados visíveis de recusa: o template não preenche lacunas nem força um tipo de gráfico inadequado.

+
+
+
+
+
?
+

Preciso confirmar os dados antes de gerar

+

A tabela recebida não deixa claro o período nem o que o valor representa. Nenhum número será completado por suposição.

+
    +
  1. 1.Qual é o período de referência?
    2. +
  2. 2.Os valores são quantidade, percentual ou outra unidade?
    3. +
  3. 3.Qual fonte deve aparecer no rodapé?
    4. +
+
Geração pausada · aguardando esclarecimentoJORGE SOLLA
+
+

Dado faltando ou ambíguo

+
+ +
+
+ +

Pizza com muitas fatias dificulta a comparação

+

Este conjunto tem mais de cinco categorias. O formato solicitado é recusado para não esconder diferenças pequenas.

+
+ Sugestão: usar barras horizontais +

As categorias ficam ordenadas, com rótulo direto e uma única ênfase. Se “parte de um todo” for essencial, reduza para até cinco grupos verificáveis.

+
+
+
+
+
Formato não gerado · alternativa indicadaJORGE SOLLA
+
+

Pizza com mais de 5 fatias

+
+
+
+ +
+
+
+

ANOTAÇÃO DE DESIGN · NÃO EXPORTAR

+

Guia de medidas e integridade

+
+
+ 34área segura do grid do perfil · ~1012 px34 +
+
+
+
+
1012 × 1350

Título, plot, fonte e marca dentro desta largura segura.

+
+
+
+
+ +
+

Canvas

1080 px de largura. Feed 1080×1350; Stories 1080×1920.

+

Tipografia mínima

Headline ≥48 px; rótulos e valores ≥30 px no arquivo final.

+

Contraste

Texto ≥4.5:1; marcas de dado ≥3:1. Cor nunca é a única pista.

+

Escala honesta

Barras e colunas começam em zero. Sem 3D, perspectiva ou eixo truncado.

+

Densidade

Até 7 pontos por gráfico. Acima disso: resumir com orientação explícita.

+

Fundo e sinal

Off-white #faf9f7. Vermelho #c51414 ocupa no máximo ~10% da peça.

+
+
+
+ + +
+ + diff --git a/docs/plans/graficos-dados-instagram.md b/docs/plans/graficos-dados-instagram.md new file mode 100644 index 00000000..c74ef201 --- /dev/null +++ b/docs/plans/graficos-dados-instagram.md @@ -0,0 +1,107 @@ +# Gráficos de dados para Instagram (skill de comunicação) + +Status: rascunho +Atualizado em: 2026-09-18 +Issue: #1145 (após `pnpm agent:register`) +Priority: P2 +Impeccable: C — fluxo novo (skill/command + template visual do gráfico); não é UI de app, mas a superfície gráfica é o produto +Design UI: `docs/plans/graficos-dados-instagram-ui-design.html` (a produzir pelo `designer`) + assets em `docs/plans/graficos-dados-instagram-ui-design-assets/` +Appetite: ~2–3 dias eng; um outcome verificável — rodar a skill com uma planilha/texto e obter um gráfico PNG 1080×1350 com a paleta Solla +Responsável: — + +## Intenção + +A equipe de comunicação do mandato recebe números em planilha, CSV, doc, markdown ou texto solto e hoje transforma isso à mão em peça de rede — lento, e muitas vezes com gráfico feio ou enganoso. Este item dá a essa equipe uma skill que aceita o dado como ele veio e devolve um **gráfico pronto para compartilhar**, já no formato de Instagram e na paleta de Jorge Solla. A skill entrega o **gráfico**; a comunicação transforma o gráfico no material final (legenda, carrossel, contexto). É a base visual confiável, não a peça acabada. + +## Persona e fluxo + +- **Persona / contexto:** equipe de comunicação/mandato (social media, assessoria), na mesa ou no celular, sem tempo e sem formação em data viz; sabe o que quer comunicar, mas não deve ter que escolher tipo de gráfico, escala ou eixo. +- **Job principal:** numa invocação, transformar um punhado de números num gráfico claro, correto e "com a cara do mandato", no tamanho do Instagram. +- **Fluxo desejado:** cola os dados no comando ou aponta o arquivo → a skill lê, entende a relação dos dados (comparação, tempo, parte-de-um-todo, ranking) e propõe o gráfico adequado → gera o PNG com título-manchete, um destaque de cor e a paleta Solla → a pessoa confere, pede ajuste (tipo/rótulo/tamanho) e leva para a produção da peça. +- **Anti-goals de produto:** virar editor gráfico/dashboard; publicar direto nas redes ou agendar; limpar/interpretar estatisticamente os dados; inventar ou inferir dado/categoria sem fonte; persistir o dado; substituir os dossiês/relatórios em PDF; segundo pipeline irmão do renderer do dossiê. + +### Esboço de fluxo (C) + +```text +[cola dados no comando | aponta xlsx/csv/md/txt] → [skill lê e classifica a relação dos dados] +→ relação ambígua ou dado faltando → pergunta (nunca inventa) +→ [propõe tipo + gera HTML/SVG com paleta Solla] → [screenshot PNG 1080×1350] → [pessoa confere/ajusta] +→ [entrega o gráfico; comunicação finaliza a peça] +``` + +### Design UI (C) + +- Design UI (gate): `docs/plans/graficos-dados-instagram-ui-design.html` — template do gráfico Instagram: capa, título-manchete, área de plot, rodapé de marca, área segura do grid (conteúdo crítico dentro de ~`1012×1350`) e variações por tipo essencial (barra, coluna, linha, número-âncora). +- A superfície é o **gráfico**, não tela de app; o artefato hi-fi é a fonte de verdade do port do template. + +## Objetivo e aceite + +- Rodar a skill com um arquivo/texto e obter **um gráfico PNG** (default `1080×1350`) legível, com a paleta Solla e a marca do mandato. +- O gráfico tem **título-manchete** (takeaway, não "Gráfico de X"), rótulos diretos, ordenação por valor e **um destaque de cor** sobre o resto neutro. +- O tipo é coerente com a relação dos dados; os tipos essenciais do v1 são barra, coluna, linha e número-âncora. +- Saída nos três tamanhos sob demanda: `1080×1350` (feed 4:5, default), `1080×1080` (quadrado) e `1080×1920` (stories/reels). +- Legibilidade no celular: rótulos ≥30px e headline ≥48px no canvas 1080; contraste ≥4.5:1 no texto e ≥3:1 nas marcas de dado; não codificar informação só por cor. +- Guardrails de correção do gráfico: barras começam no zero; nunca pizza com >5 fatias; nunca 3D/perspectiva; no máximo ~7 pontos de dado por gráfico; dado faltando/ambíguo → pergunta, nunca completa. +- Nenhum dado de campanha sai da máquina — render local. +- Todo artefato gerado permanece **gitignored** (repo público): sem dado bruto nem PNG commitado. + +## Dados (intenção) + +- **Vou apresentar dados?** Sim, superfície neste item — a própria entrega é um gráfico de dados fornecidos pela pessoa. +- **Decisões desbloqueadas:** a comunicação escolhe **qual número/ângulo** vira peça e **para qual canal** (feed × stories); a coordenação/mandato escolhe **o que destacar** no material do período. +- **Forma:** _adiada ao plano de implementação_ — aqui só restrições de produto: o tipo segue a relação dos dados; barras no zero; um destaque de cor; ≤~7 pontos; rótulo direto; sem pizza grande, sem 3D; dado sem fonte não entra. + +## Dados da decisão (literais) + +- **Nome e artefatos (verbatim):** skill `.agents/skills/graficos-dados/SKILL.md`; command `.opencode/commands/graficos-dados.md`; subagente opcional `.opencode/agent/graficos-dados.md`. Invocação: `/graficos-dados ` (texto colado ou caminho de arquivo). +- **Formatos de entrada v1 (verbatim):** `xlsx`, `csv`, `md`, `txt`, texto no comando; `doc/docx` fica fora do v1 (sem dependência) — decisão na questão em aberto. +- **Tamanhos de saída (verbatim):** `1080×1350` (feed 4:5, default), `1080×1080` (quadrado), `1080×1920` (stories/reels); sRGB, PNG <8MB. +- **Paleta Solla (hex, verbatim):** destaque `#c51414`; escuro de marca `#ae1603`; vermelho PT `#a21c1c`; amarelo PT `#ffe607`; tinta `#1c1917`; muted `#6b7280`; borda `#e7e5e4`; fundo off-white não-branco (ex.: `#faf9f7`) para aguentar dark mode. +- **Tipografia mínima (verbatim):** rótulos ≥30px; headline ≥48px; janela segura do grid do perfil ~`1012×1350`; safe zone de stories ~250px topo + ~250px base. +- **Limites (verbatim):** ≤~7 pontos de dado por gráfico; barras começam no zero. +- **Artefatos gitignored (verbatim):** `data/graficos-instagram/` (intermediários) + `docs/research/graficos-instagram/` (PNG/SVG finais) — nunca commitados. + +## Direção no codebase (hipótese) + +- **Áreas prováveis:** `.agents/skills/graficos-dados/SKILL.md`, `.opencode/commands/graficos-dados.md`, `.opencode/agent/graficos-dados.md`; primitivos de gráfico hoje em `scripts/lib/dossieRender.mjs` (`barChart` L914, `valueList` L932, `columnChart` L948, `stackedColumnChart` L969, `CHART_COLORS` L898-912) e pipeline Chromium em `scripts/lib/buildPdf.mjs`; novo entry `scripts/build-chart-from-data.mjs`. +- **Precedente a olhar:** família de skills C186/C187/C190 (skill + command + subagente + builder local, artefato gitignored), `tests/unit/opencodeCommands.unit.spec.ts:13-48` (array de commands), `tests/unit/opencodeAgents.unit.spec.ts`. +- **Risco de acoplamento:** **"edite o dono, não gema um irmão"** — extrair/parametrizar os primitivos SVG existentes em vez de um segundo renderer; não tocar no layout dos dossiês; sem schema/migration; dados nunca saem da máquina (sem MCP remoto por default). + +## Dependências + +- **Hard:** design hi-fi do template (`docs/plans/graficos-dados-instagram-ui-design.html`) produzido pelo `designer` antes do port. +- **Soft:** primitivos SVG e pipeline Chromium existentes (dossiê/PDF) disponíveis para reuso. +- **Soft:** decisões das questões em aberto (nome/ID, `doc/docx`, MCP, formato default, catálogo de tipos). + +## Fora de escopo + +- Limpeza/interpretação estatística dos dados, análise, priorização territorial — a skill representa o dado, não o interpreta. +- Legenda, carrossel final, copy e publicação — ficam com a comunicação. +- Publicar/agendar direto nas redes. +- Dossiês/relatórios completos em PDF — domínio dos irmãos C186/C187/C190. +- Persistir dados, schema ou migration; segundo cadastro/catálogo de dados. + +## Rabbit holes de produto + +- **"Editor gráfico completo."** Se alguém "só completar": cores/fontes/eixos/legenda configuráveis, drag de rótulo. **Corte neste item:** tipos essenciais + paleta fixa Solla + ajuste de tipo/rótulo/tamanho. +- **"Dashboard interativo."** **Corte neste item:** uma imagem estática por invocação. +- **"Pizza para tudo."** Dataset pede comparação e vira pizza de 9 fatias. **Corte neste item:** a relação dos dados manda no tipo; pizza só com ≤5 fatias (ou nem entra no v1). +- **"MCP remoto de gráfico."** AntV/QuickChart mandam o dado para serviço de terceiro. **Corte neste item:** render local; MCP fica com gatilho futuro (self-hosted, em subagente). +- **"Segundo renderer irmão."** **Corte neste item:** estender/extrair o dono existente. + +## Questões em aberto (produto) + +- **Nome/ID da skill e comando?** **Opções:** A) `graficos-dados` | B) `grafico-instagram` | C) `gerador-graficos`. **Recomendação:** A — descreve o insumo (dados), não amarra ao canal. _(assumido — validar)_ +- **`doc/docx` no v1?** **Opções:** A) fora — só `xlsx/csv/md/txt/texto` | B) adicionar dependência `mammoth`. **Recomendação:** A — evita dep nova; reavaliar com demanda real. _(assumido)_ +- **MCP de gráficos/planilha?** **Opções:** A) nenhum no v1, render local | B) AntV `mcp-server-chart` self-hosted em subagente | C) MCP de planilha só leitura. **Recomendação:** A — privacidade do dado de campanha e a marca/anotação finas vencem; MCP com gatilho futuro. _(assumido)_ +- **Formato default de saída?** **Opções:** A) `1080×1350` feed 4:5 | B) `1080×1080` quadrado. **Recomendação:** A — retrato é o padrão de feed em 2026 e ocupa mais tela. _(assumido)_ +- **Quantos tipos no v1?** **Opções:** A) essenciais — barra, coluna, linha, número-âncora | B) catálogo amplo tipo FT Visual Vocabulary. **Recomendação:** A — cobre a maioria dos pedidos com menos chance de escolha errada. _(assumido)_ + +## Referências + +- GitHub Issue #1145. +- Design UI (gate): `docs/plans/graficos-dados-instagram-ui-design.html` + assets em `docs/plans/graficos-dados-instagram-ui-design-assets/`. +- Irmãos: `.agents/skills/relatorio-cidade/SKILL.md`, `dossie-solla-cidade/SKILL.md`, `dossie-solla-instituicao/SKILL.md`, `docs/plans/dossie-solla-tema.md` (C190). +- Renderer/pipeline: `scripts/lib/dossieRender.mjs`, `scripts/lib/buildPdf.mjs`, `tests/unit/opencodeCommands.unit.spec.ts`. +- `DESIGN.md` §2 (paleta/regras), `AGENTS.md` (artefato gitignored, "edite o dono"). +- FT Visual Vocabulary, Datawrapper (chart types, accessible colors, size), WCAG 2.2 (contrast/use of color) — pesquisa 2026-09-18.