marp-deck-visual-designer

Name: marp-deck-visual-designer
Author: raffaelecamanzo

github.com/raffaelecamanzoドキュメント138 回インストール5 週間前に更新

リポジトリ

marp-deck-visual-designer について

既存のプレゼンテーション計画を、MARP デッキの具体的なレイアウトとビジュアルに落とし込むスキルです。スライドの順序と意図を保ち、テンプレートに基づいてレイアウトや Mermaid、Excalidraw を選びます。

主な機能

01スライド順と意図の維持
02テンプレートからのレイアウト選択
03Mermaid または Excalidraw によるビジュアル作成
04Markdown のビジュアル設計書を出力

活用シーン

01完成済みスライド計画のレイアウト設計
02計画されたビジュアルに適した図の選択

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/raffaelecamanzo/skills --skill marp-deck-visual-designer

インストール後、Claude Code で/marp-deck-visual-designerを入力して読み込まれたか確認します。

詳細

Marp ビジュアルデザイナー

目的

既存のプレゼンテーション計画を、MARP デッキのビジュアルとレイアウトの設計に変換します。

このスキルでは、次のことを行います。

スライドの意図と順序を維持します
デッキテンプレートのすべてのパターンライブラリから、具体的なレイアウトを定義します
計画されたビジュアルをMermaid 図またはExcalidraw の描画として具体化し、それぞれのビジュアルに最適なものを選びます

このスキルでは、次のことを行ってはいけません。

デッキを再計画する
重要なメッセージを変更する
スライドを追加または削除する
新しい概念を導入する

プレゼンテーション計画を最優先とします。

入力

planning/deck-plan.md — marp-deck-planner が作成
.marp/references/deck-template.md — 必須の参照資料：利用可能なすべてのレイアウトパターン、クラス名、HTML 構造、コンテンツの上限を定義します。レイアウトを割り当てる前に、全文を読みます。

出力形式

単一の Markdown ファイルを作成し、planning/deck-visual-design.md として保存します。

計画と完全に同じ順序でスライドを並べ、スライド間の区切りとして -- を使用します。

スライドの構成

各スライドについて、次を出力します。

## Title
## Layout
## Content placement
(任意) ## Image

セクション区切りスライドに含めるのは、次の項目のみです。

## Section
## Layout

ワークフロー

0. デッキテンプレートを読む（最初に必ず実行）

レイアウトについて判断する前に、.marp/references/deck-template.md を全文読みます。

このドキュメントは、次の事項の信頼できる情報源です。

利用可能なすべての CSS クラスとレイアウトパターン
有効なクラスの組み合わせ
各パターンで必要な HTML 構造
パターンごとのコンテンツの上限（箇条書き、カード、列）

箇条書きは最終手段のレイアウトです。 デッキテンプレートに適合するパターンがない場合にのみ、単一列の箇条書きを使用してください。各スライドで、より適したパターンを積極的に探してください。

コンテンツの種類	推奨パターン
4つの並列した発見事項／洞察	`insight-cards`（2×2 グリッド）
数字＋ラベル＋説明から成る3項目	`numbered-cards`
3～5段階の横並びのステップ	`timeline-steps`
コネクターでつながった3つの連続するフェーズ	`phase-cards`
ラベル＋説明を縦に並べた4～6行	`feature-layers`
目次	`toc-rows`
対比する2つのブロック	`columns two-col duo` または `columns compare split-panels`
テキスト＋図／画像	`visual-split`
テキスト＋補足統計または引用	`highlight-layout` と `highlight-box`
大きな単一のコールアウト	`hero` と `impact-list`
データグリッド／比較表	HTML の `<table>`
6つの重点領域	`labs-grid`

より適したパターンがある場合は、必ず使用してください。箇条書きに頼らないでください。

1. 構造と順序を維持する

計画に記載された正確なスライド順に従います
スライドの名前変更、統合、分割を行いません
セクションスライドはセクションスライドのままにします

2. レイアウトを明示する

## Layout では、次の内容を指定します。

最初にスライドのクラスのトークンを記述します（必須）。次の形式を厳守してください。
- Slide class: content ...（例：Slide class: content visual-split no-top-accent）
デッキテンプレートにあるレイアウトの種類（自由形式の説明は不可）
該当する場合は相対的な比率（例：60/40 の分割）
視覚的な階層（主要領域と副次領域）

