svg-illustrations

SVG イラストレーションシステム

このスキルでは、DevOps LMS 向けに一貫性のある高品質な手描き風 SVG イラストレーションを作成するためのガイダンスを提供します。

概要

このイラストレーションシステムでは、ハイブリッドなアプローチを採用しています。

1. 再利用可能な Vue コンポーネント - 一般的な図のパターン向け
2. デザインシステムのコンポーザブル - 共通の定数とユーティリティ
3. カスタム SVG - どのコンポーネントも適さない場合に限ります（まれ）

---

利用可能なコンポーネント

1. IllustrationLinearFlow

目的： 順序に沿って段階的に進むプロセス

最適な用途：

• CI/CD パイプライン
• SDLC フェーズ
• Scrum フレームワークのフロー
• A → B → C → D のような任意のプロセス

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

自動方向設定（方向の指定は不要）：

ステップ数	レイアウト	動作
≤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

目的： 手描き風のチェックボックス形式のリスト

最適な用途：

• 完了の定義
• 前提条件
• 受け入れ基準
• ベストプラクティスのリスト
• 要件チェックリスト

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 の使用方法：

::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 チームの役割
• チームや役割を示す任意の図
• 組織図

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 の使用方法：

::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 のマッピング
• 従来のアプローチと最新のアプローチ
• ビフォー／アフターの比較
• 任意の概念マッピング

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 の使用方法：

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

目的： サイズで数量や重要度を表すピラミッド／階層図

最適な用途：

• テストピラミッド（Unit → Integration → E2E）
• 優先度の階層
• レイヤードアーキテクチャ
• 土台が最も大きい、下から上へ構成する任意の構造

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 の使用方法：

::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	1 列のリストに全幅は必要ありません
IllustrationTeamComposition	full	チームカードを横方向に広げます
IllustrationComparisonMap	full	横並びの比較にはスペースが必要です
IllustrationPyramid	xl	側面の説明を含むピラミッドには、適度な幅が必要です

IllustrationLinearFlow の自動サイズ設定

このコンポーネントはレイアウトとサイズを自動的に決定します。

• ≤5 ステップ：横方向のレイアウト、全幅
• 6-10 ステップ：縦方向のレイアウト、幅 280px
• >10 ステップ：縦方向のレイアウト、最大高さ 600px でスクロール

デフォルト設定を上書きする場合

• 5 項目を超える場合に横方向にする、または 5 項目以下の場合に縦方向にするなど、特に必要な場合に限り direction を上書きしてください
• よりコンパクトな見た目にしたい場合は、size: md または size: lg を使用してください
• ほとんどの場合、デフォルト設定で問題ありません。必要な場合に限り上書きしてください

---

デザインシステムの定数

app/composables/useIllustrationDesign.ts にあります

カラーパレット

色名	メインカラーの16進数値	ライトカラーの16進数値	テキストカラーの16進数値	用途
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 を使用します
• 角丸：SPACING.borderRadius とともに rx 属性を使用します

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 のトピック

• スプリントサイクル：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

重要： Markdown ファイルで MDC 構文を使用できるようにするには、コンポーネントを components/content/ に配置する必要があります。

---

品質チェックリスト

イラストを完成させる前に、次の項目を確認してください。

• 適切なコンポーネントを使用している（またはカスタム SVG を使う理由が明確である）
• 色がトピックの意味に合っている（例：成功には emerald）
• テキストが読みやすく、重なっていない
• アクセシブルな aria-label がある
• ダークモードで正しく表示される
• レスポンシブである（w-full h-auto を使用）
• レッスンの内容に自然に溶け込んでいる

---

今後追加予定のコンポーネント

次のパターンが頻繁に必要になった場合、新しいコンポーネントを追加します。

• IllustrationTimeline - 時系列上のイベント
• IllustrationCycle - 円形／循環するプロセス
• IllustrationHierarchy - ツリー構造（親子関係）
• IllustrationPillars - 支柱の図

注：テストピラミッドや階層構造をサポートするため、IllustrationPyramid を追加しました。