Visual Diagrams

Visual Diagrams Design System

Professional-grade diagram components for Remotion explainer videos. Replaces wireframe-quality boxes-and-lines with YouTube-grade visuals: gradient fills, depth shadows, animated glowing connections, brand logo images, and layered visual hierarchy.

When to Use This Skill

• Phase 4 scene building when the plan calls for architecture/system diagrams
• Any scene showing relationships between components (hub-spoke, flow, layers)
• Infrastructure/tech stack visualizations
• Before/after or comparison layouts
• Data flow or pipeline diagrams

The Problem This Solves

Without this skill, sub-agents produce wireframe-quality diagrams:

• Thin 1-2px borders on transparent boxes
• Unicode characters as "icons" (invisible in headless Chromium)
• No shadows, no depth, no visual hierarchy
• Tiny nodes that look like developer sketches
• Thin dashed connection lines with no glow or energy

Quick Reference: Which Component to Use

Icon Library: lucide-react

All diagram components support Lucide icons (1000+ professional SVG icons). Import directly:

import { Search, Brain, Cpu, Database, Shield, Send, Package, Puzzle } from 'lucide-react';

// Use in InfographicFlow stages
{ label: 'Discovery', icon: Search, nodes: [...] }

// Use in DiagramIcon wrapper
<DiagramIcon icon={Search} color="#2E7D32" bg="#C8E6C9" size={48} />

Browse all icons: https://lucide.dev/icons

DiagramIcon Wrapper

DiagramIcon wraps any Lucide icon in a colored circle/rounded background with shadow:

import { DiagramIcon } from '../shared/components/diagrams';

<DiagramIcon icon={Brain} color="#1565C0" bg="#BBDEFB" size={52} variant="circle" />
<DiagramIcon icon={Database} color="#E65100" bg="#FFE0B2" size={48} variant="rounded" />
<DiagramIcon imageSrc={staticFile('images/comp/logo.png')} color="#333" size={48} />
<DiagramIcon letter="A" color="#7B1FA2" bg="#E1BEE7" size={44} />

Priority: Lucide icon > brand logo image > styled letter badge.

InfographicFlow — Enterprise-Grade Stage Diagrams

The flagship component. Produces pastel-banded row layouts like enterprise infographics (Anthropic, Google, DailyDoseofDS style).

import { InfographicFlow } from '../shared/components/diagrams';
import { Search, Brain, Zap } from 'lucide-react';

<InfographicFlow
  title="How It Works"
  subtitle="A 5-stage pipeline"
  mode="light"  // or "dark"
  stages={[
    {
      label: 'Discovery',
      icon: Search,
      nodes: [
        { label: 'Scan', icon: Search },
        { label: 'Match', icon: Brain },
      ],
      connector: 'arrow',  // or '+' or custom string
      description: 'Finds relevant items',
    },
    // ... more stages
  ]}
/>

Light vs Dark Mode

• Light mode (mode="light"): White background, pastel-colored bands (green, blue, orange, purple, yellow, cyan, red, indigo). Enterprise infographic style.
• Dark mode (mode="dark"): #0B1120 background, subtle tinted bands. Matches existing video dark theme.

Both modes use the same component — just flip the mode prop.

Palette System

Custom palettes available via getDiagramPalette() and getStagePalette():

import { getDiagramPalette, getStagePalette } from '../shared/components/diagrams';

const palette = getDiagramPalette('light');
const stage0Colors = getStagePalette(palette, 0); // green band
// stage0Colors.band, .accent, .iconBg, .text, .textMuted

Design Principles

1. Gradient Fills Over Flat Colors

Every node/box MUST use a subtle gradient fill, not a flat color. Gradients create depth and make elements feel three-dimensional.

// WRONG - flat transparent fill (wireframe look)
backgroundColor: `${color}22`

// CORRECT - gradient fill with depth
background: `linear-gradient(135deg, ${color}25, ${color}08)`

2. Multi-Layer Shadows for Depth

Every node MUST have at least a 2-layer box shadow: a tight inner shadow for definition and a wider outer glow for atmosphere.

// WRONG - no shadow (flat, floats in void)
// (no boxShadow property)

// CORRECT - depth + glow
boxShadow: `0 4px 20px ${color}30, 0 0 40px ${color}15, inset 0 1px 0 rgba(255,255,255,0.05)`

3. Thick Borders with Gradient Feel

