SVG Illustration System

This skill provides guidance for creating consistent, high-quality hand-drawn style SVG illustrations for the DevOps LMS.

Overview

The illustration system uses a hybrid approach:

1. Reusable Vue Components - For common diagram patterns
2. Design System Composable - Shared constants and utilities
3. Custom SVG - Only when no component fits (rare)

---

Available Components

1. IllustrationLinearFlow

Purpose: Sequential step-by-step processes

Best For:

• CI/CD Pipelines
• SDLC Phases
• Scrum Framework Flow
• Any A → B → C → D process

Props:

interface Props {
  steps: Array<{
    label: string      // Main text
    sublabel?: string  // Secondary text
    icon?: string      // Emoji icon
    color: string      // Tailwind color name
  }>
  direction?: 'horizontal' | 'vertical'  // Auto-determined by step count (optional)
  showFeedbackLoop?: boolean             // Show return arrow
  feedbackLabel?: string                 // Label for feedback
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'
}

Auto-Direction (No need to specify direction):

| Steps | Layout | Behavior | |-------|--------|----------| | ≤5 | Horizontal | Side-by-side flow, full width | | 6-10 | Vertical | Stacked flow, 280px width | | >10 | Vertical + Scroll | 600px max-height with scrolling |

You can still override with direction: horizontal or direction: vertical if needed.

MDC Usage:

::illustration-linear-flow
---
steps:
  - label: Plan
    sublabel: Sprint Planning
    icon: 📋
    color: violet
  - label: Build
    sublabel: Development
    icon: 🔨
    color: blue
  - label: Test
    sublabel: QA
    icon: ✅
    color: emerald
  - label: Deploy
    sublabel: Release
    icon: 🚀
    color: amber
showFeedbackLoop: true
feedbackLabel: Continuous Improvement
---
::

---

2. IllustrationChecklist

Purpose: Checkbox-style lists with hand-drawn aesthetic

Best For:

• Definition of Done
• Prerequisites
• Acceptance Criteria
• Best Practices lists
• Requirements checklists

Props:

interface Props {
  title: string                           // Checklist title
  items: Array<string | {                 // Simple string or object
    text: string
    icon?: string
  }>
  note?: string                           // Optional footnote with 💡
  color?: string                          // Default: emerald
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'  // Default: 2xl
}

MDC Usage:

::illustration-checklist
---
title: Definition of Done
items:
  - text: Code reviewed and approved
    icon: 👀
  - text: Unit tests passing
    icon: ✅
  - text: Documentation updated
    icon: 📝
  - text: Deployed to staging
    icon: 🚀
note: All items must be checked before marking complete
color: emerald
---
::

---

3. IllustrationTeamComposition

Purpose: Team roles in a container with responsibilities

Best For:

• Scrum Team structure
• DevOps Team roles
• Any team/role diagram
• Organizational charts

Props:

interface Props {
  title: string                           // Team title
  subtitle?: string                       // Optional subtitle
  roles: Array<{
    name: string                          // Role name
    owns: string                          // What they own
    icon: string                          // Emoji icon
    color: string                         // Tailwind color
    responsibilities: string[]            // List of responsibilities
  }>
  footnote?: string                       // Optional footnote
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'  // Default: full
}

MDC Usage:

::illustration-team-composition
---
title: Scrum Team
subtitle: Self-organizing, cross-functional
roles:
  - name: Product Owner
    owns: Product Backlog
    icon: 🎯
    color: violet
    responsibilities:
      - Maximizes value
      - Manages backlog
      - Stakeholder liaison
  - name: Scrum Master
    owns: Process
    icon: 🛡️
    color: blue
    responsibilities:
      - Removes impediments
      - Facilitates events
      - Coaches team
  - name: Developers
    owns: Sprint Work
    icon: 👥
    color: emerald
    responsibilities:
      - Build increment
      - Self-organize
      - Cross-functional
footnote: Typical team size: 5-9 people
---
::

---

4. IllustrationComparisonMap

Purpose: Side-by-side concept mapping with connectors

Best For:

• Scrum ↔ DevOps mapping
• Traditional vs Modern approaches
• Before/After comparisons
• Any concept mapping

Props:

interface Props {
  leftTitle: string                       // Left column title
  rightTitle: string                      // Right column title
  leftColor?: string                      // Default: violet
  rightColor?: string                     // Default: cyan
  connections: Array<{
    left: string                          // Left item text
    right: string                         // Right item text
    icon: string                          // Connector emoji
  }>
  footnote?: string                       // Optional footnote
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'  // Default: full
}

MDC Usage:

