logo-maker

@rules/logo-design-workflow.md @references/transparent-png-requirements.md

Logo Maker

Create logo assets that are distinctive, simple, scalable, and ready to place on arbitrary backgrounds. This skill turns brand/product requirements into a reviewed English JSON logo brief, generates or edits logo candidates, and ships only stable transparent-background PNG outputs with a local preview and archive evidence.

<routing_rule>

Use this skill when the user wants Codex to create, iterate, adapt, or prepare a logo-like raster asset, including:

brand marks, product marks, app logos, favicons, profile images, launch badges, wordmarks, monograms, and symbol marks
logo variants for dark/light surfaces, square crops, social avatars, app icons, or marketing placements
transparent-background PNG logo exports from a generated or edited image
logo generation that should not look like a generic AI emblem or stock icon

Prefer this skill over image-maker when the primary deliverable is a logo/mark rather than a scene, photo, illustration, or marketing image.

Do not use this skill when:

the user needs a hand-authored vector/SVG logo as the primary deliverable
the request is only brand strategy, naming, or critique with no logo asset output
the task is to edit existing HTML/CSS/SVG assets deterministically
the user explicitly asks for non-transparent JPG/WebP output only

</routing_rule>

<execution_contract>

Codex only: use Codex image generation/editing capability or the project-approved image path.
Model default: use gpt-image-2 when available and consistent with the project image-maker contract, unless the user explicitly changes the image model/path in a later instruction.
Prompt pipeline requirement: do not generate directly from raw user wording. Always pass through user requirements → English JSON logo brief → brief review → Codex transparent-background PNG generation/edit → visual transparency check.
Transparent PNG hard requirement: final deliverables must be .png files generated/exported by the Codex image path with a native transparent background. A white, black, checkerboard, solid color, or chroma-key background is not acceptable as the final logo asset.
Native transparency requirement: request transparent output in the image generation settings and in the model-facing prompt. Do not rely on Node scripts, chroma-key cleanup, or background-removal postprocessing as the first path. If a result comes back RGB or with a filled background, refine the brief/prompt/settings and regenerate before accepting it.
Success ladder requirement: keep looping until a verified transparent PNG exists. Try native transparent Codex generation first; if repeated native attempts still return RGB/filled backgrounds and the logo can be represented as a simple geometric mark, use the deterministic RGBA fallback renderer, then disclose the fallback path in prompt.json and the final report.
Archive requirement: every completed logo job must create .hypercore/logo-maker/<topic-slug>/, save the reviewed brief as prompt.json, copy final logo files as logo1.png, logo2.png, logo3.png, ..., create preview.html, and verify all files before completion.
Preview requirement: when the user asks to see the result, open the generated preview.html in a fresh Google Chrome window/tab with the local helper. If Chrome cannot open, report the preview path and exact command.

</execution_contract>

<trigger_examples>

Positive examples:

"Create a new HyperB product logo as a transparent background PNG."
"Generate a simple logo that can be used like an app icon and open a preview in Chrome."
"Based on this brand description, create 3 monogram logo candidates that don't look AI-generated."
"Clean up the existing logo image into a transparent PNG and also create preview.html."

Negative examples:

"Just propose a logo strategy. Don't create images." → strategy/advice only.
"Refactor this SVG path to be simpler." → deterministic SVG edit, not logo raster generation.

Boundary example:

"Create a brand image." If the desired output is a logo/mark with transparent PNG deliverables, use this skill; if it is a hero visual or campaign scene, use image-maker.

</trigger_examples>