.marp/references/deck-template.md に記載された、具体的かつ MARP と互換性のあるクラス名を使用してください。

抽象的な表現や、見た目だけに関する表現は避けてください。

3. コンテンツを意図的に配置する

## Content placement では、次の内容を説明します。

使用するデッキテンプレートのパターンと、その HTML コンテナクラス
そのパターン内での各コンテンツブロックの配置
カード、行、列、コールアウトへの項目のグループ化
強調ルール（ハイライト、要点、フッターノート）

コンテンツを書き換えたり、追加したりしないでください。

4. ビジュアルを具体化する

計画内の該当スライドに ## Image セクションがある場合：

4.1 視覚表現を決定する

ファイルを作成する前に、次の基準に従って形式を選択します。

Mermaid を使用する場合：

視覚表現が、順序のあるフロー、プロセス、または状態機械である
構造をフローチャート／グラフのノードとエッジの意味に明確に対応付けられる
階層関係または方向性のある関係が中心的な意味を持つ
例：パイプラインの手順、アーキテクチャの依存関係グラフ、シーケンス図

Excalidraw を使用する場合：

視覚表現が、明確な方向性のないハブ・アンド・スポーク型または有機的なネットワークである
アイデアが Mermaid の定義済みの図の種類に当てはまらない（明確なソース→ターゲットのエッジがない）
空間的な配置やグループ分けが意味を伝える（例：クラスター、近接性）
厳密なグラフよりも、自由形式のスケッチ風の表現が内容に適している
例：チーム／ラボの組織図、エコシステムマップ、概念の概要図

4.2 Mermaid 図を生成する（該当する場合）

計画した視覚表現を図で表すのが最適な場合：

Mermaid 図のソースファイルを作成します：diagrams/<diagram-name>.mmd
図は、計画した視覚表現の説明を直接反映する必要があります
図は簡潔で読みやすいものにします

Mermaid のスタイル設定（必須）

すべての Mermaid レンダリングで、共通のデッキ設定を使用します：

.marp/references/mermaid-config.json

ルール：

Mermaid のデフォルトの色に依存しないでください。
図は主にニュートラルな色を使用し、アクセントカラーは1色にします（設定で指定されています）。
意味を表すために必要な場合のみ、追加の classDef スタイルを使用し、mermaid config のパレットに統一します：
- 主な境界線／線の色：#da291c（SO accent / red-500）
- テキスト：#3d3935（merlin）
- 控えめな色：#716b5d（merlin-600）

図のルール（必須）

まずスライドのクラスを選択し、そのクラスに合わせて図を設計します：
- デフォルト：visual-split
- レンダリングした PNG のアスペクト比が > 2.8 の場合：image-wide を追加
- レンダリングした PNG のアスペクト比が < 0.8 の場合：image-tall を追加
可能な場合、図のアスペクト比は 1.1～2.6 を目標にします（visual-split に最も収まりやすい比率です）。
グリッドレイアウトを明示的に計画している場合を除き、1枚のスライドにつき図／画像は1つにします。
ラベルは短くします：
- 1行あたり 4語以下を目安にします
- 長いテキストは改行します（Mermaid のラベルでは <br/> を使用）
フローの方向：
- 4つ以上のノードには flowchart TB を優先します
- 左から右への意味が不可欠な場合のみ LR を使用します
長い単一路線の連鎖は避け、幅が極端にならないよう、コンパクトなグループ／サブグラフに分割します。
ループ図は、横に引き伸ばされたループではなく、コンパクトな循環形状にします。

.mmd ファイルを書いた後：

図をレンダリングします：
- 推奨：task mermaid-file FILE=diagrams/<diagram-name>.mmd
- または、すべての図を再構築します：task mermaid
デッキをレンダリングする前に、レンダリングされた PNG の寸法を検証します：
- task mermaid-check-file FILE=diagrams/<diagram-name>.mmd
- 図が平坦すぎる、または縦長すぎる場合は、まず .mmd の構造（方向、グループ分け、ラベルの改行）を調整し、その後再レンダリングします。
生成した画像を ## Image で次のように参照します：images/<diagram-name>.png

ルール：

図の名前は一貫して決定的で、内容を説明するものにします
明示的に必要とされる場合を除き、1枚のスライドにつき図は1つにします
装飾目的で図を生成しないでください

視覚表現が図でない場合は、ファイルを生成せずに説明します。

4.3 Excalidraw の図を生成する（該当する場合）

