visual-diagrams

name

visual-diagrams

description

Professional diagram and architecture visualization design system for Remotion video compositions. Use when building: architecture diagrams, hub-and-spoke layouts, flowcharts, pipeline visualizations, comparison panels, layered stacks, data flow diagrams, or any scene with connected boxes/nodes/arrows. Ensures YouTube-grade visual quality with gradient fills, depth shadows, glow effects, brand logo icons, and animated connections. Triggers on: "diagram", "architecture", "flowchart", "pipeline", "hub and spoke", "data flow", "system diagram", "connected boxes", "infrastructure layout", "tech stack visualization".

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

Visual Need	Component	When to Use
Multi-stage process (PREFERRED)	InfographicFlow	Pipelines, workflows, how-it-works, stage-by-stage explanations — enterprise-grade pastel bands with Lucide icons
Central element + surrounding services	HubAndSpoke	Tech stacks, service architectures, API ecosystems
Sequential process/pipeline	FlowDiagram	Simple 3-5 node pipelines, build chains
Stacked layers (UI > API > DB)	LayeredArchitecture	Software architecture, network stacks, abstraction layers
Side-by-side comparison	ComparisonDiagram	Before/after, old vs new, competitor analysis
Git workflow visualization	GitBranching	Branching strategies, CI/CD flows, merge patterns

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:

Element	Minimum Size	Recommended
Hub/center node	180x120px	200x140px
Spoke/satellite node	160x100px	180x110px
Flow diagram node	200x100px	220x120px
Layer bar height	90px	100-120px
Icon/logo inside node	36x36px	40-48px
Node label font	24px	26-28px
Sub-label font	20px	22px

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:

Rule	Pattern	Fix
Wireframe node (no gradient/shadow)	backgroundColor: '${color} + hex ≤ 2 chars opacity, no boxShadow	Add gradient fill + multi-layer shadow
Thin border on diagram node	border: '1px on diagram container	Minimum 2px border
Missing connection glow	SVG <line> without glow filter or duplicate blur line	Add glow layer or SVG filter
Unicode emoji as diagram icon	Emoji char in node content div	Replace with brand logo image or styled letter badge
Undersized diagram node	Node width < 160px or height < 100px	Increase to minimum sizes
Flat connection lines	strokeWidth < 2.5 on connection lines	Increase to 2.5px minimum