` (breaks accessibility). ### Size Budget | SVG Type | Target Size | Max | |----------|-------------|-----| | Icon | < 1 KB | 2 KB | | Badge/shield | < 2 KB | 5 KB | | Banner | < 10 KB | 25 KB | | Complex diagram | < 25 KB | 50 KB | ### Common Optimization Wins | Technique | Savings | |-----------|---------| | Remove editor metadata (Inkscape, Illustrator) | 20-50% | | Simplify paths (reduce decimal precision) | 10-20% | | Remove empty groups/unused defs | 5-15% | | Convert shapes to paths | 5-10% | | Gzip on server | 60-80% additional | ## Accessibility - `role="img"` on decorative SVGs - `<title>` for screen readers - Sufficient contrast (4.5:1 min) - `aria-hidden="true"` if decorative ## Tools | Tool | Purpose | | ---- | ------- | | SVGO | Optimize/minify | | Inkscape | Visual editing | | svg-to-png | Rasterization | ## SVG for Documentation Illustrations SVG isn't just for branding — it's the best format for **polished documentation visuals** that need more control than Mermaid provides. ### When to Choose SVG Over Mermaid | Scenario | Use SVG | Use Mermaid | |----------|---------|-------------| | Architecture overview for README | ✅ Branded, polished | ❌ Too generic | | Internal dev docs flow | ❌ Overkill | ✅ Quick, accurate | | Marketing / landing page | ✅ Full design control | ❌ Unbranded | | Infographic with custom layout | ✅ Arbitrary positioning | ❌ Auto-layout only | | Dark/light theme required | ✅ CSS media queries | ⚠️ Limited theming | | Print / high-DPI output | ✅ Infinitely scalable | ⚠️ Rasterized at render | ### Illustration Template ```xml <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400" role="img"> <title>Architecture Overview