Clarify by inference first. Infer brand name, product/domain, audience, tone, symbol/wordmark needs, usage surface, aspect ratio, color constraints, and whether text must appear. Ask only if a missing detail would make the logo materially wrong.
Define the logo job. Classify as new logo, logo variant, transparent export, edit existing logo, favicon/app icon, or batch concepts.
Load logo rules. Use rules/logo-design-workflow.md for logo-specific simplicity, scalability, silhouette, typography, and anti-generic checks.
Write an English JSON logo brief. Use the schema below. Keep prompt-facing creative values in English while preserving exact brand/name text verbatim in logo_prompt.text.verbatim.
Review the brief before generation. Parse the JSON, check required fields, verify a coherent mark type, confirm format: png and background: transparent, and ensure text/brand constraints are inspectable.
Generate/edit native transparent PNG candidates. Use the reviewed generation_prompt as source of truth and request transparent-background PNG output directly in the Codex image generation path. The prompt must say the logo is an isolated mark on transparent background, with no background fill, no white square, no checkerboard pattern, no mockup, and no scene.
Inspect alpha and iterate. Run file plus an alpha-pixel check on the returned PNG. If it is RGB, fully opaque RGBA, filled-background, checkerboard, chroma-key, mockup scene, or non-PNG, mark the attempt failed, refine the JSON brief/prompt/settings, and regenerate.
Fallback only after native attempts fail. If native transparent generation repeatedly fails but the requested logo is a simple geometric mark, render a deterministic transparent RGBA fallback with scripts/render-simple-logo-rgba.mjs, then archive and disclose that this fallback produced the final transparent PNG. Do not use this fallback to hide a failed photoreal/logo-generation result; it is only for clean geometric logo assets.
Validate as a logo. Check silhouette at small sizes, legibility, uniqueness, brand fit, geometry, text accuracy, edge cleanliness, and whether it works on light/dark/checkerboard backgrounds.
Archive deliberately. Copy final verified transparent PNG outputs into .hypercore/logo-maker/<topic-slug>/ as logo1.png, logo2.png, ... and write the reviewed brief as prompt.json. The optional archive helper may be used for file copying, alpha verification, and preview.
Create/show preview. Create preview.html from assets/logo-preview-template.html or the optional archive helper. Use a fresh Chrome window when the user asked to see the result.
Verify completion. List the archive directory and confirm prompt.json, preview.html, and every expected logoN.png exists. Require alpha evidence such as RGBA, color_type: 6, and at least one transparent pixel. Visually check the logo over checkerboard, white, black, and brand-color surfaces.
Report evidence. Include archive path, preview path, whether Chrome opened, generation/fallback path used, alpha verification output, final brief or concise summary, and remaining risks such as exact text rendering or trademark similarity.

<archive_helper>

The archive helper is optional but recommended for verification and preview. Use it after a final PNG exists from either native Codex transparent generation or the explicit deterministic fallback:

node skills/logo-maker/scripts/archive-logo-assets.mjs \
  --topic "descriptive logo topic" \
  --prompt /path/to/reviewed-logo-brief.json \
  --logos /path/to/logo-candidate-1.png /path/to/logo-candidate-2.png \
  --open-preview

The helper copies existing PNG files and writes preview/archive files:

.hypercore/logo-maker/<topic-slug>/prompt.json
.hypercore/logo-maker/<topic-slug>/logo1.png, logo2.png, ...
.hypercore/logo-maker/<topic-slug>/preview.html

Use --no-preview only for non-visual automation where a browser preview is unnecessary. If you do not use the helper, manually create equivalent archive, alpha-verification, and preview evidence.

</archive_helper>

<fallback_renderer>

Use the deterministic fallback only after native transparent generation attempts fail and the requested logo can be represented as a simple geometric mark:

node skills/logo-maker/scripts/render-simple-logo-rgba.mjs \
  --out .hypercore/tmp-logo-final/logo.png \
  --size 1024

Then archive that PNG with scripts/archive-logo-assets.mjs. The fallback always writes a real RGBA PNG with transparent pixels, but it is intentionally limited to clean geometric marks. Record generation_settings.api_path: "deterministic_rgba_fallback" in prompt.json when this path is used.

</fallback_renderer>

<json_logo_brief>

The logo brief must be valid JSON: double-quoted keys/strings, no comments, no trailing commas.

