docs-diagrams

ドキュメントの図

ドキュメントですでに公開されている図を参考にしてください。これらの図には、薄いグリッドの背景、柔らかな影付きの枠線パネル、グレーのスケルトン UI、グレーの矢印、そしてそれぞれに一貫した意味が割り当てられた小規模なアクセントカラーのパレットが共通しています。このスキルでは、コードからそのビジュアルスタイルを再現します。

ファイル

タスク	確認するファイル
色、サイズ、フォント、各色の意味、図形の構造	style-tokens.md
引き渡す前にレンダリング結果を確認する	review-checklist.md
プリミティブ：キャンバス、パネル、ツリーの行、ウィンドウ、穴、バッジ	scripts/lib.mjs
すべての図モジュールの SVG と HTML を生成する	scripts/gen.mjs
ライトモードとダークモードの PNG を 2x でスクリーンショットする	scripts/render.sh
インク部分からレンダリング結果の余白を測定する	scripts/measure.py

ワークフロー

1. mdx を読む

<Image> ブロックには、ファイル名（srcLight="/docs/light/<name>.png"）、ページで確保される width と height、そして要件を示す alt テキストが記載されています。

画像の前の段落には、色の凡例が言葉で示されていることがよくあります（「グレーは静的な出力、青はリクエスト時にレンダリングできるコンテンツを示します」など）。その場合、図はその文と正確に一致させる必要があります。そうでない場合は、alt テキストで示された状態（Suspense のフォールバック、リクエスト時のコンテンツ）を、style-tokens.md の「色の意味」に従って割り当て、引き渡し時に mdx へ凡例の文を追加するよう提案してください。

要件に記載されたものだけを描画してください。alt テキストと前後の段落によって、表示する値、行、ラベルが決まります。ラベルには alt テキストにあるものを使い、要件で明示されていない用語には docs/01-app/04-glossary.mdx を参照してください。

2. ドキュメントから参考画像を取得する

画像はこのリポジトリにはなく、ドキュメントの blob ストアから配信されています。描画を始める前に、存在する画像を一覧表示し、似た内容を説明している画像を 2、3 点、両方のテーマで取得してください。

grep -rhoE 'srcLight="[^"]+"' docs | sort -u
curl -sL -o ref.png "https://h8DxKfmAPhn8O0p3.public.blob.vercel-storage.com/docs/light/nested-layouts.png"

完全な srcLight パスを使ってください。画像の多くは /docs/ 以下にありますが、一部は /learn/ 以下にあります。ダークモード用の画像には、light を dark に置き換えてください。描画対象のページにすでに画像がある場合は、それらを最初に参考にしてください。複数の画像を確認してください。構造は一貫しているため、1 枚だけの癖ではなく、共通する部分を取り入れるようにします。公開済みのファイルには 1x と 2x が混在していますが、これはこれまでの経緯によるものです。目標ではありません。必ず 2x で作成してください。

3. 図のモジュールを作成する

scripts/ をリポジトリの外にある作業用フォルダーにコピーし、diagrams/<name>.mjs を追加します。

export default {
  name: 'my-diagram', // must equal the mdx srcLight basename
  width: 1600, // what the mdx declares
  height: 700,
  draw(t, lib, { width, height }) {
    const k = width / 1600
    const s = []
    // compose lib primitives here, laid out from a few named constants
    return s.join('\n')
  },
}

lib.mjs には、ドキュメントの図を構成する図形が用意されています。

• パネルと行：panel、treePanel、urlPill、urlStack、codePanel。
• 矢印とキャプション：arrow、bracketArrow、bracketCaption、callout。
• ブラウザーウィンドウ：フレーム用の browserWindow(t, x, y, w, h, url, body = '')、ウィンドウ内のページ用の pageLayout、コンテンツ用の postCard と commentRows、単一のプレースホルダー用の skel.*。URL と本文は位置引数として渡します。
• 状態と比較：hole（まだ描画されていない状態）、card（描画済み、またはハイライト表示）、grid（バーの列とスパン）。
• バッジと凡例：badge、statusBadge、legendRow、swatchLegend。
• テキスト：label、code、ラベルを囲むブロックのサイズを調整する textWidth、および icons。

