frontend-design

# frontend-design

Use this as the design-lead layer for VideoStudio COMPOSE work. It shapes `project/composition/composition-manifest.json::art_direction` and the model-authored HTML/SVG motion graphics in `index.html`.

This skill does not pick the video production line, replace `video-craft`, or relax Orkas renderer constraints. If there is a conflict, renderer determinism, safe zones, legibility, audio ownership, and user-approved creative direction win.

## Generation references

Read only the references required by the current composition:

- [HTML generation playbook](references/html-generation-playbook.md) — read before coding every non-trivial COMPOSE deliverable for the private art-direction pass, frame-composition rules, and opening/resolved-state authoring pattern.
- [Visual primitives](references/visual-primitives.md) — read when selecting reusable CSS/SVG composition primitives and scene grammar.
- [Worked compositions](references/worked-compositions.md) — read when examples are needed to turn subject matter into a cohesive visual system without copying a fixed template.

These references improve the initial generation. They do not create a new artifact, user gate, or approval step. Keep the art-direction pass internal and record only the decisions needed to make the manifest art direction executable.

## Design Thesis

Before writing HTML, choose a compact visual thesis:

- `subject_world`: the real materials, artifacts, interface metaphors, gestures, environment, or culture of the topic.
- `audience`: who must understand this at phone size and what they already know.
- `one_job`: what this video frame sequence must make clear.
- `tone`: one or two precise words that shape type, color, spacing, and motion.
- `signature_device`: one memorable visual move that belongs to this brief.
- `aesthetic_risk`: one justified choice that avoids generic output without hurting readability.

Keep the thesis specific. "Modern tech style" is not a thesis. "Battery-lab oscilloscope traces become the progress line" is.

## HyperFrames-style authoring discipline

This is a creative discipline, not a fixed renderer or template catalog. VideoStudio still uses model-authored HTML, but the model must author like a motion designer instead of jumping straight from storyboard text to scattered SVG nodes.

### Visual identity hard gate

Do not start `index.html` until the composition has a usable visual identity in `manifest.art_direction`:

- `aesthetic.subject_world`
- `aesthetic.one_job`
- `aesthetic.signature_device`
- `aesthetic.aesthetic_risk`
- `aesthetic.anti_template_check` (or legacy `anti_template`)
- `cover` with first-scene id, approved headline, two or more content signals, hero visual, composition strategy, and `frame_time_sec:0`
- role-based `typography_tokens`
- baseline `color_tokens`
- `visual_direction` with a design tradition, lazy-default rejections, video-scale rule, depth-layer rule, motion-verb rule, and rhythm pattern
- a scene-level plan with `hero_visual`, `depth_layers`, `opening_state`, and `resolved_state`
- for every concrete reference image or video, executable `references` + `reference_fidelity` contracts from `design-system-importer`, based on reproduce/edit/guide intent rather than origin

If the first concrete visual move is a generic grid, circles connected by lines, a centered title card, emoji-as-icon, or a web-dashboard layout, the visual identity is not ready. Revise the art direction first; do not compensate with more glows or animation.

### VisualDirectionV1

For non-trivial COMPOSE work, write a compact `visual_direction` object inside `manifest.art_direction`. It is the front-loaded aesthetic director for HTML authoring; it is not a template and not a user gate.

Required fields:

- `visual_tradition`: a real design tradition, designer, art movement, or cultural reference that controls composition behavior. Examples: `Swiss Pulse / Josef Müller-Brockmann precision grid`, `Data Drift / Refik Anadol data field`, `Velvet Standard / Vignelli restraint`, `Deconstructed / Neville Brody rupture`, `Maximalist Type / Paula Scher scale`. Avoid empty labels such as "modern tech", "premium", or "cinematic" by themselves.
- `composition_behavior`: how frames should be arranged and how the eye should travel: grid-locked data, research atlas, editorial archive, full-bleed object, kinetic type wall, product surface, map/flow, or diagram build.
- `lazy_defaults_rejected`: the first generic design move rejected and the brief-specific replacement. Question purple/blue neon gradients, black neon circles, centered equal-weight layouts, identical cards, decorative emoji/icons, tiny badges, default web dashboards, and pure black/white.
- `video_scale`: the scale floor for this canvas. For 1920x1080, default to headline 72-140px, body 28-42px, labels 18-26px, borders 2-4px, safe padding 60-140px, and decorative opacity 12-25%.
- `depth_layer_rule`: how every scene will maintain background atmosphere, midground content, and foreground accents/metadata with topic-derived materials.
- `motion_verb_rule`: the verbs primary elements are allowed to use. Every meaningful element needs a verb such as draws, locks, counts up, slams, drifts, fractures, reveals, or resolves.
- `typography_register`: the communication roles for display, body, data/label, caption, and any expressive font. Do not pair two similar sans-serifs; use extreme weight/scale contrast and video-readable type.
- `rhythm_pattern`: the scene rhythm before HTML, such as `hook-build-HOLD-surge-resolve`, `drift-build-PEAK-drift-resolve`, or `fast-fast-SLOW-fast-hold`.

Example:

```json
{
  "visual_direction": {
    "visual_tradition": "Swiss Pulse precision grid + Data Drift AI atmosphere",
    "composition_behavior": "research atlas: huge years anchor a coordinate grid while model/paper fragments lock into position",
    "lazy_defaults_rejected": "reject glowing circles on a thin timeline; replace with paper fragments,