UI-Demo-Komponist
Ein Produktvideo ist hier eine HyperFrames-Komposition, die aus drei Dateien pro Video und einem Kit besteht, das von jedem Video gemeinsam genutzt wird:
| Datei | Was sie ist | Wer sie bearbeitet |
|---|---|---|
video/build.py | Die Beat-Tabelle T: jede Zeit abgeleitet aus den Wort-Timings | Du |
video/src/template.tpl | Die nachgebaute UI, die Bildschirmebenen und die GSAP-Timeline | Du |
video/src/app.css | Das Produkt-UI-CSS, Literalwerte aus specs/ | Du |
kit/stage.css, kit/titles.css, kit/stage.js | Bühnenebenen und suchsichere Helfer | Diese Skill |
products/<slug>/kit/tokens.css, fonts/, icons/, ui/ | Die Tokens, Schriften, Icons und geteilten UI-Stücke des Produkts | product-kit |
video/index.html | Von build.py generiert. Niemals von Hand bearbeiten | Niemand |
scripts/buildlib.py erledigt den generischen Teil jedes Builds (Timings, das Signatur-Gate, Audio-Tags, Inlining, Platzhalter, Icons, die Kamera-Clampung), sodass build.py eine kurze Liste von Beats bleibt.
Das Bühnenmodell
#root > #stage > #camera > #blurWrap > #app das Produkt, in App-Pixeln
> #veil, .pvs-ttl, #endS, #lock, #fade Bildschirmraum, 1920x1080
- Die UI wird im nativen Viewport nachgebaut und einmal skaliert.
#appistproduct.yaml app_canvas.logicalCSS-Pixel (z. B. 1440x810), skaliert auf 1920x1080 durch eine Transform. Produktions-CSS behält seine Literalpixel, sodass ein Spezifikationswert unverändert eingefügt wird und jeder Messwert 1:1 mit dem Code verglichen werden kann. Wähle eine Desktop-Breite oberhalb des Breakpoints der App, im 16:9-Format; falls es eine Bildschirmaufzeichnung gibt, verwende deren logische Größe. Eine Leinwand, die nicht 16:9 ist, wird letterboxed (buildlib warnt). - Positionen werden gemessen, nie eingetippt.
S.box(sel)summiert Offsets bis zu#appnachdem Schriften geladen sind. Wenn sich das CSS ändert, landet der Cursor trotzdem auf dem Button. - Der Cursor und der Klick-Ripple sind die letzten Kinder von
#app, sodass sie mit dem Produkt skalieren und unscharf werden. Pop-ups (.pvs-modal) und Toasts (.pvs-toast-slot) leben ebenfalls in#app. - Nur
#camerabewegt sich und nur#blurWrapmacht unscharf. Tweene niemals#appoder#stage.
Rahmung: 1x ganze Seite als Standard
Standardmäßig jeder Produkt-Beat auf 1x, ganze Seite, mit Pop-ups in natürlicher Größe und zentriert,
wie die App sie zeigt. Push-ins sind sanft (bis zu video.max_zoom, standardmäßig 1,35),
halten den gesamten Abschnitt im Rahmen und setzen nie einen Rahmenrand durch ein Label. Ein
Rahmen pro Kapitel: führe die Bewegung hinter dem Kapiteltitel aus, während das Produkt unscharf ist, oder als eine
einzige langsame Signaturbewegung.
Warum: In der Produktion, aus der diese Skills stammen, wurde ein Einstellungsvideo zweimal wegen Zooms abgelehnt.
Ein 1,67x Push-in schnitt Labels in der Hälfte ab („Ich kann nicht erkennen, was passiert“), und spätere Rahmungen
von etwa 2x pro Spalte wirkten beengt, selbst wenn nichts abgeschnitten war. Das Video, das der Gutachter als
Vorbild nannte, lief die ganze Zeit bei 1x. Eine weit entfernte Leinwand (bei 50 % angezeigt) oder eine schmale
Chat-Spalte toleriert mehr: erhöhe max_zoom in product.yaml für dieses Produkt, nicht pro Beat.
b.cam() und S.cam() clamben oberhalb von max_zoom und warnen. Details und Zahlen:
references/framing-and-pacing.md.
Tempo: Kapitel sind Pausen
- Öffne im Kontext, niemals mitten in der UI: Logo, Produktname und eine Zeile, was es ist, über dem Produkt unscharf.
- Jedes Kapitel öffnet mit einem zweifarbigen Titel über dem unscharf gestellten Produkt (Unschärfe plus Schleier), hält mindestens etwa 1,4 s, und der Fokus kehrt kurz vor dem Wort zurück, das die erste Aktion benennt. Bildschirmwechsel erfolgen hinter dem Titel, sodass es keine harten Schnitte gibt.
- Eine Idee pro Kapitel, eine Änderung nach der anderen, 0,6 bis 1 s Abstand, ein Innehalten von etwa 0,8 s am Ende jedes Kapitels. Echte Wartezeiten des Produkts werden auf 1 oder 2 s komprimiert.
- Der Endbildschirm zeigt die Breite (was das Produkt sonst noch kann, mit echten UI-Stücken), dann das Lockup.
Warum: Ein dichter One-Take-Cut mit einer Mikro-Aktion alle 0,5 s wirkte für den Macher wie poliert und für den Gutachter wie Rauschen („zu schnell, zu viel auf einmal, überwältigend“); Hinein- und Herauszoomen in den Ergebnissen machte sie unmöglich zu verfolgen. Die ruhige, kapitulierte Version wurde genehmigt.
Jeder Beat ist an ein Wort verankert
b = buildlib.Build(__file__)
T, w, end = b.T, b.w, b.end
T["N2"] = T["ch1"] + 0.3 # Platzieren einer Clip-ID platziert diesen Clip
T["rack1"] = T["N2"] + w("N2", "nach") - 0.25 # Fokus kehrt kurz vor „nach“ zurück
T["send1"] = max(T["type1"] + T["type1Dur"] + 0.4, end("N3") + 0.15)
w(clip, prefix, nth=1)ist der Start des ersten Wortes, das mitprefixbeginnt, relativ zum Clip. Es löst einen Fehler aus, wenn das Wort fehlt (kein stiller Fallback: Ein Fallback, der einen Beat stillschweigend zu einer Standardzeit setzt, führt dazu, dass die Bewegung unbemerkt von der Stimme abdriftet).- Ein UI-Ereignis führt das Wort, das es benennt, um 0,05 bis 0,45 s an.
max()stellt sowohl die Erzählreihenfolge als auch „die UI ist fertig“ sicher;end(k)istT[k]plus die Clip-Dauer (oderb.dur(k, d)). - Tippgeschwindigkeit ist Zeichen pro Sekunde (etwa 17 bis 21), oder festgelegt, um einen Beat zu passen.
- Klicks, Tippen und Pop-ups erhalten ihren Ton auf demselben
T(b.click(t),b.typing(text, t, dur),b.pop(t)), sodass ein neu getakteter Beat auch seinen Ton bewegt. - Das Neugenerieren einer Sprachzeile taktet das gesamte Video neu. Das ist der Sinn.
Warum: Timing hat eine einzige Quelle der Wahrheit. Wenn eine Zeile neu generiert wird, bewegt sich alles, was daran verankert ist, mit; handgetippte Sekunden werden beim ersten Retake ungültig.
Arbeitsablauf
- Lese
BRIEF.md(Kapitel, Rahmung),COVERAGE.md(was jedes Kapitel auf dem Bildschirm erklären muss),specs/*.mdundTRUTH.md. Erfinde keine UI: Ein Bildschirm oder Verhalten ohne Quelle inSOURCES.mdoderspecs/bleibt außen vor. - Baue die Bildschirme in
src/template.tplundsrc/app.cssaus den Spezifikationen mit fiktiven Daten aus product.yamlcastwieder. Verwende Produktstücke auskit/ui/mit{{UI:name}}, anstatt sie aus einem anderen Video zu kopieren (references/ui-component-library.md). - Schreibe die Beats in
build.pyund die Timeline in der Vorlage mit den Kit-Helfern (references/stage-kit.mdfür die API,references/beat-recipes.mdfür jeden Beat,references/end-screen-and-lockup.md). Folge der suchsicheren Bewegungsskill für jedes Tween. - Baue einen Entwurf und lese die Beat-Tabelle, die er ausgibt:
Bevor eine Stimme existiert, erfindetPVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)" "$PVS_HOME/bin/pvs-py" <video_dir>/video/build.py --draft--draft --fake-timingsWort-Timings auslines.tsv, sodass du Bildschirme anordnen kannst. - Linten und prüfen, von
<video_dir>/video/:Erwarte 0 Fehler und 0 Laufzeitwarnungen. Eine Lint-Warnung wird für die monolithische Bühne erwartet:"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" . npx --yes [email protected] checkcomposition_file_too_large(das Kit ist inline). Führe dann die zweitecheckaus, die der Build ausgibt,check --at <Setup-Beat-Zeiten>: Die Standard-Stichproben landen oft nur auf unscharfen Momenten, bei denen das Kit den Produkttext vor dem Kontrastdurchlauf versteckt (der Text ist absichtlich unscharf), sodasscontrast ... checked 0dort nichts geprüft hat, was ein Zuschauer liest.checkallein ist nicht genug: Es bestand ein Video, bei dem sich bewegende Elemente für den größten Teil ihres Pfads unsichtbar waren. Betrachte die Einzelbilder. - Erstelle einen Snapshot von jedem Setup-Beat und betrachte jedes Bild selbst. Markiere sie mit
b.snap(t, label)in build.py; der Build gibt den genauen Befehl aus:npx --yes [email protected] snapshot . --at 3.2,4.7,9.98 --no-end --describe false -o snapshots/setup--no-enderfasst nur diese Zeiten;--describe falseverhindert das Senden von Einzelbildern an eine externe Vision-API. Überprüfe die Rahmung (nichts an einer Kante abgeschnitten), den Cursor auf seinem Ziel, Pop-ups zentriert in natürlicher Größe, Titel vollständig.--zoom "#toast" --zoom-scale 2beschneidet ein Element. Um ein verdächtiges Tween zu testen, muss--at <start>,<later>mit--at <later>übereinstimmen. - Rendern. Ein Entwurf zur Überprüfung, dann die Auslieferung, sobald BRIEF.md unterschrieben ist (build.py gibt diese Zeile aus):
Führe dann render-qa auf der MP4 aus. Behalte die MP4 jeder Version.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
Das Signatur-Gate
build.py weigert sich zu bauen, bis coverage_signed_by und claims_signed_by in
BRIEF.md gesetzt sind (exit 2). --draft baut trotzdem und markiert <meta name="pvs-draft" content="1">
in index.html; QA markiert seinen Bericht als Entwurf und die Auslieferung lehnt ihn ab. Unterschreibe nicht im Namen des
Prüfers und entferne das Meta nicht: Ein Entwurf dient zum Ansehen, niemals zum Versand.
Warum: In der Produktion, aus der diese Skills stammen, geschahen 9 von 26 Versionen, weil ein Video keine Funktion erklärte, die dem Prüfer wichtig war, und niemand diese Funktionen vor dem Bau notiert hatte. Das Gate stellt die Vereinbarung an erste Stelle.
Regeln aus Vorfällen
- Behebe Produktionsfehler, behalte das Aussehen. Behalte Layout, Tokens und Verhalten 1:1, behebe aber sichtbare Mängel der Live-App (fehlende Abstände, überlaufender oder abgeschnittener Text, graue native Steuerelemente, ein nach einem Klick übrig gebliebener Fokusring). Liste jede Behebung in den Notizen von BRIEF.md auf.
- Zeige, was konfigurierbar ist, wenn das Produkt konfigurierbar ist: Die Einstellungen, nach denen ein Käufer fragen würde, gehören auf den Bildschirm, nicht nur in die Erzählung.
- Schließe ein Menü einen Frame, bevor du ein Modal darüber öffnest. Ein geöffnetes Dropdown unter einem neuen Dialog hinterließ in einem Rendering Geistertext.
- Überblende nur den Inhalt des Endbildschirms in das Lockup, behalte seinen Hintergrund, bis das Lockup
angezeigt wird. Das Überblenden beider zeigte einen Frame einer scharfen UI dazwischen (
S.lockupmacht dies). - Hover vor dem Klick (
hov-Klasse etwa 0,12 s davor), Cursor nach dem ersten Rack hinein und vor dem Endbildschirm heraus. - Keine Hersteller- oder verbotenen Namen in UI, Daten oder Erzählung (product.yaml
banned_terms,names). Wenn ein echter Bildschirm einen zeigt, halte dieses Stück aus dem Frame und lasse es nie sichtbar leer. - Render nicht, um frühzeitig Fortschritt zu zeigen. Iteriere mit Snapshots; rendere erst, wenn die Setup-Beats korrekt aussehen.
Dateien
| Pfad | Lies es, wenn |
|---|---|
references/stage-kit.md | Du benötigst die Signatur eines Helfers, einen Platzhalter, eine CSS-Variable oder die buildlib-API |
references/beat-recipes.md | Du baust einen bestimmten Beat: Eröffnung, Kapitel, Klick, Tippen, Streaming, Pop-up, Dropdown, Toast, Scrollen, Push-in |
references/framing-and-pacing.md | Du wählst eine Rahmung oder einen Rhythmus, oder der Prüfer sagt „gezoomt“, „schnell“, „chaotisch“ |
references/end-screen-and-lockup.md | Du baust das Ende |
references/ui-component-library.md | Ein UI-Stück wird in mehr als einem Video erscheinen, oder du bist dabei, Markup aus einem anderen Video zu kopieren |
scripts/buildlib.py | Du benötigst Verhalten, das die API-Referenz nicht abdeckt |
kit/stage.js | Dasselbe, für die Timeline-Helfer |
PVS_HOME/_template/video/video/ | Das Beispiel build.py, template.tpl und app.css, von dem jedes neue Video ausgeht |