Communitygithub.com

josueh04/product-video-skills

將產品的實際前端程式碼轉換為 1:1 的影片重建規範,每個畫面使用一個唯讀子代理,回傳靜態 HTML、CSS,所有變數解析為字面值並附上引用、每個狀態、動畫轉場、圖示與 i18n 字串。

product-video-skills 是什麼?

這項技能旨在解決產品影片重建過程中,因為規格資訊不精確而導致的品質問題。它會從產品的真實前端程式碼中提取所有視覺細節,包括幾何尺寸、字體、顏色、動畫、圖示與文字字串,並確保每個值都是實際運行的字面值,而非推測值。 它的運作方式是先為整個產品建立全域渲染事實(如根字型大小、主題、設計 token),然後為每個畫面啟動一個獨立的唯讀子代理,平行掃描原始碼並回傳精確的 HTML/CSS 規格。所有 CSS 變數都會被解析,未定義的變數會被標記,圖示直接來自產品的圖示庫,字串取自 i18n 檔案。 技能支援 Angular with PrimeNG(經生產驗證),以及 React、Vue、Tailwind 與純 HTML(尚未驗證)。它也包含修復可見生產缺陷的邏輯,例如內距遺失、文字截斷或未定義變數,同時保留設計決策。最終產出是每個畫面的規格文件(.md 與 .html),並附上完整的引用與檢查清單,供影片建置流程使用。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/ui-spec-from-code

在你喜歡的 AI 中提問

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

說明文件

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-primengreferences/adapters/angular-primeng.md經生產驗證
reactreferences/adapters/react.md未經驗證
vuereferences/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 或真實客戶資料
  • 已列出修正與保留的奇特之處;已為審查者列出未驗證的值

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

相關技能