Community画像github.com

Unicode Diagrams(ユニコード図表)

アーキテクチャ、システム設計、フロー図をUnicode箱描画文字(┌─┐ │ └─┘ ░ 影)で描きます。テキスト図、ASCII図、箱描画図が必要な場合や、設計書やREADMEに図を入れたい場合に使用します。

Unicode Diagrams(ユニコード図表) とは?

Unicode Diagrams は、開発者がテキストベースのアーキテクチャ図をUnicode箱描画文字で一貫性のあるスタイルで描くためのスキルです。このスキルは、Claude Code、Cursor、CodexなどのAIエージェントが、システム設計やフロー図を生成する際に使用します。MermaidやSVG、画像、絵文字は使用せず、常にフェンスドコードブロック内のプレーンテキストで出力されます。図は80カラム幅がデフォルトで、テキストはすべて大文字に変換されます(一部の単位は例外)。主な構成要素として、コンポーネントボックス(システムの一部)、タイトルボックス(図表のタイトル)、フレームボックス(セクションヘッダーや注意書き)があり、それぞれに異なる線種と影のルールが適用されます。矢印は水平、垂直、屈折、バス(分岐)など様々なタイプに対応し、塗りつぶし矢印(▶)と中抜き矢印(▷)を使い分けることで、同期/非同期などの関係を表現できます。このスキルの核となるエンジンは `/tmp/textdiagram/textdiagram.py` に配置され、毎セッションごとに最新版を配置する必要があります。ユーザーはレイアウトヘルパー( `x_right_of` 、 `y_below` など)を使って座標を計算し、Pythonスクリプトで図を定義してレンダリングします。エンジンは重なりや小さな隙間、不正なレーン値などのエラーを `DiagramError` として報告するため、正確な図が保証されます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rohalrafael/unicode-diagrams/tree/HEAD

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Unicode Diagrams

Unicode箱描画文字を使い、一貫性のある自社スタイルで図をプレーンテキストとして描きます。 常に以下の textdiagram.py グリッドエンジンを使って図を構築すること。手描きは禁止: 手描きの図は位置がずれます。

スタイルルール

  • プレーンテキストをフェンスドコードブロックで記述します。Mermaid、SVG、画像、絵文字は使用しません。
  • 幅:デフォルト80カラム。変更するにはコンストラクタに max_width を渡します。 例: D(max_width=100) 。エンジンは長い行があるとエラーを発生します。
  • すべてのテキストは大文字です。エンジンが自動的に行います:スクリプトには通常のテキストを書いてください。 例外:意味が変わる単位は、以下のように正確に記述した場合にそのまま保持されます: Hz kHz MHz GHz、kB MB GB TB KiB MiB GiB TiB、 kb Mb Gb Tb kbps Mbps Gbps、ms µs ns。NGINXやK8Sなどの単語は大文字になります。
  • コンポーネントボックス(システムの一部:サービス、クライアント、データベース、キュー、ワーカー): 細線 ┌─┐ │ └─┘ と、右1カラム・下1行に薄い影 ░ を付けます。 パーツをグループ化するには、1つのボックスをセクションに分割します:細い区切り線 ├───┤ 、1つの枠、1つの影。
  • タイトルボックス(ドキュメントのメインタイトル、図に1つ):二重線 ╔═╗ ║ ╚═╝ 、影なし。 1行に1アイテム(名前、ドキュメント種別、バージョン)、各行はボックス内で中央揃え。 d.header(...) で作成:エンジンが図全体に対してボックスを中央揃えに配置します。 オプション:左にメタボックス(会社、RFC、日付)、右にスタンプボックス(ステータス)。3つすべての高さは同じになります。 タイトルボックスのパディング行には中央にドット · を配置します。 ヘッダーボックスから矢印を開始・終了することはできません。
  • フレームボックス(セクションヘッダー、注釈、注意書き):細線、影なし。 注釈/注意書き:名前を上枠に配置します(例: ┌─ NOTE ───┐ )。 凡例は追加しないでください:すべての図でスタイルは同じです。
  • フリーテキスト(d.annotate):ボックスのない短いコメント、図の横に配置。使用は控えめに。行が交差してはいけません。
  • 水平矢印:ラベルは線の内側に、両側に1スペースずつ: ── HTTPS ──▶ 。 両端がボックスに接します:線は送信ボックスの影のカラムから始まり、矢印の先が受信ボックスに接します。
  • 垂直矢印:線は下枠の ┬ から始まり、 ▼ で終わります。ラベルは線の右側、影の1行下に配置されます。 またはラベルを線に埋め込む(inline=True):線、空白行、ラベル行(線に中央揃え)、空白行、線。
  • 屈折矢印(d.route):任意の数の屈折、任意の方向(▲ ▼ ◀ ▶)。ラベルは横断セグメント内側、 または上下セグメントの横(もしくは inline=True で埋め込み)に配置。 線が交差または結合する場所には交差点文字(┼ ├ ┤ ┬ ┴)を配置。線がボックスを通過することはありません。
  • バス(d.fan_out):1つのボックスから出て各ターゲットごとに1本の矢印に分岐する線。 ラベルは共有線に配置。
  • 矢印の先:主なフローには塗りつぶし ▶ ◀ ▲ ▼ 。別の種類の関係(非同期、オプション、イベント)には中抜き ▷ ◁ △ ▽ 。 図に2種類の関係が必要な場合のみ中抜きを使用し、凡例ではなくラベルや注釈で意味を明記します。
  • すべての矢印に、何が流れるか(プロトコル、イベント、データ)をラベル付けします。
  • どのボックスがどの役割か不明な場合:システムパーツはコンポーネント、メインタイトルはタイトル、その他はすべてフレーム。

