smyrna-pergamum/aperture-topology-story

光圈拓撲故事

一個像寧靜工程文件一樣的產品頁面，但帶有一個電影般的動作：讀者滾動 進入 網路的一個節點，深色頁面像相機光圈一樣打開，露出一個明亮的紙張工作區，產品真實的工作流程以卡片形式在此上演。它適合那些價值在於可展示管線（輸入 → 來源/對等點 → 結果 → 輸出）的工具：推理網格、OSINT 與研究工具、資料管線、CI、同步引擎、套件註冊表。不適合生活方式或時尚品牌。

參考實作是 example/index.html：OSINT-Book（一個被動、來源優先的 Android 與 Windows OSINT 筆記本）的真實網站，支援英文/土耳其文，並使用應用程式本身的顏色。詳細程式碼在 references/components.md；screenshots/ 顯示了每個區段、每個故事階段、土耳其文、減量動畫與行動版。

如果使用者指定了一個參考網站，只取其風格。絕不複製其渲染、產品名稱、文案、標誌或資料。

1. 設計之前

1. 先閱讀產品的原始來源：README、使用者指南、隱私/威脅模型、API 或來源註冊表、發行說明、CHANGELOG。頁面上的每個宣稱都對應到其中一個來源。精確複製數字（版本、檔案名稱、大小、SHA-256、連接埠）。如果兩個來源不一致（例如「22 個模組」對比一個 20 行的表格），顯示表格證明了什麼。
2. 從產品本身提取顏色：啟動器圖示、Android colors.xml / Compose lightColorScheme 和 darkColorScheme、Web CSS 自訂屬性。將應用程式的深色配置映射到深色背景，將其淺色配置映射到光圈工作區——頁面因此從應用程式的一個主題切換到另一個主題。
3. 找到故事：將產品的工作流程寫成四個動詞（OSINT-Book：目標 → 發現 → 分析 → 報告；推理網格：模型 → 切片 → 放置 → 服務）。每個階段一個動詞。每個階段需要一個 ≤ 6 個字的標題。
4. 故事中的範例資料必須明顯是範例：example.org、文件 IP（192.0.2.x、203.0.113.x）、每張卡片上有一個「範例資料」晶片。絕不發明統計數據、使用者數量、基準測試或見證。
5. 在架構區段使用真實的應用程式螢幕截圖（WebP，約800px 寬）。

2. 視覺 DNA

元素	規則
深色背景	近黑色，稍微帶有品牌色調：--bg-2（頁面）/ --bg / --surface / --surface-2 / --surface-3。整個主體上方有 36px 網格（1px 線，約 7% 淺色墨水）。英雄區與舞台後方有放射狀光暈池（品牌色約 13%，第二信號色約 6%）。
淺色工作區	應用程式的淺色背景（--paper），帶有 5.5% 墨水的 34px 網格和中間的柔和品牌容器色放射狀渲染。僅在光圈內部。
墨水	深色：--fg / --fg-2 / --muted（muted 在背景上 ≥ 4.5:1）。淺色：--ink / --ink-2 / --ink-muted。
品牌色	用於目標節點、光圈原點、「範例資料」晶片、注意狀態、啟用導覽列項目、懸停邊框的產品顏色。在深色上使用較淺色調（--brand-2），在紙張上使用較深色調（--brand-ink）。
信號色	另外兩種色調，各有一種含義：青色 = 自由 / 正常 / 發現已返回；金色 = 需要金鑰 / 可選 / 遺失。輸出封包使用品牌色，返回封包使用青色。嚴重性始終是顏色 + 圖示 + 文字。
展示字體	Rajdhani 700，行高 .84–.98，字距 0，使用句首大寫。英雄區標題 2.6–5.2rem，帶有四層發光：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> sprite 中；同一個 sprite 透過 <use> 在 SVG 圖形中使用。

3. 區段模式

1. 固定導航欄（64px，半透明深色 + 16px 模糊，底部細線）– 圖示 + 雙色字標，小型連結，帶有版本的 GitHub 藥丸按鈕，EN/TR 切換，主要按鈕。
2. 英雄區 – 全寬 SVG 拓撲（viewBox 1200×520；目標節點在中間，帶有光暈 + 環；5–7 個來源節點在帶虛線的曲線邊緣上，每個都有等寬標籤和一個說明存取狀態的子標籤：key-free， your key）。展示標題位於圖形左下角。其下方：一個句子的引言和一個三列行 – 「執行它」（一個帶有複製功能的命令晶片 + 主要/幽靈下載按鈕 + 「跟隨…」連結）、「它是什麼」（粗體首句 + 帶有彩色點的事實行）、以及一個小型品牌徽章。如果產品有一個拓撲中未顯示的標題功能（OSINT-Book：可選的 AI 分析），在引言中命名它，並在其下方添加一個藥丸按鈕：一個填充的品牌標籤（AI analysis）+ 一行 + 箭頭，連結到該區段，然後該區段會排在故事之後。
3. 光圈故事（固定定位，約 640vh）– 參見 §4。
4. 整合條 – 左側等寬大寫標籤，右側是帶點的名稱包裝列表，上下有細線。
5. 架構切換器 – 區段標題（左側大型展示標題，右側段落），然後是一個深色面板：一個標籤列表（填充的藥丸 = 選中）、一個文字欄（標題、一個段落、✓ 列表）和一個 HTML 節點圖表，圖表在帶有動畫虛線連接器的 SVG 之上（品牌色 = 離開，青色 = 返回，金色 = 可選），然後是一個帶有等寬字型說明的真實螢幕截圖水平條，最後是圖例頁腳。
6. 模組區塊 – 頂邊有兩個小「拼圖標籤」的區塊：輸入行 → 一個側面/中心/側面行（中心區塊較大，帶品牌色調，使用展示字體）→ 一行 6 個輸出；其下有一條等寬字型註釋。
7. 目錄表格 – 搜尋欄位 + 等寬字型標籤選擇器，一個表格包含名稱 + 等寬 ID、類型藥丸、帶有彩色點的存取欄、等寬配額欄、備註；頁腳顯示「Showing x–y of n · source file」和一個分頁器。其下有一個 <details>「刻意遺漏」列表。
8. 範圍分割 – 兩個深色面板，「它能做什麼」（青色方形）/「它絕對不做什麼」（紅色方形），每個項目有一個粗體引導語加一個句子，左側有細線。
9. 安裝 – 兩個下載卡片（圖示瓷磚、名稱、等寬檔案名稱 · 大小），然後是一個終端機視窗（流量燈號、等寬標籤、只複製命令的 COPY 按鈕、彩色提示符號 / 命令 / 標誌 / 註釋 / 輸出），附帶一個狀態頁腳（發光的即時點），然後是一個誠實的金色「早期版本」說明。
10. 頁腳 – 關於文字 + 語言藥丸，兩個連結卡片列表（帶箭頭的行；↗ 外部，→ 文件），底行帶有字標、版本晶片和署名行。

