Icon Forge

O que Icon Forge faz?

Desenhe ícones personalizados que pareçam ter saído de um conjunto profissional e os entregue sem dependências em tempo de execução. Você concluiu quando todos os ícones passam pelo lint, você olhou para a pré-visualização em 16/20/24px e ela está legível e consistente em fundo claro e escuro, e os componentes gerados estão integrados com uso acessível.

<skill> abaixo significa a pasta que contém este arquivo (ex: .claude/skills/icon-forge, .cursor/skills/icon-forge, .agents/skills/icon-forge). Os scripts precisam de Node ≥18 e nenhuma dependência do projeto.

Quando usar / quando não usar

• Use: uma barra lateral, navbar, painel de controle, página de configurações, estado vazio ou barra de ferramentas precisa de ícones; o usuário pede um ícone personalizado ou faltante; o usuário quer substituir emojis/placeholders ou um pacote de ícones pesado por um conjunto pequeno próprio.
• Não use: logotipos e marcas (marcas registradas; precisam de um designer), favicons/ícones de aplicativos, ilustrações ou arte pontual, fotos/raster, Lottie animado. Se o usuário pedir explicitamente para instalar uma biblioteca (ex: "usa Lucide mesmo"), faça o que ele pediu; esta habilidade existe para o caminho personalizado.

Regras rígidas (e porquê)

1. Desenhe cada ícone você mesmo; não adicione dependência de biblioteca de ícones. O usuário escolheu ícones próprios pelo tamanho do bundle e por uma aparência única. Não cole dados de caminho do Lucide, Heroicons, Material, etc. (licenciamento e originalidade). Use references/glyph-cookbook.md (desenhos originais) como geometria inicial.
2. Se o projeto já usa uma biblioteca de ícones, corresponda à sua grade, traço, extremidades e raio (veja scripts/detect.mjs e design-rules §10). Novos ícones devem ficar ao lado dos existentes sem parecerem estrangeiros.
3. Um conjunto, um estilo. Mesma grade, espessura de traço, extremidades/uniões, escala de raio, preenchimento e nível de detalhe para cada ícone. Consistência é mais importante do que qualquer ícone engenhoso isolado.
4. Atributos de apresentação vivem apenas no <svg> raiz, a cor é currentColor, e as fontes não contêm ids, estilos, classes, transformações ou <g>. Caso contrário, a tematização, o modo escuro, a propriedade strokeWidth e a inserção em linha quebram.
5. Nunca afirme que um ícone está bom sem renderizá-lo e visualizar o PNG. Geometrias que parecem certas no código rotineiramente falham em 16px: manchas, lacunas fechadas, formas descentralizadas, peso incompatível.
6. Execute os scripts; não os reimplemente. Lint, otimização, pré-visualização e geração de código são determinísticos. Nunca edite manualmente arquivos gerados; altere icons/src/ e reconstrua.
7. Não modifique as dependências do usuário. As ferramentas de pré-visualização instalam em ~/.cache/icon-forge (--install); o SVGO é executado via npx se ausente. Pergunte antes de adicionar qualquer pacote ao projeto.
8. Acessível por padrão. Ícones são aria-hidden a menos que rotulados; controles apenas com ícone recebem aria-label; alvos interativos ≥44px; ícones significativos ≥3:1 de contraste.

Fluxo de trabalho

1. Detectar stack e estilo existente

node <skill>/scripts/detect.mjs .

Anote o framework, TypeScript, Tailwind, qualquer biblioteca de ícones (e seu preset de estilo), ícones SVG locais e o diretório de saída sugerido. Se existir um conjunto existente, abra 2–3 dos seus SVGs e copie os números da raiz. Caso contrário, use o padrão: grade 24, traço 2, extremidades/uniões arredondadas.

2. Planejar a lista: significado → metáfora → nome do arquivo

Escreva uma tabela curta antes de desenhar: rótulo | metáfora (o que é desenhado) | nome do arquivo | início do cookbook. Exemplo: Projects | quadro kanban | kanban.svg | kanban. Escolha metáforas convencionais (design-rules §7) e uma metáfora por significado. Nomeie os arquivos pelo objeto, em kebab-case. Pergunte ao usuário apenas se um rótulo for ambíguo e a escolha mudar o significado na interface; caso contrário, decida e declare a escolha.