ワークフロー

  1. 描画する前に、コンポーネント、フレーム、矢印をリストアップします。
  2. エンジンを /tmp/textdiagram/textdiagram.py に書き出します(このファイルの最後に完全なソースがあります。 正確にコピーしてください)。毎セッションごとに再度書き出すことで、古いバージョンが使われないようにします。
  3. エンジンをインポートして図を構築する短いPythonスクリプトを記述します。レイアウトヘルパーを使って ボックスを配置します(座標は推測しないこと):
    • Diagram.x_right_of(a, label) — ボックス a の右に次のボックスを配置するためのx座標(矢印ラベルのスペースを含む)。
    • Diagram.x_left_of(a, lines, label) — ボックス a の左に新しいボックスを配置するためのx座標(ラベルのスペースを含む)。
    • Diagram.y_below(a) — ボックス a の下にボックスを配置するためのy座標。インラインラベルあり:Diagram.y_below(a, lines=N)。
    • Diagram.x_centered_under(a, lines) — ボックス a の下に中央揃えでボックスを配置するためのx座標(arrow_v に必要)。
    • ルートレーンには、ボックスの端を使用:a.right + 4、a.bottom + 2。
  4. スクリプトを実行します。DiagramError が発生した場合は、メッセージに従ってレイアウトを修正し、再実行します。
  5. 出力をコードブロックに 印刷されたとおり正確に 貼り付けます。手動で編集しないでください。 変更するには、スクリプトを編集して再実行します。