4. 簽名互動：光圈故事

一個 section.story（高度 ≈ 640vh）包含一個 position:sticky; top:0; height:100svh 的舞台，有兩層：

• 深色層 – 相同的拓撲圖形、一個等寬提示（scroll · follow one target）和結束行。
• 淺色層 – clip-path: circle(R at X Y) 其中 X/Y 是目標節點在螢幕上的位置（透過 getBoundingClientRect 測量）。內部：四個堆疊標題（只有一個 .on）、一個邏輯板（寬 1120×560，窄 360×640）按比例縮放，以及一個等寬階段導軌。

單一進度值 p = -rect.top / (story.offsetHeight - innerHeight) 驅動所有內容；每個元素都有關鍵影格 [p, {x, y, s, o}]，使用 ease-in-out-cubic 插值，並套用 translate() scale() + opacity。向後滾動會精確復原。

p	階段	移動的內容
.015 → .10	光圈打開	R 從 0 增長到最遠的角落；提示淡出。然後 clip-path:none。
.00 → .33	1 · 輸入	輸入卡片升起；其檢查清單行逐個勾選（p > .13 + i·.026）；受金鑰限制的行保持未勾選。
.31 → .56	2 · 結果	輸入卡片淡出；「筆記本」卡片取代其位置；六個來源卡片出現在它周圍；每個來源的一個晶片從其卡片飛入筆記本中的一個插槽（st = .37 + i·.024，在 st + .04 處著陸）。缺口晶片是虛線的。
.56 → .79	3 · 解讀	來源卡片縮成點；筆記本向左滑動（晶片跟隨其變換）；三個觀察卡片從右側滑入；從被引用的晶片到每張卡片繪製虛線連接器；出現一個「無判定」藥丸。
.79 → .92	4 · 輸出	所有內容折疊成一張報告卡片；其下方升起一個提交卡片，其六個路線點亮起。
.915 → .975	光圈關閉	R 縮小到 0 回到節點；深色層上的發光結束行淡入。

• 滾動時只有 transform、opacity、clip-path 和 SVG 屬性會改變（一個 rAF 節流的處理器）。
• 圖形封包僅在圖形在螢幕上時以 rAF 迴圈運行，絕不在減量動畫或隱藏標籤下運行。
• 窄螢幕 (< 760px)： 第二個板佈局（來源作為頂部的 3×2 藥丸網格，階段 3 中筆記本縮放到 .6，觀察堆疊，隱藏連接器）。相同的時間軸。
• 減量動畫（或 ?motion=reduce 用於審查）：無固定定位，無光圈；故事呈現為四個靜態紙張影格（p = .30, .55, .78, 1 處的板）及其標題。
• 板是 aria-hidden；一個 sr-only 有序列表講述相同的四個步驟。

5. 建置規則

• 一個獨立的 index.html：doctype、charset、viewport、color-scheme: dark、theme-color；內聯 CSS 和 JS；僅 Google Fonts（Rajdhani, Geist, Geist Mono）；圖片作為 WebP 放在頁面旁邊；圖示作為內聯 SVG sprite。
• 在 :root 上使用令牌；頁面的每種顏色都來自它們（§2）。以角色命名它們，保留產品的十六進位值。
• 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 單欄，圖形 viewBox 裁剪（150 40 900 480）並帶有更大的標籤且無子標籤，窄故事板，圖形節點無子線條。在 360px 處無水平滾動；檢查 grid 子項目是否有 min-width:0。
• 在你用 innerHTML 渲染的任何資料字串中轉義 < 和 >（http://<server-ip>）。

6. 撰寫文案

• 標題是兩行簡短的文字，陳述一個屬性，而不是一個承諾：「每個發現都保留其來源。」「兩個版本。一種檔案格式。」「AI 讀取發現。從不重寫它們。」
• 段落：一或兩個簡單的句子，包含具體名詞（連接埠、格式、演算法、檔案名稱）。
• 限制與功能獲得同等重視（「它絕對不做什麼」、「早期版本」、「刻意遺漏」）。
• 等寬標籤為小寫且簡潔（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。