人に読ませる資料(報告、草案、比較や判断の資料、事業の資料、開発の説明)を、HTML のページ、Artifact、Markdown で図を中心に作り切るための skill。図の形を選ぶ順、資料の形式と字体、事業の図112種と開発の図38種の見本を持つ

GitHub stars
64

Install

/plugin install figure-docs@u-ichi

Run it inside Claude Code after adding the marketplace with /plugin marketplace add u-ichi/agent-plugins.

Contents

Discovered from source

Skills 1

図を中心にした資料の作り方

  • 言いたいことごとに1文に決め、下の「形を選ぶ順」で形を選んで図を先に描き、文章は図ごとの要点1行にする。節の見出しは題(「市場」)でなく、その1文にする。詳細は畳み、開いた中も図と要点1行で説明する。出す前に、文章を消し、図の中の文字も部品の名前と値だけにして、位置、長さ、線、色で言いたいことが分かるかを見る(文章を先に書いて図を後から足しても、文を図の中へ移しても、図の付いた文章の資料になり、読み手が要点をつかめなかったため)。
  • 3つ以上の部品や人の関係、画面や状態をまたぐ流れ、変更の前と後、時間で変わる数、3つ以上の数の比較、正と負のある内訳は図にする。行と列の欄に文が入る対応は HTML か Markdown の表にし、svg で描かない(svg にするのは、位置、長さ、線が意味を持つときだけ。表を svg で描くと、文字が重なり、直しにくい)。2つのものの関係、分岐の無い短い手順、1つの値は文章で書く。
  • 資料を見せた後の問いにも同じように答える。数の動きや内訳を聞かれたら(なぜ増えたか、いつ足りなくなるか)、数の表で返さず、その問いに答える図を1枚描く(数の表では、読み手が差を自分で計算することになるため)。
  • 図と文章の言葉は、読み手が使っている名前にそろえ、同じものを図と文章で別の名前で呼ばない。作業の中で付けた記号や略称(案 A、証明1)を図に出すときは、何を指すかをその図に書く。見出し、図の中の部品の名前、カードの隅などに出す短い文字は、資料を作った会話も元の資料も知らない読み手が、その文字と上の見出しだけで何を指すか分かる言葉にし、値には何の値かを書く(「要る時:11月末」でなく「承認が要る時期:11月末」)。ほかの資料の見出しを写すときも、元の文脈を外して読めるかで書き直す(名前と値だけに縮めた見出しが、会話を知らない読み手に何の話か分からなかったため)。
  • 形の一覧は目安で、言いたいことに合わなければほかの形を選ぶ(形を1つの表に固定すると、どの資料も同じ型になるため)。

資料の形式

  • 事業の資料は、1つの HTML のページで作る。Claude のように Artifact を作れる環境では Artifact にする。Word や PDF などの形式を名指しされたときはその形式で作る。
  • 開発の説明は、置き場所が GitHub の Markdown(PR の説明、issue、リポジトリの文書)なら、Markdown に Mermaid の図を入れて書く。図の多い説明や、Mermaid で描けない形が要るときは、事業の資料と同じ HTML のページにする。
  • 日本語の文字は、図やグラフの中も含めてゴシック体にし、明朝体を使わない。HTML では Google Fonts の Noto Sans JP を読み込み、font-family: "Noto Sans JP", "Hiragino Sans", "Yu Gothic", Meiryo, sans-serif を指定する(指定しないと明朝体で出る環境があり、読み込まないと端末ごとに字体が変わるため)。
  • 図の中の文字は、何を指すか分かる部品の名前と、何の値か分かる値と、数語の注記にする。文を四角に詰めると図の形をした文章になり、読み手は結局文章を読むことになる。文は図の下の要点1行か、畳んだ詳細に置く。
  • 図は資料の本文の幅に収め、表示したときの文字を 11px より小さくしない。部品が多くて収まらないときは、全体の図と部分の図に分ける。