例1:ヘッダー、セクション、ルート

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()                                                   # max_width=80 がデフォルト
t = d.header(["Order Platform", "Architecture"],
             left=["Acme Inc", "RFC 9000", "Nov 2026"],
             right=["*~~~~~~~~~*", "Deep Dive", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Client"])                             # role="component" がデフォルト
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Gateway"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2,                 # セクション:1つのボックス、1つの影
            [["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls")  # S字
d.arrow_h(svc, cache, "Reads", row=svc.rows[1])           # 1つのセクションに接続
cache = d.box(D.x_left_of(svc, ["Cache"], "Reads"), svc.rows[1] - 1, ["Cache"])
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events")  # 1回屈折
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2],   # ループ:3回屈折
        via=[svc.right + 4, svc.bottom + 2], label="Retry")
print(d.render())

出力:

┌────────────┐               ╔══════════════════╗            ┌───────────────┐
│  ACME INC  │               ║  ORDER PLATFORM  ║            │  *~~~~~~~~~*  │
│  RFC 9000  │               ║   ARCHITECTURE   ║            │   DEEP DIVE   │
│  NOV 2026  │               ║        ·         ║            │  *~~~~~~~~~*  │
└────────────┘               ╚══════════════════╝            └───────────────┘

┌──────────┐            ┌───────────┐                             ┌─────────┐
│  CLIENT  │── HTTPS ──▶│  GATEWAY  │░                            │  AUDIT  │░
└──────────┘░           └─────┬─────┘░                            └─────────┘░
 ░░░░░▲░░░░░░            ░░░░░│░░░░░░░                             ░░░░▲░░░░░░
      │                       │                                        │
      │                       │                                        │
      │                       └───── CALLS ─────┐                      │
      │                                         │                      │
      │                                         ▼                      │
      │                                 ┌─ SERVICES ────┐              │
      │                                 │  AUTH         │─── EVENTS ───┘
      │          ┌─────────┐            ├───────────────┤░
      │          │  CACHE  │◀─ READS ───│  ORDERS       │░
      │          └─────────┘░           ├───────────────┤░
      │           ░░░░░░░░░░░           │  BILLING      │────┐
      │                                 └───────────────┘░   │
      │                                  ░░░░░░░░░░░░░░░░░   │
      │                                                      │
      └─────────────────────── RETRY ────────────────────────┘

例2:バス、中抜き矢印、インラインラベル、フリーテキスト

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()
t = d.header(["Event Bus", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
             right=["*~~~~~~~*", "Draft", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publisher"])
s1 = d.box(36, y - 2, ["Billing"])
s2 = d.box(36, y + 4, ["Audit"])
s3 = d.box(36, y + 10, ["Search"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Events", head="hollow")  # バス、中抜き矢印
arc = d.box(D.x_centered_under(pub, ["Archive"]), D.y_below(pub, lines=2), ["Archive"])
d.arrow_v(pub, arc, "Nightly\nbackup", inline=True)       # ラベルを線に埋め込み
d.annotate(46, y + 16, ["At-least-once", "delivery"])     # フリーテキスト、ボックスなし
print(d.render())

出力:

┌────────────┐        ╔═════════════╗       ┌─────────────┐
│  ACME INC  │        ║  EVENT BUS  ║       │  *~~~~~~~*  │
│  ADR 12    │        ║    DESIGN   ║       │    DRAFT    │
│  NOV 2026  │        ║      ·      ║       │  *~~~~~~~*  │
└────────────┘        ╚═════════════╝       └─────────────┘

                                    ┌───────────┐
                            ┌──────▷│  BILLING  │░
┌─────────────┐             │       └───────────┘░
│  PUBLISHER  │── EVENTS ───┤        ░░░░░░░░░░░░░
└──────┬──────┘░            │
 ░░░░░░│░░░░░░░░            │
                            │       ┌─────────┐
    NIGHTLY                 ├──────▷│  AUDIT  │░
    BACKUP                  │       └─────────┘░
                            │        ░░░░░░░░░░░
       │                    │
       ▼                    │
 ┌───────────┐              │       ┌──────────┐
 │  ARCHIVE  │░             └──────▷│  SEARCH  │░
 └───────────┘░                     └──────────┘░
  ░░░░░░░░░░░░░                      ░░░░░░░░░░░░


                                              AT-LEAST-ONCE
                                              DELIVERY

API リファレンス

  • D(max_width=80) — 図を作成します。max_width はカラム数の上限です。
  • d.box(x, y, lines, role="component"|"frame"|"title", title=None, w=None, align="left") → Box (.x .y .w .h .right .bottom .cx .rows;right/bottom は影を含みます)。 lines は行のリスト、またはボックスを分割するためのセクション(行のリスト)のリストです。 box.rows は各セクションの矢印行を保持します。align="center" でテキストを中央揃えにします。
  • d.header(title, left=None, right=None, y=0) → タイトル Box。各引数は行のリストです。 ボックスの最終的なx座標はレンダリング時に決定されます。図に1つのヘッダーのみ。
  • d.arrow_h(a, b, label="", row=None, head="filled") — a と b が横に並んでいる場合に使用。両方向で動作します。 row でセクション行(a.rows[i])を選択します。head は "filled" または "hollow"。
  • d.arrow_v(a, b, label="", head="filled", inline=False) — b は a の下、その中央に配置されます。 ラベルは複数行("\n")にできます。inline=True の場合は、Diagram.y_below(a, lines=N) でスペースを確保します。
  • d.route(a, a_side, b, b_side, via=(), label="", label_seg=None, a_row=None, b_row=None, head="filled", inline=False) — 辺は "left" "right" "top" "bottom"。線は a の a_side から出て b の b_side に入ります。 len(via) + 2 のセグメントを持ち、横方向と上下方向が交互に並び、a_side から出る方向で始まります。 各 via 値は1つの中間セグメントのレーンで、上下セグメントの場合はx座標、横セグメントの場合はy座標です。 via=[] は1回屈折、1つの値は2回屈折(S字またはU字)、2つの値は3回屈折(ループ)です。 a_row / b_row でセクション行を選択します。label_seg でラベルを配置するセグメント(0から開始)を選択します。
  • d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False) — バス。trunk は共有線のレーン:左右の辺の場合はx座標、上下の辺の場合はy座標。
  • d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled") — 1回屈折、route の簡易形式。 vh:a の下辺から出て、b の側面に入ります。hv:a の側面から出て、b の上辺に降りて入ります。 方向は b の位置に従います。
  • d.annotate(x, y, lines, align="left") → Box(role "text") — フリーテキスト、大文字化されます。 lines はstr("\n" で改行)またはリスト。
  • d.text(x, y, s) — 生テキスト(大文字化されません)。
  • d.render() — 図を返します。ヘッダーを配置し、幅とワイド文字をチェックします。
  • エンジンは、重なり、小さな隙間、不正なレーン値、最大幅を超える行に対して DiagramError を発生します。

シェルが利用できない場合

同じルールで手描きします。その後、各行のカラム数を数えて以下を確認します: 右の影はボックスの右に1カラム;下の影行はボックスの左端から1カラム右に始まり、影のカラムで終わる; すべてのボックスの端が揃っている。

エンジンソース:textdiagram.py

"""textdiagram: 文字グリッド上に整列されたUnicode箱図を描画します。

スタイル:
  すべてのテキストは大文字ですが、KEEP 内の単位は例外です。
  コンポーネントボックス:細線 + 右1カラム・下1行に薄い影 (░)。
  タイトルボックス:二重線、影なし、図全体に対して中央揃え(レンダリング時に配置)。
  フレームボックス:細線、影なし(注釈、注意書き)。
  ヘッダー:タイトルボックスと、オプションのメタボックス(左)およびスタンプボックス(右)。
  タイトルボックスのパディング行には中央にドットを配置。
  セクション:細い区切り線で分割された1つのボックス、ボックス全体に1つの影。
  水平矢印:ラベルは線の内側、両端はボックスに接します:  ── ラベル ──▶
  垂直矢印:ラベルは線の右側、影の1行下。
  ルート:レーン座標(via)で設定された任意の数の屈折を持つ矢印。
  矢印の先:塗りつぶし (▶) または中抜き (▷)。fan_out:1本の線から複数の矢印に分岐。
  上下線上のラベル:線の横、または線に埋め込まれます(inline=True)。
  annotate:ボックスなしのフリーテキスト。
"""
import re
import unicodedata

SHADOW = "░"
MIN_DASH = 2  # 矢印ラベルの両側のダッシュ数
HEADER_GAP = 2  # ヘッダーボックス間のカラム数

# 意味が変わる単位(MB=バイト、Mb=ビット、ms=ミリ秒、MS=メガ秒)。
# 単語は、以下のいずれかと完全に一致する場合にのみ保持されます。
KEEP = {
    "Hz", "kHz", "MHz", "GHz",
    "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
    "kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
    "ms", "µs", "ns",
}

# 箱描画文字を腕の集合として定義:2本の矢印線が出会う場所では、
# 腕が1つの交差点文字(┼、├、...)に結合されます。
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
        "├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v):

…

[翻訳のため省略]

関連スキル