ウィンドウ内のページは、スケルトンのパーツを手作業で配置するのではなく、pageLayout で構成します。これを使うと、プレースホルダーをページらしく見せるための間隔が適用され、コンテンツ列を一般的な投稿とコメントに分ける regions.post と regions.comments が返されます。

説明に複数の時点や段階（前後、Shell → Prefetch → Navigation など）がある場合、ドキュメントではブラウザーウィンドウを矢印でつないで横一列に並べ、各ウィンドウにその時点のページを表示します。ある時点ですでに描画されているコンテンツは、その後のすべての時点でも同じスタイルで描画したままにします。各時点の値や API を比較する必要がある場合は、ウィンドウの間隔に合わせて区切ったバーの行を下に配置します。grid はそのバーをレイアウトするためのもので、列見出しはウィンドウの下に置き、各ウィンドウのキャプションも兼ねます（2つの位置をそろえる方法は grid のコメントを参照してください）。ウィンドウを使う必要がない場合は、grid だけを使います。

名前付き定数を使って図のブロックをレイアウトし、キャンバスの中央に配置します。lib にない図形が必要な場合は、既存のトークンを使い、同じスタイルで lib.mjs に追加してください。そうすれば、次の図でも使えます。図形内に色やその場限りのオフセットをハードコードしないでください。

1つのモジュールから、同じ図を構成する複数の図を配列としてエクスポートできます。default export のないヘルパーモジュールはスキップされます。

4. レンダリングする

作業用フォルダー内で ./render.sh を実行します。このスクリプトは node gen.mjs を実行し、ヘッドレス Chrome で各 <name>-<theme>.html を --force-device-scale-factor=2 を指定してスクリーンショットにします。出力先は light/<name>.png と dark/<name>.png で、mdx が想定する名前です。作成中に図を1つだけ再生成するには、node gen.mjs <name> を実行します。

スクリプトでは、macOS の Google Chrome のパスがデフォルトで使われます。Linux、Windows、または Chrome が別の場所にインストールされている環境では、ブラウザーの実行ファイルを CHROME に設定します。

CHROME=/path/to/chrome ./render.sh

5. 確認する

両方の PNG を原寸で確認し、review-checklist.md およびステップ 2 の参考資料と照らし合わせます。余白を確認するには、python3 scripts/measure.py light/<name>.png を実行します。定数を修正して再レンダリングしてください。実物を確認していない PNG は引き渡さないでください。

6. 引き渡す

PNG のピクセル寸法と、それぞれに対応する mdx のパスを添えて納品します。blob ストアへのアップロードはドキュメントメンテナーが手作業で行うため、納品物は PNG であり、コミットではありません。mdx の srcLight のベース名と PNG の名前が、単数形か複数形かも含めて一致していることを確認します。lib.mjs にプリミティブを追加した場合は、このスキルにコミットするか、コミットできない場合は差分を引き渡してください。

ドキュメントでよく使われる図

公開されている図は、いくつかの形状を組み合わせて作られています。よく使われる種類を以下に示します。それぞれの例を確認できるページも記載しています。ほかにも種類があり、新しい概念には新たな組み合わせが必要になる場合があります。

