設計畫布

設計畫布 是做什麼的？

你可以在專案內部將螢幕設計為真實的 HTML 檔案，並在本地端的設計檢視器中顯示它們。使用者可以並排看到每個螢幕、切換裝置尺寸和淺色/深色主題、匯出 PNG 以及對螢幕進行評論；評論會以帶有精確前綴的聊天訊息形式回傳給你。

檔案 (合約)

design/
  tokens.json            每個設計權杖的唯一真相來源
                         (兩個主題)；品牌價值唯一存在的地方
  design-system.css      從 tokens.json 生成：
                         [data-theme="light"] 和 [data-theme="dark"] 的設計權杖 (禁止編輯)
  utilities.css          從 tokens.json 生成：封閉的實用程式
                         詞彙表 (禁止編輯)
  design-system.md       品牌決策的文字說明 (簡短)
  validate.mjs           驗證器 (每個專案複製一次 — 參閱設定)
  serve.mjs              用於檢視器的迷你靜態伺服器 (每個專案複製一次)
  viewer.html            檢視器 (每個專案複製一次)
  mock.js                用於互動式螢幕的模擬執行期 (每個專案複製一次)
  mock.css               mock 執行期類別的靜態樣式 (每個專案複製一次)
                         — toast/overlay/enter-transition 狀態；
                         螢幕將其連結為 `../mock.css`；mock.js 僅切換
                         這些類別，絕不注入 CSS
  scripts/               每個專案複製一次 (參閱設定)
    gen-tokens.mjs       從 tokens.json 重新生成 design-system.css + utilities.css
    sync-components.mjs  從其部分模板重新具體化每個元件標記區域 (每個專案複製一次)
    marker-parser.mjs    sync 在執行期匯入的共享標記語法解析器 (每個專案複製一次)
  components/            元件註冊表 + 部分模板種子 (每個專案複製
                         一次)：components.json + 每個元件一個部分模板
  vendor/html-to-image.js  PNG 匯出函式庫 (每個專案複製一次)
  index.json             {"canvases": ["login", ...]} 以便檢視器列出它們
  <canvas>/              每個畫布一個資料夾，kebab-case (例如 login, dashboard)
    canvas.json
    data.json            可選的虛構資料；可選的 "scenarios" 物件
                         包含命名的頂層覆寫 (empty, critical…)
    01-<screen>.html     每個螢幕一個完整的 HTML 文件
    assets/              可選的本地端圖片/腳本

canvas.json (螢幕以此順序顯示)：

{
  "title": "Login do app",
  "screens": [
    { "id": "login", "name": "Login", "file": "01-login.html", "device": "mobile" },
    { "id": "cadastro", "name": "Cadastro", "file": "02-cadastro.html", "device": "mobile" }
  ]
}

• device：mobile = 390×844, tablet = 834×1112, desktop = 1440×900； 可選的 width/height (整數 100–10000) 可覆寫它。
• group (可選)：將螢幕聚類到檢視器列中帶標題區塊的標籤 — 即使是複雜的專案也保持可讀性 (例如 "group": "Checkout")。
• transition (可選)：fade, slide-left 或 none (預設)。它是 Mock.go 之後的螢幕進入動畫 — 參閱工作流程步驟 3 了解 同畫布/跨畫布規則。
• id 唯一且非空；name 非空；title 可選。
• file 是相對於畫布資料夾的路徑：禁止使用 ..、前導 /、\ 或 協定 (http:、file: …)。

每個專案的一次性設定

如果 design/ 尚不存在，請建立它並從此技能的資料夾 (包含此 SKILL.md 的資料夾) 複製：

• scripts/validate.mjs → design/validate.mjs
• assets/viewer.html → design/viewer.html
• assets/serve.mjs → design/serve.mjs
• assets/mock.js → design/mock.js
• assets/mock.css → design/mock.css (mock 執行期類別的樣式； 螢幕連結 ../mock.css)
• assets/docs.html → design/docs.html (使用指南，從檢視器的 📘 Docs 按鈕連結)
• assets/vendor/html-to-image.js → design/vendor/html-to-image.js
• scripts/gen-tokens.mjs → design/scripts/gen-tokens.mjs
• assets/components/ → design/components/ (註冊表 + 部分模板種子)
• scripts/sync-components.mjs → design/scripts/sync-components.mjs
• scripts/marker-parser.mjs → design/scripts/marker-parser.mjs (共享的 解析器模組 sync 匯入，在執行期需要)
• scripts/export-tokens.mjs → design/scripts/export-tokens.mjs (W3C/DTCG 交換格式匯出：tokens.json → tokens.w3c.json；衍生工件，禁止 手動編輯)

