Communitygithub.com

josueh04/product-video-skills

将产品的真实前端代码转化为一比一重建视频的规范说明,每个屏幕由一个只读子代理处理,返回静态HTML/CSS,所有变量解析为字面值并附上引用,涵盖每个状态、过渡动画、图标和国际化字符串。

product-video-skills 是什么?

该技能用于从产品的前端代码中精确提取UI规范,以便在视频中重建界面,而非录制真实窗口。它通过只读子代理并行处理每个屏幕,返回静态HTML与CSS,其中每个CSS值都解析为字面量并附带代码引用(角色/路径:行号@提交SHA),确保所有变量、字体、图标、过渡动画和i18n字符串均来自真实代码。技能支持Angular+PrimeNG(已验证)以及React、Vue、Tailwind和纯HTML(未验证)的适配器架构,并提供resolve_tokens.py工具将设计令牌导出为kit/tokens.css。它特别适合需要在视频中精确复现产品界面的场景,当屏幕在视觉上与真实应用存在差异时,能自动标记并修复生产缺陷(如未定义的变量、被截断的文本、错误的字体大小),同时保留合理的设计异常。

兼容平台✓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 中的框架适配器状态
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 显示桌面布局。

然后写入令牌,解析为视频主题的字面量:

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 ...]

它读取 CSS 自定义属性、顶层 SCSS 变量以及来自 sources/<role>/ 的 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、渲染事实、令牌以及已重建部分的 CSS,以便新部分与之匹配。

每个子代理返回:画布内的几何信息、每个状态的静态 HTML(无框架语法)、一个包含字面值和每个值引用的 CSS 块、作为额外类的悬停/聚焦/激活/禁用/加载状态、具有确切持续时间和缓动函数的过渡和关键帧、按库和名称组织的图标(或逐字内联 SVG)、每个可见字符串,以及一个明确的“未验证”列表。

协调器(您)本身不会提取规范:真实应用的一个屏幕可能需要数十千字节的调查结果,而一个上下文在视频中间填满的协调器会丢失整个构建的跟踪。

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 中的文件 | 引用 |

## 字符串
| 键 | 文本 | 引用 |

## 修复(视频中修复的生产故障)
| 内容 | 生产环境表现 | 视频表现 | 原因 |

## 未验证
- <值或行为,原因,以及最佳可用参考>

保持外观,修复故障

一比一重建布局、令牌和行为,包括使其感觉像真实产品的动画、悬停、打字和加载状态。但修复可见的生产缺陷,因为视频展示了产品的最佳状态,审核人员会问为什么屏幕上显示了一个错误:缺少内边距、溢出、文本被截断、原生的浏览器控件(一个灰色的默认音频播放器)出现在产品原本设计的位置、未定义的变量绘制回退值、点击后的聚焦环残留。在规范的“修复”表和 BRIEF 注释中列出每个修复。保留设计决策中的异常(覆盖字段的粘性页脚、随内容滚动的侧边栏);改变这些属于重新设计,而非修复。

规范还应用并记录了两种转换:

  • 规范名称。 即使实时 UI 仍显示旧名称,也将 product.yaml names 中的遗留字符串替换为规范名称,并保留该元素的其他所有内容。
  • 禁止术语。 如果真实屏幕显示了供应商或 banned_terms 中的术语(模型选择器、集成卡片),请将该部分排除在画面之外。它不能看起来空荡荡或破损;选择一个它自然缺席的取景或状态。

数据

规范仅携带来自 product.yaml cast 的虚构数据。仓库中的夹具、种子和截图可以包含真实姓名;使用它们的形状,绝不使用它们的值。

将规范交给构建之前的检查清单

  • 引用了锁定的提交;写入了渲染事实;令牌已针对视频主题解析
  • 画布大小超过桌面断点;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.

相关技能