::illustration-comparison-map
---
leftTitle: Scrum
rightTitle: DevOps
leftColor: violet
rightColor: cyan
connections:
  - left: Sprint
    right: Pipeline
    icon: 🔄
  - left: Backlog
    right: Kanban Board
    icon: 📋
  - left: Retrospective
    right: Post-mortem
    icon: 🔍
footnote: Both emphasize continuous improvement
---
::

---

5. IllustrationPyramid

Purpose: Pyramid/hierarchy diagrams where size indicates quantity or importance

Best For:

• Testing Pyramid (Unit → Integration → E2E)
• Priority hierarchies
• Layered architectures
• Any bottom-up structure where base is largest

Props:

interface Props {
  layers: Array<{
    label: string           // Layer name (displayed inside)
    description?: string    // Text shown to the right
    icon?: string           // Emoji shown to the left
    color: string           // Tailwind color name
  }>  // Order: top (smallest) to bottom (largest)
  title?: string            // Optional title above pyramid
  footnote?: string         // Optional centered footnote below
  size?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'  // Default: xl
}

MDC Usage:

::illustration-pyramid
---
layers:
  - label: E2E Tests
    description: Few - slow, fragile
    icon: 🌐
    color: rose
  - label: Integration
    description: Some - moderate speed
    icon: 🔗
    color: amber
  - label: Unit Tests
    description: Many - fast, cheap
    icon: 🧩
    color: emerald
footnote: More tests at the bottom, fewer at the top
size: xl
---
::

Visual Structure:

         /\
        /  \     ← Top layer (few/small) - rose
       /____\
      /      \   ← Middle layer (some/medium) - amber
     /________\
    /          \ ← Bottom layer (many/large) - emerald
   /______________\

---

Size Options

All illustration components support a size prop to control the maximum width:

| Size | Max Width | Best For | |------|-----------|----------| | sm | 384px | Vertical flows, simple diagrams | | md | 448px | Compact horizontal flows | | lg | 512px | Medium checklists | | xl | 576px | Standard illustrations | | 2xl | 672px | Checklists with longer text | | 3xl | 768px | Wide comparisons | | full | 100% | Full-width illustrations (default for most) |

Default Sizes by Component

| Component | Default Size | Reasoning | |-----------|--------------|-----------| | IllustrationLinearFlow | Auto-sized | Direction and size determined by step count | | IllustrationChecklist | 2xl | Single-column lists don't need full width | | IllustrationTeamComposition | full | Team cards spread horizontally | | IllustrationComparisonMap | full | Side-by-side comparisons need space | | IllustrationPyramid | xl | Pyramid with side descriptions needs moderate width |

IllustrationLinearFlow Auto-Sizing

The component automatically determines layout and size:

• ≤5 steps: Horizontal layout, full width
• 6-10 steps: Vertical layout, 280px width
• >10 steps: Vertical layout with 600px max-height scrolling

When to Override Defaults

• Override direction only when you specifically need horizontal for >5 items or vertical for ≤5 items
• Use size: md or size: lg when you want a more compact look
• Defaults work well for most cases - only override when needed

---

Design System Constants

Located in app/composables/useIllustrationDesign.ts

Color Palette

| Color Name | Main Hex | Light Hex | Text Hex | Use For | |------------|----------|-----------|----------|---------| | violet | #8b5cf6 | #a78bfa | #c4b5fd | Planning, Strategy, Product | | blue | #3b82f6 | #60a5fa | #93c5fd | Development, Build, Process | | emerald | #10b981 | #34d399 | #6ee7b7 | Testing, Success, Done | | amber | #f59e0b | #fbbf24 | #fcd34d | Warnings, Important, Deploy | | rose | #f43f5e | #fb7185 | #fda4af | Critical, Errors, Blockers | | cyan | #06b6d4 | #22d3ee | #67e8f9 | Information, Links, Ops | | gray | #6b7280 | #9ca3af | #d1d5db | Neutral, Disabled, Background |

Spacing Constants

SPACING = {
  boxPadding: 20,        // Inside boxes
  itemGap: 35,           // Between list items
  arrowLength: 50,       // Arrow length
  containerPadding: 30,  // Container padding
  boxWidth: 140,         // Standard box
  boxHeight: 70,         // Standard box
  largeBoxWidth: 160,    // Role cards
  largeBoxHeight: 200,   // Role cards
  borderRadius: 12,      // Rounded corners
  iconRadius: 25         // Icon circles
}

Stroke Styles

STROKES = {
  boxDash: '8,4',           // Box stroke pattern
  arrowDash: '4,3',         // Arrow stroke pattern
  containerDash: '10,5',    // Container stroke pattern
  boxStrokeWidth: 2.5,      // Box stroke width
  arrowStrokeWidth: 2,      // Arrow stroke width
  containerStrokeWidth: 2   // Container stroke width
}

