# Contrato de iconografia — Baluarte v1.5
## Fonte oficial
O Baluarte usa **Phosphor 2.1** como única família de ícones de sistema. Os assets vieram de `phosphor-icons.zip`, possuem licença MIT e são servidos localmente.
Pesos instalados:
| Papel | Fonte | Classe | Uso |
|---|---|---|---|
| padrão | Phosphor Regular | `ph` | menus, botões, campos, listas e navegação |
| ênfase | Phosphor Bold | `ph-bold` | destaque excepcional e justificado |
| seleção | Phosphor Fill | `ph-fill` | selecionado, favorito ou estado ativo |
Thin, Light e Duotone existem na fonte original, mas não pertencem ao contrato atual.
## Princípios
As práticas abaixo adaptam aprendizados do sistema de símbolos da Apple ao contexto web e à família Phosphor. O Baluarte não distribui nem imita SF Symbols.
1. **Símbolos trabalham com texto.** O glyph e o label são elementos separados e alinhados pela caixa do componente.
2. **Margens ópticas são intencionais.** Silhuetas diferentes não devem ser esticadas para ocupar exatamente a mesma área visível.
3. **Peso é um desenho, não um efeito.** Use a fonte Bold; nunca aumente `stroke-width`, aplique text-shadow ou duplique paths.
4. **Outline é o padrão.** Fill comunica seleção ou superfície semântica maior.
5. **Escala e alvo são independentes.** Um glyph de 16 ou 20px pode viver em alvo de 32, 40 ou 44px.
6. **Direção depende do significado.** Navegação pode espelhar em RTL; mídia, relógios, marcas e objetos físicos não.
7. **Semântica precede aparência.** Escolha pelo conceito e registre equivalências no de–para.
8. **Acessibilidade não depende do ícone.** Nome acessível, estado ARIA e texto continuam obrigatórios.
Referências:
- [Apple HIG — SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols)
- [Introducing SF Symbols — WWDC19](https://developer.apple.com/videos/play/wwdc2019/206/)
- [What's new in SF Symbols — WWDC21](https://developer.apple.com/videos/play/wwdc2021/10097/)
- [Phosphor Icons](https://phosphoricons.com/)
## Escala
| Token | Caixa | Contexto principal |
|---|---:|---|
| `--b-icon-compact` | 16px | metadados, tabs densas, chips e controles compactos |
| `--b-icon-default` | 20px | botões padrão, campos, rail, navegação lateral, Menu e marks/representações compactas |
| `--b-icon-large` | 24px | headers, ações destacadas |
| `--b-icon-display` | 32px | empty states e specimens |
Largura, altura, flex-basis e font-size avançam juntos por `--b-icon-size`. Rail, menu lateral do portal, Menu de ações e marks de entidade convergem em 20px. Em Icon Button, a relação alvo/glyph é normativa em `ICON-BUTTON.md`: 32/16, 40/20 e 44/24.
## Emoji
Emoji configurável usa `.b-emoji` e a mesma escala 16/20/24/32, mas não se torna ícone de sistema. Caixa, `font-size` e `line-height` avançam juntos; texto cru fora da API é inválido, exceto em exemplos de código. Emoji decorativo permanece `aria-hidden`; ação e estado continuam descritos pelo controle ou label.
```html
🤖
```
O contrato completo de Picker, representação e Live está em `REPRESENTATION-AND-LIVE.md`.
## Alinhamento
- Use `inline-grid` e `place-items: center` na caixa `.b-icon`.
- Use `align-items: center` no componente que combina ícone e label.
- Não aplique `top`, `bottom`, margem negativa ou `translateY`.
- Não altere apenas `font-size`.
- Respeite a silhueta e o espaço interno do glyph Phosphor.
- Teste no mínimo em 16 e 20px, nos temas claro e escuro.
## Implementação
```html
```
Peso forte:
```html
```
Selecionado:
```html
```
`data-icon` mantém temporariamente o nome anterior para rastreabilidade. Novos componentes devem consultar `reports/icon-migration-phosphor-v1.5.md` e reutilizar o significado já aprovado.
## Cor e estado
- A cor padrão é herdada por `currentColor`.
- Azul indica foco, link ou seleção conforme o componente.
- Vermelho é exclusivo de erro, perigo ou destruição.
- Fill, cor ou peso nunca são o único indicador de estado.
- Não use multicolor ou duotone no core atual.
## Acessibilidade
- Ícone com label visível: `aria-hidden="true"`.
- Botão apenas com ícone: `aria-label` no botão.
- Estado selecionado: `aria-current`, `aria-pressed`, `aria-checked` ou papel equivalente.
- Não use o nome visual do ícone como nome acessível quando ele não descreve a ação.
- Valide contraste do ícone funcional em pelo menos 3:1 contra o fundo.
## Marcas oficiais
Marcas não são ícones de sistema. `.b-brand-mark--display` oferece uma caixa de 32px para specimens e comparações. O asset monocromático segue o contraste da superfície:
- tema ou superfície clara: desenho escuro;
- tema ou superfície escura: desenho claro;
- use `.b-brand-mark--on-light` ou `.b-brand-mark--on-dark` quando a superfície local divergir do tema;
- não aplique cor de acento, Fill ou stroke Phosphor à marca;
- preserve proporção e área transparente do asset oficial;
- a caixa pode ter 32px, mas a área óptica visível deve manter pelo menos 4px de respiro e não tocar o perímetro.
## Arquivos e artefatos
Ícones de arquivo usam o glyph Phosphor específico da extensão sempre que ele existir. Não substitua DOC, XLS ou PPT por ícones genéricos de texto, tabela ou apresentação.
| Família da referência | Extensões cobertas | Estratégia Phosphor |
|---|---|---|
| imagem | `png`, `jpg`, `jpeg`, `gif`, `webp`, `bmp`, `svg`, `ico`, `avif`, `tif`, `tiff` | glyph exato para PNG/JPG/SVG; `file-image` nos demais |
| PDF | `pdf` | `file-pdf` |
| dados tabulares | `csv` | `file-csv` |
| documento | `doc`, `docx`, `odt`, `rtf` | `file-doc` |
| planilha | `xls`, `xlsx`, `ods` | `file-xls` |
| apresentação | `ppt`, `pptx`, `odp` | `file-ppt` |
| texto | `txt`, `md`, `log` | `file-txt`, `file-md` ou `file-text` |
| estruturado | `json`, `xml` | `file-code`, pois Phosphor não possui glyph dedicado |
| compactado | `zip`, `rar`, `7z`, `tar`, `gz` | `file-zip` ou `file-archive` |
| código | `js`, `jsx`, `ts`, `tsx`, `py`, `java`, `c`, `cpp`, `cs`, `php`, `rb`, `go`, `rs`, `swift`, `kt`, `sql`, `sh`, `html`, `css`, `scss`, `less`, `yaml`, `yml` | glyph exato quando disponível; `file-code` como fallback |
| desconhecido | qualquer outra extensão | `file-text` |
O manifesto `assets/icons/file-formats.json` contém o de–para individual das **56 extensões** observadas no classificador `getFileVisualMeta` da referência. O inventário reproduzível e os três hashes idênticos estão em `reports/clickagents-file-formats-v1.5.md`.
Em Media Card, o nome do arquivo continua visível no footer. Em `.b-file-tile`, o glyph com sigla já identifica visualmente o formato: remova o label redundante, centralize o ícone em 32px e dê nome ao botão com `aria-label`. As cores `--file-*` são categóricas e nunca representam status; vermelho continua reservado a perigo, erro e destruição.
## Navegação expansível
Grupos laterais usam `ph-bold ph-caret-down` em slot oficial de 16px com glyph óptico de 10px alinhado ao fim do eixo de bloco. A cor é `--text-subtle`; opacidade permanece em 100% no default e no hover para resistir ao antialiasing. A orientação muda pela rotação do pseudo-elemento no centro do próprio glyph, sem rotacionar o slot e sem trocar glyph; RTL inverte o sentido fechado. Título e chevron permanecem adjacentes; trigger e slot externo 16px ficam centralizados e estáveis. Padding de bloco final derivado de `--b-space-1 / 2` sobe o glyph 1px nos dois estados; não há margem negativa ou offset.
## Localização e RTL
- Setas de voltar/avançar e progressão direcional podem espelhar.
- Play, relógio, reload, marcas, arquivos e objetos físicos preservam orientação.
- Um ícone com letra, número ou escrita exige revisão por locale.
- O label localizado é a fonte primária de significado.
## Ícones customizados
Um ícone customizado só pode existir quando não houver equivalente semântico no Phosphor.
A proposta deve incluir:
1. nome semântico e contexto;
2. busca documentada no catálogo Phosphor;
3. viewBox 256 × 256;
4. Regular com stroke 16 e Bold com stroke 24;
5. caps e joins arredondados;
6. margens ópticas compatíveis com a família;
7. versão Fill, quando houver estado selecionado;
8. comportamento RTL;
9. nome acessível e critérios de uso;
10. teste a 16, 20, 24 e 32px em claro e escuro.
## Governança
Qualquer troca de glyph deve atualizar simultaneamente:
- `reports/icon-migration-phosphor-v1.5.md`;
- `scripts/unify_icons.py`;
- subset local `assets/icons/phosphor/phosphor.css`;
- specimens afetados;
- auditoria estática e 32 renders.
## Specimens no portal
O catálogo usa muro de glyphs, caixas tracejadas 16/20/24/32, pesos Regular/Bold/Fill e oito práticas demonstradas. Todo `.b-icon` mantém `data-icon`, classe Phosphor correspondente e `aria-hidden="true"`; o significado continua no texto adjacente ou no nome acessível do controle. Demonstrações decorativas não criam novas decisões no de–para.