# Svg Graphics > Scalable, accessible, theme-aware visuals. - Skill: `majiayu000/svg-graphics` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add majiayu000/svg-graphics` - Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/svg-graphics/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: majiayu000 (https://skillmd.com/u/majiayu000) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/majiayu000/svg-graphics --- # 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 ```xml ``` ## Key Techniques | Technique | Use Case | | --------- | -------- | | `viewBox` | Responsive scaling | | `` + `` | Reusable components | | `` | Modern backgrounds | | `` | Shaped containers | | CSS variables | Theme switching | ## Dark/Light Mode ```xml ``` ## Icon Guidelines | Size | Use | | ---- | --- | | 16x16 | Favicon, small UI | | 32x32 | Tab icon, lists | | 128x128 | App icon | | 512x512 | Store listing | ## SMIL Animation ### Delayed Fade-In Pattern Elements that should appear after load (hero text, feature pills, etc.): ```xml Title ``` **Key attributes**: | Attribute | Purpose | Values | |-----------|---------|--------| | `begin` | Delay before start | `"0.5s"`, `"1s"`, `"click"` | | `dur` | Animation duration | `"0.3s"` to `"2s"` typical | | `fill` | State after animation | `"freeze"` (keep end state) or `"remove"` (revert) | | `repeatCount` | Repetitions | `"1"`, `"3"`, `"indefinite"` | ### Staggered Entrance Multiple elements appearing in sequence: ```xml Feature 1 Feature 2 Feature 3 ``` **Pattern**: Increment `begin` by `0.3s` per element for smooth staggering. ### SMIL Compatibility | Platform | Support | |----------|---------| | Chrome/Edge | Full SMIL | | Firefox | Full SMIL | | Safari | Full SMIL | | GitHub README | **No animation** (static render) | | npm/PyPI README | **No animation** (static render) | **Rule**: For README badges/banners, set initial `opacity="1"` as fallback — animated SVGs render as static first frame in non-animated contexts. ## CSS Transform Patterns ### The Nested Group Pattern **Problem**: Combining position transforms (`translate`) with animation transforms (`rotate`, `scale`) on the same element causes conflicts — the animation resets position. **Solution**: Use nested `` groups to separate concerns: ```xml ``` **Rule**: Never mix static positioning and animated transforms on the same element. Always wrap in a positioning group. ### Scale from Center ```xml ``` ### Pulse Effect ```xml ``` ## ClipPath Container Layering ### The 3-Layer Pattern For shaped containers with content and visible borders: ```xml Overlay Text ``` **Draw order matters**: 1. Background fill (behind everything) 2. Clipped content group (contained within shape) 3. Border outline (on top, `fill="none"`) ### Rounded Card Pattern ```xml Card Title Card content here ``` ## SVG Optimization ### SVGO Configuration ```json { "plugins": [ "preset-default", { "name": "removeViewBox", "active": false }, { "name": "removeDimensions", "active": true }, { "name": "removeTitle", "active": false } ] } ``` **Critical**: Never remove `viewBox` (breaks scaling) or `` (breaks accessibility). ### Size Budget | SVG Type | Target Size | Max | |----------|-------------|-----| | Icon | < 1 KB | 2 KB | | Badge/shield | < 2 KB | 5 KB | | Banner | < 10 KB | 25 KB | | Complex diagram | < 25 KB | 50 KB | ### Common Optimization Wins | Technique | Savings | |-----------|---------| | Remove editor metadata (Inkscape, Illustrator) | 20-50% | | Simplify paths (reduce decimal precision) | 10-20% | | Remove empty groups/unused defs | 5-15% | | Convert shapes to paths | 5-10% | | Gzip on server | 60-80% additional | ## Accessibility - `role="img"` on decorative SVGs - `<title>` for screen readers - Sufficient contrast (4.5:1 min) - `aria-hidden="true"` if decorative ## Tools | Tool | Purpose | | ---- | ------- | | SVGO | Optimize/minify | | Inkscape | Visual editing | | svg-to-png | Rasterization | ## SVG for Documentation Illustrations SVG isn't just for branding — it's the best format for **polished documentation visuals** that need more control than Mermaid provides. ### When to Choose SVG Over Mermaid | Scenario | Use SVG | Use Mermaid | |----------|---------|-------------| | Architecture overview for README | ✅ Branded, polished | ❌ Too generic | | Internal dev docs flow | ❌ Overkill | ✅ Quick, accurate | | Marketing / landing page | ✅ Full design control | ❌ Unbranded | | Infographic with custom layout | ✅ Arbitrary positioning | ❌ Auto-layout only | | Dark/light theme required | ✅ CSS media queries | ⚠️ Limited theming | | Print / high-DPI output | ✅ Infinitely scalable | ⚠️ Rasterized at render | ### Illustration Template ```xml <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400" role="img"> <title>Architecture Overview Architecture Name Component A Component B ``` ### Key Principles for Illustrations 1. **Always include dark/light mode** via `@media (prefers-color-scheme: ...)` — GitHub renders both 2. **Use semantic class names** (`.box`, `.accent`, `.connector`) not inline styles 3. **Center with `text-anchor="middle"`** — more maintainable than manual x positioning 4. **Group with ``** — move entire components by adjusting one value 5. **Keep `viewBox` ratio consistent** — 800×400 (2:1) for wide illustrations, 600×600 (1:1) for square ## Illustrating Real-World Subjects (Animals, Objects, People) ### The Snowman Problem **Problem**: When asked to draw a dog, cat, person, or any real-world subject, AI defaults to stacking circles and rectangles — producing geometric snowmen with accessories instead of recognizable illustrations. **Root Cause**: The model uses primitive shapes (``, ``, ``) as building blocks. Real-world subjects have **organic, asymmetric silhouettes** that require `` elements with Bezier curves. **The Snowman Test**: If you remove all color, texture, and small details — does the **silhouette alone** identify the subject? A circle on a circle is always a snowman, no matter how many ears/tails you add. ### Mandatory Rules for Subject Illustrations | # | Rule | Why | |---|------|-----| | 1 | **Start with the silhouette** — sketch the outer `` outline FIRST | The outline makes or breaks recognition. If the outline looks wrong, details won't fix it. | | 2 | **Use `` with Bezier curves** for ALL organic shapes | `` and `` produce geometric/robotic results. Real animals have no perfect circles. | | 3 | **Pass the squint test** — outline alone must be identifiable | Remove all fill colors and details. If the outline doesn't read as the subject, redo the outline. | | 4 | **Get proportions right before adding details** | Head-to-body ratio, limb length, and placement matter more than eyes/nose/accessories. | | 5 | **Count limbs correctly** — quadrupeds have 4 legs, birds have 2 + wings | The most common error. Don't draw 2 legs on a 4-legged animal. In side view, show at least 3 legs (near pair + 1 far). | | 6 | **Differentiate species by key anatomical features** | A dog is not a cat is not a bear. See the feature table below. | ### Feature Differentiation Table What makes each animal **visually distinct** — the features to exaggerate: | Animal | Key Silhouette Features | Common AI Mistakes | |--------|------------------------|--------------------| | **Dog** | Snout/muzzle protruding from head, floppy or pointed ears (SIDE of head, not top), 4 legs, wagging tail, body longer than tall | Flat face (no snout), cat ears on top, 2 legs, perfect circle head | | **Cat** | Pointed ears on TOP of head, round face, long curved whiskers, slender body, long curving tail, 4 legs with small paws | No whiskers, dog-like snout added, thick stocky body | | **Bird** | Beak (triangular), wings (large relative to body), 2 thin legs, tail feathers, no arms | 4 legs, no beak, arms instead of wings | | **Fish** | Streamlined oval body, tail fin, dorsal fin, NO legs | Legs added, round body (balloon), no fins | | **Person** | Head on neck on shoulders, 2 arms with hands, 2 legs with feet, torso taller than wide | Snowman stack, no neck, T-pose arms | | **Horse** | Long neck, elongated head with flat front, 4 long thin legs, mane, flowing tail | Dog-like proportions, short legs, round head | | **Rabbit** | LONG upright ears (longer than head), round body, short front legs, large hind legs, cotton tail | Short ears (looks like a bear), same-length legs | ### The Path-First Approach **Never build an animal from primitive shapes.** Build from a single continuous `` outline. #### Step-by-Step: Drawing a Dog (Side View) ```xml ``` **Why this works**: - Silhouette reads as "dog" even without color (elongated body, protruding snout, floppy ear) - Snout is the dominant facial feature — face is NOT flat - 4 legs visible (2 front, 2 back in side view) - Body is longer than tall (dog proportions, not snowman proportions) - ALL shapes use `` with curves — no perfect circles ### Proportion Guide For side-view quadrupeds (dog, cat, horse): ```text ┌──────────────────────────────────────────┐ │ HEAD NECK BODY │ │ ┌───┐ ┌─┐ ┌──────────┐ │ │ ear→ │ │───│ │───│ │ ←tail │ │ │ • │ │ │ │ │ / │ │ snout→│ ▪ │ └─┘ │ │ / │ │ └───┘ │ │/ │ │ └──┬──┬──┬─┘ │ │ │ │ │ │ │ │ legs (4, not 2!) │ │ │ │ HEAD:BODY ratio ≈ 1:2.5 (dog) │ │ HEAD:BODY ratio ≈ 1:2 (cat) │ │ HEAD:BODY ratio ≈ 1:4 (horse) │ │ LEG length ≈ body height (dog, horse) │ │ LEG length ≈ 0.7× body height (cat) │ └──────────────────────────────────────────┘ ``` ### Color Guidelines for Illustrated Subjects | Subject | Natural Palette | Avoid | |---------|----------------|-------| | Dog | Browns (#c89050, #a0703c, #6b4226), Golden (#e8c690), Black, White, Gray | Green, blue, purple (unnatural) | | Cat | Gray (#8e8e8e), Orange (#d68c45), Black, White, Siamese (#c4a882) | Bright green, neon colors | | Bird | Species-specific; blue (#4a90d9), red (#cf4040), yellow (#e6b422), green (#5ab05a) | All one color (usually multi-toned) | | Person | Skin tones, clothing colors | Geometric shapes for body parts | | Tree | Green canopy (#4a8c3f, #6aad5a), brown trunk (#6b4226, #8b6914) | Blue leaves, gray trunk | **Rule**: Use **realistic base colors** unless the user specifically requests a stylized/cartoon palette. ### Common Failure Modes | Failure | Cause | Fix | |---------|-------|-----| | "Snowman with ears" | Using stacked circles for body | Use one continuous `` for body outline | | "Cat ears on everything" | Triangles placed on top of circular head | Place ears on SIDE of head (dogs), check species table | | "Floating face" | Features placed on a perfect circle with no jaw/chin structure | Give head a distinct shape — snout, jawline, not a circle | | "Stick figure animal" | Rectangles for legs attached to circles | Legs should taper, connect to body organically with curves | | "2-legged quadruped" | Forgetting rear or front leg pair | Always count: is this animal 2-legged or 4-legged? | | "Psychedelic colors" | Using brand/branding palette instead of natural colors | Real animals have earthy, natural tones — check color table | | "Giant head, tiny body" | No proportion reference | Check proportion guide — head is usually smaller than body | ### Workflow for Subject Illustrations 1. **Identify** — What species/object? What view? (side/front/3-quarter) 2. **Reference proportions** — Check the proportion guide and feature table 3. **Draw silhouette** — Single `` for body outline. Apply squint test. 4. **Add major features** — Head shape, ears at correct position, limbs (count them!) 5. **Add details last** — Eyes, nose, mouth, texture, color 6. **Squint test** — Remove all color. Is the silhouette recognizable? --- ## Synapses See [synapses.json](synapses.json) for connections.