UI 規格來自程式碼
影片是重建產品的介面(使用 HTML 與 CSS),而不是錄製畫面,因此介面的真實度完全取決於重建所依據的規格。任何近似值都會被察覺:在這些技能所來自的實際製作中,審查者在第一次審查就拒絕了手繪的圖示與標誌,而一個尺寸和名稱錯誤的手工徽章更讓他勃然大怒。修正是透過閱讀程式碼來進行的,而程式碼中藏著肉眼看不到的陷阱:根字型大小在執行時由應用程式外殼設定(14 px,而非樣式表宣告的 10 px)、數個 CSS 變數在生產環境中並不存在而呈現了備用值、一個元件的裝飾條早在兩個月前的一次提交中遺失、以及兩個「對話框」實際上是自訂彈出視窗,而非該函式庫的對話框。
因此,規格中的每個值都是字面值且附有引用,而任何你無法引用的值都會被標記,絕不猜測。
輸入
videos/<video>/SOURCES.md來自 source-recon:每個畫面、其路由、元件與狀態。如果缺少此檔案,請先執行 source-recon。sources/<role>/與sources.lock。每個引用都使用鎖定的 sha。product.yaml:app_canvas.logical(重建 UI 的視埠)、app_canvas.theme、app_canvas.rem_px、sources[].framework。- 該框架的適配器:
references/adapters/<framework>.md。在撰寫子代理提示詞之前先閱讀它;它說明了在該技術堆疊中數值隱藏在何處。
| product.yaml 中的 framework | 適配器 | 狀態 |
|---|---|---|
angular-primeng | references/adapters/angular-primeng.md | 經生產驗證 |
react | references/adapters/react.md | 未經驗證 |
vue | references/adapters/vue.md | 未經驗證 |
| 任何使用 Tailwind 的技術堆疊 | references/adapters/tailwind.md(與該框架自身的搭配使用) | 未經驗證 |
html、other、伺服器模板 | references/adapters/html.md | 未經驗證 |
對於未經驗證的適配器,請告知使用者其未經驗證狀態,遵循它,並在最後將你學到的內容新增到其中(一個簡短的「在 上學到的」章節),以便下一個產品能從更高的起點開始。
1. 全域渲染事實(每個產品一次)
在任何畫面之前,先建立每個畫面都會依賴的事實,並將它們寫入 kit/render-facts.md,並附上引用:
- 根字型大小 在執行時(搜尋應用程式外殼中設定它的程式碼,而不僅僅是 CSS),以便
rem能正確轉換。如果有所不同,請更新 product.yaml 中的app_canvas.rem_px。 - 主題:哪個選擇器能開啟影片的主題,以及它是否預設為開啟。
- Token 檔案、CSS 層級或匯入順序(哪條規則勝出),以及元件函式庫,包含來自鎖定檔的確切版本及其主題預設。
- 實際載入的字型(link 標籤、
@font-face、字型套件),而不僅僅是在 CSS 中命名的。在生產環境中,已宣告但從未載入的字型會以備用字型呈現。 - 桌面斷點,以確認
app_canvas.logical顯示的是桌面佈局。
然後撰寫 token,針對影片的主題解析為字面值:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <product_dir> \
[--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]
它會從 sources/<role>/ 讀取 CSS 自訂屬性、頂層 SCSS 變數以及 Tailwind v3 主題(靜態地),解析每個 var() 與 $variable,並寫入 kit/tokens.css,每行附上 /* role/path:line@sha */ 的引用。被標記為 UNDEFINED 的行是生產環境中未定義的變數(可能的錯誤);needs a Sass compile 則標記使用 Sass 函數建構的值,子代理必須根據函數及其輸入手動解析。當匯出的檔案包含不相關的樣式表(說明文件站點、電子郵件模板、供應商提供的 CSS)時,請使用 --files。
2. 每個畫面一個子代理
每個畫面(或大型畫面的一個面板)啟動一個唯讀子代理,全部並行執行,填入 references/ui-spec-prompt.md 並附加適配器的「數值隱藏位置」清單。將每個子代理指向 sources/<role>/(而非使用者的簽出副本),並提供渲染上下文:邏輯畫布尺寸、主題、rem、渲染事實、token,以及已重建片段的 CSS,以便新片段能與之匹配。
每個子代理回傳:畫布內的幾何資訊、每個狀態的靜態 HTML(無框架語法)、一個包含字面值與每個值引用的 CSS 區塊、作為額外類別的 hover/focus/active/disabled/loading 狀態、具有確切持續時間和緩動函數的轉場與關鍵影格、依函式庫和名稱分類的圖示(或逐字內聯 SVG)、每個可見字串,以及一個明確的「未驗證」清單。
協調者(你)本身不提取規格:真實應用程式的一個畫面可能包含數十 KB 的發現結果,而若協調者的上下文在影片中途被填滿,將會失去對整個建置流程的掌握。
3. 圖示與圖片
圖示來自產品自身的圖示集與資產,絕不手繪,也絕不來自瀏覽器設定檔或擴充功能資料夾。每個產品執行一次 references/icon-extraction-prompt.md(並在新畫面出現時再次執行),以將影片所需的每個圖示對應到其函式庫和名稱,然後將這些名稱交給 product-kit 的 collect_icons.py,它會將 SVG 複製到 kit/icons/ 並附上引用。對於沒有 SVG 檔案的圖示字型,建置流程會從函式庫自身的 CSS 寫入碼點,並且在遇到未知名稱時必須失敗,而不是渲染一個空盒子。
4. 撰寫規格
每個畫面產生 videos/<video>/specs/<screen>.md 與 specs/<screen>.html:
# 規格:<screen>
來源:frontend@1a2b3c4(參見 SOURCES.md)。畫布 1440x810,主題 light,rem 16。
## 幾何
| 元素 | x | y | w | h | 引用 |
## 狀態
S1 <name>:<顯示的內容,虛構資料>。HTML 位於 <screen>.html,章節 S1。
## CSS
<一個區塊,字面值,每行附上 /* role/path:line@sha */>
## 動態效果
| 項目 | 屬性 | 從 | 到 | 持續時間 | 緩動函數 | 延遲 | 引用 |
## 圖示
| 鍵 | 函式庫 | 名稱 | kit/icons 中的檔案 | 引用 |
## 字串
| 鍵 | 文字 | 引用 |
## 修正(在影片中修正的生產環境錯誤)
| 項目 | 生產環境行為 | 影片行為 | 原因 |
## 未驗證
- <數值或行為、原因,以及最佳可用參考>
保留外觀,修正錯誤
1:1 重建佈局、token 與行為,包含讓它看起來像真實產品的動畫、懸停、打字與載入狀態。但請修正可見的生產缺陷,因為影片展現的是產品的最佳狀態,而審查者會問為什麼畫面上會有錯誤:缺失的內距、溢出、文字被裁切、原生瀏覽器控制項(一個灰色的預設音訊播放器)而非產品設計的控制項、描繪備用值的未定義變數、點擊後殘留的焦點環。在規格的「修正」表格和 BRIEF 筆記中列出每個修正。保留屬於設計決策的奇特之處(例如覆蓋某個欄位的固定頁尾、與內容一起滾動的側邊欄);更改這些是重新設計,而非修正。
規格會套用並記錄兩個額外的轉換:
- 規範名稱。 將來自
product.yaml names的舊字串取代為規範名稱,即使實際 UI 仍顯示舊名稱,並保留該元素的其他所有部分。 - 禁用詞彙。 如果實際畫面顯示了供應商或在
banned_terms中的詞彙(例如模型選擇器、整合卡片),則將該部分排除在畫面之外。不能讓它看起來是空的或壞掉的;選擇一個它自然不存在的取景或狀態。
資料
規格僅使用來自 product.yaml cast 的虛構資料。儲存庫中的 Fixture、種子和螢幕截圖可以包含真實姓名;使用它們的形式,絕不使用它們的值。
將規格交給建置流程前的檢查清單
- 鎖定的提交已引用;渲染事實已撰寫;針對影片的主題解析了 token
- 畫布尺寸高於桌面斷點;rem 與執行時相符
- 每個
var()已解析;未定義的已列出其備用值(或作為錯誤修正) - 每個字串來自 i18n 檔案或模板;已套用規範名稱
- 每個圖示來自應用程式的函式庫;建置流程在遇到缺少的字形時會失敗
- 標誌與圖片來自儲存庫資產
- 預設狀態(分頁、手風琴、切換開關)與程式碼相符
- 疊加層、彈出視窗與轉場時間設定具有確切的緩動函數
- 滾動範圍在實際內容之內;文字沒有在邊緣被截斷
- 畫面中沒有供應商、禁用詞彙、內部 ID 或真實客戶資料
- 已列出修正與保留的奇特之處;已為審查者列出未驗證的值