Anatomia do Ícone
Um ícone de produto Koder é um símbolo 3D em que a forma é o conceito — sem texto, sem moldura — gerado a partir de um master SVG único e exportado pra toda plataforma pela ferramenta kicon, nunca desenhado por densidade à mão. As regras normativas moram em icons/products.kmd e a matriz de export por plataforma em generation-targets.kmd.
Um ícone se decompõe em quatro famílias de elementos: geométricos (o grid e suas zonas), visuais (a forma e a cor), de camada (a entrega adaptativa) e metadados.
1. Elementos geométricos / estruturais
| # | Elemento | Descrição | Valor Koder |
|---|---|---|---|
| 1 | Canvas | Área total do ícone (sistema de coordenadas) | viewBox 0 0 512 512 |
| 2 | Live area | O que sobrevive à máscara do SO | varia por OEM |
| 3 | Safe zone | Região central nunca clipada | 66,7% (Android); 80% (PWA) |
| 4 | Bleed zone | Faixa externa que pode ser clipada | 16,7% por lado (Android) |
| 5 | Margem / padding | Faixa entre o desenho e a borda, igual nos 4 lados | alvo ~10%/lado (§3) |
| 6 | Keyline shapes | Formas-guia que igualam o peso óptico | quadrado/círculo/retângulo |
| 7 | Centro / eixo óptico | Ponto de equilíbrio visual (não o centro geométrico) | centralização ±4px |
2. Elementos visuais / de conteúdo
| # | Elemento | Descrição | Regra |
|---|---|---|---|
| 8 | Silhueta dominante | A forma principal — é o ícone | R2 (uma só) |
| 9 | Glyph primário | Símbolo que nomeia a função (envelope, seta, mic…) | R5 (branco sólido) |
| 10 | Detalhe secundário | Elementos de apoio | R5 (opacidade 0,3–0,95) |
| 11 | Espaço negativo | Vazio que reforça a leitura figura-fundo | favorecer |
| 12 | Cor dominante (hue) | Cor de marca do produto | R6 (mono-hue) |
| 13 | Gradiente | Variação de cor que dá luz/direção | R3 (vertical 700→500→400) |
| 14 | Overlay de profundidade | Sombra de profundidade/assentamento | R4 (preto 0→0,18) |
| 15 | Overlay de brilho | Gloss discreto | R4 (branco 0,12→0) |
| 16 | Drop shadow | Sombra projetada que separa do fundo | feDropShadow |
| 17 | Luz direcional | Fonte de luz coerente (de cima) | R3 |
3. Camadas técnicas (entrega adaptativa)
| # | Camada | Arquivo / forma | Conteúdo |
|---|---|---|---|
| 18 | Master SVG | icon.svg (raiz do produto) | fonte única, 512² |
| 19 | Foreground | ic_launcher_foreground.png | símbolo, fundo transparente |
| 20 | Background | @color/ic_launcher_background | cor de marca (não branco) |
| 21 | Monochrome | ic_launcher_monochrome.png | silhueta branca (Android 13+) |
| 22 | Legacy | ic_launcher.png | API <26, sem camadas |
| 23 | Adaptive descriptor | mipmap-anydpi-v26/ic_launcher.xml | liga bg+fg+monochrome |
| 24 | Maskable / Dark | icon-512-maskable · icon-dark.svg | PWA 80% · variante escura |
4. Gramática de família (normativa — R1 a R7)
| Regra | Definição |
|---|---|
| R1 — Frameless absoluto | Nenhum retângulo/forma de fundo cobrindo o canvas no master. A silhueta é o ícone. kicon validate reprova fundo full-canvas (erro duro). |
| R2 — Uma silhueta dominante | Reduzir a uma forma. Proibido: skeuomorfismo, cena literal, múltiplos elementos, line-art fino. |
| R3 — Gradiente = luz de cima | linearGradient vertical em userSpaceOnUse, 3 stops: 700 (base) → 500 (meio) → 400 (topo). |
| R4 — Overlays de profundidade/brilho | dep: preto 0→0,18 (base). sh: branco 0,12→0 (topo). Ambos userSpaceOnUse. |
| R5 — Detalhe interno branco | Glyph primário branco sólido (#fff); detalhe secundário 0,3–0,95. Piso de legibilidade 32×32px. |
| R6 — Mono-hue | Um hue dominante por produto. Sem acento policromático (exceto a travessia de R3). |
| R7 — Preenchimento ~92% no master | A silhueta preenche ~92% do canvas (margem óptica ±4%); kicon generate reduz pro foreground adaptativo. |
5. Geometria — margem e área
A margem é uma medida linear (faixa por lado). Convertendo pra área do canvas: uma margem linear m por lado deixa conteúdo de lado (1−2m) → área do conteúdo = (1−2m)².
| Margem linear / lado | Conteúdo (% da área) | Fundo (% da área) | Uso típico |
|---|---|---|---|
| 8% | 70,6% | 29,4% | Material legacy keyline |
| 10% (alvo Koder) | 64,0% | 36,0% | logo-em-tile (macOS / PWA) — sweet-spot |
| 12% | 57,8% | 42,2% | alternativa mais folgada |
| 16,7% | 44,4% | 55,6% | foreground Android adaptive (anti-clip OEM) |
6. Geração — kicon
Toda variante é gerada do master via kicon (nunca renderizada por densidade à mão). Rode kicon validate pra forçar a gramática R1–R7 + safe-circle, e kicon generate pras saídas por plataforma (mipmaps Android, iOS, macOS .icns, Windows .ico, Linux hicolor, favicons web, PWA maskable, store listing).
7. Glifo inscrito — figura em contêiner de UI (normativo)
Os capítulos 1–6 tratam do *ícone de produto* (3D, launcher). Esta seção fecha o outro plano: o *glyph de UI dentro de um contêiner* — botão circular, tile, chip, pílula. Spec normativa completa (fórmulas, keylines, testes T1–T4): specs/icons/inscribed-glyph.kmd.
O problema tem três objetos: o *contêiner* K (com centro C e margem m), a *figura* F (o conjunto de pontos com tinta — fills e strokes com a espessura contada) e o *envolvente da tinta* B. Inscrever é satisfazer três igualdades independentes: centro de B ≡ C; tinta escalada tocando o limite útil K⊖m; e a mesma razão de ocupação entre todos os irmãos da família.
*A regra que evita 90% dos defeitos: medir a TINTA, nunca a moldura.* Duas figuras na mesma moldura (viewBox) podem pintar extensões 40% diferentes — com a mesma escala, uma família exibe glifos visivelmente desiguais. O protocolo em ordem: medir tinta → centralizar na moldura → escalar pelo contêiner → compor → ajuste óptico (se assimétrica) → medir de volta.
A escala máxima depende da *forma do contêiner* (formulação geral: funcional de Minkowski do contêiner erodido pela margem). No círculo, quem manda é o ponto da tinta mais distante do centro; no quadrado/squircle, a maior coordenada; na pílula, a altura da faixa central:
Para famílias heterogêneas, a consistência usa keylines (como Material/SF Symbols): extensões-alvo por proporção do envolvente — quadrado 0,82, retrato/ paisagem 0,90 na dimensão dominante, circular 0,86 — compensando a massa percebida de cada formato.
