joeseesun/qiaomu-icon-generator

Qiaomu Icon Generator

Use the native QM Icon Studio CLI or Codex built-in image generation to generate multiple sets of icon candidates for websites, apps, tools, or skills, and present a choice sheet to the user.

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

When To Use

• New websites, apps, Chrome extensions, skills, or CLI tools need a favicon, app icon, or brand entry icon.
• Users want to explore multiple directions before choosing, rather than directly replacing production icons.
• The project does not yet have a complete brand system but has a name, domain, purpose, or one-line description.

Method Choice

Use the QM Icon Studio CLI method when the user wants deterministic, vector-friendly icons based on Iconify-style symbols, or when they need fast clean SVG candidates.

Use the Codex bitmap reference method when the user explicitly asks for Codex built-in image generation, wants richer iOS-style app icons, asks to reference existing icon galleries, or needs a polished raster icon direction before final export.

Workflow: QM Icon Studio CLI

Read references/qm-icon-studio-cli-method.md before using this path.

1. Read project context: README.md, package.json, site domain, existing icons in public/ or assets/, primary color CSS variables.
2. Extract a short English semantic keyword, e.g., rocket, globe, code, book, camera, music, money. Chinese requests can be passed directly to the CLI; the CLI will translate first and then search Iconify. If necessary, you can manually change to a more accurate English word.
3. Create a candidate directory inside the project, defaulting to design/icon-options/; if the project already has a design directory, use the existing structure.
4. If the current machine has the QM Icon Studio CLI, invoke:

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

If this local path does not exist, use the Codex bitmap reference method, or ask the user to provide their own icon generation CLI / icon reference library path.

5. Display contact-sheet.png or contact-sheet.svg to the user and recommend 2–3 directions best suited to the project's character.
6. If --png is skipped because Playwright is unavailable, continue with SVG output; do not misinterpret "no PNG" as generation failure. In the README or report, display contact-sheet.svg, 1–2 option-*.svg files, and explain that SVG is an editable source file.
7. Check SVG geometry: option-*.svg must be strictly square source images; if the contact sheet or README images show rounded corner previews, they must be cropped with a uniform mask, and must not display square source images covering the rounded frame with only the corner arcs visible.
8. After user confirmation, copy the selected SVG/PNG to the target project, or open QM Icon Studio to continue exporting the full platform asset package.

Workflow: Codex Bitmap Reference Method

Read references/codex-bitmap-reference-method.md before using this path.

1. Read project context: product name, purpose, domain, existing favicon/app icon, primary color, brand tone, target platforms.
2. If the user wants to reference the Icon Museum, prioritize using the available local reference library. Joe's default path is $HOME/Documents/图片参考生成icon/icon-museum/manifest.json and icons/; other machines can use a user-provided manifest/image directory. Filter 6–12 reference directions by category, color, and purpose, but do not copy original images, trademarks, app names, or unique compositions.
3. Create a candidate directory inside the project, defaulting to design/<product-slug>-icon-options/, containing prompts.md, choices.md, candidate PNGs, a choice sheet, and export sizes.
4. Use Codex built-in image_gen, generating each candidate separately. The prompt must include: square app icon, opaque background, no text/letters/numbers/watermark, centered bold symbol, readable at 32px, iOS and web favicon use.
5. Copy the built-in image generation output from $CODEX_HOME/generated_images/... to the candidate directory, naming them option-01.png through option-10.png. Keep the original generated files, do not delete them.
6. Generate contact-sheet.png and favicon-readability-sheet.png, and verify readability at 64px and 32px.
7. After user selection, run the export script to generate Web/iOS assets:

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. Update the website entry to reference the real PNG favicon/apple-touch icon; for iOS projects, update the existing sizes in .appiconset. Do not overwrite production icons before user confirmation.

Rules

• Do not overwrite existing production icons before user selection.
• Do not treat purely decorative patterns as brand icons; the graphic must be recognizable at 32px favicon size.
• Preferably generate 6–12 candidates; fewer than 4 makes comparison difficult, more than 12 makes selection tiring.
• Keep the candidate sheet as square source images; round corners and platform-specific formats (iOS, macOS, Windows) are handled during the final export stage.
• If PNG generation fails, continue with SVG candidates and explain that Playwright is unavailable.
• If external network is unavailable, add --offline to use the built-in icon library and continue generating candidates.
• SVG CLI candidate source files must be square; rounded corners should only be used as preview masks in the contact sheet/README, not baked into the source image or rendered as partial rounded borders.
• The Codex bitmap reference method must avoid text, letters, numbers, pseudo-letters, watermarks, real trademarks, and near copies of reference images.
• Final Web/iOS assets must be square, have no transparency, and feature a centered subject with safe margins; the iOS App Store master uses 1024x1024 PNG.
• To replace an existing website or app icon, first confirm that the user has selected a candidate number, then export and replace.

Output

A QM Icon Studio CLI candidate directory typically contains:

• option-01.svg through option-08.svg
• option-01.png through option-08.png, if Playwright is available
• contact-sheet.svg
• contact-sheet.png, if Playwright is available
• choices.md
• qm-icon-options.json

A Codex bitmap reference method candidate directory typically contains:

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

Public Example Assets

Public README main examples should prioritize real product cases, not just generate an icon for the repository itself. The current recommended example is Qiaomu Music:

• Codex bitmap reference method: docs/assets/examples/qiaomu-music/codex-bitmap/contact-sheet.png
• Selected final icon: docs/assets/examples/qiaomu-music/codex-bitmap/selected-option-05-ios-1024.png
• Favicon readability: docs/assets/examples/qiaomu-music/codex-bitmap/favicon-readability-sheet.png
• SVG CLI method: docs/assets/examples/qiaomu-music/svg-cli/contact-sheet.svg
• SVG CLI preview: docs/assets/examples/qiaomu-music/svg-cli/svg-cli-preview.png

When adding a new public example, include both visual proof and process notes: candidate sheet, selected asset, small-size readability test, and the command or prompt used to produce it.