• ファイルツリー → URL：ファイルツリーのパネル（フォルダー、ファイル、レイアウト、ルートのアイコン。対象ページの行は太字で青いドット付き。省略された子要素はグレーの ... 行）から、グレーの矢印で URL のピル（地球儀 + パス。ルーティングできないパスはグレーで塗りつぶし）へつなぎます。ツリーの横にある括弧付きの矢印は、どのレイアウトがどのルートを囲むかを示し、等幅フォントのステータスバッジ（Routable、Not Routable）も表示します。レイアウトとページとプロジェクト構成を参照してください。
• ファイル → コンポーネント階層：ファイル一覧から、コードパネル（バーに React のロゴとタイトルがあり、入れ子になった JSX をドキュメントの構文カラーで表示）へ矢印でつなぎます。プロジェクト構成を参照してください。
• スケルトン UI を表示したブラウザーウィンドウ：信号機アイコンと URL のピルがあり、ページはグレーのスケルトン形状（アバター、バー、サイドバー、画像のプレースホルダー）で表します。まだ描画されていないコンテンツは破線の穴で、表示されたコンテンツや主題となるコンテンツはアクセントカラーのカードで示します。カードは青い矢印とともにウィンドウの外側に浮かべることもあります。矢印でつないだウィンドウの列は一連の流れを示し、下の括弧付きのキャプションはグループ名を示します。データの取得とキャッシュを参照してください。
• バッジ付きの領域マップ：ウィンドウ内の領域をカテゴリ別に枠線で囲み、色を付けて、それぞれに文字のバッジを付けます。引き出し線には注釈を添え、凡例も表示します。同じバッジをツリーの行やコードパネルの行にも付けて、各ビューを相互に参照できるようにします。並列ルートを参照してください。
• ゾーングラフ：色分けされた破線のボックスの隅にタグを付け、ボックス内に等幅フォントのルートのピルを配置します。ボックス同士はグレーの矢印でつなぎ、矢印には等幅フォントのピル（SOFT NAV、HARD NAV）を添えます。マルチゾーンを参照してください。

ドキュメントの画像には、製品のスクリーンショット（DevTools のパネル、バンドルアナライザー、OS のダイアログ）もあります。これらは実際の UI からキャプチャしてください。このスキルでは作成しません。

規約

キャンバス。 ドキュメントのキャンバス幅は 1600 CSS px で、ページ側でカラム幅に合わせて拡大・縮小されるため、トークン内のサイズは幅 1600 の場合のサイズです。新しい図では幅を 1600 に指定し、高さはコンテンツに合わせます。ページですでに幅が狭く指定されている場合は、その幅に合わせて要素のサイズを k = width / 1600 で縮小してください。そうしないと、ページで拡大・縮小されたときに、図が隣の図より大きく表示されます。grid、swatchLegend、arrow、pageLayout、postCard、commentRows は k を受け取るか算出して、デフォルト値をそれに応じて縮小します。skel.*、hole、card には、自分で × k のサイズを渡してください。

余白。 mdx の height が優先されます。コンテンツを、指定されたボックスに収めてください。上下の余白は等しく、左右の余白も等しくなるようにします（差は 4px 以内）。ただし、上下の余白と左右の余白は同じでなくてもかまいません。渡した座標ではなく、scripts/measure.py を使って描画部分から余白を測定してください。dominant-baseline="central" で描画されたテキストの視覚的な上端は、y より約 0.35 × size 上にあり、textWidth は概算値のため、測定後に数 px の微調整が必要になることがあります。

色。 1 つの図では、バーと凡例の色がそれぞれ 1 つの意味だけを表すようにします。凡例で青が「リクエスト時のコンテンツ」を表すなら、ほかのものを青にしてはいけません。ウィンドウ内では、バーでグレーが何を意味するかにかかわらず、レンダリング済みの UI は常にグレーのスケルトンで表します。これはドキュメントの規約です。ウィンドウ内の青は、図が示す対象の状態（静的出力に含まれない状態、または新たにレンダリングされた状態）を表します。バーでも、同じ状態を青で示します。style-tokens.md の「色の意味」を参照してください。

配置。 余白を均等にし、端を揃え、ボックス内のテキストを中央に配置し、矢印と分岐が図全体を通して垂直方向に揃うようにします。これがレビューの基準です。

書体。 コードとルートには Geist Mono、それ以外には Inter を使います。Geist Mono はローカルにインストールする必要があります。フォールバックは ui-monospace です。

関連するスキル

• $write-guide と $write-api-reference は、これらの画像を参照する mdx を生成します。
• $update-docs は、コード変更の影響を受けるドキュメントのページを探すために使います。