hayatosc/html-artifacts

HTML Artifacts

交付一個可從磁碟開啟且離線運作的單一人用 .html 檔案。使用捆綁的日本數位廳設計系統（DADS）文件配接器，而非 CDN 或框架。保持面向代理的原始碼為 Markdown 格式。這是一個非官方的文件配接器，並非 DADS 所有元件的完整實作。

程序

1. 了解讀者與來源

在選擇結構之前，先確定主題、受眾、目的與證據。對於計畫，保留目標、完成證據、限制條件、檢查點與風險。包含描述性標題、簡短的定向說明，以及來源/日期出處。僅在有用時加入目錄；不要強制要求章節數量或圖表。

從零開始解釋：從具體情境和主題功能開始，再引入技術名稱。首次使用時定義術語，每個步驟只傳達一個想法，僅在圖片比文字更清楚解釋時使用標註圖片。僅在類比關係與其限制明確時才使用；保持成人、直接的口吻，除非是為兒童撰寫。新手應能理解發生了什麼、為什麼以及下一步該做什麼。

2. 自動建置 — 絕不重新輸入 CSS

閱讀 build.md。從此檔案的位置解析技能目錄，而非目前專案的工作目錄。使用 Python 3.10+：

python /absolute/path/to/html-artifacts/scripts/build.py /absolute/path/to/output.html --title "主題"

建置器會讀取 assets/template.html，嵌入 所有 的 assets/dads.css 與 assets/print.js，並插入離線內容安全政策（CSP）。它拒絕覆蓋現有檔案。無需下載、安裝套件、伺服器、打包工具或相鄰的資源資料夾。在此儲存庫中，可使用其 Python 執行器（uv run python 也可以）。

3. 編輯內容，而非基礎架構

編輯產生的檔案。取代起始的解釋性內容、出處與目錄；移除不需要的章節。保留 style#dads-css、script#dads-print、CSP、charset、viewport 與 only light 色彩配置中繼資料。

• 僅使用內嵌 SVG 與嵌入的點陣圖像。無遠端/本地樣式表、腳本、字型、圖片、iframe、import、fetch 或分析依賴。一般來源超連結可以指向網路；將本地來源檔案標記為文字，而非失效的相對連結。
• 使用語義化 HTML 與捆綁的類別/符號。閱讀 dads.md 以了解類別 API、官方來源與本地改編。不要將上游 data-type/data-size API 與此配接器的修飾符混合使用。
• 在加入 SVG 前先使用 diagrams.md。為每個有意義的圖表提供標題、描述、標籤與文字替代方案。將寬圖表放入帶有標籤且鍵盤可聚焦的 .dads-diagram-scroll 區域。
• 使用已安裝的字型備援；缺少 Noto 時不得隱藏文字。將 lang 與內容匹配。正文為 1rem/1.7（預設設定下為 16px）。保留瀏覽器縮放與重排功能。
• 預設使用連結與原生 disclosures。保持 disclosures 初始為 open，以便無腳本列印時保留內容；捆綁的腳本也會在列印時開啟任何讀者收合的 disclosure，並在之後恢復原狀。不要加入分頁、無效按鈕、任意 JavaScript 或事件處理器屬性。
• 在深色作業系統設定中保持淺色：此配接器沒有經過驗證的官方深色調色盤。不要僅反轉頁面背景或自行發明深色符號集。尊重強制色彩與減少動畫設定。
• 優先使用現有元件。如果必要，將少量文件特定規則放入獨立的內嵌 <style> 中；新類別必須是 artifact-* 並在其中定義。使用已知的符號，絕不重新定義或修改捆綁的 CSS。在瀏覽器中檢查這些規則；靜態驗證並非 CSS 解析器或對比度稽核。

4. 最終自我檢查 — 在交付前修正失敗

在最後一次編輯後執行：

python /absolute/path/to/html-artifacts/scripts/check.py /absolute/path/to/output.html

然後在瀏覽器中檢查實際檔案，並在可能時停用網路連線：

1. 內容： 起始的散文/佔位符已消失；要求的證據、來源、日期與下一步行動仍然存在。獨立閱讀圖表描述；它們必須傳達含義。
2. 離線： 無資源請求、無失敗資產、無 CSP 違規、無主控台錯誤。來源超連結是導航，而非嵌入的依賴。
3. 行動版/桌面版： 檢查 390px 與 1280px 的螢幕截圖；另外在 320px/200% 文字大小下檢查重排。無頁面寬度水平溢位；僅有標籤且可聚焦的程式碼/表格/圖表區域可以滾動。檢查實際日文字形與長 URL。
4. 鍵盤/狀態： 跟隨跳過連結與目錄，標籤至滾動區域，切換 disclosures，並檢查可見的焦點與按鈕連結對比度（包括已訪問/懸停）。無僅以顏色傳達意義的情況。
5. 深色/列印： 模擬深色偏好設定（頁面必須保持可讀的淺色），以關閉的 disclosure 列印，驗證其主體列印出來，並檢查寬表格/程式碼與分頁。透過保持 disclosures 初始為 open，在無 JavaScript 時保留內容。

檢查器會強制執行捆綁的資產/政策合約、已知類別/符號與保守的離線資源規則。它不會驗證 CSS 語法、版面、對比度、無障礙性或任意 HTML 的正確性。如果沒有瀏覽器可用，請說明哪些視覺/互動檢查仍未驗證；永遠不要僅憑靜態檢查就聲稱有螢幕截圖。

5. 交付

儲存在來源旁或工作目錄中，以主題命名（計畫則為 PLAN.html）。回傳成品連結與重大限制，而非文件副本或第二份通用自我稽核。

對於 SSH/其他裝置，請遵循 remote-preview.md。遠端路徑或 xdg-open 並非可用的檢視交接方式。僅提供隔離的副本，僅對授權公開共享的內容使用公開隧道，否則使用 SSH 轉發/存取控制，並提供清理說明。保持原始 HTML 離線安全。

資源

• assets/template.html, assets/dads.css, assets/print.js：機械式嵌入的來源。
• scripts/build.py, scripts/check.py：標準函式庫建置與最終合約檢查。
• build.md：編輯模式與疑難排解。
• dads.md：官方出處、符號、配接器元件 API。
• diagrams.md：可讀的內嵌 SVG 模式。
• remote-preview.md：安全的遠端交接。

從零開始解釋的方法靈感來自 ELI5 技能。