Aperture Topology Story
一つの映画的な動きを持つ、静かなエンジニアリングドキュメントのように振る舞う製品ページです。読者はネットワークのノードの中にスクロールし、暗いページがカメラの絞りのように明るい紙のワークスペースに開き、そこで製品の実際のワークフローがカードで表現されます。これは、見せられるパイプライン（入力→ソース/ピア→結果→出力）を持つツールに適しています。推論メッシュ、OSINTおよびリサーチツール、データパイプライン、CI、同期エンジン、パッケージレジストリなどです。ライフスタイルやファッションブランドには適していません。
リファレンスビルドは example/index.html です。これは OSINT-Book（Android と Windows 向けのパッシブかつソースファーストな OSINT ノートブック）の実際のウェブサイトで、EN/TR、アプリ独自の色を使用しています。詳細なコードは references/components.md にあります。screenshots/ にはすべてのセクション、すべてのストーリーフェーズ、トルコ語版、動きの抑制モード、モバイル版のスクリーンショットがあります。
ユーザーが参照サイトを指定した場合は、そのスタイルのみを採用してください。そのレンダリング、製品名、コピー、ロゴ、データを決してコピーしないでください。
1. デザイン前の準備
- まず製品のソースを読む: README、ユーザーガイド、プライバシー/脅威モデル、APIまたはソースレジストリ、リリースノート、CHANGELOG。ページ上のすべての主張は、それらのいずれかに対応します。数値（バージョン、ファイル名、サイズ、SHA-256、ポート）は正確にコピーします。2つのソースが矛盾する場合（例：「22モジュール」と20行のテーブル）、テーブルが証明する内容を示します。
- 製品自体から色を取得する: ランチャーアイコン、Android の
colors.xml/ Compose のlightColorSchemeとdarkColorScheme、Web CSS カスタムプロパティ。アプリのダークスキームを暗い基盤に、ライトスキームを絞りワークスペースにマッピングします。これにより、ページはアプリの一方のテーマからもう一方のテーマに文字通り切り替わります。 - ストーリーを見つける: 製品のワークフローを4つの動詞として書きます（OSINT-Book: ターゲット → 発見 → 分析 → レポート; 推論メッシュ: モデル → スライス → 配置 → 提供。フェーズごとに1つの動詞）。各フェーズには6ワード以内の見出しが必要です。
- ストーリー内のサンプルデータは明らかにサンプルであること:
example.org、ドキュメント用IP（192.0.2.x、203.0.113.x）、各カードに「sample data」チップ。統計、ユーザー数、ベンチマーク、推薦文を決してでっち上げないでください。 - アーキテクチャセクションには実際のアプリのスクリーンショット（WebP、約800px幅）を使用します。
2. ビジュアルDNA
| 要素 | ルール |
|---|---|
| 暗い基盤 | ほぼ黒で、ブランドでわずかに色合いを付ける: --bg-2（ページ）/ --bg / --surface / --surface-2 / --surface-3。本文全体に1px線の36pxグリッドを、明るいインクの約7%で配置。ヒーローとステージの背後に放射状のグローのプール（ブランドカラー約13%、セカンドシグナル約6%）。 |
| 明るいワークスペース | アプリの明るい背景（--paper）に、約5.5%のインクの34pxグリッドと、中央にブランドコンテナカラーの柔らかな放射状ウォッシュ。アパチャーの内側のみ。 |
| インク | 暗い方: --fg / --fg-2 / --muted（ミュートは基盤に対して4.5:1以上）。明るい方: --ink / --ink-2 / --ink-muted。 |
| ブランド | ターゲットノード、アパチャー原点、「sample data」チップ、アテンション状態、アクティブなレールアイテム、ホバーボーダーに使用する製品カラー。暗い方では明るいトーン（--brand-2）、紙の上では深いトーン（--brand-ink）を使用。 |
| シグナル | さらに2つの色相。それぞれ意味を持つ: ティール = フリー / OK / 発見が返ってきた; ゴールド = キーが必要 / オプション / 不足。送信パケットはブランド、戻りパケットはティール。重大度は常に色 + アイコン + 単語。 |
| ディスプレイ | Rajdhani 700、行間 .84–.98、文字間隔 0、文の先頭のみ大文字。ヒーローは 2.6–5.2rem で4層のグローを持つ: 0 0 2px #fff·86%, 0 0 18px brand-2·36%, 0 0 48px teal·14%, 0 18px 52px #000·60%。紙の上では同じ書体で 0 1px #fff, 0 14px 34px ink·12%。 |
| 本文 / UI | Geist 400–700、14–17px。 |
| ラベル | Geist Mono 10–13px: ノードラベル、サブラベル、チップ、テーブルクォータ、ターミナル、レール、アイブロウ（01 / ai analysis、大文字 + .14em はここだけ）。 |
| カード | ダークパネル: 16px 半径、1px --line-2、垂直グラデーション表面。ペーパーカード: 白、14px 半径、1px 暖色線、0 14px 34px -14px シャドウ。チップはピル型（高さ20px）。発見行には左側に6×18pxのグラデーションハンドル。 |
| ボタン | プライマリ = ほぼ白の塗りつぶしに濃いインク（8px 半径、40px）。ゴースト = 1px 線、ホバー時に brand-2 に変化。ナビ内のピルボタンにはモノサフィックス（· web-v0.2.2）が付く。 |
| アイコン | 24グリッドの1.7px線のシングルストロークアイコンをインラインの <symbol> スプライトに; 同じスプライトがSVGグラフ内でも <use> される。 |
3. セクションパターン
- 固定ナビ (64px、半透明暗色 + 16px ぼかし、下にヘアライン) – アイコン + 2トーンのワードマーク、小さなリンク、バージョン付きGitHubピル、EN/TRトグル、プライマリボタン。
- ヒーロー – 全幅SVGトポロジー（viewBox 1200×520; 中央にターゲットノード（ハロー＋リング付き）; 5～7個のソースノードが曲線の破線エッジ上に配置され、各ノードにモノラルラベルとアクセスを示すモノラルサブラベル（
key-free、your key）。ディスプレイ見出しはグラフの左下に配置。その下に: 1文のリードと3カラムの行 – 「run it」（コピー付きコマンドチップ + プライマリ/ゴーストダウンロードボタン + 「follow …」リンク）、「what it is」（太字の最初の文 + 色付きドットのファクト行）、および小さなブランドバッジ。製品にトポロジーが示さない特徴的な機能がある場合（OSINT-Book: オプションのAI分析）、リード内で名前を挙げ、その下に1つのピルを追加する: 塗りつぶしブランドタグ（AI analysis）+ 1行 + 矢印、そのセクションにリンクする。そのセクションはストーリーの後に最初に来る。 - アパチャーストーリー（ピン留め、約640vh）– §4 を参照。
- 統合ストリップ – 左にモノラル大文字ラベル、右に折り返された点線名のリスト、上下にヘアライン。
- アーキテクチャスイッチャー – セクションヘッド（左に大きなディスプレイタイトル、右に段落）、次に1つのダークパネル: タブリスト（塗りつぶしピル = 選択状態）、テキストカラム（タイトル、1段落、✓リスト）、およびアニメーションする破線コネクタ（ブランド = 送信、ティール = 戻り、ゴールド = オプション）上のSVG上のHTMLノードの図、次にモノラルキャプション付きの実際のスクリーンショットの水平ストリップ、最後に凡例フッター。
- モジュールブロック – 上部エッジに2つの小さな「パズルタブ」を持つブロック: 入力行 → サイド/センター/サイド行（中央ブロックは大きく、ブランド色味、ディスプレイフォント）→ 6つの出力の行; その下に1つのモノノート。
- カタログテーブル – 検索フィールド + モノラルラベル付きセレクト、名前 + モノラルID、タイプピル、色付きドットのアクセスカラム、モノラルクォータカラム、ノートがあるテーブル; フッターに「Showing x–y of n · source file」とページャー。その下に
<details>「left out, on purpose」リスト。 - スコープ分割 – 2つのダークパネル、「What it does」（ティールの四角）/「What it never does」（赤の四角）、各項目は太字のリードイン + 1文、左ヘアライン。
- インストール – 2つのダウンロードカード（アイコンタイル、名前、モノファイル名·サイズ）、次にターミナルウィンドウ（信号機、モノタブ、
COPYはコマンドのみコピー、色付きプロンプト/コマンド/フラグ/コメント/出力）、ステータスフッター（発光ライブドット）、最後に正直なゴールド「Early releases」ノート。 - フッター – テキスト + 言語ピル、2つのリンクカードリスト（矢印付き行; ↗ 外部、→ 文書）、最下行にワードマーク、バージョンチップ、帰属行。
4. シグネチャーインタラクション: アパチャーストーリー
section.story（高さ約640vh）は position:sticky; top:0; height:100svh のステージを保持し、2つのレイヤーを持つ:
- 暗いレイヤー – 同じトポロジーグラフ、モノヒント（
scroll · follow one target）、および閉じる線。 - 明るいレイヤー –
clip-path: circle(R at X Y)。X/Y はターゲットノードの画面位置（getBoundingClientRectで測定）。内部: 4つの積み重ねられた見出し（.onは1つだけ）、論理的なボード（ワイド時 1120×560、ナロー時 360×640、フィットするようにスケール）、モノフェーズレール。
単一の進行値 p = -rect.top / (story.offsetHeight - innerHeight) がすべてを駆動する; すべての要素は [p, {x, y, s, o}] のキーフレームを持ち、イーズインアウトキュービックで補間され、translate() scale() + opacity として適用される。スクロールバックは正確に巻き戻る。
| p | フェーズ | 動くもの |
|---|---|---|
| .015 → .10 | アパチャーオープン | R が0から最も遠い角まで成長; ヒントがフェードアウト。その後 clip-path:none。 |
| .00 → .33 | 1 · 入力 | 入力カードが上昇表示; チェックリスト行が1つずつチェックされる（p > .13 + i·.026）; キーゲート行はチェックされずに残る。 |
| .31 → .56 | 2 · 結果 | 入力カードがフェードアウト; 「notebook」カードが取って代わる; 6つのソースカードがその周りに現れる; 各ソースから1つのチップがカードから飛び出し、ノートブック内のスロットに入る（st = .37 + i·.024、st + .04 で着地）。ギャップチップは破線。 |
| .56 → .79 | 3 · 解釈 | ソースカードがドットに縮小; ノートブックが左にスライド（チップはそのtransformに従う）; 3つの観察カードが右からスライドイン; 引用されたチップから各カードへの破線コネクタが描画される; 「no verdict」ピルが表示される。 |
| .79 → .92 | 4 · 出力 | すべてが1つのレポートカードに折りたたまれる; その下にコミットカードが上昇し、その6つのルートドットが点灯する。 |
| .915 → .975 | アパチャークローズ | R がノードに戻って0に縮小; 暗いレイヤーに発光する閉じる線がフェードイン。 |
- スクロール中は
transform、opacity、clip-pathおよび SVG 属性のみが変更される（1つの rAF スロットルされたハンドラ）。 - グラフパケットは、グラフが画面に表示されている間のみ rAF ループで実行され、動きの抑制時や非表示タブでは決して実行されない。
- 狭い画面 (< 760px): 2番目のボードレイアウト（ソースは上部に3×2のピルグリッド、フェーズ3ではノートブックは .6 にスケール、観察は積み重ね、コネクタは非表示）。同じタイムライン。
- 動きの抑制（またはレビュー用に
?motion=reduce）: ピン留めなし、アパチャーなし; ストーリーは4つの静的なペーパーフレーム（p = .30、.55、.78、1 でのボード）を見出しとともにレンダリングする。 - ボードは
aria-hidden;sr-onlyの順序付きリストが同じ4つのステップを伝える。
5. ビルドルール
- 単一のスタンドアロン
index.html: doctype、charset、viewport、color-scheme: dark、theme-color; インラインCSSとJS; Google Fonts（Rajdhani、Geist、Geist Mono）のみ; 画像はページの隣にWebPとして配置; アイコンはインラインSVGスプライトとして。 - トークンは
:root上に; ページのすべての色はそれらから来る（§2）。役割に基づいて名前を付け、製品の16進値を維持する。 - i18n: 英語はHTML内に存在する（
data-i18nキーは英語のソースとして一度だけ読み取られる）; 他の言語はJSディクショナリ内に; JSによって構築される文字列はT({en, tr})を使用する。選択をlocalStorageに try/catch 内で永続化する。アイブロウも翻訳する（大文字 + トルコ語ロケールは「install」を「İNSTALL」にする）。 - アクセシビリティ: 両方の基盤でAAコントラスト、可視のフォーカスリング（brand-2）、スキップリンク、
role=tabのタブ、aria-selected、ロービング tabindex と矢印キー、実際の<table>と<details>、ラベル付きコピーボタン。 - レスポンシブ: ≥1060px はフルレイアウト; <1060px はヒーローサイドバッジ非表示、AIグリッドスタック、エディションスタック; <760px は1カラム、グラフ viewBox をクロップ（
150 40 900 480）、ラベルを大きくしサブラベルなし、狭いストーリーボード、サブラインなしの図ノード。360px で水平スクロールなし;gridの子にmin-width:0があることを確認する。 innerHTMLでレンダリングするデータ文字列内で<と>をエスケープする（http://<server-ip>）。
6. コピーの書き方
- 見出しは、約束ではなくプロパティを述べる2つの短い行: 「Every finding keeps its source.」「Two editions. One file format.」「AI that reads findings. Never rewrites them.」
- 段落: 具体的な名詞（ポート、フォーマット、アルゴリズム、ファイル名）を含む1つまたは2つの平易な文。
- 制限事項は機能と同じ重みを得る（「What it never does」「Early releases」「left out, on purpose」）。
- モノラルラベルは小文字で簡潔に（
key-free、your key、target · sample、sha-256 3f9a…）。
7. 完了チェックリスト
- すべての主張、番号、ファイル名、ハッシュが製品の実際のファイルと最新リリースと一致している。
- カラートークンは製品から来ている（アイコン + ライト/ダークスキーム）; 重大度は色だけで示されていない。
- ストーリーは双方向で同期しており、アパチャーはノードから開きノードに閉じ、p = .27/.5/.75/.9 で重なるものがない。
- 狭いレイアウトと動き抑制フレームの両方が正しく読める; パケットは画面外で停止する。
- タブ、ページャー、検索、フィルター、コピーボタンがキーボードで動作する; フォーカスが可視。
- EN/TR切り替えがボード、図、テーブル、ターミナル、アイブロウを再レンダリングする。
- 360/390px で水平スクロールがない; コンソールエラーがない。
- 1440×900 と 390×844 でのスクリーンショット:
node scripts/screenshots.mjs example/index.html screenshots。