<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" width="400" height="200" rx="16" fill="none" stroke="#d1d9e0" stroke-width="2"/>

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:

Start with silhouette — outline must be identifiable alone
Use <path> with curves for ALL organic shapes
Get proportions right before details
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

svg-graphics

SVG Graphics Skill

Why SVG

Banner Template