UI 示範編輯器
產品影片在這裡是一個 HyperFrames 組合,由每個影片你編寫的三個檔案和每個影片共享的工具包組成:
| 檔案 | 用途 | 編輯者 |
|---|---|---|
video/build.py | 節拍表 T:所有時間點皆源自字詞時間 | 你 |
video/src/template.tpl | 重建的 UI、螢幕圖層和 GSAP 時間軸 | 你 |
video/src/app.css | 產品 UI CSS,來自 specs/ 的字面值 | 你 |
kit/stage.css、kit/titles.css、kit/stage.js | 舞台圖層和防跳動輔助工具 | 此技能 |
products/<slug>/kit/tokens.css、fonts/、icons/、ui/ | 產品的 tokens、字型、圖示和共享 UI 片段 | product-kit |
video/index.html | 由 build.py 產生。切勿手動編輯。 | 無人 |
scripts/buildlib.py 處理每個建置的通用部分(時間點、簽署門檻、音訊標籤、內嵌、佔位符、圖示、攝影機限制),讓 build.py 保持為簡短的節拍列表。
舞台模型
#root > #stage > #camera > #blurWrap > #app 產品,以應用程式像素為單位
> #veil, .pvs-ttl, #endS, #lock, #fade 螢幕空間,1920x1080
- UI 在其真實視口重建並縮放一次。
#app是product.yaml app_canvas.logicalCSS 像素(例如 1440x810),透過一個 transform 縮放至 1920x1080。生產 CSS 保留其字面像素,因此規格值可直接貼入,且每個測量值都能與程式碼進行 1:1 比較。選擇一個高於應用程式斷點、長寬比為 16:9 的桌面寬度;如果有螢幕錄影,則使用其邏輯尺寸。非 16:9 的畫布會加上黑邊(buildlib 會發出警告)。 - 位置是測量出來的,不是手動輸入的。
S.box(sel)在字型載入後將偏移量加總至#app。如果 CSS 更改,游標仍會落在按鈕上。 - 游標和點擊漣漪是
#app的最後一個子元素,因此它們會隨產品一起縮放和模糊。彈出視窗(.pvs-modal)和提示訊息(.pvs-toast-slot)也位於#app中。 - 只有
#camera移動,只有#blurWrap模糊。 切勿對#app或#stage進行補間動畫。
取景:預設為 1 倍全頁
預設每個產品節拍為 1 倍、全頁,彈出視窗以自然大小顯示並置中,如同應用程式顯示它們的方式。推近是溫和的(最高 video.max_zoom,預設為 1.35),保持整個區域在畫面內,切勿讓畫面邊緣穿過標籤。每個章節一個取景:在產品失焦時,在章節標題後方進行移動,或作為一個緩慢的簽名式移動。
原因:在這些技能所源自的生產過程中,一個設定影片因縮放而被拒絕了兩次。1.67 倍的推近裁剪了標籤的一半(「我看不出發生了什麼事」),之後每欄約 2 倍的取景即使沒有裁剪也感到擁擠。審查者視為模型的影片全程以 1 倍執行。一個較遠的畫布(顯示為 50%)或一個狹窄的聊天欄可以容忍更多:為該產品在 product.yaml 中提高 max_zoom,而不是為每個節拍。b.cam() 和 S.cam() 會將值限制在 max_zoom 以上並發出警告。詳細資訊和數字:references/framing-and-pacing.md。
節奏:章節是暫停
- 從背景開始,切勿從 UI 中間開始:標誌、產品名稱和一行關於它是什麼的文字,位於失焦的產品上方。
- 每個章節以一個雙色標題開頭,位於產品模糊失焦(模糊加面紗)之上,至少保持約 1.4 秒,並且正好在命名第一個動作的字詞之前恢復對焦。畫面變化發生在標題後方,因此沒有硬切。
- 每個章節一個想法,一次一個變化,間隔 0.6 到 1 秒,每個章節結束時暫留約 0.8 秒。產品的實際等待時間壓縮為 1 或 2 秒。
- 結束畫面顯示廣度(產品還能做什麼,使用真實的 UI 片段),然後是鎖定畫面。
原因:一個密集的一鏡到底剪輯,每 0.5 秒有一個微動作,對製作者來說是精緻,對審查者來說是雜訊(「太快、一次太多、令人難以承受」);在結果中放大和縮小使它們無法跟上。平靜的章節化版本獲得批准。
每個節拍都錨定在一個字詞上
b = buildlib.Build(__file__)
T, w, end = b.T, b.w, b.end
T["N2"] = T["ch1"] + 0.3 # 放置剪輯 ID 會放置該剪輯
T["rack1"] = T["N2"] + w("N2", "after") - 0.25 # 對焦正好在 "after" 之前恢復
T["send1"] = max(T["type1"] + T["type1Dur"] + 0.4, end("N3") + 0.15)
w(clip, prefix, nth=1)是第一個以prefix開頭的字詞的開始時間(相對於該剪輯)。當找不到該字詞時會引發錯誤(沒有靜默回退:一個會將節拍靜默地落在預設時間的回退,正是動作不知不覺偏離旁白的原因)。- UI 事件比命名它的字詞早 0.05 到 0.45 秒發生。
max()同時保留了旁白順序和「UI 已完成」;end(k)是T[k]加上剪輯持續時間(或b.dur(k, d))。 - 打字速度以每秒字元數為單位(約 17 到 21),或固定以符合一個節拍。
- 點擊、打字和彈出視窗的聲音發生在同一個
T上(b.click(t)、b.typing(text, t, dur)、b.pop(t)),因此重新調整時間的節拍也會移動其聲音。 - 重新產生一行語音會重新計時整個影片。這就是重點。
原因:時間控制有單一事實來源。當一行臺詞重新產生時,所有錨定在它上面的東西都會一起移動;手動輸入的秒數在第一次重拍時就會過時。
工作流程
- 閱讀
BRIEF.md(章節、取景)、COVERAGE.md(每個章節必須在螢幕上解釋什麼)、specs/*.md和TRUTH.md。不要發明 UI:一個沒有SOURCES.md或specs/中來源的螢幕或行為,就應排除在外。 - 根據規格在
src/template.tpl和src/app.css中重建螢幕,使用來自 product.yamlcast的虛構資料。使用{{UI:name}}重用kit/ui/中的產品片段,而不是從另一個影片複製(references/ui-component-library.md)。 - 使用工具輔助工具在
build.py中編寫節拍,並在範本中編寫時間軸(API 請參閱references/stage-kit.md,每個節拍的詳細資訊請參閱references/beat-recipes.md,請參閱references/end-screen-and-lockup.md)。遵循每個補間動畫的防跳動運動技能。 - 建立草稿並讀取它列印的節拍表:
在任何語音存在之前,PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)" "$PVS_HOME/bin/pvs-py" <video_dir>/video/build.py --draft--draft --fake-timings會從lines.tsv發明字詞時間,以便你可以佈局螢幕。 - Lint 和檢查,從
<video_dir>/video/:預期 0 個錯誤和 0 個執行時期警告。對於單一架構舞台,預計會有一個 lint 警告:"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" . npx --yes [email protected] checkcomposition_file_too_large(工具包已內嵌)。然後執行建置列印的第二個check,check --at <設定節拍時間>:預設樣本通常只落在失焦的時刻,工具包在那裡對比度傳遞隱藏了產品文字(因為它故意模糊),因此那裡的contrast ... checked 0並未稽核讀者看到的任何內容。僅check是不夠的:它在一個移動項目在其路徑的大部分時間都不可見的影片上通過了。查看畫格。 - 快照每個設定節拍並親自查看每個圖片。在 build.py 中使用
b.snap(t, label)標記它們;建置會列印確切的命令:npx --yes [email protected] snapshot . --at 3.2,4.7,9.98 --no-end --describe false -o snapshots/setup--no-end僅捕獲那些時間點;--describe false防止畫格被發送到外部視覺 API。檢查取景(沒有在邊緣裁剪任何東西)、游標在其目標上、彈出視窗以自然大小居中、標題完整。--zoom "#toast" --zoom-scale 2會裁剪一個元素。要測試可疑的補間動畫,--at <start>,<later>必須與--at <later>匹配。 - 渲染。一個用於審查的草稿,然後在 BRIEF.md 簽署後進行交付(build.py 會列印此行):
然後在 MP4 上執行 render-qa。保留每個版本的 MP4。npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality draft npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality delivery
簽署門檻
build.py 拒絕建置,直到 coverage_signed_by 和 claims_signed_by 在 BRIEF.md 中設定(退出碼 2)。--draft 無論如何都會建置,並將 <meta name="pvs-draft" content="1"> 蓋入 index.html;QA 將其報告標記為草稿,而交付則拒絕它。不要代表審查者簽署,也不要移除 meta:草稿是為了查看,絕不能用於發布。
原因:在這些技能所源自的生產過程中,26 個版本中有 9 個是因為影片沒有解釋審查者在意的功能,而且沒有人在建置之前寫下這些功能。門檻確保協議優先。
來自事件的規則
- 修復生產瑕疵,保留外觀。 保持佈局、tokens 和行為 1:1,但修復即時應用程式的可見缺陷(缺少的內邊距、溢出或裁剪的文字、灰色原生控制項、點擊後留下的焦點環)。在 BRIEF.md 筆記中列出每個修復。
- 當產品可設定時,顯示可設定的內容。 買家會問到的設定應顯示在螢幕上,而不僅在旁白中。
- 在開啟覆蓋於選單上方的模態視窗前一畫格,關閉該選單。 一個新對話框下開啟的下拉選單在一個渲染中留下了幽靈文字。
- 僅將結束畫面內容淡入鎖定畫面,在鎖定畫面出現之前保留其背景。兩者都淡出會在它們之間顯示一個尖銳 UI 的畫格(
S.lockup會執行此操作)。 - 在點擊之前懸停(在點擊前約 0.12 秒使用
hov類別),游標在第一次失焦之後進入,並在結束畫面之前移出。 - UI、資料或旁白中不得有供應商或禁止的名稱(product.yaml
banned_terms、names)。如果真實螢幕顯示了一個,請將該片段保持在畫面外,並且切勿讓它明顯地空白。 - 不要為了及早顯示進度而渲染。 使用快照進行迭代;當設定節拍看起來正確時再進行渲染。
檔案
| 路徑 | 何時閱讀 |
|---|---|
references/stage-kit.md | 當你需要輔助工具的簽名、佔位符、CSS 變數或 buildlib API 時 |
references/beat-recipes.md | 當你建立特定節拍時:開場、章節、點擊、打字、串流、彈出視窗、下拉選單、提示訊息、滾動、推近 |
references/framing-and-pacing.md | 當你選擇取景或節奏,或審查者說「縮放」、「太快」、「混亂」時 |
references/end-screen-and-lockup.md | 當你建立結尾時 |
references/ui-component-library.md | 當一個 UI 片段會出現在多個影片中,或你正要從另一個影片複製標記時 |
scripts/buildlib.py | 當你需要 API 參考未涵蓋的行為時 |
kit/stage.js | 相同,用於時間軸輔助工具 |
PVS_HOME/_template/video/video/ | 每個新影片開始時的範例 build.py、template.tpl 和 app.css |