svg-graphics

name	svg-graphics
description	Scalable, accessible, theme-aware visuals
tier	standard
applyTo	**/*.svg,**/*icon*,**/*graphic*

SVG Graphics Skill

Scalable, accessible, theme-aware visuals.

Why SVG

• Scales infinitely (retina, print)
• Text is searchable/accessible
• CSS-styleable (dark mode)
• Small file size
• Version control friendly

Banner Template

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 300">
  <rect width="100%" height="100%" fill="#1a1a2e"/>
  <text x="50" y="100" font-size="48" fill="#fff" font-family="system-ui">
    Project Name
  </text>
  <text x="50" y="150" font-size="24" fill="#888">One-line description</text>
</svg>

Key Techniques

Technique	Use Case
viewBox	Responsive scaling
<defs> + <use>	Reusable components
<linearGradient>	Modern backgrounds
<clipPath>	Shaped containers
CSS variables	Theme switching

Dark/Light Mode

<style>
  @media (prefers-color-scheme: dark) {
    .bg { fill: #1a1a2e; }
    .text { fill: #ffffff; }
  }
  @media (prefers-color-scheme: light) {
    .bg { fill: #ffffff; }
    .text { fill: #1a1a2e; }
  }
</style>

Icon Guidelines

Size	Use
16x16	Favicon, small UI
32x32	Tab icon, lists
128x128	App icon
512x512	Store listing

SMIL Animation

Fade-In Pattern

<g opacity="0">
  <text x="50" y="100" font-size="48" fill="#fff">Title</text>
  <animate attributeName="opacity" from="0" to="1" dur="0.8s" begin="0.5s" fill="freeze"/>
</g>

Attribute	Purpose
begin	Delay before start
dur	Animation duration
fill	"freeze" (keep state) or "remove" (revert)

Staggered Entrance

Increment begin by 0.3s per element for smooth staggering.

Note: GitHub README renders SVG statically — animations won't play.

CSS Transforms

Nested Group Pattern

Separate position and animation transforms:

<!-- Outer: position -->
<g transform="translate(600, 150)">
  <!-- Inner: animation -->
  <g>
    <animateTransform attributeName="transform" type="rotate" from="0" to="360" dur="10s" repeatCount="indefinite"/>
    <circle r="20" fill="#4a90d9"/>
  </g>
</g>

Rule: Never mix static positioning and animated transforms on the same element.

ClipPath Layers

3-layer pattern for shaped containers:

<defs>
  <clipPath id="card">
    <rect x="50" y="50" width="400" height="200" rx="16"/>
  </clipPath>
</defs>

<!-- Layer 1: Background -->
<rect x="50" y="50" width="400" height="200" rx="16" fill="#f6f8fa"/>

<!-- Layer 2: Clipped content -->
<g clip-path="url(#card)">
  <image href="photo.jpg" x="50" y="50" width="400" height="200"/>
</g>

<!-- Layer 3: Border (on top) -->
<rect x="50" y="50" = = = = = =/>

Optimization

SVGO Config

{
  "plugins": [
    "preset-default",
    { "name": "removeViewBox", "active": false },
    { "name": "removeDimensions", "active": true }
  ]
}

Critical: Never remove viewBox (breaks scaling) or <title> (breaks accessibility).

Size Budget

Type	Target	Max
Icon	< 1 KB	2 KB
Badge	< 2 KB	5 KB
Banner	< 10 KB	25 KB
Diagram	< 25 KB	50 KB

Accessibility

• role="img" on decorative SVGs
• <title> for screen readers
• Sufficient contrast (4.5:1 min)
• aria-hidden="true" if purely decorative

SVG vs Mermaid

Scenario	SVG	Mermaid
README branding	✅	❌
Dev docs flow	❌	✅
Dark/light theme	✅	⚠️
High-DPI output	✅	⚠️

Illustration: Organic Shapes

The Snowman Problem

AI defaults to stacking circles — producing geometric snowmen. Real subjects need <path> with Bezier curves.

Mandatory Rules:

1. Start with silhouette — outline must be identifiable alone
2. Use <path> with curves for ALL organic shapes
3. Get proportions right before details
4. Count limbs correctly (quadrupeds have 4 legs)

Feature Table

Animal	Key Features	Common Mistake
Dog	Snout, floppy ears on SIDE, 4 legs	Flat face, ears on top
Cat	Pointed ears on TOP, whiskers, slender	No whiskers, stocky
Bird	Beak, wings, 2 legs, NO arms	4 legs, arms not wings

Path-First Approach

<!-- Dog body outline - single path defining silhouette -->
<path d="M 120,180 C 120,140 140,110 180,105 C 210,100 250,100 280,110..." 
      fill="#c89050" stroke="#6b4226" stroke-width="2"/>

Why: Silhouette reads as "dog" even without color. ALL shapes use <path> — no perfect circles.

Tools

Tool	Purpose
SVGO	Optimize/minify
Inkscape	Visual editing
svg-to-png	Rasterization