形を選ぶ順

  1. その図で答える問いを決め、言いたいことを1文に決める(例:「A の市場は B の3倍ある」「決済の失敗は API と外部の決済サービスの間で起きる」)。問いは、読み手がその図を見て何を判断するかから取る。1枚の図は1つの問いに答え、聞かれていない話題を混ぜない。判断がほかの量(人数、件数、時期)に左右されるなら、その量を図の軸か線にする。
  2. その1文が何を比べるか、何を見せるかを、下の「事業の図の分類」か「開発の図の分類」から決める。
  3. 見本のその分類の図から形を選ぶ。事業の図は references/business.html、開発の図は references/dev.html にある。形から先に決めない。
  4. 描き方は、次の順で最初に当てはまるものを使う。
    1. Artifact の側にその形の描き方があればそれを使う。Artifact の側とは、Artifact の tool が作れる種類(Dashboard など)と、その時点の skill の一覧にある Artifact や図の skill(artifact-design、artifact-diagramming、dataviz など)である。数のある図は、dataviz のような数の図の skill があれば先に読む。直す元の資料に同じ図や操作(スライダー、切り替え)があれば、それも使う。Artifact の側は色、明暗の配色、操作まで整っているので、見本で描き直すと劣るため。
    2. 開発の図で、見本に Mermaid の行があり、置き場所が Mermaid を表示できる(GitHub の Markdown、Artifact)なら、その種類の Mermaid で書く。差分で読め、直しやすいため。
    3. どちらも無ければ、見本を写して svg で描く。

見本には、名前、形(何を、どの軸や位置や線や色で描くか)、使う場面、最小の svg が並び、開発の図には描ける Mermaid の種類も添えてある。名前だけで形が浮かばない図は、その図の <figure> を読んで形を写す(ファイルは大きいので、名前で探して読む)。見本の svg は形を示すためのもので、描く手段は決めない。

この順は Gene Zelazny の Say It With Charts(言いたいこと、比べ方、形の順)による。

位置の計算が要る図(Sankey、Chord、Network、Contour map、Treemap など)は、作る側で d3 などを動かして位置を計算し、結果を svg に書き出してページに埋め込む。地図は、都道府県の境界のデータ(npm の jpn-atlas など)を簡略化した path にして埋め込む(事業の図の元の93種を試しに描いたとき、どれもこの方法で描けた。ページを開くたびにライブラリや境界のデータを読み込む方法は試せていない)。

事業の図の分類

数のある図の9分類と図の名前は Financial Times Visual Vocabulary(MIT)による。

分類使う場面
差0、目標、平均などの基準からの上下
相関2つ以上の値の関係。因果と読まれやすいので、因果でなければそう書く
順位値そのものより、並びの中の位置が大事なとき
分布値がどこにどれだけあるか、偏り
時間での変化傾向の変わり方。期間の取り方で印象が変わる
内訳全体を部品に分ける。部品の大きさだけが関心なら「大きさ」
大きさ人数、金額などの数えた量の比較(率や割合でなく)
地理場所や地域の違いがほかの何より大事なときだけ
流れ2つ以上の状態や場所の間を動く量(お金、患者、情報)
数が無い論点位置づけ、構造と分け方、決まった枠組み(SWOT、7S、キャンバス)、役割の分担、手順と時間、関係、因果、確からしさ、優先と判断、前と後

大きさは面積か長さ、確からしさは線の種類(実線、点線)、関係の近さは距離、重みは線の太さで描き分ける。文章では同じ重さに並ぶ差が、図では見える。