此複製清單的規則：只有已存在的檔案才能進入清單 ("só entra no copy list arquivo que já existe")。尚未到來的檔案只會在其合約波次加入：export-tokens.mjs 在合約波次 6 (todo 30) 加入並在上方列出 — 規則已滿足 (因為檔案自 todo 26 起就已存在)。(mock.css 在波次 3 加入並在上方列出。)

每當 tokens.json 變更時，從專案根目錄重新生成兩個生成的檔案：

node design/scripts/gen-tokens.mjs

建立 design/index.json ({"canvases": []}) 並在建立新畫布時將每個新畫布名稱加入其中。一個完整有效的範例位於此技能的 assets/example/ 中 — 一個跨越兩個畫布、可運作的 stock-app 系統：login/ (登入、註冊和一個透過普通連結以疊層開啟的刪除帳戶確認模態框) 和 dashboard/ (互動式概覽，包含長項目清單、一個演示 fade 過渡和還原捲動的同畫布 "Atualizar lista" 重新整理)，其中登入和註冊會跨畫布導航到概覽頁面，該頁面讀取其虛構項目、支援命名場景，並可登出回到登入畫布。在開始新的設計系統或畫布之前請先閱讀並調整它。種子 example/components/ 是 assets/components/ 的逐位元組副本 ("example/components/ é cópia byte-idêntica de assets/components/ (fonte única)")：僅在 assets/components/ 中編輯部分模板，切勿在範例副本中編輯。

工作流程

1. 先建立設計系統。 讀取 design/design-system.css 和 design/design-system.md。如果它們不存在，詢問使用者品牌 (主要顏色、字體感覺、調性；提供中性色板作為一個選項)， 然後創建兩者。後續畫布會重複使用它們。僅在詢問後才更改權杖。
2. 僅詢問遺漏的資訊。 如果請求模糊不清 (哪些螢幕、哪個 平台、什麼資料)，詢問一次；如果很清楚，就開始。
3. 建立畫布。 首先從此技能的資料夾讀取 assets/craft.md (它融合了同級工藝技能 — taste, emil-design-eng, impeccable — 成為 畫布螢幕的規則) 並將其應用於每個螢幕。然後建立 canvas.json 和螢幕。每個螢幕的規則：
   • 樣式政策：實用程式詞彙表就是詞彙表。任何基於權杖的內容 (顏色、字體、間距、圓角) 都要透過生成的實用程式：連結 <link rel="stylesheet" href="../design-system.css"> 和 <link rel="stylesheet" href="../utilities.css">，然後使用如 bg-accent, p-2, text-heading, rounded-md 的類別。互動式 螢幕也要連結 <link rel="stylesheet" href="../mock.css"> (mock 執行期 類別：toast, overlay, enter 過渡)。語義類別只承載 結構和佈局。在沒有實用程式符合的地方允許使用 var(--…)， 並且允許使用內聯 <style> 區塊，但必須包含零個字面 顏色。禁用掃描會掃描 <style>、style="" 和 SVG fill=/stroke= 的 VALUE 位置中的字面顏色； 它也會禁止螢幕中任何位置的 http(s)://、Tailwind 色板類別如 bg-zinc-900， 以及任意值如 text-[13px]。
   • 透過權杖處理兩個主題；主題作為 data-theme 出現在 <html> 上 (預設為 light — 包含此屬性)。
   • 禁止任何形式的 CDN 或遠端 URL (畫布是離線且沙盒化的)： 內嵌 SVG 圖示、系統字體或 design/ 下的字型檔案、本地端圖片。
   • 使用使用者的語言 (預設為巴西葡萄牙語) 和 合理的樣本資料 — 禁止使用 Lorem Ipsum。
   • 在必要時，以額外螢幕的方式涵蓋空狀態、載入狀態和錯誤狀態。
   • 無障礙基礎：輸入框有標籤、可見的焦點、足夠的對比度、 行動裝置上點擊目標 ≥ 44px。
   • 佈局必須適合螢幕的裝置寬度。
   • 元件是部分模板的實例，而不是鬆散的元件標記 ("instância usa partial, nunca markup solto de componente")。將每個 實例包裹在標記配對中 <!-- component:id size=md tone=primary state=default -->…<!-- /component:id --> 並帶有三個必需的參數 size=、tone=、state= (值必須 在 design/components/components.json 的註冊表列舉中)， 並使用配對標記 <!-- slot:name -->…<!-- /slot:name --> 填入其插槽。 優先級：標記參數是真相來源 (marker-args-win)。同步 會在每次執行時從標記重新發出 data-size/data-tone/data-state 和變體 類別；插槽內容和根元素上的使用者額外 data-* 屬性會保留。
   • 使其成為系統預覽，而不是海報。 當請求暗示一個 運作中的產品時，使用 mock 執行期連接螢幕 (<script src="../mock.js"></script>，由 Setup 複製)：表單會驗證 並提交，按鈕會給予回饋，螢幕會使用 Mock.go('03-dashboard.html') 導航，虛構資料存在於畫布的 data.json 中 (await Mock.data('items'))，流程狀態 (已登入的使用者、 過程中建立的項目) 存在於 Mock.state 中 (會話，按畫布 命名空間)，模擬的操作會使用 Mock.toast('…') 確認。 每個螢幕在 JavaScript 失敗時仍然必須能夠作為靜態構圖呈現。 檢視器會在已導航的卡片上顯示一個 ↺ início 按鈕，以及 "⟲ Reset fluxo" 來從頭開始整個流程。涵蓋重要的狀態作為 data.json 中的命名 scenarios (頂層覆寫，例如 "vazio": {"items": []}) — 檢視器會獲得一個選擇器， 選擇會在導航過程中保留，並且每個 scenario 必須能良好組合 (空清單、所有項目低於最低限度、API 失敗)。一個系統可以跨越 多個畫布 (每個流程一個)：使用 Mock.go('../<canvas>/<screen>.html') 跨畫布導航 — 流程狀態在整個專案中共享，因此登入畫布設定使用者，儀表板 畫布讀取它。檢視器的畫布選擇器可在畫布之間跳轉 (每個畫布保留自己的 scenario、主題和裝置)。模態框和 確認對話框也是完整的畫布螢幕 (單一事實來源)： 觸發器是一個普通的螢幕連結 <a href="03-modal.html">，mock 執行期會攔截它成為 Mock.overlay('03-modal.html') — 如果沒有 JS， 未修改的 href 會導航到模態框螢幕本身 (JS-off 的備援方案)。持久性導航 (側邊欄、頂部選單、分頁) 必須實際切換 螢幕：在每個項目上放置 data-go="02-cadastro.html" (在 同一個連結上保留一個真實的 href="02-cadastro.html" 作為 JS-off 的備援方案 — 執行期會將 data-go 路由到 Mock.go，保留 ?scenario= 和 進入過渡效果)。普通連結保留給疊層觸發器 (模態框/詳細資訊 — 一個普通的螢幕連結總是開啟一個疊層)； 在畫布的每個螢幕上重複相同的導航區塊，並標記 活動項目。螢幕可以在 canvas.json 中宣告 "transition": "fade"|"slide-left"| "none"：Mock.go 會向目標螢幕添加一個進入類別 (mock-enter-fade/mock-enter-slide-left，在 300 毫秒內自動移除)。 交接會讀取由目標檔案名稱匹配的 CURRENT 畫布的 canvas.json， 因此它適用於同畫布跳轉 (像 Mock.go('01-overview.html') 這樣的自我導航 是一種重新整理模式) — 跨畫布 Mock.go('../<canvas>/<screen>.html') 是一個沒有進入類別的普通導航。 每個螢幕的捲動位置會保留 (scroll.<canvas>.<file> 在 sessionStorage 中，當螢幕 返回時還原，並且在 ⟲ Reset fluxo 後仍然存在，後者只會清除 mock.*)。