3. Desenhar na grade 24

Crie icons/src/<nome>.svg com a raiz canônica (svg-code-rules.md). Para cada ícone:

• Comece pela keyline correspondente: círculo r10, quadrado 18 (x/y 3), retrato 16×20, paisagem 20×16. As keylines são linhas centrais do traço.
• Mantenha a borda externa do traço a ≥1 unidade da borda da tela. Use raio 2 em cantos grandes e 1–1.5 em cantos pequenos; mantenha lacunas com ≥2 unidades de espaço livre.
• Faça as partes se encontrarem exatamente ou mantenha uma lacuna clara. Use coordenadas inteiras para traços de 2px. Use o mínimo de elementos possível (≤6 é típico).
• Comece pela entrada mais próxima de references/glyph-cookbook.md, depois adapte. Copie a geometria de <skill>/assets/cookbook/<nome>.svg quando um glifo servir como está.
• Calcule geometria repetida (dentes, raios, pontas de estrela) com algumas linhas de JS em vez de adivinhar. Desenhe o conjunto inteiro primeiro, depois refine. A consistência é julgada lado a lado.

4. Lint

node <skill>/scripts/lint.mjs icons/src

Corrija cada ✖. Trate ⚠ gap, density, scale e bounds como problemas de design a corrigir, não como ruído. Anote cada ℹ gap e verifique na etapa 6; traços paralelos apertados (barras, linhas) borram em 16px a menos que estejam a 4 unidades de distância. Reexecute até mostrar PASS sem avisos que você não possa justificar. Flags: --grid, --padding, --mode fill, --strict, --json.

5. Otimizar

node <skill>/scripts/optimize.mjs icons/src icons/svg

Isso arredonda números, executa SVGO (instalação local ou npx svgo@4; recai para o canonicalizador embutido offline), reordena atributos raiz e imprime bytes por ícone mais o gzip total. Faça lint da saída também: node <skill>/scripts/lint.mjs icons/svg.

6. Visualizar e OLHAR, depois iterar

node <skill>/scripts/preview.mjs icons/svg --out icons/preview.png \
  --sidebar "dashboard:Dashboard,kanban:Projects" --active dashboard   # adicione --install na primeira vez se não houver mecanismo PNG

Veja os PNGs com sua ferramenta de visualização de imagens, nesta ordem:

1. icons/[email protected]: a faixa do conjunto e as simulações da barra lateral. É pequeno o suficiente para ver em detalhe total.
2. icons/[email protected]: cada ícone em cada tamanho, mais a vista de inspeção. É alto, então corte se seu visualizador reduzir a escala.
3. icons/preview.png: pixels reais 1×.

Juntos eles mostram:

• uma faixa 24/16px em claro e escuro;
• uma simulação de barra lateral com um item ativo e uma trilha recolhida;
• linhas por ícone em 16/20/24/48;
• uma vista de inspeção 4× com grade, keylines azuis e o limite vermelho de 1px de preenchimento.

Responda às perguntas de auto-revisão em design-rules §12. Correções típicas:

Você vê	Corrija
Um ícone parece mais claro/menor na faixa	amplie para sua keyline, ou adicione uma moldura/eixo (glifos abertos parecem mais leves)
Um parece mais pesado/ocupado	remova detalhes; ≤3 barras, ≤6 dentes, ≤2 linhas de texto
Um borrão onde partes se encontram em 16px	una exatamente ou abra a lacuna para ≥2 unidades
Forma encostada em um lado na vista de inspeção	recentralize, ou desloque 0.5–1 unidade para equilíbrio óptico
Metáfora pouco clara na trilha recolhida	escolha uma metáfora mais literal (etapa 2)

Repita as etapas 3–6 até que uma segunda olhada não encontre nada para corrigir. Normalmente 1–3 rodadas.

7. Gerar saída do framework

