agentleFS
MohamedAbdallah-14MohamedAbdallah-14/prompt-to-asset/.cursor/skills/svg-authoring/SKILL.md

svg-authoring

Skill18 starsChanged 7 months agoMITView on GitHub

Author production-grade inline SVG (logos, favicons, icon packs, stickers, transparent marks) when the P2A `inline_svg` execution mode is selected. Enforces viewBox, path-budget, palette, optical balance, and small-scale legibility rules so the emitted `<svg>` survives `asset_save_inline_svg` validation and renders crisp from 16×16 through 1024×1024.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before emitting, picture the mark at 16×16:

    line 60
  2. Very specific:

    If the brief requires <text>:

    line 70
  3. Very specific:

    Use a web-safe stack: font-family="ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" — never a single exotic font.

    line 71
  4. Distinctive:

    Never embed actual font files.

    line 72
  5. Distinctive:

    Run OCR validation post-render.

    line 73
  6. Distinctive:

    If brief expects dark-mode variant: emit two SVGs (light + dark), do not algorithmically invert (loses contrast).

    line 79
  7. Very specific:

    Use currentColor for icon-pack icons so consumers can theme via CSS.

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

Asset typeviewBoxPath budgetColorsSafe-zoneNotes
logo0 0 120 120 (or brief-specified)≤402–4 hexsubject fits inside 80% center boxFlat, geometric, closed shapes
favicon (master SVG)0 0 64 64≤302–3 hexlegible at 16×16 after downsampling≥2px stroke equivalent at 16²
icon_pack (per icon)0 0 24 24≤8monocolor (currentColor) OR 2 tones2px grid, 1.5–2px strokesAll icons share grid + stroke weight
sticker0 0 240 240≤60up to 6 hexbleed allowed; no hard edge requirementChunkier line weights OK
transparent_mark0 0 200 200≤402–3 hex80% centerNever emit <rect fill="white"> as "background"
app_icon master0 0 1024 1024≤603–5 hexiOS HIG 824² centerOpaque bg allowed; no alpha needed on this one

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

MistakeSymptomFix
Coordinates > viewBoxSubject clipped / off-canvasKeep all coordinates within [0, viewBox_size]
Open paths (missing Z)Fill leaks, unpredictable strokeAlways Z before starting new subpath
Sub-pixel coordinates (e.g. 60.000001)Blurry rasterizationRound to 2 decimals
Stroke sized for 1024 canvas in a favicon viewBoxInvisible at 16²Size strokes as ratio of viewBox
Over-detail / literal interpretationCannot read at small scaleReduce to silhouette; cut paths
Mixed stroke/fill conventionsInconsistent icons in a packPick one and declare at <svg> root
Gradient in faviconMuddy at 16²Flat fills only below 64×64 viewBox
Drop shadows / filtersBroken in most renderersDo not use <filter> in brand assets

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)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.