4.1 の判断基準で Excalidraw が選択された場合：

ファイル名

次のファイルを作成します：diagrams/<diagram-name>.excalidraw
名前は一貫して決定的で、内容を説明するもの（小文字、ハイフン区切り）にします

エクスポートツール

task excalidraw-file は @napi-rs/canvas（Node 18+）を使用し、node .marp/scripts/render-excalidraw.js でレンダリングします。Docker への依存はありません。

前提条件 — プロジェクトのルートに package.json が存在する必要があります。 task excalidraw-file はレンダリングのたびに npm install を実行します。プロジェクトに package.json がない場合、インストールはエラーを出さずに失敗し（終了コード 254）、PNG は生成されません。

初めて task excalidraw-file を実行する前に、ファイルがあるか確認してください。
ls package.json 2>/dev/null || echo "missing"
ファイルがない場合は、作成してください。
{
  "name": "deck-builder",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@napi-rs/canvas": "^0.1.65"
  }
}
その後、タスクを実行する前に npm install を手動で一度実行してください。以降の task excalidraw-file の実行では、インストール済みのモジュールが再利用されます。

有効な JSON 構造

.excalidraw ファイルは、スキーマバージョン 2 に準拠した有効な JSON である必要があります。

{
  "type": "excalidraw",
  "version": 2,
  "source": "marp-visual-designer",
  "elements": [ ... ],
  "appState": {
    "gridSize": 20,
    "gridStep": 5,
    "gridModeEnabled": false,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

要素の作成ルール

図形 — ほとんどのノードには rectangle を使用し、あらゆる方向にスポークが伸びる真の放射状ハブである場合にのみ ellipse を使用します。

どちらにも必要なプロパティ： id、type、x、y、width、height、angle: 0、strokeColor、backgroundColor、fillStyle: "solid"、strokeWidth、roughness: 0、opacity: 100、groupIds: []、isDeleted: false、boundElements: [...]、locked: false

テキストラベル — 親を指す containerId を設定し、図形ごとに text 要素を 1 つ使用します。

x、y、width、height は親図形と完全に一致する必要があります
必須の追加プロパティ：text、fontSize: 14、fontFamily: 1、textAlign: "center"、verticalAlign: "middle"、containerId: "<shape-id>"、originalText: "<same as text>"、lineHeight: 1.25
親図形の boundElements に {"type": "text", "id": "<text-id>"} を含める必要があります
複数行のテキスト：JSON 文字列値には、リテラルの改行文字 \n を使用します

矢印 — 静的エクスポートでは、常に明示的な座標 points を指定し、バインディングを null にします。

startBinding: null、endBinding: null
startArrowhead: null、endArrowhead: "triangle_outline"
points は、矢印自身の x, y を基準とする [dx, dy] オフセットの配列です。最初の点は常に [0, 0] です
A の右側から B の左側へ直線の矢印を引く場合：矢印の x, y を A の右中央に設定し、points: [[0, 0], [gap, 0]] とします
エルボー型のコネクター（例：行折り返し）には、4 点のパスを使用します。 points: [[0, 0], [0, down], [left_offset, down], [left_offset, down + drop]] ここで down は垂直方向の中間点、left_offset は負の値（左方向への移動）です

必須プロパティ：id、type、x、y、width、height、angle: 0、strokeColor、backgroundColor: "transparent"、fillStyle: "solid"、strokeWidth: 2、roughness: 0、opacity: 100、groupIds: []、isDeleted: false、boundElements: []、locked: false、points、startBinding、endBinding、startArrowhead、endArrowhead

グループ化：論理的なグループ内のすべての要素で、同じ文字列を groupIds 配列に割り当てます

ブランドカラーパレット（必ず従ってください）

用途	色
プライマリハブ／主要な概念	線 `#da291c`、塗り `#ffffff`、線幅 `3`
セカンダリノード／カード	線 `#716b5d`、塗り `#f4f4f2`、線幅 `2`
アクセント要素（例：ターミナル／結果ノード）	線 `#e35205`、塗り `#ffffff`、線幅 `2`
テキスト	`#3d3935`
フロー矢印（同じ行）	線 `#3d3935`
エルボー型の行間コネクター	線 `#da291c`
背景	`#ffffff`

アスペクト比の予測（エクスポート前に使用）

.marp/scripts/render-excalidraw.js では、左右それぞれに固定の PADDING = 24px と scale = 2× を使用します。エクスポート前に、以下の正確な式で PNG の出力サイズを予測してください。

content_width  = max(element.x + element.width)  − min(element.x)   [all non-arrow elements]
content_height = max(element.y + element.height) − min(element.y)    [all non-arrow elements]

exported_width  = (content_width  + 48) × 2   [exact: PADDING=24 each side, 2× scale]
exported_height = (content_height + 48) × 2   [exact: same]

predicted_ratio = (content_width + 48) / (content_height + 48)
                  [the ×2 cancels; ratio is scale-independent]

デザインルール：快適な visual-split の配置にするため、predicted_ratio を 1.8–2.4 にします（安全範囲の 1.1–2.6 に十分収まります）。この式は正確で、丸め誤差はありません。推奨される初期値 inter_row_gap ≈ 1.4 × node_height を使うと、150×75 px のノードを3つずつ2行に配置した場合、自然に比率は約 1.81 となり、最初の試行で目標範囲に収まります。

空間レイアウトのガイド

1行のチェーン（最大4ノード）：ノードを左から右に20–30pxの間隔で配置し、ノード間を直線の矢印でつなぎます。
複数行のチェーン（5つ以上のノード、または1行にした場合の比率が2.6を超えるとき）：2行に分け、各行のノード数を同数またはほぼ同数にします。
- 1行目：y = 30、2行目：y = 30 + node_height + inter_row_gap
- predicted_ratio が1.8–2.4になるように inter_row_gap を選びます： inter_row_gap ≈ (1.4 × node_height) を信頼できる初期値として使用できます
- 1行目の最後のノードと2行目の最初のノードを、赤い折れ線矢印でつなぎます：
  - 始点は1行目の最後のノードの下辺中央にします
  - 終点は2行目の最初のノードの上辺中央にします
  - 中点は始点から down = inter_row_gap / 2 の位置にします
- 2行目のノード数が1行目より少ない場合は、2行目を水平方向の中央に配置します
各ノードの基準サイズは、幅 140–160px × 高さ70–80px とします。

エクスポートと検証

.excalidraw ファイルを作成した後：

上記の式で比率を予測し、必要に応じてエクスポート前にレイアウトを調整します。
エクスポートします：task excalidraw-file FILE=diagrams/<diagram-name>.excalidraw
実際の PNG の寸法を検証します：task mermaid-check-file FILE=diagrams/<diagram-name>.excalidraw
- 検証スクリプトは、ソースの形式にかかわらず PNG IHDR バイトを読み取ります。
実際の比率が目標範囲外の場合：inter_row_gap またはノードの位置を調整し、再エクスポートします。

生成した画像は ## Image に次のように記載します：images/<diagram-name>.png

ルール：

図の名前は、決定的で内容がわかるものにします
明示的な要件がない限り、スライドごとに図は1つにします
装飾目的の図は生成しません

5. MARP の制約を守る

すべてのレイアウトとビジュアルは、以下に対応している必要があります：

静的な Markdown スライド
CSS ベースのテーマ設定
PDF / HTML エクスポート

以下は避けてください：

アニメーション
インタラクティブ要素
レイヤー構造や動的なビジュアル

セクション区切りスライド

セクションスライドでは：

次のような最小限のレイアウト指示のみを記載します：
「セクションタイトルをスライド全体の中央に配置」
「追加要素のないシンプルな区切りスライド」

セクションスライドにビジュアルや図は使用しません。

品質チェック（必須）

最終確定の前に、以下を確認してください：

レイアウトを割り当てる前に .marp/references/deck-template.md を読んだ
デッキテンプレートのパターンがより適している箇所で、スライドに箇条書きを使用していない
Mermaid と Excalidraw の選択は、好みではなくコンテンツの構造に基づいて判断されている
スライドの順序が計画と完全に一致している
新しい情報や解釈を加えていない
図が計画されたビジュアルを厳密に反映している
生成した図がすべて正しく参照されている
出力が MARP デッキの制作にすぐ使用できる
PDF QA：通常のズームでラベルが読みづらい場合は、CSS だけでなく、まず図の構造を修正する

成果物は探索的なものではなく、すぐに実行できる状態でなければなりません。

Markdown 対応

ログインしてコメント

基本情報

作者: raffaelecamanzo
リポジトリ: raffaelecamanzo/skills
カテゴリ: ドキュメント
インストール数: 38
GitHub スター: 1

問題を報告