node <skill>/scripts/build.mjs icons/svg --out src/components/icons --framework react --lang ts \
  --labels "kanban:Projects,dashboard:Dashboard"

--framework react|vue|svelte|html|all; --lang ts|js; --package @app/icons escreve um package.json com sideEffects:false. A saída é um módulo por ícone passível de tree-shaking, um componente base compartilhado (size, color, strokeWidth, absoluteStrokeWidth, title, className), exportações nomeadas index e icons.json. HTML fornece sprite.svg + usage.html. Detalhes: references/output-formats.md.

Em seguida, verifique os tipos ou construa o projeto se ele tiver um script (npx tsc --noEmit, npm run build) e corrija quaisquer erros.

8. Integrar com uso acessível

Use o padrão de references/accessibility-and-usage.md:

• <nav aria-label>; aria-current="page" mais cor e fundo para o item ativo;
• ícone size-5 shrink-0 e decorativo;
• um aria-label em botões apenas com ícone; logout como um <button>;
• linhas ≥44px; cores suaves que ainda atingem 3:1.

Formato de saída

Termine com um breve relatório para o usuário:

1. Ícones: tabela rótulo → componente → metáfora e os caminhos das pastas (icons/src, icons/svg, diretório gerado).
2. Verificações: resultado do lint (erros/avisos), totais da otimização (médio B/ícone, gzip total) e o(s) caminho(s) da pré-visualização que você inspecionou, além do que você alterou após olhar.
3. Trecho de uso para o framework deles, com atributos de a11y.
4. Notas: decisões de estilo (grade/traço/preset correspondido), ícones RTL a espelhar e qualquer coisa que você não pôde verificar.

Exemplo

Usuário: "Preciso de ícones de barra lateral para Dashboard, Projects, Team, Settings no meu app Next.js + Tailwind." → detect: React (Next) + TS + Tailwind, sem biblioteca de ícones → planejar: dashboard/tiles, kanban, users, settings/gear → desenhar a partir do cookbook e adaptar → lint PASS → otimizar: 4 ícones, média ~340 B, ~0.4 KB gzip → visualizar: Projects parecia leve, então adicione barras; re-verificar → build --framework react em src/components/icons → <DashboardIcon className="size-5 shrink-0" /> no nav com aria-current.

Referências

Abra quando precisar…	Leia
escolher tamanhos, keylines, raios, lacunas, metáforas ou corrigir um problema de pré-visualização	references/design-rules.md
escrever ou depurar marcação SVG, ou entender um erro de lint	references/svg-code-rules.md
começar de geometria comprovada para um ícone de interface comum (56 glifos desenhados)	references/glyph-cookbook.md + assets/cookbook/*.svg
gerar ou adaptar manualmente saída React/Vue/Svelte/Angular/HTML, ou reduzir o tamanho do bundle	references/output-formats.md
escrever o trecho de uso: padrões de nav/barra lateral, estado ativo, rótulos, contraste, RTL	references/accessibility-and-usage.md
alterar a forma dos componentes gerados (props, nomes de classe, padrões de a11y)	templates/<framework>/, que build.mjs lê; edite lá, nunca na saída
testar alterações nesta habilidade	evals/evals.json

Lista de verificação (tudo deve ser verdadeiro antes de relatar conclusão)

• Nenhuma biblioteca de ícones adicionada; cada ícone desenhado para esta tarefa ou adaptado do cookbook.
• Estilo corresponde aos ícones existentes do projeto (ou ao preset padrão) em todo o conjunto.
• lint.mjs PASS em icons/src e icons/svg; avisos restantes justificados no relatório.
• Você visualizou o PNG de pré-visualização após sua última alteração; linhas 16px claro/escuro estão limpas; nenhum ícone é mais pesado, mais leve ou maior que seus irmãos.
• Componentes gerados por build.mjs; verificação de tipo/construção do projeto passa (quando disponível).
• Uso: ícones decorativos ocultos, controles apenas com ícone rotulados, estado ativo não apenas com cor, alvos ≥44px, contraste ≥3:1.
• Relatório inclui tamanhos (média de bytes/ícone, gzip total) e caminho da pré-visualização.