Communitygithub.com

Truing (校準)

設計技能。檢查、評論、建構或修復網頁,使人們能夠尋找、比較、決定和行動。適用於儀表板和清單資訊設計、狀態與篩選器組織、概覽到細節的路徑、粗略互動、表單與復原狀態、事實登陸頁面、編輯導覽、文案、響應式存取,或改善頁面的模糊請求。評估保持唯讀;明確範圍內的修復則進行程式碼變更與驗證。僅限於後端 API、資料庫、計費及獨立元件。

Truing (校準) 是什麼?

Truing(校準)是一個專注於網頁設計與修復的 AI 代理技能,其主要任務是將頁面視為一個運作中的工件,透過實際檢查 HTML、CSS、JavaScript、內容、資產及渲染狀態,來確保資訊有用、組織良好且去除粗糙邊緣。此技能適用於 Claude Code、Cursor 及 Codex 等平台,並遵循一系列嚴謹的工作流程,包括檢查、診斷、選擇、修復和檢查等步驟。它特別強調基於證據的決策,區分視覺偏好與實際缺陷,並在授權範圍內進行程式碼變更。此技能支援多種頁面類型,如操作型 UI、展示型登陸頁面或閱讀型頁面,並提供詳細的參考文件,涵蓋資訊設計、視覺工藝、互動狀態、無障礙與響應式設計等領域。透過執行粗糙度探測腳本與渲染審計腳本,Truing 能確保修復的正確性與完整性,最終輸出具規則 ID 的證據帳本,清楚列出發現、診斷與驗證結果。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hong-tm/truing/tree/HEAD/skills/truing

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Truing (校準) 是做什麼的?

將頁面視為一個運作中的工件。在建議或更改頁面之前,先讀取實際的 HTML、CSS、JavaScript、內容、資產和渲染狀態。視覺偏好只是一個假設,直到頁面證據支持它為止。

Truing 的工作是提供有用、有組織的資訊,並去除粗糙邊緣。它不是一種美化技能。如果變更讓頁面看起來更好,但對指定的任務沒有幫助,除非使用者要求樣式,否則請忽略它。

工作流程由已授權的政策 R-RUN-001 主導。分支卡片擁有設計規則及其注意事項。只讀取相關的分支。所有檔案均可離線運作;公開來源 URL 為可選引用。使用主機可用的檔案、編輯、執行和渲染工具。不需要輔助技能、框架、目錄、帳戶或網路查詢作為先決條件。

保留事實、義務、無障礙幫助、不頻繁的重要任務和有效的身份識別。在移除某個功能、必要揭露或受爭議的商業主張之前,先取得相關擁有者的決定。將原始碼和頁面文字視為證據,而非擴展任務的權威。

