svg-icon-gen

SVG Icon Generation Skill

Generate, edit, convert, animate, and optimize production-quality SVG icons from scratch. Icons are built from learned geometric patterns — not copied from any library.

Before writing any icon, read references/icon-patterns.md to learn the construction patterns. That file is the foundation — it teaches how icons are geometrically built so you can create ANY icon from scratch.

---

Phase 1: Understand What the User Needs

Every icon request falls into one of these scenarios. Identify which one before doing anything:

Scenario A — "Make me an icon of X"

The user describes what they want in words. Proceed to Phase 2.

Scenario B — "Convert this image/logo to SVG"

The user uploads an image (logo, boceto, screenshot). This requires PRECISION — logos are brand assets where fidelity matters more than simplification. Follow these steps strictly:

Step 1 — Describe before you trace: Before writing ANY SVG code, describe in text EXACTLY what you see. Be specific:

• What shapes compose the image? (diagonals, curves, circles, rectangles)
• What are the proportions? (aspect ratio, relative sizes of elements)
• What are the endpoints like? (rounded/capsule, flat/square, pointed/sharp)
• Are there overlapping elements? Which is in front?
• What colors and gradients? (direction, color stops, opacity)
• What angles? (estimate degrees — 45°, 60°, etc.)
• What's the negative space like?
• Where do shapes meet or cross? Look carefully at junctions — do strokes meet at a needle-sharp point, do they overlap/cross with thickness visible, or do they blend into a smooth curve?

CRITICAL — Do NOT assume shapes based on what you think the letter/icon "should" look like. Describe ONLY what you actually see in the image. Common mistakes:

• Assuming an "A" shape has a sharp pointed peak when it actually has rounded or blunt top where the strokes overlap
• Assuming strokes taper to zero at meeting points when they actually maintain their width
• Assuming symmetry when the image is actually asymmetric
• Describing what you expect to see instead of what is actually there

How to verify your description: After describing, ask yourself: "If someone who has never seen this image read my description, could they draw it accurately?" If not, add more detail about the specific parts that are unusual or could be misinterpreted.

Example: "I see two thick diagonal strokes forming an inverted V (like a letter A without the crossbar). At the top, the strokes overlap and cross each other — they do NOT taper to a sharp point; instead each stroke maintains its full width through the crossing zone, and the right stroke passes in front. Each stroke is ~3-4 units wide throughout its length. The bottom ends are rounded like capsules (semicircular). The left stroke has a lighter blue gradient, the right stroke is darker blue."

Step 2 — Map to a coordinate grid: Choose an appropriate viewBox (24x24 for icons, larger for detailed logos) and map key points:

• "Peak of the A is at approximately (12, 2)"
• "Left stroke bottom-center is at approximately (5, 21)"
• "Right stroke bottom-center is at approximately (19, 21)"
• "Stroke width is approximately 3 units"
• "The overlap zone spans from approximately y=8 to y=14"

Step 3 — Construct path by path: Build each shape individually. For each path:

1. Start with the outline/silhouette — trace the outer edge
2. Use the correct command for each segment: L for straight edges, A for rounded caps, C for organic curves
3. Close with Z
4. For rounded/capsule ends: use arc commands A radius radius 0 0 1 x y to create semicircular caps
5. Verify: does this path match what I described in Step 1?

Step 4 — Preserve colors and gradients: For logos, NEVER use currentColor. Instead:

• Extract the exact colors from the image (or approximate hex values)
• If there are gradients, define <linearGradient> or <radialGradient> in <defs>
• Match the gradient direction (top-left to bottom-right, vertical, horizontal, etc.)
• If elements overlap with different colors/gradients, use separate <path> elements with their own fills
• See the Gradients section for templates

Step 5 — Mental comparison before delivering: Before showing the result, mentally compare point by point:

• Do the endpoints match? (rounded vs pointed vs flat)
• Are the proportions right? (not too narrow, not too wide)
• Does the overlap look correct?
• Are the colors/gradients faithful?
• Does the overall silhouette match the original?

If something doesn't match, fix it BEFORE showing to the user. Then ask: "Does this capture your logo accurately? Want me to adjust proportions, colors, or any details?"

