svg-illustrations

SVG 插图系统

此技能为 DevOps LMS 提供创建风格一致、高质量手绘风格 SVG 插图的指南。

概述

插图系统采用混合方案：

1. 可复用的 Vue 组件 — 用于常见的图表模式
2. 设计系统组合式函数 — 共享常量和实用工具
3. 自定义 SVG — 仅在没有适用组件时使用（少见）

---

可用组件

1. IllustrationLinearFlow

用途： 按顺序分步展示流程

适用场景：

• CI/CD 流水线
• SDLC 阶段
• Scrum 框架流程
• 任何 A → B → C → D 流程

属性：

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'
}

自动确定方向（无需指定方向）：

步骤数	布局	行为
≤5	水平	并排流程，占满宽度
6-10	垂直	堆叠流程，宽度为 280px
>10	垂直 + 滚动	最大高度为 600px，并支持滚动

如有需要，仍可通过 direction: horizontal 或 direction: vertical 覆盖设置。

MDC 用法：

::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

用途： 具有手绘美感的复选框列表

适用场景：

• 完成定义
• 前置条件
• 验收标准
• 最佳实践列表
• 需求检查清单

属性：

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 用法：

::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

用途： 在容器中展示团队角色及其职责

适用场景：

• Scrum 团队结构
• DevOps 团队角色
• 任何团队／角色图表
• 组织结构图

属性：

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 用法：

::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

用途： 通过连接线并排映射概念

适用场景：

• Scrum ↔ DevOps 映射
• 传统方法与现代方法对比
• 前后对比
• 任何概念映射

属性：

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 用法：

::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

用途： 通过大小表示数量或重要性的金字塔／层级图

适用场景：

• 测试金字塔（单元测试 → 集成测试 → 端到端测试）
• 优先级层级
• 分层架构
• 任何底部最大、自下而上的结构

属性：

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 用法：

::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
---
::

视觉结构：

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

---

尺寸选项

所有插图组件都支持 size 属性，用于控制最大宽度：

尺寸	最大宽度	适用场景
sm	384px	垂直流程、简单图表
md	448px	紧凑的水平流程
lg	512px	中等大小的检查清单
xl	576px	标准插图
2xl	672px	文本较长的检查清单
3xl	768px	宽幅对比图
full	100%	全宽插图（大多数组件的默认值）

各组件的默认尺寸

组件	默认尺寸	原因
IllustrationLinearFlow	自动调整	根据步骤数确定方向和尺寸
IllustrationChecklist	2xl	单列列表不需要占满宽度
IllustrationTeamComposition	full	团队卡片横向展开
IllustrationComparisonMap	full	并排对比需要空间
IllustrationPyramid	xl	带侧边说明的金字塔需要适中的宽度

IllustrationLinearFlow 自动调整尺寸

组件会自动确定布局和尺寸：

• ≤5 个步骤：水平布局，占满宽度
• 6-10 个步骤：垂直布局，宽度为 280px
• >10 个步骤：垂直布局，最大高度为 600px，并支持滚动

何时覆盖默认值

• 仅在超过 5 项时需要水平布局，或不超过 5 项时需要垂直布局的情况下，才覆盖 direction
• 想要更紧凑的外观时，使用 size: md 或 size: lg
• 默认值适用于大多数情况，仅在必要时覆盖

---

设计系统常量

位于 app/composables/useIllustrationDesign.ts

颜色调色板

颜色名称	主色 Hex	浅色 Hex	文本 Hex	用途
violet	#8b5cf6	#a78bfa	#c4b5fd	规划、战略、产品
blue	#3b82f6	#60a5fa	#93c5fd	开发、构建、流程
emerald	#10b981	#34d399	#6ee7b7	测试、成功、完成
amber	#f59e0b	#fbbf24	#fcd34d	警告、重要事项、部署
rose	#f43f5e	#fb7185	#fda4af	严重问题、错误、阻碍
cyan	#06b6d4	#22d3ee	#67e8f9	信息、链接、运维
gray	#6b7280	#9ca3af	#d1d5db	中性、禁用、背景

间距常量

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
}

描边样式

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 = {
  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
}

---

何时使用各组件

决策树

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)

---

创建自定义 SVG（少见情况）

只有在没有合适组件时才创建自定义 SVG。请遵循以下规则：

1. 使用设计系统常量

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

2. 手绘风格规则

• 虚线描边：使用 stroke-dasharray 和设计系统模式
• 轻微旋转：应用 getHandDrawnRotation(index) 以实现变化
• 半透明填充：使用 OPACITY 常量中的 fill-opacity
• 圆角：使用 rx 属性和 SPACING.borderRadius

3. 模板结构

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

4. 无障碍性

• 始终包含 role="img" 和 aria-label
• 为屏幕阅读器使用描述性标签
• 确保具有足够的颜色对比度

---

与课程集成

在 Markdown 文件中（MDC）

通过 MDC 语法，组件会自动在 Markdown 中可用：

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...

在 Vue 页面中

直接从组件目录导入：

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

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

---

各主题的常见模式

SDLC 主题

• 流程图：IllustrationLinearFlow
• 阶段比较：IllustrationComparisonMap
• 方法论检查清单：IllustrationChecklist

DevOps 主题

• 流水线可视化：IllustrationLinearFlow（水平）
• 工具比较：IllustrationComparisonMap
• 团队结构：IllustrationTeamComposition

Agile/Scrum 主题

• Sprint 周期：IllustrationLinearFlow（带反馈环）
• 团队角色：IllustrationTeamComposition
• 完成定义：IllustrationChecklist
• Scrum 与 Kanban 对比：IllustrationComparisonMap

容器主题

• 部署流程：IllustrationLinearFlow
• 架构比较：IllustrationComparisonMap

---

文件位置

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

**重要：**组件必须位于 components/content/ 中，才能在 Markdown 文件中使用 MDC 语法。

---

质量检查清单

完成任何插图之前：

• 使用合适的组件（或说明使用自定义 SVG 的理由）
• 颜色符合主题语义（例如，成功使用 emerald）
• 文本清晰易读且没有重叠
• 包含无障碍 aria-label
• 在深色模式下正确渲染
• 响应式布局（使用 w-full h-auto）
• 与课程内容自然融合

---

未来组件（计划中）

当这些模式频繁出现时，将添加新组件：

• IllustrationTimeline - 时间线上的事件
• IllustrationCycle - 循环流程
• IllustrationHierarchy - 树形结构（父子关系）
• IllustrationPillars - 支撑支柱示意图

注意：已添加 IllustrationPyramid，以支持测试金字塔和分层结构。