# GIRO — Design system v1.0

16/09/2026 · Base de produto para validação. Derivada da identidade v1 com apenas o I em laranja.

## Escopo e entrega

Abra `index.html` no navegador. Tudo funciona localmente, sem instalação ou acesso à rede. A biblioteca inclui tokens CSS/JSON, CSS de componentes, marca e fonte locais, exemplos interativos e regras de uso. Os exemplos são fictícios; não há backend nem persistência. O software existente não foi alterado. React aparece apenas como exemplo de consumo dos mesmos estilos, não como pacote publicado ou testado.

## Princípios

- A próxima ação tem hierarquia clara; usar uma ação primária por grupo.
- Mostrar fonte, período, cobertura e atualização dos indicadores.
- Dado ausente é `null`, mostrado como “—” com motivo. Zero só quando efetivamente registrado.
- Automação não sobrescreve confirmação humana. Divergências exigem revisão com valor anterior e proposta lado a lado.
- Conclusão exige critério de pronto e evidência, verificados também no servidor.
- Parecer de IA é identificado como rascunho, com fontes consultáveis e confirmação humana separada.

## Tokens

`tokens.css` é a fonte de verdade desta versão. `tokens.json` é uma exportação com nome, tipo e valor; não pressupõe plugin de Figma ou conformidade com um formato de importação específico. Atualizar ambos em uma nova versão.

Primitivos de marca: verde #173E35, laranja #D8663A, marfim #F5F3EB. Semânticos: ação, texto, superfície, borda, sucesso, atenção, erro e informação. Não reutilizar a cor de marca como código de estado.

### Regra do acento laranja

O laranja marca movimento ou foco atual. Pode aparecer no marcador vertical de títulos, no número da navegação ativa, na linha da etapa atual, em uma decisão prioritária e em pequenos marcadores de seleção ou gráfico. Como referência visual, ocupar aproximadamente 5% da composição. Verde continua conduzindo ações. Laranja não significa erro, alerta, sucesso ou aprovação; esses estados usam os tokens semânticos. Não preencher grandes superfícies nem transformar todo botão primário em laranja.

Manrope 400–500 no corpo, 600 em labels, 700 em títulos. Base 16/24 px; tabelas e ajuda 14/21 px; metadados 12/18 px. Escala: 12, 14, 16, 20, 24, 32 e 44 px. Texto nunca embutido em imagens para dados e controles. Os caminhos do logo não dependem da fonte.

Espaçamento: 4, 8, 12, 16, 24, 32, 48 e 64 px. Raio: 4 em etiquetas, 8 em controles, 12 em superfícies, sem arredondamento excessivo. Sombra reservada ao diálogo. Movimento de 140 ms; respeitar `prefers-reduced-motion`.

## Layout responsivo

- Acima de 1100 px: navegação lateral 238 px e margens de conteúdo 48 px.
- 761–1100 px: navegação de 205 px e margens de 28 px.
- Até 760 px: navegação em faixa rolável, margens de 20 px, coluna única e ações quebrando linha.
- Referência de grid: 12 colunas no desktop, 4 no celular; os exemplos usam grids fluidos por conteúdo.
- Tabelas largas rolam dentro da região nomeada e focável, nunca ampliam o viewport. Priorizar os campos essenciais para a tarefa mobile.
- Alvos principais de 44 × 44 px. Não reduzir tipografia para resolver excesso de conteúdo.

## Contrato dos componentes

| Componente | Variantes / estados | Regras |
| --- | --- | --- |
| Botão | Primário, secundário, discreto, destrutivo; hover, active, foco, desabilitado, carregando | Rótulo verbo + objeto; `disabled` real; motivo visível; carregamento com `aria-busy` |
| Campo | Texto, seleção, área de texto, checkbox; normal, foco, inválido, somente leitura, desabilitado | `label` vinculado; erro via `aria-describedby` e `aria-invalid`; erro não apaga entrada |
| Etiqueta | Neutro, sucesso, atenção, perigo, informação | Texto de estado obrigatório; não simular botão |
| Alerta | Informação, atenção, erro, sucesso | Mensagem + ação de recuperação; anúncios dinâmicos em região viva apropriada |
| Tabela | Cabeçalhos, legenda, dados, região rolável | Números tabulares; unidade e período; “—” para falta; sem ordenação fictícia |
| Indicador | Valor confirmado, ausente, desatualizado | Fonte, período e condição visíveis; sem delta quando falta base |
| Diálogo | Evidência, confirmação destrutiva | `dialog.showModal()`, título acessível, Escape, foco interno, retorno de foco |
| Toast | Confirmação não crítica | `role=status`; nunca única localização de uma falha ou decisão; resultado relevante permanece na tela |
| Vazio | Nenhum registro | Explica o que falta e o próximo passo; não confundir com falha de conexão |
| Carregamento | Botão e skeleton disponível no CSS | Não apresentar zero ou progresso inventado; bloquear envio duplicado |
| Trilha | Concluído, atual, portão pendente, não iniciado | `aria-current=step`; critério e decisor do portão explícitos |
| Tarefa | Pendente, concluída com evidência | Pessoa/cadeira responsável, critério de pronto, evidência consultável |

