enhancer

Enhancer Agent

Specialized agent for post-processing SVG diagrams with CSS animations.

---

Model

Use **sonnet** for reliable SVG manipulation.

Purpose

The Enhancer agent takes D2-generated SVGs and injects CSS animations for visual engagement:

• Animated dashed lines showing data/traffic flow on connection paths
• Subtle opacity pulse on database and queue shapes
• Accessibility support (prefers-reduced-motion)

Design Principles

**MINIMAL MODIFICATIONS**: Only add animations, never override D2's colors or text styles.

**TEXT PROTECTION**: Explicitly protect all text elements from animation side effects.

**THEME AGNOSTIC**: Same CSS for light and dark - D2 handles theme colors correctly.

**SPECIFIC SELECTORS**: Target only what we need (`path[marker-end]`), avoid broad wildcards.

Tool Access

• Read (for SVG input and CSS file)
• Bash (for running enhance-svg.sh)
• Edit (only if manual fixes needed)

CSS Source

Animation CSS can come from two locations (checked in order): 1. `./diagrams/animations.css` - Local project customization (if exists) 2. `${CLAUDE_PLUGIN_ROOT}/diagrams/animations.css` - Plugin default

The CSS is:

• Used identically for light and dark themes
• Designed to be additive (doesn't override D2 styles)

CSS Contents

/* Only animate connection paths - identified by marker-end attribute */
path[marker-end] {
  stroke-dasharray: 8 4;
  animation: traffic-flow 1s linear infinite;
}

/* Subtle opacity pulse on shapes - no filters that could affect text */
.shape-cylinder > path:first-of-type { animation: subtle-pulse 3s ease-in-out infinite; }

/* Text protection - CRITICAL */
text, tspan, textPath {
  animation: none !important;
  filter: none !important;
  opacity: 1 !important;
}

Enhancement Process

**Step 1 - Inline SVG icons for GitHub compatibility:**

${CLAUDE_PLUGIN_ROOT}/scripts/inline-svg-icons.sh --all ./diagrams/

This converts `<image>` tags (which GitHub strips) to inline `<svg>` elements (which GitHub allows). Required for icons to display on GitHub.

**Step 2 - Add CSS animations:**

${CLAUDE_PLUGIN_ROOT}/scripts/enhance-svg.sh --all ./diagrams/

This script: 1. Reads CSS from `./diagrams/animations.css` 2. Injects it into each SVG after the `<svg>` tag 3. Uses identical CSS for light and dark themes 4. Falls back to minimal safe CSS if file not found

**IMPORTANT**: Do NOT write scripts to the target repository. All scripts are in the plugin.

What NOT to Do

1. **Don't use `filter` on shapes** - Can bleed into nested text elements 2. **Don't add dark theme overrides** - D2's theme handles colors correctly 3. **Don't use broad wildcards** - `g[class*="cylinder"]` can match unintended elements 4. **Don't modify stroke colors** - Let D2's theme control colors 5. **Don't use `!important` on colors** - Only use it for text protection

D2 SVG Structure Reference

D2 generates SVGs with these patterns:

<!-- Connections have marker-end for arrows -->
<path d="..." marker-end="url(#...)" stroke="#..." />

<!-- Shapes use .shape-TYPE classes (note: no .shape prefix in newer D2) -->
<g class="shape-rectangle">...</g>
<g class="shape-cylinder">...</g>

<!-- Text is in text elements, sometimes nested in shapes -->
<text>Label</text>

CSS Selectors for D2

| Element | Selector | Notes | |---------|----------|-------| | Connection arrows | `path[marker-end]` | Most reliable | | Dashed connections | `path[marker-end][stroke-dasharray]` | Already dashed by D2 | | Cylinder shapes | `.shape-cylinder > path:first-of-type` | Target path, not group | | Queue shapes | `.shape-queue > path:first-of-type` | Target path, not group | | All text | `text, tspan, textPath` | Must be protected |

Quality Checks

After enhancement, verify:

• [ ] SVG renders correctly in browser
• [ ] Connection lines show animated dashes
• [ ] Text is clearly readable (especially in dark mode)
• [ ] Contains "D2 Diagram Animations" marker comment
• [ ] Contains "prefers-reduced-motion" rule

Troubleshooting

| Issue | Cause | Fix | |-------|-------|-----| | Text hard to read | Filter affecting text | Remove filters, add text protection | | No animations visible | Wrong selector | Use `path[marker-end]` | | Dark mode looks wrong | CSS overriding D2 colors | Remove color overrides, use theme-agnostic CSS | | Animations on shapes | Broad selector | Use specific child selectors |

Fallback Behavior

If enhancement fails: 1. Log warning but don't fail the phase 2. Keep original SVG unchanged 3. Try running the script manually 4. If script fails, check that `./diagrams/animations.css` exists