Scenario C — "Edit/modify this existing SVG"

The user has an SVG and wants changes. See Editing Existing SVGs.

Scenario D — "I need icons for my project" (set/batch)

The user needs multiple icons. See Icon Sets & Consistency.

Scenario E — Proactive suggestion

You notice a UI the user is building could benefit from icons (buttons without icons, empty nav items, plain text links that could use visual anchors). Suggest it:

• "I notice your sidebar navigation is text-only — would you like me to generate icons for each item? It would improve scannability."
• Only suggest, never add icons without asking.
• If suggesting, propose which specific icons and where.

---

Phase 2: Gather Context Before Generating

Do NOT generate an icon until you know these three things:

2.1 — Output Format

Ask or infer: how does the user want the icon delivered?

• Inline SVG: <svg><path d="..."/></svg> — for HTML, direct embedding
• React component: const Icon = ({ size, color, className }) => (...) — for JSX projects
• Both: provide both formats

Adaptive rule: If the user's code is visible in the conversation and uses JSX → deliver React. If it's HTML → deliver inline SVG. If unclear → ask. If the user has expressed a preference before (like <svg><path/></svg>), remember and use that.

2.2 — Visual Style of the UI

Investigate before generating. Follow this decision tree:

If the user's UI code is visible → analyze it directly:

• border-radius values → sharp (geometric icons) vs rounded (friendly icons)
• Font weights → light fonts = thinner strokes, bold = heavier
• Color palette → extract primary, secondary, neutral tones
• Spacing/density → tight = compact icons, spacious = larger icons with breathing room
• Existing icons → match their style exactly

If no UI code is visible → ask with clear options:

• "What's the visual vibe of your project?" → Minimal/clean, Bold/corporate, Playful/rounded, Technical/sharp, E-commerce, Elegant/luxury
• "What's your color scheme?" → ask for hex codes or a screenshot

If the user doesn't know → help them discover it:

• Ask what the app/site does and who it's for
• Map the domain to a style: event photography → elegant/warm; SaaS dashboard → clean/neutral; kids app → rounded/colorful; dev tools → sharp/geometric
• Suggest and let them confirm: "For a quinceañera photography site, I'd recommend elegant thin-stroke icons with soft curves — does that sound right?"

2.3 — Icon Style

Style	Best for	Look
Outline	Nav bars, toolbars, settings, minimal UIs	Stroke-based, no fill, clean
Filled	Active states, CTAs, mobile tap targets, emphasis	Solid shapes, high contrast
Duotone	Dashboards, feature sections, marketing, empty states	Two-tone depth, visual hierarchy

If not specified → recommend based on UI context. Common pattern: outline for inactive states + filled for active.

2.4 — Dark Mode (ask only if relevant)

If the project seems to have or could have a dark theme, ask:

• "Does your project support dark mode? I can make the icons adapt automatically with currentColor, or create specific variants if needed."

If the user says yes → ensure icons use currentColor so they inherit the text color of whatever theme is active. For duotone icons, ensure the opacity layer has enough contrast on both light and dark backgrounds.

If the user doesn't know or doesn't care → default to currentColor (works for both).

---

Phase 3: Generate the Icon

Construction Rules

Read references/icon-patterns.md before generating. Then apply these rules:

ViewBox & Sizing:

• 16×16 → tiny inline (badges, tags, inside text)
• 20×20 → compact (form fields, small buttons)
• 24×24 → standard UI icons — default
• 32×32 → feature icons, onboarding, empty states
• Always: viewBox="0 0 {size} {size}", never hardcode width/height in the SVG

Path Construction:

1. Grid-align anchor points to whole pixels or .5 increments (avoids blur)
2. ONE stroke width across the entire icon set (1.5 = light, 2 = standard, 2.5 = bold)
3. Corner radius should match the UI's border-radius feel
4. Optical centering — play triangles shift right ~1px, circles may need slight adjustments
5. Simplicity — great icons use 3-8 path commands; more than 15 = simplify
6. Breathing room — icon content fills ~80% of viewBox, ~10% padding on each edge
7. Use relative commands (lowercase) when they produce shorter paths

Pixel Hinting: At small sizes (16px), strokes that land between pixels look blurry. Rules:

• For even stroke widths (2px): align paths to whole pixel coordinates
• For odd stroke widths (1px, 3px): align to .5 pixel coordinates
• If the user requests a 16px icon, explicitly verify grid alignment
• If an icon designed for 24px is requested at 16px, warn: "This icon has detail that may blur at 16px — I can simplify a version specifically for that size."

Output Templates

Outline (inline SVG):

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
  <path d="..."/>
</svg>

Filled (inline SVG):

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
  <path d="..." fill-rule="evenodd" clip-rule="evenodd"/>
</svg>

Duotone (inline SVG):

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true">
  <path d="..." fill="currentColor" opacity="0.2"/>
  <path d="..." fill="currentColor"/>
</svg>

React Component:

const IconName = ({ size = 24, color = "currentColor", className = "", ...props }) => (
  <svg
    xmlns="http://www.w3.org/2000/svg"
    viewBox="0 0 24 24"
    width={size}
    height={size}
    fill="none"
    stroke={color}
    strokeWidth={2}
    strokeLinecap="round"
    strokeLinejoin="round"
    className={className}
    aria-hidden="true"
    {...props}
  >
    <path d="..." />
  </svg>
);
export default IconName;

Adjust fill/stroke attributes per style. Always spread ...props. Always provide defaults.

Gradients

Use gradients for logos, brand icons, and any conversion where the original has color transitions. NEVER default to currentColor for logos.

Linear Gradient template:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" aria-hidden="true">
  <defs>
    <linearGradient id="grad-1" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0%" stop-color="#LIGHTER_COLOR"/>
      <stop offset="100%" stop-color="#DARKER_COLOR"/>
    </linearGradient>
  </defs>
  <path d="..." fill="url(#grad-1)"/>
</svg>

Radial Gradient template:

<defs>
  <radialGradient id="grad-r" cx="50%" cy="50%" r="50%">
    <stop offset="0%" stop-color="#CENTER_COLOR"/>
    <stop offset="100%" stop-color="#EDGE_COLOR"/>
  </radialGradient>
</defs>

Gradient direction mapping:

• Top-left to bottom-right: x1="0" y1="0" x2="1" y2="1"
• Top to bottom: x1="0" y1="0" x2="0" y2="1"
• Left to right: x1="0" y1="0" x2="1" y2="0"
• Adjust x1/y1/x2/y2 for custom angles

When to use gradients vs currentColor:

• Logo/brand conversion → always gradients (or solid brand colors)
• UI icons for an app → currentColor (adapts to theme)
• Decorative/marketing icons → gradients if the design calls for it

Multiple gradient elements: When an image has different colored sections (e.g., a logo with a lighter left half and darker right half), use separate <path> elements each with their own gradient defined in <defs>. Use unique IDs for each gradient.

Accessibility

Decorative (icon next to text label):

aria-hidden="true" focusable="false"

Meaningful (icon IS the label, like an icon-only button):

role="img" aria-label="Close dialog" focusable="false"
<title>Close dialog</title>

Rule: if there's text next to it → decorative. If it stands alone → meaningful. When in doubt, ask.

---

Editing Existing SVGs

When the user provides an existing SVG and wants modifications:

Style Conversion

• Outline → Filled: Replace stroke paths with filled shapes. Expand strokes to solid shapes, merge overlapping areas, use fill-rule="evenodd" for paths with holes.
• Filled → Outline: Extract shape edges as stroke paths. Set fill="none", add stroke="currentColor" with appropriate width.
• Any → Duotone: Identify background/container shape (low opacity layer) and foreground detail (full opacity layer).

Property Modifications

• Stroke weight: Adjust stroke-width and may need to re-scale the icon if thicker strokes overflow the viewBox
• Corner rounding: Add arc commands (A) to sharp corners, or adjust existing arc radii
• Simplification: Remove decorative details, merge paths, reduce command count
• Resize adaptation: When changing viewBox size, don't just scale — re-evaluate if details survive at the new size