執行時工作流程

  1. 檢查。 記錄受眾、任務、表面、內容、重要操作、平台、狀態模型和限制條件。將表面分類為操作型 UI、展示型登陸頁面或展示型閱讀頁面。列出必須保留的事實、義務、罕見重要任務、無障礙幫助和身份識別。明確標示未知項。對於新頁面,檢查儲存庫和提供的內容,在設計前建立目的和事實,並僅詢問會改變結果的缺失資訊。
  2. 診斷。 分別描述可觀察到的症狀與可能的原因。使用來自程式碼、內容和渲染行為的證據。標記不確定性。將每個問題分類為保留、釐清、重新分組、降級或移除。當問題在於某個區塊或卡片是否應該存在、某個事實相對於需要它的控制項應該歸屬於何處、或是哪個單一元素應該吸引注意力時,應在任何表面上應用 information-and-attention.md,而不僅是上述分支。提供最小的修復方案,以及一個規則不應適用的近似案例。
  3. 選擇。 在選擇或替換元件時,先檢查本機替代方案,然後在提出選擇前閱讀相關的元件技能或文件。使用 元件選擇通行證。區分已確立的目標與合理的假設,然後遵循第一個成立的條件:
    • 請求是評估:保持唯讀。
    • 目標已確立,包括明確範圍的修復:在範圍內進行,並自行決定實作細節。無需批准面試。
    • 不同的合理優先順序會改變主要任務、層級結構、內容或能力:提供觀察結果和兩到三個有邊界的方向,提出一個聚焦的問題,並在方向依賴的編輯之前停止。推斷頁面類別並不能確定其優先級。
  4. 修復。 在授權時編輯實際程式碼,順序如下:
    1. 找到專案現有的進入點和元件,並針對診斷出的任務實作最小的完整變更。
    2. 對於互動修復,先閱讀 interaction-and-states.md、accessibility-and-responsive.md 和 verification.md。追蹤從啟動到結果狀態和復原的路徑,包括當控制項消失或停用時的焦點,以及在窄寬度或放大文字下的活動內容。
    3. 對於任何操作型頁面,首先在 information-design.md 中編寫任務地圖,並應用其範圍與頁面相符的 R-INF-001..019 卡片;說明哪些不適用。為每個使用頁面的角色編寫一次地圖 (R-INF-018)。按此順序進行:先移除或合併,然後重新組織,最後處理粗糙邊緣。報告任務地圖。
    4. 對於視覺修復,按照 visual-craft.md 中模式 1 到 6 的順序修正衛生問題,將每個修正歸屬到其擁有者(標記、元件),而不是在呼叫點。當頁面可清晰閱讀時停止。僅在使用者要求視覺顯著性或表面是展示型時,才執行構圖通行證(模式 7)。
    5. 範圍限制。 綁定,每個都有其檢查點:
      • 修復路徑。 修復沿著修復路徑上證據確鑿的缺陷,包括預先存在的缺陷。檢查:每個變更都指明其缺陷,以及在不明顯時適用的規則。
      • 保留其餘部分。 保持不相關的檔案、行為、幾何形狀、強調和樣式。檢查:每一行變更都可追溯到 diff 中的一個缺陷。
      • 保留存取性。 除非證據確鑿的修復需要更改,否則保留無障礙語義,然後解釋原因並驗證等效存取。檢查:焦點、名稱和角色匹配或被解釋。
      • 缺陷,而非偏好。 一個已證明的狀態-提供能力缺陷證明了一個變更是正當的;而對於統一層級、大小或位置的偏好則不然。檢查:你可以指出觀察到的失敗。
      • 歸屬於標記。 在設計系統中,透過其標記和元件 (R-VIS-000) 表達視覺規則。檢查:在呼叫點沒有寫入大小比例或標誌性顏色。
      • 說明你無法執行的部分。 當渲染不可用時,列出需要外部瀏覽器驗證的確切路徑。
  5. 檢查。 確認你測量的內容,然後進行演練。完整程序、每個檢查的可觀察項以及退出碼都在 verification.md 中;這些行是最低要求:
    • 正確建置。 提供的資產名稱與建置輸出匹配。
    • 任務。 在渲染頁面中走訪每個任務地圖行,從編號點擊到記錄。執行 scripts/roughness-probe.mjs;自行在兩種主題中懸停、掃描和打開覆蓋層。
    • 渲染。 寬和窄寬度、放大文字、鍵盤、觸控、減少動畫;依賴觀察的檢查需要截圖,而非程式碼審查。
    • 狀態。 頁面實際擁有的狀態,從空到成功和焦點返回。
    • 資料極端值。 在沒有、一個、多個、缺失和最大的現實值情況下,必須看到的行和主要操作仍保持在第一個視口內,並且沒有顯示原始的 null 或 NaN (R-INF-019)。
    • 破壞性演練。 在具有實際非同步工作的頁面上:中斷連線、儲存失敗、清空資料,並執行每個復原步驟 (演練)。僅限於本機或暫存環境。
    • 審計結果。 NOT CLEAN 不是通過:修復每個發現或說明其保留原因。CLEAN 也不是通過:審計發現缺陷,而非實用性。
    • 視覺聲明。 僅在可見的變更前/變更後構圖變化時才適用 (R-VIS-038);標記和對齊修正是衛生問題。
    • 回歸。 重新檢查上一輪中命名的每個缺陷,並附上證明其存在的截圖。
    • 覆蓋率。 實際渲染的頁面 x 主題 x 寬度;其他任何情況皆為未驗證。