## Modelo de dados recomendado para integração

```ts
type Origem = 'automatico' | 'semiautomatico' | 'manual' | 'planilha';
type Indicador = {
  id: string;
  valor: number | null;
  unidade: string;
  periodo: { inicio: string; fim: string };
  origem: Origem | null;
  fonteId: string | null;
  atualizadoEm: string | null;
  condicao: 'atual' | 'desatualizado' | 'ausente';
  confirmadoPor: string | null;
  versao: number;
  cobertura?: { observado: number; universo: number | null };
};
```

Origem e confirmação não são sinônimos. Automático não significa confirmado. Período da informação e data de importação também não são a mesma coisa. Uma atualização automática deve gerar uma proposta de nova versão quando existe valor humano protegido.

## Padrões de negócio

### Evidência

Produção pode oferecer link, foto, número ou texto. O protótipo implementa somente texto. Não aceitar espaços em branco. Exibir resultado registrado e manter autoria, data, tarefa e versão no backend. Reabertura ou correção deve manter histórico.

### IA e regulação

Separar origem de IA, revisão humana e decisão vigente. Um selo de confiança de agente não substitui a confirmação de um parecer. Uma citação clicável não comprova validade: a validação de fontes pertence ao backend. Bloqueio regulatório mostra motivo, fonte, trecho e responsável por corrigir; não oferecer publicação enquanto bloqueado. A biblioteca demonstra o estado, não faz análise regulatória.

### Dados comerciais

Sell-in, sell-through e sell-out não são intercambiáveis. Dado estimado deve ter rótulo, método e cobertura. Não projetar visualmente uma amostra como se fosse o total da indústria. O catálogo não contém números de clientes.

### Gráficos

Usar apenas quando melhorarem uma decisão. Séries devem ter rótulos/unidades/períodos e tabela ou descrição equivalente. Não usar laranja como sinal de aumento/desempenho; ele pode identificar uma série, desde que haja rótulo e distinção adicional. Valores ausentes geram lacunas, nunca pontos em zero. Eixo truncado precisa de indicação. Gráficos complexos ficam fora desta primeira biblioteca.

### Ícones

O G é reservado à marca, sem usar como ícone de estado. Nesta versão as ações têm texto visível e os estados combinam sinais simples com texto. Se adotar uma biblioteca de ícones, manter uma única família de traço, 20 px para controles de 44 px, elementos decorativos ocultos de tecnologias assistivas e nome acessível para botões sem texto. Não há dependência externa de ícones neste pacote.

## Acessibilidade

Meta de texto normal 4,5:1, texto grande 3:1; contornos que identificam controles e foco devem ser perceptíveis. Pares calculados em `VERIFICACAO.json`. Bordas estruturais discretas não são o único indicador de controles. Superfícies escuras especiais precisam de estilos explícitos para conteúdo e controles. Não aplicar tema escuro global nesta versão.

Referências: [contraste](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html), [tamanho de alvos](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html), [diálogo modal](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).

Critérios de aceite de uma tela integrada: fluxo por teclado completo, foco visível, rótulos associados, erros vinculados, ausência de perda de dados após falha, estado ausente distinto de zero, valores formatados pt-BR, reflow a 200% e 400%, alvos adequados e leitura com tecnologia assistiva. Os testes desta entrega não equivalem a uma certificação WCAG.

## Adoção e evolução

Começar pela tela de tarefas, seguida de indicadores e instrumentos. Não importar `catalog.css` ou `catalog.js` no produto: são exclusivos da documentação. `components.css` utiliza escopo `.giro` e classes prefixadas para reduzir conflitos, mas isso não elimina a necessidade de inspecionar estilos legados.

Em React, converter marcação para JSX, mover interações para estado e preservar atributos acessíveis. Usar o diálogo nativo ou uma implementação de modal testada; não criar somente uma sobreposição visual. Não portar os dados fictícios.

Nomeação: `--giro-*` para tokens e `giro-*` para componentes. Alterações de paleta ou comportamento devem ter versão, motivo, telas afetadas e teste. Componentes novos entram após aparecerem em uma necessidade real, não apenas para completar um catálogo.

Fora desta versão: autenticação, backend, permissões reais, upload, integração ERP, gráficos avançados, componentes React distribuíveis e tema escuro global. Nenhum desses recursos é necessário para avaliar a base visual entregue.