Typography

TYPOGRAPHY = {
  fontFamily: "'Segoe UI', system-ui, sans-serif",
  titleSize: 14,      // Titles/headers
  labelSize: 12,      // Main labels
  sublabelSize: 10,   // Secondary text
  smallSize: 9,       // Notes/captions
  iconSize: 20        // Emoji size
}

---

When to Use Each Component

Decision Tree

What type of diagram do you need?
│
├── Sequential process? (A → B → C)
│   └── Use: IllustrationLinearFlow
│
├── Checklist/list with checkboxes?
│   └── Use: IllustrationChecklist
│
├── Team/roles with responsibilities?
│   └── Use: IllustrationTeamComposition
│
├── Side-by-side comparison?
│   └── Use: IllustrationComparisonMap
│
├── Pyramid/hierarchy where size shows quantity?
│   └── Use: IllustrationPyramid
│
└── None of the above?
    └── Create custom SVG (see below)

---

Creating Custom SVG (Rare Cases)

Only create custom SVG when no component fits. Follow these rules:

1. Use Design System Constants

<script setup>
import {
  COLORS,
  SPACING,
  STROKES,
  OPACITY,
  TYPOGRAPHY,
  getColor,
  getHandDrawnRotation
} from '~/composables/useIllustrationDesign'
</script>

2. Hand-Drawn Style Rules

• Dashed strokes: Use stroke-dasharray with design system patterns
• Slight rotation: Apply getHandDrawnRotation(index) for variation
• Semi-transparent fills: Use fill-opacity from OPACITY constants
• Rounded corners: Use rx attribute with SPACING.borderRadius

3. Template Structure

<template>
  <svg
    :viewBox="`0 0 ${width} ${height}`"
    class="w-full h-auto"
    role="img"
    aria-label="Descriptive label"
  >
    <!-- Elements here -->
  </svg>
</template>

4. Accessibility

• Always include role="img" and aria-label
• Use descriptive labels for screen readers
• Ensure sufficient color contrast

---

Integration with Lessons

In Markdown Files (MDC)

Components are automatically available in markdown via MDC syntax:

Here's how the Scrum framework flows:

::illustration-linear-flow
---
steps:
  - label: Sprint Planning
    color: violet
  - label: Daily Scrum
    color: blue
  - label: Sprint Review
    color: emerald
  - label: Retrospective
    color: amber
---
::

As you can see, Scrum is an iterative process...

In Vue Pages

Import directly from the components directory:

<script setup>
import { IllustrationLinearFlow } from '~/components/illustrations'
</script>

<template>
  <IllustrationLinearFlow :steps="mySteps" />
</template>

---

Common Patterns by Topic

SDLC Topics

• Flow diagrams: IllustrationLinearFlow
• Phase comparison: IllustrationComparisonMap
• Methodology checklist: IllustrationChecklist

DevOps Topics

• Pipeline visualization: IllustrationLinearFlow (horizontal)
• Tool comparison: IllustrationComparisonMap
• Team structure: IllustrationTeamComposition

Agile/Scrum Topics

• Sprint cycle: IllustrationLinearFlow (with feedback loop)
• Team roles: IllustrationTeamComposition
• Definition of Done: IllustrationChecklist
• Scrum vs Kanban: IllustrationComparisonMap

Container Topics

• Deployment flow: IllustrationLinearFlow
• Architecture comparison: IllustrationComparisonMap

---

File Locations

app/
├── components/content/           # MDC components (auto-registered for markdown)
│   ├── IllustrationLinearFlow.vue
│   ├── IllustrationChecklist.vue
│   ├── IllustrationTeamComposition.vue
│   ├── IllustrationComparisonMap.vue
│   └── IllustrationPyramid.vue
└── composables/
    └── useIllustrationDesign.ts

Important: Components must be in components/content/ for MDC syntax to work in markdown files.

---

Quality Checklist

Before completing any illustration:

• [ ] Uses appropriate component (or justified custom SVG)
• [ ] Colors match topic semantics (e.g., emerald for success)
• [ ] Text is readable and not overlapping
• [ ] Has accessible aria-label
• [ ] Renders correctly in dark mode
• [ ] Responsive (uses w-full h-auto)
• [ ] Integrates naturally with lesson content

---

Future Components (Planned)

When these patterns are needed frequently, new components will be added:

• IllustrationTimeline - Events on a timeline
• IllustrationCycle - Circular/cyclic processes
• IllustrationHierarchy - Tree structures (parent-child relationships)
• IllustrationPillars - Supporting pillars diagram

Note: IllustrationPyramid was added to support testing pyramids and layered hierarchies.