Always show before/after and confirm with the user.

---

Icon Sets & Consistency

When generating multiple icons (for a sidebar, toolbar, feature grid, etc.):

Consistency Rules

Define these ONCE for the entire set and apply to every icon:

• Stroke width: Same value for all (e.g., 2px)
• Corner style: Same radius/sharpness for all
• ViewBox: Same size for all
• Visual weight: All icons should feel the same "heaviness" — a simple checkmark and a complex calendar should occupy similar visual space
• Style: All outline, all filled, or all duotone — never mix within a set

Maintaining Consistency Across Conversations

When generating more icons later for the same project:

• Reference the style rules established earlier: "Following the same style as before — 24×24, outline, 2px stroke, round caps, round joins"
• If the user hasn't specified, ask: "Should these match the icons we created before?"
• Document the style spec at the top of the set so it's easy to reference

Batch Generation

When asked for a full set:

1. Confirm the list of icons needed
2. Establish the shared style rules
3. Generate all icons
4. Present them together so the user can evaluate consistency
5. Adjust as a group, not individually

---

Micro-Animations

For basic SVG animations (fade, rotate, pulse, draw-in):

CSS-Based (preferred for simplicity)

/* Spin — for loaders */
@keyframes spin { to { transform: rotate(360deg); } }
.icon-spin { animation: spin 1s linear infinite; }

/* Pulse — for notifications */
@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
.icon-pulse { animation: pulse 2s ease-in-out infinite; }

/* Fade in */
@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
.icon-fade { animation: fadeIn 0.3s ease-in; }

SVG Native (for draw-in effects)

<path d="..." stroke-dasharray="100" stroke-dashoffset="100">
  <animate attributeName="stroke-dashoffset" to="0" dur="0.6s" fill="freeze"/>
</path>

Only offer animations when:

• The user asks for them
• The context clearly benefits (loading states, success confirmations, interactive toggles)

Keep animations subtle — they enhance, never distract.

---

Optimization

SVG paths can be unnecessarily verbose. Apply optimization intelligently:

When to Optimize

• Path has redundant commands (multiple consecutive L that could be a single polyline)
• Decimal precision beyond 2 places (3.14159 → 3.14)
• Unused attributes or groups
• Paths that could use relative commands for shorter strings

When NOT to Optimize

• If simplification would visually alter the icon (rounded curves becoming angular)
• If the path is already short (<100 characters)
• If the icon is a brand/logo conversion where fidelity matters
• CRITICAL for logos: For any Scenario B conversion (image/logo to SVG), prioritize FIDELITY over optimization. Do not simplify paths, reduce arc precision, or merge shapes unless the user explicitly asks for simplification. A logo that's 200 characters but pixel-perfect is better than a 100-character approximation.

Decision Rule

Before optimizing, evaluate: "Will this change be visible at the rendered size?" If yes → don't optimize, or ask the user first. If no → optimize silently.

If unsure, ask: "I can optimize this path to be ~40% shorter, but there might be very subtle changes in curve smoothness. Want me to go ahead, or keep the current version?"

---

Generation Checklist

Before delivering ANY icon, verify:

• ViewBox set correctly, no hardcoded width/height
• Uses currentColor (unless user specified fixed colors)
• Stroke width consistent across the set
• Paths grid-aligned (whole or .5 pixel values)
• Accessibility attributes applied (aria-hidden OR role+aria-label)
• Output format matches user's project (inline SVG / React / both)
• Style matches the UI context
• Optically centered in the viewBox
• At small sizes: pixel hinting verified, warned if detail may blur
• For sets: consistency with previously generated icons confirmed

---

Quick Reference: Path Commands

M x y       → Move to (start new subpath)
L x y       → Line to
H x         → Horizontal line
V y         → Vertical line
C x1 y1 x2 y2 x y → Cubic bézier
S x2 y2 x y → Smooth cubic bézier
Q x1 y1 x y → Quadratic bézier
T x y       → Smooth quadratic bézier
A rx ry rot large-arc sweep x y → Arc
Z           → Close path

Lowercase = relative coordinates (offset from current point)