mohamedabdallah-14/prompt-to-asset/svg-authoring

SVG authoring (inline_svg mode)

Engaged when asset_generate_* returns an InlineSvgPlan. Read svg_brief (viewBox, palette, path_budget, require[], do_not[], skeleton) and emit one <svg>…</svg> code block that honors every constraint. Then call asset_save_inline_svg({ svg, asset_type }) so the file lands on disk.

Hard constraints (non-negotiable)

Never emit: <image> tags, external refs, <script>, inline Base64, fonts with unverified family names, CSS animations in a favicon master, gradients in an icon-pack icon.

Design principles (from frontend-design, adapted for SVG)

1. Aesthetic commitment — pick one direction from the brief and execute it precisely. Brutalist, minimal, geometric, organic — not a blend. Do not hedge.
2. Silhouette clarity — the shape must read as a single-color fill. Squint test: does it hold together when all paths collapse to black?
3. Optical balance over mathematical centering — curves/triangles need ~2–4% shift to feel centered. Use the viewBox midpoint as a starting reference, not a law.
4. Proportional stroke weights — strokes authored as a ratio of viewBox, not absolute pixels. A 1px stroke at viewBox 120 becomes invisible at 16×16. Use 2–4px for icons, 4–8px for logos.
5. Negative space as structure — gaps between paths carry meaning. Don't fill every cell.
6. Every path earns its place — if a path can be removed without changing the silhouette, remove it. Path count is a quality signal.

SVG grammar cheatsheet

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" fill="none" stroke="currentColor" stroke-width="4" stroke-linecap="round" stroke-linejoin="round">
  <!-- primitives beat paths for circles/rects -->
  <circle cx="60" cy="60" r="40" />
  <rect x="30" y="30" width="60" height="60" rx="8" />
  <!-- paths: M (moveto), L (lineto), C (cubic), Z (close) -->
  <path d="M40 80 L60 40 L80 80 Z" fill="#0A1F44" />
  <!-- groups scope styles; use currentColor for theming -->
  <g fill="#FF6B6B"><path d="…"/><path d="…"/></g>
</svg>

Rules: always close shapes with Z; round coordinates to 2 decimals; prefer primitives (<circle>, <rect>) over equivalent <path>; use <g> to deduplicate fill/stroke.

Style taxonomy

Flat-geometric — primitives + straight paths, fills only, 2–3 hex. Default for logos/favicons. Outlined (stroke-only) — fill="none", uniform stroke-width, round caps/joins. Default for icon packs (Lucide/Heroicons pattern). Filled (solid) — single-color fills, currentColor for theming. Compact file size. Duotone — two layered <g> groups, contrasting hex codes. Good for logos with depth. Minimal/brutalist — 1–3 shapes, monocolor, asymmetric composition. Highest failure rate if executed carelessly. Gradient — <linearGradient> or <radialGradient> in <defs>. Avoid in favicons (collapses at 16²).

Small-scale survivability check

Before emitting, picture the mark at 16×16:

• Strokes ≥2px at final render size? (A 2px stroke at viewBox 120 → renders as 2 × 16/120 = 0.27px at 16×16. Too thin. Use 6–8px at viewBox 120 for favicons.)
• ≤3 perceptual shapes? (More collapses into mush.)
• ≥4.5:1 contrast between foreground and expected background (white browser chrome AND dark chrome)?
• Single visual idea? (No secondary glyphs, no borders, no flourishes.)

Text inside SVG

Default: no text. Composite brand typography in the application layer using real fonts.

If the brief requires <text>:

• Use a web-safe stack: font-family="ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" — never a single exotic font.
• Never embed actual font files.
• Run OCR validation post-render; reject Levenshtein >1 vs. intended wordmark.
• For >3 words: generate text-free mark, composite type post-render. Do not emit SVG text at that length.

Color application

• Palette comes from svg_brief.palette. Use it strictly. No new hex codes.
• If brief expects dark-mode variant: emit two SVGs (light + dark), do not algorithmically invert (loses contrast).
• Use currentColor for icon-pack icons so consumers can theme via CSS.
• Validate ΔE2000 ≤10 vs brand palette (handled post-save by asset_save_inline_svg).

Failure patterns to avoid

Round-trip contract

The asset_save_inline_svg tool validates your SVG against the brief. If it returns an error:

• viewBox mismatch — you used a different viewBox than the brief specified
• path count > budget — reduce via primitives, merging, or deletion of decorative paths
• unknown palette color — swap rogue hex for nearest palette entry
• external reference — remove <image href>, <use href>, etc.

Regenerate the SVG with the correction; call asset_save_inline_svg again. Max 2 retries, then report back to user.

Research

• docs/research/12-vector-svg-generation/12d-llm-direct-svg-code-generation.md — LLM-author SVG patterns, StarVector, path budgets
• docs/research/12-vector-svg-generation/12e-hybrid-vector-pipeline-architectures.md — fallback paths when inline fails
• docs/research/24-skills-for-p2a/02-svg-authoring-skill-design.md — full spec (this file is the shipping distillation)