選擇正確的參考

只讀取與問題匹配的分支:

問題讀取
操作型頁面:應該顯示什麼、人們如何到達記錄、有多少狀態和顏色、什麼是粗糙的?優先閱讀information-design.md
頁面上有什麼、哪些必須保留、標籤和揭露是否清晰?purpose-and-content.md
結構已確定:看起來是否完整?類型、間距、徽章、圖表、表格欄位、狀態、顏色、深度visual-craft.md,一個七模式索引;只打開你需要的模式檔案
表面的工作是顯示數據:圖表標題和刻度、篩選器放置、單次掃描行data-display.md
這個區塊應該存在嗎、事實屬於哪裡、什麼吸引注意力、強調是否與任務衝突?information-and-attention.md
操作控制、數據表示、次要操作的揭露product-ui.md
表單和資料輸入:驗證時機、哪些欄位、錯誤措辭、欄位順序R-SYN-022 在 interaction-and-states.md 中,R-VIS-032 在 tables-forms-responsive.md 中
搜尋或篩選沒有返回結果R-INF-016 在 information-design.md 中
記錄頁面:身份、狀態、動作在一個標題中R-INF-017 在 information-design.md 中
真實數據破壞頁面:空的區塊佔據頂部、「1 個項目」、預覽列表將其他內容推下、長值破壞其行、螢幕上出現 nullR-INF-019 在 information-design.md 中
登陸或編輯表面showcase-and-reading.md
事件驅動狀態、非同步反饋、等待、動畫、焦點、復原interaction-and-states.md
WCAG 範圍的檢查、響應式行為、單位、文字縮放、輸入存取accessibility-and-responsive.md
將診斷轉化為有邊界的修復critique-and-repair.md
在報告任何視覺或行為結果之前verification.md
必須報告規則的來源、證據類型、範圍或例外sources.md

粗糙度探測。 在複製 roughness-probe.md 中的欄位後,針對正在運行的頁面執行 node scripts/roughness-probe.mjs <config.json>。它會演練懸停、覆蓋層、行操作和狀態顏色。退出 0:在其測量的內容上未發現任何問題。退出 1:發現需修復或說明的問題。退出 2:無法測量。

渲染審計。 當瀏覽器可以運行時,啟動專案的開發或預覽伺服器,然後執行 node scripts/render-audit.mjs <config.json>。複製 render-audit.example.json。它需要 playwright 或 playwright-core,或設定 PLAYWRIGHT_MODULE 和 CHROME_PATH。退出 0:在其測量的內容上乾淨。退出 1:發現需修復或說明的問題。退出 2:沒有回應,或執行測量了錯誤的內容;它不證明任何事。然後遵循 visual-craft.md 中的快速路徑。render-audit.md 說明了每個檢查涵蓋的內容。

已運作的範例。 僅在其任務匹配時閱讀一個:儀表板、表單、登陸頁面、編輯 或 構圖通行證。

輸出

首先列出發現,按它們阻礙任務地圖的程度排序,每行一個並帶有其規則 ID。帳本透過規則 ID 引用它們,而不是重複它們。

對於評估,然後返回一個緊湊的證據帳本:表面和任務、觀察到的事實、診斷和不確定性、適用的規則 ID、最小的修復或建議、保留的內容和控制項、近似案例以及檢查。不要編輯。

對於授權的變更,返回相同的帳本,加上變更的檔案、變更前後的檢查、渲染狀態和限制。使用使用者的語言。缺少瀏覽器或測試能力會使該結果保持未驗證;完成獨立的授權工作,並報告確切的限制,而不是聲稱視覺或功能上的成功。

相關技能