数のある図

  • 長さ、面積、位置は値と目盛りから計算して置く。座標を手で決めず、小さい値を見えるように伸ばさない。大きさの差が言いたいことなら、値に比例する形(棒、面積を値に合わせた入れ子の四角)を選ぶ。入れ子、同心円、階段を値に比例させずに使うのは、含む関係や順序だけを言うときにする。そのときは額を形の外に書き、大きさが値を表さないことも図に書く。比例しない大きさに額を添えると、読み手は大きさで比べるためである。
  • 棒の軸は0から始める。対数にするときは軸にそう書く。線や棒を図の端で切らず、値が枠を越えるなら目盛りを広げる。並べて比べる図は同じ目盛りにする。桁の違う値は図を分けるか対数にする。
  • 時間の軸は期間の長さに比例させ、長さの違う期を同じ幅で並べない。
  • 期ごとの額を比べる図は期ごとにその期の額だけを積む。前の期からの増減を描くなら、無くなる項目を減る棒で描く(増えた分だけを積むと、前の期だけの費用が次の期にも残っているように見えるため)。合計と部品を同じ列の棒に並べない。
  • 見込みや推計には幅(Fan chart、範囲つきの棒)を描き、1つの値に見せない。根拠が無く自分で置いた値は、根拠のある値と線や塗りで描き分け、置いた値だと図に書く。
  • 値が無いもの、決まっていないものには大きさも位置も与えず、空の枠と「値なし」の文字で描く。数の無い評価(難しさ、近さ、優先)は棒の長さにせず、3段階ほどの印か並び順で描く(細かい長さは、測った値に見えるため)。
  • 色、縞、線の種類の意味は資料の中でそろえ、意味のある色を使う図には凡例を付ける。

出す前に確かめる

  • 図の中の数の合計を、題、要点、ほかのページの同じ数と突き合わせる。同じ量は1つの計算から出し、古い計算を資料に残さない。
  • 要点の1行はその図から読めることだけにする。図から読めない主張は図に足すか要点から外す。
  • 画面に出して見る(HTML はブラウザで開いて画像に撮る)。文字の重なり、はみ出し、札と線の対応、文字の大きさを確かめる。
  • 既にある資料に足すときは、同じ話の章を書き換える。ページを足すのは新しい話のときだけにする(足し続けると、読み手が今の結論を探せなくなるため)。

開発の図の分類

分類見せること
構造何がどの部品でできていて、境界と依存の向きはどうか
やりとり誰が誰に、どの順で、何を頼み、何が返るか
状態と手順状態がどう変わり、処理がどこで分かれるか
データ何がどこに入り、どう流れ、どう関係するか
配置どこで動き、どの境界をまたいで通信するか
時間いつ何が起き、どの順で進むか
変更前と後で何が変わり、どの順で移すか
性能と信頼性どこで時間や資源を使い、どれだけ失敗してよいか
判断案をどの観点で比べ、何を選ぶか

役割ごとの手順(スイムレーン)、期間の計画(ガント)、条件の分かれ(判断の木)、原因の分解(なぜの木、フィッシュボーン)、量の流れ(Sankey)は、事業の図の見本にある形を使う。

開発の図は次も守る。

  • 1枚の図の四角は6つまでにする。超えるときは、範囲を分けた図にするか、下の連作にする(四角を詰めると、どこを見ればよいかが読み手に分からなくなるため)。
  • どの四角も、ほかの四角と矢印か入れ子でつなぐ。つながらない四角は描かない。
  • 矢印には、何を渡すか(呼び出し、データの名前、方式)を書く。同期の呼び出しは実線、応答や非同期は点線にする。
  • 部品が3つ以上増える構成や、3段階以上の移行は、同じ配置の図を段階ごとに並べ、各段階で1つずつ足す連作にする。
  • 変更の前と後は同じ配置で並べ、足すものを緑、消すものを赤の点線、変えるものを太線にして、変わらない所には印を付けない。
  • 状態の図は、先に状態と遷移(出来事と条件)を一覧にして、抜けと行き止まりを確かめてから描く。

Sponsors

Details

Marketplace
u-ichi/agent-plugins
Source
plugins/figure-docs
Category
Community