{
  "schema_version": "1.0",
  "model": "gpt-image-2",
  "task": "new logo",
  "use_case": "brand mark",
  "generation_settings": {
    "api_path": "image_api",
    "size": "1024x1024",
    "quality": "medium",
    "format": "png",
    "background": "transparent",
    "transparent_background": true,
    "destination_intent": "project-bound",
    "archive_dir": ".hypercore/logo-maker/descriptive-logo-topic",
    "save_paths": [
      ".hypercore/logo-maker/descriptive-logo-topic/logo1.png"
    ],
    "prompt_path": ".hypercore/logo-maker/descriptive-logo-topic/prompt.json",
    "preview_html_path": ".hypercore/logo-maker/descriptive-logo-topic/preview.html"
  },
  "logo_archive": {
    "topic": "Human-readable topic for this logo job.",
    "topic_slug": "descriptive-logo-topic",
    "prompt_path": ".hypercore/logo-maker/descriptive-logo-topic/prompt.json",
    "logo_paths": [
      ".hypercore/logo-maker/descriptive-logo-topic/logo1.png"
    ],
    "preview_path": ".hypercore/logo-maker/descriptive-logo-topic/preview.html",
    "transparent_png_required": true
  },
  "user_requirements_summary": "English summary of the user's requirements and inferred constraints.",
  "assumptions": [
    "Assumption made because the user did not specify brand tone, symbol, color, usage surface, or text constraints."
  ],
  "source_inputs": [
    {
      "id": "reference_1",
      "type": "local_file | url | generated_reference | none",
      "role": "existing_logo | brand_reference | style_reference | competitor_reference | color_reference",
      "path_or_url": "",
      "must_preserve": [
        "Brand name, symbol idea, color, geometry, or typography invariant from this source."
      ]
    }
  ],
  "brand_context": {
    "name": "Brand or product name.",
    "domain": "What the brand/product does.",
    "audience": "Who should recognize or trust it.",
    "personality": ["clear", "modern", "credible"]
  },
  "placement": {
    "primary_surface": "website header | app icon | favicon | social avatar | deck | product UI",
    "safe_zone": "Centered mark with padding; must remain readable at small sizes.",
    "backgrounds_to_test": ["transparent checkerboard", "white", "black", "brand color"]
  },
  "logo_prompt": {
    "mark_type": "symbol | wordmark | combination mark | monogram | badge | app icon",
    "primary_request": "The logo to create, in English.",
    "symbol_concept": "One clear visual metaphor, not a collage of unrelated symbols.",
    "composition": "Centered, balanced, flat logo asset on transparent background; isolated mark only, no background layer.",
    "style_direction": "Minimal, scalable, vector-like raster output; no scene or mockup.",
    "color_palette": "Exact or inferred colors and contrast notes.",
    "typography": "Letterform style if text is included; avoid unreadable microtext.",
    "text": {
      "verbatim": "",
      "placement": "",
      "text_risk": "none | low | medium | high"
    },
    "must_keep": [
      "Required brand name, geometry, colors, symbol, or reference invariants."
    ],
    "avoid": [
      "background fill",
      "white box",
      "checkerboard pattern baked into the image",
      "chroma-key background",
      "mockup scene",
      "drop shadow as background crutch",
      "generic globe/rocket/leaf unless requested",
      "AI emblem clutter",
      "warped text",
      "watermark",
      "trademark-confusing similarity"
    ]
  },
  "review_checklist": {
    "valid_json": true,
    "schema_fields_complete": true,
    "transparent_png_required": true,
    "native_transparent_generation_requested": true,
    "single_clear_logo_concept": true,
    "works_without_background": true,
    "small_size_legibility_considered": true,
    "text_constraints_are_verbatim_and_inspectable": true,
    "trademark_similarity_risk_checked": true
  },
  "review_notes": {
    "prompt_strengths": [
      "Why this brief should produce a usable logo."
    ],
    "unresolved_risks": [
      "Known risk such as exact text, trademark similarity, brand ambiguity, or small-size legibility."
    ],
    "iteration_strategy_if_failed": "Change only one dimension next: symbol, geometry, typography, color, transparency, or crop."
  },
  "generation_prompt": "A concise English prompt assembled from logo_prompt and constraints after review. Explicitly request a native transparent-background PNG logo asset with no background fill, no white square, no checkerboard, no mockup, and no scene."
}

</json_logo_brief>

Before completion, pass all checks:

The request was correctly routed as logo/mark work rather than a general image scene.
User requirements were converted into a valid English JSON logo brief before generation/editing.
The brief explicitly requires format: png, background: transparent, and native transparent Codex image generation.
The model-facing prompt explicitly asks for an isolated transparent-background PNG logo with no background fill, white box, checkerboard, chroma-key, mockup, or scene.
Final files are PNGs named logo1.png, logo2.png, ... under .hypercore/logo-maker/<topic-slug>/.
The logo works on transparent checkerboard, white, black, and expected brand backgrounds.
The logo remains recognizable at small sizes or known small-size risks are reported.
Text, if present, is inspected for spelling, distortion, and legibility.
Trademark/confusing-similarity risk was considered for brand marks.
The archive contains prompt.json, preview.html, and every expected logoN.png.
If the user asked to see the result, the preview opened in a fresh Chrome window/tab or the failure/open command was reported.
Final response includes saved paths, preview path, generation path/model, and remaining risks.

<reference_map>

rules/logo-design-workflow.md: practical rules for simple, scalable, brand-usable logo direction.
references/transparent-png-requirements.md: transparent PNG prompt/settings contract and visual validation notes.
scripts/archive-logo-assets.mjs: archive/preview helper that verifies final PNG alpha evidence.
scripts/render-simple-logo-rgba.mjs: deterministic fallback renderer for simple geometric marks when native transparent generation repeatedly returns RGB/filled-background images.
assets/logo-preview-template.html: local preview template rendered into .hypercore/logo-maker/<topic-slug>/preview.html.

</reference_map>

About this skill