
figure-docs
人に読ませる資料(報告、草案、比較や判断の資料、事業の資料、開発の説明)を、HTML のページ、Artifact、Markdown で図を中心に作り切るための skill。図の形を選ぶ順、資料の形式と字体、事業の図112種と開発の図38種の見本を持つ
- GitHub stars
- 64
Install
/plugin install figure-docs@u-ichiRun it inside Claude Code after adding the marketplace with /plugin marketplace add u-ichi/agent-plugins.
Contents
Discovered from sourceSkills 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文に決める(例:「A の市場は B の3倍ある」「決済の失敗は API と外部の決済サービスの間で起きる」)。問いは、読み手がその図を見て何を判断するかから取る。1枚の図は1つの問いに答え、聞かれていない話題を混ぜない。判断がほかの量(人数、件数、時期)に左右されるなら、その量を図の軸か線にする。
- その1文が何を比べるか、何を見せるかを、下の「事業の図の分類」か「開発の図の分類」から決める。
- 見本のその分類の図から形を選ぶ。事業の図は references/business.html、開発の図は references/dev.html にある。形から先に決めない。
- 描き方は、次の順で最初に当てはまるものを使う。
- Artifact の側にその形の描き方があればそれを使う。Artifact の側とは、Artifact の tool が作れる種類(Dashboard など)と、その時点の skill の一覧にある Artifact や図の skill(artifact-design、artifact-diagramming、dataviz など)である。数のある図は、dataviz のような数の図の skill があれば先に読む。直す元の資料に同じ図や操作(スライダー、切り替え)があれば、それも使う。Artifact の側は色、明暗の配色、操作まで整っているので、見本で描き直すと劣るため。
- 開発の図で、見本に Mermaid の行があり、置き場所が Mermaid を表示できる(GitHub の Markdown、Artifact)なら、その種類の Mermaid で書く。差分で読め、直しやすいため。
- どちらも無ければ、見本を写して 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