Verge Symbols (UI icon design language)

Status: draft v0.1 (2026-05-28). Não bloqueia PRs até v1.0.0. O nome Verge Symbols foi ratificado em 2026-05-28: registrado em registries/component-names.md (type design-language, slug verge-symbols, par natural do Verge visual language) e validado por koder-spec-audit naming (T1–T11 verdes para a row). A família de glyphs ainda não foi desenhada; o trabalho de desenho é owner-driven e roda em meta/brand/koder-design (ticket #033). Esta spec é o contrato de design + adoção; ela governa os glyphs assim que existirem.

R1 — Position: dois planos de iconografia, não um

A Koder Stack tem duas camadas de ícone, com linguagens visuais opostas e propósitos distintos. Confundi-las é o erro que esta spec fecha.

O plano de produto está specado e operante. O plano de glyph de UI não existe: hoje todo app Koder consome Icons.* (Material Icons built-in do Flutter — 70 arquivos no koder_kit). Isso é o buraco que o usuário identifica quando observa que GoogleAppleMicrosoft têm "uma linha de design de ícones": o que elas têm de mais característico é o glyph system de UI, e é exatamente isso que falta.

R1.1 — Verge Symbols ⊂ Koder Design System

Espelha a relação Verge ⊂ KDS de specs/themes/verge.kmd §R1:

Verge Symbols é peer do Verge dentro do KDS, não subordinado: os glyphs alinham com os tokens Verge (traço, raio, cor de accent) mas versionam por conta própria (R9). A verge.kmd §R1 enumera as specs cross-stack que o KDS hospeda — esta spec entra nessa lista (a edição correspondente em verge.kmd adiciona a referência).

R1.2 — Por quê custom, e não continuar com Material Icons

Decisão owner 2026-05-28: família custom do zero. Justificativa:

• policies/self-hosted-first.kmd — usar a glyph library inteira da

  Google na UI contradiz o gate self-hosted-first que já governa Koda vs Rust, kodec vs FFmpeg, kdb-next vs Postgres.

• Coerência com a tipografia — o koder-design já desenha uma

  família tipográfica própria (SansMonoDisplay, brief fonts/DESIGN-BRIEF.kmd, DNA "engineering-first, K geométrico"). Typeface custom + glyphs emprestados da Material é incongruente: SF Symbols existe justamente para casar com San Francisco.

• Identidade — Verge já diverge do Adwaita pra ter "sentimento

  Koder" (verge.kmd §R4.3). Glyphs Material default neutralizam esse esforço.

R2 — Naming forms (per specsnamingforms.kmd) — ratificado 2026-05-28

Dart enum/identificador de família: KoderIcons (analogia a Icons). Cada glyph: KoderIcons.search, KoderIcons.add, etc.

Ratificado: row adicionada a registries/component-names.md (seção Meta — Design Language, irmã de Verge) e validada por koder-spec-audit naming — T1–T11 verdes para a row (as falhas que o audit reporta são pré-existentes em outros componentes). O token distintivo Verge já estava ratificado (verge.kmd §R2); Symbols é descritor de categoria por convenção da indústria (Material Symbols, SF Symbols), não token de marca pontuável. Risco herdado de overlap com "The Verge" anotado em verge.kmd §R2 — não bloqueia (namespaces distintos).

R3 — DNA visual (engineering-first, K geométrico)

Os glyphs compartilham o DNA da marca Koder, alinhado ao brief tipográfico (fonts/DESIGN-BRIEF.kmd §1):

• Confiante, técnica, contemporânea. Não retro, não humanista, sem

  ornamento gratuito.

• Geometria precisa — construído sobre círculos, retas e arcos

  exatos; sem curvas "à mão". Caráter relacionado ao K geométrico do logotipo.

• Clareza em tamanho pequeno — legível e inconfundível em 16px.
• Mono-line por default — traço de espessura constante (o eixo de

  peso, R6, modula essa espessura uniformemente).

R3.1 — O que herdar de quem (destilação do survey)

Síntese subtrativa de 13 sistemas (dossiê em meta/brand/koder-design/symbols/design-intelligence-survey.kmd). Não copiar nenhum por inteiro — herdar o subconjunto coerente, atribuído:

• Filosofia "o ícone é extensão da tipografia" ← SF Symbols. Operada

  no R6.1 (type-coupling contract) — o diferencial central de Verge.

• Eixos variable-font reais (weightfillopsz) ← Material Symbols.

  Reduzidos a 2 pesos (não os 9 stops do SF) — R6.

• Execução mono-line geométrica ← Phosphor / Lucide, mas sem o

  round-cap default deles (anti-técnico — ver R5).

• Masters ópticos discretos por tamanho ← Fluent + Carbon (contra o

  downscale degradado de Lucide/Atlassian) — R6.

• Regra de canto híbrida (externo arredondado / interno vivo) ←

  Atlassian + Carbon — R5.

• DNA derivado da typeface companheira ← Carbon (Plex→icons); aqui,

  do K geométrico + Koder Sans (fonts/DESIGN-BRIEF.kmd).

• Recolor semântico runtime por classe ← Adwaita symbolic — R7.
• Escopo cirúrgico, opinativo, pequeno ← Radix (~318); resistir ao

  sprawl de TablerFluentMaterial — R10.

• Distribuição dual + licença permissiva ← Material (variable font) +

  Lucide/Radix (per-glyph tree-shakeable); nunca o lock-in proprietário de SF Symbols/Atlassian — R8.

R4 — Grid de construção & keylines

Análogo ao keyline system do Material e ao canvas grid do SF Symbols.

R4.1 — Canvas base

• Grid base: 24 × 24 (unidade de design). Todos os glyphs são

  desenhados nesse canvas; o export reescala (R8).

• Live area (área viva, onde o glyph respira): 20 × 20 central.
• Trim / padding: ≥ 2px de margem em cada lado no grid 24

  (≈ 8,3%). Nenhum traço encosta na borda do canvas.

• Pixel snapping: como Verge entrega fill achatado (não stroke

  vivo), são as arestas externas do path preenchido que caem em pixel inteiro @16 e @24 — deixa só uma aresta no sub-pixel, evitando blur em tamanho pequeno. (Lição Fluent/Atlassian: alinhar a borda externa do traço, não o centerline.)

R4.2 — Keyline shapes

Toda forma deve se ancorar a uma das keylines canônicas (mantém peso óptico consistente entre glyphs, igual ao Material):

A ancoragem a uma keyline é normativa para todo glyph novo (não só guideline) — keylines sub-especificadas são a causa do drift de contribuição que o Carbon sofre. Enforcement: kicon validate checa a ancoragem em severidade Warning (não Error), espelhando o modelo de safe-zone de generation-targets.kmd — a tolerância de overshoot óptico (R4.3) e o caráter parcialmente estético da ancoragem tornam Error rígido demais; o Warning expõe o glyph cuja bbox não cabe em nenhuma keyline (± overshoot) sem bloquear a geração. Ver R8.

R4.3 — Correções ópticas

Formas circulares e pontiagudas estouram ligeiramente as keylines pra parecerem do mesmo tamanho que quadradas (overshoot ~1px). Documentar o overshoot por glyph no source — não é "erro de grid".

R5 — Regras geométricas

Regra de canto híbrida (← Atlassian + Carbon): arredondar só o contorno externo (R2) e manter os cantos internos/concave vivos faz o mono-line geométrico parecer técnico e type-friendly ao mesmo tempo — softness suficiente pra casar com os terminais da Koder Sans (fonts/DESIGN-BRIEF.kmd §1) sem cair no friendly humanista proibido.

Lista fechada de round-cap (exceção de movimento). O round cap é a assinatura do look friendly (LucideTablerPhosphor) que o DNA proíbe (R3) — por isso a exceção é uma allowlist explícita, não um critério subjetivo "quando o glyph pede". Round cap é permitido somente nos glyphs cuja semântica é movimento/rotação contínuo, onde o terminal arredondado lê como rastro de movimento:

refresh · replay · sync · rotate · undo · redo · loading (spinner) · progress-activity

Qualquer glyph fora dessa lista usa butt cap. Adicionar um glyph à lista exige edição desta linha (mantém a allowlist auditável) — kicon validate sinaliza round cap em glyph fora da lista como Warning.

Todo glyph é entregue como outline preenchido (fill), não stroke vivo — assim o eixo de peso e o render em qualquer tamanho não dependem de stroke-width do consumidor. Isso evita a parede do Radix (peso baked, não re-pesável — issue #177) e a distorção de stroke-scaling em extremos (Lucide/Tabler): o peso é eixo real, entregue como fill achatado por instância de eixo.

R6 — Eixos (variabilidade)

Modelo dos 4 eixos do Material Symbols. v1.0.0 não precisa shipar todos — mas a spec reserva o eixo pra evitar redesenho:

Default canônico: weight 400, fill 0, opsz 24.

R6.1 — Contrato de acoplamento com a tipografia (type-coupling)

Normativo. Esta é a diferenciação central de Verge Symbols e o que o survey de 13 sistemas confirmou que quase nenhum set FOSS tem (LucidePhosphorTabler/Radix: zero; Material: não amarra a um typeface específico; Fluent: fraco). Só o SF Symbols faz forte — e é proprietário Apple-only. Borrow: filosofia SF Symbols + size-calibration do Carbon (Plex). O glyph é uma extensão da tipografia Koder, não um vizinho solto:

• Map de peso: o eixo weight do glyph casa 1:1 com o weight da

  Koder Sans — glyph 400 ↔ Sans Regular, glyph 600 ↔ Sans SemiBold. Um ícone ao lado de um texto SemiBold renderiza em 600.

• Alinhamento vertical: a caixa óptica do glyph snapa à cap-height

  (não à x-height) da Koder Sans no tamanho corrente, alinhada à baseline do texto adjacente.

• Size-calibration: os masters opsz (R6: 162024) calibram contra os

  tamanhos de texto correspondentes da Sans (≈ 141620pt), como o Carbon faz contra o Plex.

• Dependência: este contrato depende da família tipográfica Koder

  (fonts/DESIGN-BRIEF.kmd, #006), ainda em desenho. Até a Sans existir, o map usa os weights canônicos de typography.kmd (400/600) como proxy.

R7 — Modos de renderização

Modelo SF Symbols (rendering modes) adaptado ao Verge:

Regra: monochrome é o default absoluto. Um glyph que só funciona colorido provavelmente é um ícone de produto (R1) e não pertence aqui. A cor vem sempre do token Verge, nunca hardcoded no glyph (exceto multicolor semântico).

Mecanismo de cor (← Adwaita symbolic, a melhor ideia daquele sistema): o glyph é um path com fill="currentColor" / fill=none no root (single-property theming, ← RadixPhosphorLucide). Os modos filled/multicolor semântico se resolvem por classe injetada pelo token Verge (fg / accent / success / warning / error / disabled) em runtime — zero asset duplicado, nunca cor hardcoded no SVG. O KoderIcon (R9) expõe esses slots; resto herda currentColor.

Nota (2026-05-28): a multicor pertence ao plano de produto (R1), não ao de glyph. É tentador achar que "várias cores facilitam" — mas em glyph de UI a cor é passivo: precisa herdar o tema, sobreviver a 16px e ler em toolbar densa, por isso Material Symbols / SF Symbols / Fluent são monocromáticos. Reforço externo: o redesign de ícones de produto do Google (Gemini Era, abr–mai/2026) abandonou a regra das 4 cores obrigatórias e os frames em favor de forma distinta + gradiente — ou seja, big-tech está afrouxando cor mesmo no plano colorido. Verge Symbols (glyph) fica monochrome-first sem hesitar.

R8 — Formatos de export & geração (via kicon)

Fonte única → múltiplos formatos, codificado em dev/kicon (nunca à mão — policies/sdk-first.kmd). O target verge-symbols (glyph-set, family-level) está especificado em specs/icons/generation-targets.kmd — par do target de produto-icon, mas para o glyph set:

• Codepoints: faixa Private Use Area estável; um glyph nunca muda de

  codepoint entre versões (compat — policies/always-on.kmd). O codepoint PUA é o mecanismo de delivery canônico (o binding Dart KoderIcons e o koder_web_kit resolvem por codepoint).

• Ligature (aditivo, opcional — kicon#041): a .woff2/.ttf também carrega

  uma tabela GSUB liga que mapeia o nome do glyph (kebab/snake) + seus aliases R10.2 → o glyph (ex.: digitar chevron-right em webmarkdowntempl renderiza o ícone), paridade com a icon-font do Material. É conveniência de DX, não o delivery primário: o codepoint PUA permanece o contrato (ligature é frágil p/ a11yi18ncolisão de nome — survey §4.8). O codepoint PUA do glyph fica inalterado; a ligature só adiciona uma rota a mais pro mesmo glyph (append-only, como o codepoint).

• Validação (kicon validate, gate pré-geração). Error (bloqueia

  geração): glyph cabe no canvas 24 com trim ≥ 2px; codepoint PUA único e estável; nomenclatura R10 válida; arestas externas do path em pixel inteiro @16/@24 (R4.1). Warning (não bloqueia): ancoragem a uma keyline R4.2 (± overshoot R4.3); round cap em glyph fora da lista fechada de movimento (R5); legibilidade @16 (assert estrutural). Severidade espelha generation-targets.kmd (margin = Error, safe-zone = Warning).

R9 — Adoção no KDS / SDK (KoderIcon)

O contrato de consumo. Hoje o koder_kit chama Icons.add, Icons.search, etc. (Material). A migração:

1. KoderIcon widget no koder_kit — substitui Icon(Icons.x) por

   KoderIcon(KoderIcons.x); resolve pesofillopsz a partir do tema Verge ativo e do tamanho; default monochrome herdando --on-surface.

2. koder_web_kit — componente/CSS equivalente; classe

   [data-icon="search"] ou <koder-icon name="search"> servindo da .woff2/sprite self-hosted.

3. Lint SDK-first — Icons.* (Material) na UI Koder vira finding do

   /k-sdkify e do lint tasks:sdk-first-lint, igual a qualquer reimplementação de primitive. Exceção: ícones de marcas externas (logos de terceiros) que não pertencem ao set Koder.

4. Registro no Verge — verge.kmd cross-link + entry na lista de

   specs KDS de §R1.

A migração dos 70 call sites é tracked no koder_kit (ticket #071) e é mecânica assim que o set v1 + KoderIcons existirem. Não começar a trocar call sites antes de a família ter cobertura ≥ do conjunto Material em uso (R10).

R10 — Cobertura mínima & nomenclatura

R10.1 — Conjunto v1.0.0 (cobre o uso atual + comum)

O conjunto v1.0.0 está enumerado (não estimado) no inventário meta/brand/koder-design/symbols/glyph-inventory-v1.kmd: 140 glyphs em 9 categorias (navegação / ações / status / toggle / mídia / comunicação / arquivos / sistema / editor), cada um com bucket de naming (R10.2) e o Icons.* Material que substitui (map de migração de #071). Cobre 100% dos Icons.* auditados no koder_kit em 2026-05-28 (add, search, error_outline→error, expand_more, close, chevron_right, edit, check, star, share, schedule→clock, replay, refresh, play_arrow→play, language→globe, expand_less, delete_outline→delete, block) + o núcleo universal que toda UI precisa. Escopo cirúrgico (ordem de grandeza Radix 318, não o sprawl Material 2500 / Tabler 6k). Adicionar glyph ao v1 = editar o inventário (mantém auditável).

Meta de cobertura — crescimento sob demanda (decisão B3, owner 2026-06-03, koder-design#035). O número não é fixo em 140: 140 é o piso do v1.0.0 (cobre 100% do uso atual). A meta de regime é crescer guiado por demanda real rumo à banda dos design systems opinativos de produto (~250–350, faixa Radix 318 / Polaris ~480 / Salesforce-utility ~200) — nunca a escala plataforma-wide (Material 3.8k / Fluent 4.3k / SF 6.9k), que é sprawl pra um set frameless opinativo. O sinal de demanda é mecânico: todo Icons.* (Material) que aparecer na UI Koder sem par Verge — detectado pelo lint SDK-first (R9.3) / /k-sdkify — é candidato a entrar no inventário. Fundamentação: análise comparativa multi-bigtech meta/brand/koder-design/symbols/bigtech-icon-engineering-comparison.kmd.

R10.2 — Naming híbrido two-bucket (← Atlassian)

Regra de dois baldes, auditável:

• Single-purpose → nome de conceito/função: delete (não trash),

  settings (não gear). (SF Symbols / Material convention.)

• Multi-purpose / primitiva de forma → nome literal: chevron-right,

  dot, circle — quando o glyph serve a vários contextos e não tem função única, o nome descreve a forma.

• kebab-case no source e no sprite (chevron-right); snake_case no

  identificador Dart (KoderIcons.chevron_right).

• Aliases permitidos pra estabilidade (mapeia nome Material → Koder no

  manifest), igual aos aliases de kicon em generation-targets.kmd.

• Direcionais explícitos: chevron-right / chevron-left /

  chevron-up / chevron-down (RTL resolve no consumidor, não no glyph).

R11 — Versionamento

Análogo a verge.kmd §R6 (Verge v0→v1→v2):

• v0.x (esta fase) — spec + DNA + grid ratificados; glyphs em

  desenho. Sem release de família.

• v1.0.0 — primeira família utilizável: cobertura R10.1, eixos

  weight {400,600} + fill {0,1} + opsz {16,20,24}, KoderIcons Dart + .woff2 + sprite. Gate de release (R8 validação) verde.

• v2+ — grade axis, modos hierarchical/multicolor completos,

  cobertura expandida.

Codepoints são append-only entre versões (R8). Cada release ganha changelog e (se o portal existir) página em kds.koder.dev.

R12 — Checklist de aprovação (por glyph)

• [ ] Desenhado no grid 24, live area 20, trim ≥ 2px
• [ ] Ancorado a uma keyline (R4.2) ou overshoot documentado
• [ ] Traço 2px / cantos R2 / ângulos múltiplos de 15° (R5)
• [ ] Entregue como fill achatado (não stroke vivo)
• [ ] Hint @ 16 e @ 20 (opsz) revisado — não é o 24 reescalado
• [ ] Monochrome herda token Verge (zero cor hardcoded, salvo multicolor semântico)
• [ ] Nome semântico kebab-case + alias Material mapeado (R10.2)
• [ ] Codepoint PUA único e estável
• [ ] kicon validate verde

R13 — Motion (glyphs animados) — DRAFT (pendente ratificação do owner)

Status: DRAFT. Esta seção é uma proposta redigida pelo par tooling (kicon#040) pra de-riscar a construtibilidade do export animado; o DNA de motion + os morph-pairs bespoke são trabalho de design (koder-design#036) e a ratificação normativa é do owner. O que está implementado hoje é só o preset determinístico R13.2 (draw-on/off); o resto é contrato proposto.

R13.1 — Princípio

Motion de glyph é funcional e geométrico, não decorativo (espelha o DNA Verge, engineering-first). Reusa integralmente o vocabulário de specs/themes/motion/easing-duration.kmd (durations + easing) — não inventa tokens próprios. Não confundir com KdsMotion (transição de widget): R13 é o movimento do glyph em si.

R13.2 — Preset draw-on / draw-off (determinístico — IMPLEMENTADO)

Aparição/saída por traçado, derivada deterministicamente do stroke do master (sem keyframes desenhados): cada <path> recebe pathLength="1" + stroke-dasharray:1 e o stroke-dashoffset anima 1→0 (on) ou 0→1 (off). É geométrico (sem feel caligráfico), aplicável a qualquer glyph. Default estático = traçado completo (stroke-dashoffset:0) → renderer sem animação/SMIL mostra o ícone inteiro (fallback grátis). Gerado por kicon animate --preset draw-on.

R13.3 — Morph-pairs (bespoke — design-pending #036)

Transições estado A↔B no mesmo glyph: menu↔close, play↔pause, chevron (rotação), check↔spinner, heart/star fill, search↔close. São design criativo (interpolação entre glyphs distintos, path-compatível) — NÃO determinísticos; enumerados e desenhados em koder-design#036. O tooling (kicon#040) consome os keyframes-fonte que #036 produzir.

R13.4 — Contrato reduced-motion (OBRIGATÓRIO)

Todo glyph animado tem fallback estático e respeita prefers-reduced-motion / MediaQuery.disableAnimations. No alvo SVG, a animação roda só sob @media (prefers-reduced-motion: no-preference); o estado base é o ícone estático. Espelha o contrato do KdsMotion.

R13.5 — Alvos de export (via kicon)

kicon animate emite, do mesmo motion-spec: animated SVG (CSS/SMIL — web inline + docs, IMPLEMENTADO), AnimatedVectorDrawable (<animated-vector> XML — Android, follow-up), Lottie (.json — Flutter/web via koder_kit, follow-up). Toda saída carrega o fallback estático. GRAD/opsz são font-axis; motion é export-only (sem rung de PNG).

R13.6 — Gate (kicon validate)

Glyph animado: durações/easing só dos tokens de easing-duration.kmd; fallback estático presente. Warning→Error conforme a ratificação do owner amadurecer.

Cross-link

• specs/icons/products.kmd — o outro plano (ícone 3D de produto/launcher)
• specs/icons/generation-targets.kmd — matriz de export do kicon (par do R8)
• specs/themes/verge.kmd — linguagem visual irmã; tokens de cortraçoraio que os glyphs herdam
• specs/fonts/typography.kmd — weights canônicos + self-hosted .woff2 (mesmo regime do icon font)
• specs/naming/forms.kmd + registries/component-names.md — ratificação do nome (R2)
• policies/self-hosted-first.kmd — gate que motiva custom-vs-Material (R1.2)
• meta/brand/koder-design #033 — DNA brief + desenho da família (owner-side)
• engines/sdk/koder_kit #071 — KoderIcon + migração dos call sites (R9)
• dev/kicon — implementação do target de geração (R8)

/content /invoke