Use 2-3px borders minimum. 1px borders disappear on YouTube at 720p. Use the node's accent color at 40-60% opacity for borders (not 20%).

// WRONG - too thin, too transparent
border: `1px solid ${color}22`

// CORRECT - visible at YouTube resolution
border: `2px solid ${color}66`
borderTop: `3px solid ${color}`  // accent top edge

4. Brand Logo Images Instead of Unicode Icons

When referencing known tools/services (GitHub, Docker, AWS, Cloudflare, etc.), use actual brand logo images downloaded to public/images/<composition>/. Unicode symbols and emoji render as black glyphs in headless Chromium.

// WRONG - invisible in rendered video
<div style={{ fontSize: 36 }}>{'🐳'}</div>

// CORRECT - actual brand logo
<Img src={staticFile('images/mycomp/docker-logo.png')}
     style={{ width: 40, height: 40, objectFit: 'contain' }} />

Image acquisition: During Phase 4 scene building, if a brand logo is needed:

1. Check if it already exists in public/images/<composition>/
2. If not, download from GitHub avatars: https://github.com/<org>.png?size=128
3. Or use the scene's screenshots.json manifest for batch capture
4. Fall back to a styled letter badge (colored circle + first letter) — never Unicode emoji

5. Generous Node Sizing

Nodes must be large enough to be instantly readable at 720p. Minimum sizes:

6. Animated Glowing Connections

Connection lines between nodes must have:

• Minimum 2.5px stroke width (not 1-2px)
• A subtle glow via SVG filter or duplicate line with blur
• Animated draw-on via strokeDasharray/strokeDashoffset
• Color matching the source or target node's accent

// WRONG - thin invisible line
<line stroke={color} strokeWidth={1} strokeDasharray="4 4" />

// CORRECT - visible glowing connection
<>
  {/* Glow layer */}
  <line stroke={color} strokeWidth={6} opacity={0.15}
        filter="url(#connectionGlow)" />
  {/* Main line */}
  <line stroke={color} strokeWidth={2.5} opacity={0.7}
        strokeDasharray={len} strokeDashoffset={dashOff} />
</>

7. SVG Glow Filter (Add to Every Diagram SVG)

<svg>
  <defs>
    <filter id="connectionGlow" x="-50%" y="-50%" width="200%" height="200%">
      <feGaussianBlur stdDeviation="4" result="blur" />
      <feMerge>
        <feMergeNode in="blur" />
        <feMergeNode in="SourceGraphic" />
      </feMerge>
    </filter>
    <marker id="arrowhead" markerWidth="12" markerHeight="8"
            refX="11" refY="4" orient="auto">
      <polygon points="0 0, 12 4, 0 8" fill={COLORS.primary} />
    </marker>
  </defs>
</svg>

8. Background Atmosphere

Diagram scenes should include subtle background elements for depth:

• ProceduralNoise with low opacity (0.08-0.12) for organic movement
• Subtle radial gradient centered on the diagram's focal point
• Optional grid pattern at very low opacity (0.03-0.05)

{/* Atmospheric background */}
<div style={{
  position: 'absolute', inset: 0,
  background: `radial-gradient(ellipse at ${CENTER_X}px ${CENTER_Y}px,
    ${COLORS.primary}08 0%, transparent 60%)`,
}} />
<ProceduralNoise seed="diagram" color={COLORS.primary}
                 count={12} opacity={0.08} speed={0.004} />

Component Upgrade Patterns

See references/component-patterns.md for detailed before/after code patterns for each shared component (HubAndSpoke, FlowDiagram, LayeredArchitecture, ComparisonDiagram).

See references/icon-strategy.md for the complete icon/logo acquisition and fallback strategy.

See references/animation-choreography.md for connection line animation, node entrance sequencing, and SpotlightFocus patterns for multi-phase diagrams.

Integration with Phase 4

When Phase 4 encounters a scene plan that calls for an architecture diagram or connected component visualization:

1. Load this skill for design guidance
2. Check shared components — use HubAndSpoke, FlowDiagram, LayeredArchitecture, ComparisonDiagram, or GitBranching as the foundation
3. Download brand logos if the diagram references known tools/services
4. Use the component's props — all components accept nodeStyle, connectionStyle, and iconSrc overrides for professional visual treatment
5. Add background atmosphere — ProceduralNoise + radial gradient behind the diagram
6. Run /validate-scene after building to catch visual quality issues

Rulecheck Integration

The visual scanner (rulecheck-scanner-visual) checks for these diagram-specific violations: