joeseesun/qiaomu-icon-generator

Qiaomu Icon Generator

Use o CLI do QM Icon Studio local ou a capacidade de geração de imagens integrada do Codex para gerar vários conjuntos de candidatos a ícones para sites, aplicativos, ferramentas ou skills, e apresente ao usuário uma folha de seleção.

Copyright (c) 向阳乔木 X: https://x.com/vista8 GitHub: https://github.com/joeseesun/

Quando Usar

• Novo site, aplicativo, plugin Chrome, skill ou ferramenta CLI precisa de favicon, ícone de aplicativo ou ícone de entrada da marca.
• O usuário quer ver múltiplas direções antes de escolher, em vez de substituir diretamente o ícone de produção.
• O projeto ainda não possui um sistema de marca completo, mas já tem nome, domínio, propósito ou uma descrição curta.

Escolha do Método

Use o método CLI do QM Icon Studio quando o usuário desejar ícones determinísticos e amigáveis a vetores, baseados em símbolos no estilo Iconify, ou quando precisar de candidatos SVG limpos e rápidos.

Use o método de referência bitmap do Codex quando o usuário solicitar explicitamente a geração de imagens integrada do Codex, desejar ícones de aplicativo estilo iOS mais ricos, pedir para consultar galerias de ícones existentes ou precisar de uma direção de ícone rasterizada polida antes da exportação final.

Fluxo de Trabalho: CLI do QM Icon Studio

Leia references/qm-icon-studio-cli-method.md antes de usar este caminho.

1. Leia o contexto do projeto: README.md, package.json, domínio do site, ícones existentes em public/ ou assets/, variáveis CSS de cor principal.
2. Extraia uma palavra-chave semântica curta em inglês, por exemplo, rocket, globe, code, book, camera, music, money. Requisitos em chinês podem ser passados diretamente para o CLI; o CLI primeiro traduz e depois pesquisa no Iconify; se necessário, você pode manualmente alterar para uma palavra em inglês mais precisa.
3. Crie um diretório de candidatos dentro do projeto, por padrão design/icon-options/; se o projeto já tiver um diretório de design, use a estrutura existente.
4. Se a máquina atual tiver o CLI do QM Icon Studio, execute:

node "$HOME/Documents/qm-icon-studio/cli/qm-icon-options.mjs" \
  --name "Nome do Produto" \
  --query "rocket" \
  --count 8 \
  --out design/icon-options \
  --png

Se este caminho local não existir, use o método de referência bitmap do Codex, ou peça ao usuário para fornecer seu próprio CLI de geração de ícones / caminho da biblioteca de referência.

5. Mostre contact-sheet.png ou contact-sheet.svg ao usuário e recomende 2 a 3 direções que melhor se adequam ao estilo do projeto.
6. Se --png for ignorado porque o Playwright não está disponível, continue usando a saída SVG; não interprete erroneamente a "falta de PNG" como falha de geração. No README ou relatório, exiba contact-sheet.svg, 1 a 2 option-*.svg e explique que SVGs são arquivos fonte editáveis.
7. Verifique a geometria do SVG: option-*.svg deve ser uma fonte quadrada rigorosa; se a folha de contato ou imagem do README mostrar pré-visualização arredondada, ela deve ser cortada com uma máscara uniforme, sem aparecer cantos arredondados onde a fonte quadrada é coberta por uma moldura redonda.
8. Após a confirmação do usuário, copie o SVG/PNG selecionado para o projeto de destino, ou abra o QM Icon Studio para continuar exportando o pacote completo de ativos da plataforma.

Fluxo de Trabalho: Método de Referência Bitmap do Codex

Leia references/codex-bitmap-reference-method.md antes de usar este caminho.

1. Leia o contexto do projeto: nome do produto, propósito, domínio, favicon/ícone de aplicativo existente, cor principal, tom da marca, plataforma de destino.
2. Se o usuário quiser consultar o Museu de Ícones (Icon Museum), priorize o uso da biblioteca de referência local disponível. O caminho padrão de Joe é $HOME/Documents/图片参考生成icon/icon-museum/manifest.json e icons/; outras máquinas podem usar o manifesto / diretório de imagens fornecido pelo usuário. Filtre de 6 a 12 direções de referência por categoria, cor e propósito, mas não copie a imagem original, logotipo, nome do aplicativo ou composição única.
3. Crie um diretório de candidatos dentro do projeto, por padrão design/<slug-do-produto>-icon-options/, contendo prompts.md, choices.md, PNGs candidatos, folha de seleção e tamanhos de exportação.
4. Use o image_gen integrado do Codex, gerando cada candidato separadamente. O prompt deve incluir: square app icon, opaque background, no text/letters/numbers/watermark, centered bold symbol, readable at 32px, iOS and web favicon use.
5. Copie a saída da geração de imagem integrada de $CODEX_HOME/generated_images/... para o diretório de candidatos, nomeando como option-01.png a option-10.png. Mantenha os arquivos gerados originais, não os exclua.
6. Gere contact-sheet.png e favicon-readability-sheet.png e verifique se ainda são reconhecíveis em 64px e 32px.
7. Após a seleção do usuário, execute o script de exportação para gerar ativos Web/iOS:

python3 scripts/export_selected_icon.py \
  --source design/qiaomu-music-icon-options/ios-1024/option-05.png \
  --web-out public/icons \
  --web-prefix qiaomu-music-icon \
  --appiconset ios/QiaomuMusic/QiaomuMusic/Assets.xcassets/AppIcon.appiconset

8. Atualize a entrada do site para referenciar o favicon PNG real / apple-touch icon; para projetos iOS, atualize os tamanhos existentes no .appiconset. Não substitua ícones de produção antes da confirmação do usuário.

Regras

• Não substitua ícones de produção existentes antes da escolha do usuário.
• Não considere padrões puramente decorativos como ícones de marca; o gráfico deve ser identificável em um favicon de 32px.
• Gere preferencialmente de 6 a 12 candidatos; menos de 4 dificulta a comparação, mais de 12 torna a escolha cansativa.
• Mantenha a fonte quadrada por padrão nos candidatos; arredondamentos e formatos específicos de plataforma (iOS, macOS, Windows) são tratados apenas na fase de exportação final.
• Se a renderização PNG falhar, continue com candidatos SVG e explique que o Playwright não está disponível.
• Se a rede externa não estiver disponível, use --offline para continuar gerando candidatos com a biblioteca de ícones interna.
• Os arquivos fonte SVG do CLI devem ser quadrados; cantos arredondados são apenas uma máscara de pré-visualização na folha de contato / README, não devem ser gravados na fonte nem feitos como borda arredondada incompleta.
• O método de referência bitmap do Codex deve evitar texto, letras, números, pseudo-texto, marcas d'água, logotipos reais e cópia aproximada de imagens de referência.
• Os ativos finais Web/iOS devem ser quadrados, sem canal alfa, com símbolo centralizado e margem de segurança; o mestre da App Store iOS usa PNG 1024x1024.
• Se for substituir ícones de site ou aplicativo existentes, primeiro confirme que o usuário selecionou o número do candidato, depois exporte e substitua.

Saída

O diretório de candidatos do CLI do QM Icon Studio geralmente contém:

• option-01.svg a option-08.svg
• option-01.png a option-08.png, se o Playwright estiver disponível
• contact-sheet.svg
• contact-sheet.png, se o Playwright estiver disponível
• choices.md
• qm-icon-options.json

O diretório de candidatos do método de referência bitmap do Codex geralmente contém:

• option-01.png a option-10.png
• ios-1024/
• web-180/
• web-64/
• web-32/
• contact-sheet.png
• favicon-readability-sheet.png
• prompts.md
• choices.md

Ativos de Exemplo Público

O exemplo principal do README público deve priorizar casos de uso reais de produtos, em vez de gerar apenas um ícone para o próprio repositório. O exemplo recomendado atualmente é o site Qiaomu Music:

• Método de referência bitmap do Codex: docs/assets/examples/qiaomu-music/codex-bitmap/contact-sheet.png
• Ícone final selecionado: docs/assets/examples/qiaomu-music/codex-bitmap/selected-option-05-ios-1024.png
• Teste de legibilidade do favicon: docs/assets/examples/qiaomu-music/codex-bitmap/favicon-readability-sheet.png
• Método SVG CLI: docs/assets/examples/qiaomu-music/svg-cli/contact-sheet.svg
• Pré-visualização SVG CLI: docs/assets/examples/qiaomu-music/svg-cli/svg-cli-preview.png

Ao adicionar um novo exemplo público, inclua tanto a prova visual quanto as notas do processo: folha de candidatos, ativo selecionado, teste de legibilidade em tamanho pequeno e o comando ou prompt usado para produzi-lo.