4. 驗證並修復。 強制性的同步第一步：在編輯 design/components/ 中的任何部分模板 (或任何標記的參數) 之後，從專案根目錄執行 node design/scripts/sync-components.mjs，然後再呈現任何內容；它會從其部分模板重新具體化每個實例 (marker-args-win)。--check 是乾執行形式：它會列印每個分歧區域的 file:line 差異，並在分歧時退出碼 1 (0 表示乾淨)，絕不寫入。然後從專案根目錄執行： node design/validate.mjs design/<canvas>。修復它列出的每個問題，並再次執行，直到只剩下摘要行。切勿呈現有問題的畫布。驗證器的參數可以是設計根目錄 (專案模式) 或單個畫布資料夾 (畫布模式)；無參數時預設為 ./design。結構性檢查僅涵蓋 canvas.json 中列出的螢幕；專案模式另外檢查權杖/生成的 CSS 是否過時、元件和註解。元件規則會在每個非豁免的 .html 上掃描，與 canvas.json 無關，包含代碼 component-unknown、component-variant、component-marker、component-divergence 和 slot-marker。--allow-stale 僅跳過過時檢查；--mark-stale 是驗證器唯一寫入的操作 (它會標記錨點已消失的註解釘子)；--example-inventory 是範例合約檢查 (精確的 inventory.json 檔案清單 + 每個釘子上的 "_demo": true；沒有 inventory.json = 跳過，退出碼 0)。 4b. Impeccable 稽核。 驗證後，對畫布執行同級 impeccable 技能的技術稽核 (安裝的佈局，win32)： <skill-impeccable>/scripts/impeccable.cmd audit design/<canvas> - 路徑是從安裝的 [...] 解析的

[截斷以待翻譯]