Design Polish

Design Polish (Asset Generation)

Replace placeholder assets in a React frontend with AI-generated visuals that match the project's design system. Uses nano-banana-pro for image generation.

When to Use

• Frontend has data-asset placeholder attributes ready for replacement
• Frontend has existing assets that need regeneration (style refresh, audience change)
• Design system (design-system/MASTER.md) exists with style/color definitions
• Preparing for demo, launch, or stakeholder review
• Post-implementation visual polish pass

When NOT to Use

• No frontend UI exists yet
• No design system defined (create one first)
• Need hand-crafted assets (use a designer)

Inputs

Resolved automatically. Override with $ARGUMENTS if provided.

Process

1. Resolve Inputs

Read CLAUDE.md → extract from "## Project" section:
  - product_description (what the app does)
  - target_users (adults, kids, professionals, etc.)
  - product_type (e.g., recipe app, task manager, marketplace)
  If CLAUDE.md or ## Project missing → WARN: "No project context found. Image prompts will lack audience targeting."

If $ARGUMENTS provided → use as spec path
Else → search for _docs/*spec*, **/SPEC.md
Read design-system/MASTER.md → extract style name, mood, palette, aesthetic
Locate frontend source root

2. Asset Inventory

Build inventory from two sources:

From spec (if available):

From code — placeholders (always):

Scan frontend source for data-asset="{type}-{name}" attributes. Each placeholder maps to an inventory item. Flag any placeholders that do not match a spec-driven inventory item as "unmatched placeholders" in the inventory file.

From code — existing assets (always):

Scan for <img src="/assets/..."> tags in frontend source. Each existing asset is added to inventory with status existing. These will be regenerated with the current design system and project context, replacing the old files in-place.

Also scan frontend/public/assets/ directory. Files present on disk but not referenced by any component are flagged as "orphaned" in the inventory.

Write inventory to _docs/design-polish/asset-inventory.md. Each entry has status: placeholder | existing | spec-only | orphaned | minimum | enhancement.

Minimum required assets — always generate these regardless of placeholders:

If any of these already exist in inventory (from placeholders or existing assets), skip the duplicate. Otherwise add them with status minimum. These are generated even if the project has zero placeholders.

Creative enhancement scan — proactively find opportunities:

After building the base inventory, scan the frontend for visual enhancement opportunities. Think hard about what would make this product more polished and professional:

Walk through each page/route in the frontend:
  - Landing page → does it have a compelling hero? background texture? section dividers?
  - Empty states → "no items yet" screens benefit from friendly illustrations
  - Loading states → could use branded skeleton/spinner graphics
  - Error pages → 404, 500, offline — each deserves a unique illustration
  - About/info pages → team photos, product story illustrations
  - Feature sections → icons or illustrations per feature highlight
  - Onboarding → step illustrations for first-time users
  - Success confirmations → celebratory illustrations (task complete, purchase done)

For each opportunity found:
  - Add to inventory with status `enhancement`
  - Note which component/page it targets
  - Note what visual would improve the UX

The enhancement scan uses project context from CLAUDE.md (target audience, product type) to decide what's appropriate. A kids' app needs playful illustrations everywhere; a B2B dashboard needs subtle, professional graphics.

3. Generate Assets

For each asset in inventory (placeholder, existing, minimum, and enhancement status):

1. Read MASTER.md for style context
2. Read project context from Step 1 (sourced from CLAUDE.md)
3. Construct prompt:

   "{style_name} aesthetic. {mood_keywords} mood.
    Colors: {palette}.
    Generate: {asset_description}.
    Dimensions: {width}x{height}.
    Format: PNG transparent (illustrations) / JPG (photos).
    Product: {product_description}.
    Target audience: {target_users}.
    Product type: {product_type}."
   

4. Invoke nano-banana-pro via Skill tool with the prompt
5. Save to frontend/public/assets/{category}/{filename}
6. Verify file exists and has expected dimensions
7. Log to _docs/design-polish/generation-log.md
8. If fails after 2 retries → mark "manual needed", continue

4. Wire Assets to Components

Placeholders — for each data-asset placeholder found:

• Replace placeholder div with <img> tag:

  <img src="/assets/{category}/{filename}" alt="{description}" className="..." />
  

Existing assets — no component rewiring needed. The new file overwrites the old at the same path. Verify the <img> tag's alt text still matches the regenerated content; update if not.

Minimum/enhancement assets — wire into the appropriate component:

• Logo → navbar, footer, favicon, OG image
• Landing hero → landing page hero section (create section if missing)
• Enhancement illustrations → add <img> tag in the target component noted in inventory

Update index.html:

• <meta property="og:image" content="/assets/marketing/og-image.jpg" />
• <link rel="icon" href="/assets/icons/favicon-32.png" />

5. Verify

• Check for remaining placeholders: search for data-asset= in frontend source
• If E2E tests exist: run cd frontend && npx playwright test
• If E2E fails → debug and fix (up to 2 attempts)

Asset Directory Structure

frontend/public/assets/
├── heroes/
│   └── landing-hero.jpg
├── illustrations/
│   ├── empty-state.png
│   ├── error-state.png
│   └── success-state.png
├── icons/
│   ├── favicon-32.png
│   ├── favicon-192.png
│   └── favicon-512.png
└── marketing/
    └── og-image.jpg

Output

• _docs/design-polish/asset-inventory.md — what was planned
• _docs/design-polish/generation-log.md — what was generated (with prompts used)
• frontend/public/assets/ — populated with generated images
• Components updated with real <img> tags
• No data-asset= placeholders remaining
• Existing assets regenerated with current design system

Completion Checklist

• Asset inventory exists at _docs/design-polish/asset-inventory.md
• Generation log exists at _docs/design-polish/generation-log.md
• Minimum assets generated: logo, landing hero, OG image, favicon set
• All hero images generated (or marked manual)
• All illustration assets generated (or marked manual)
• All existing assets regenerated (or marked manual)
• Enhancement opportunities identified and generated
• OG image + favicon generated
• No data-asset= placeholders remaining in code
• E2E tests still pass (if they exist)

Common Mistakes

• Generating before reading MASTER.md — assets won't match the design system. Always extract style context first.
• Hardcoding asset paths — use the {category}/{filename} convention so paths stay consistent.
• Skipping failed assets — mark them "manual needed" in the log, don't silently skip.
• Only generating what's explicitly placeholdered — the skill should proactively enhance the product. Few placeholders ≠ few assets needed. Walk every page and think about what visuals would elevate the experience.
• Ignoring audience context — a kids' app needs playful, colorful illustrations; a finance dashboard needs subtle, professional graphics. Always read CLAUDE.md for target audience before generating.