orkas-ai/orkas-videostudio/design-system-importer

design-system-importer

Use this when COMPOSE or an AUTO compose segment has external reference media or a style source: an image, video, DESIGN.md, brand guide, screenshot, existing website, design notes, or an explicit named visual direction.

Do not use it for ordinary editing, TTS, shot generation, or clip selection. Do not introduce a new user Gate. The output is an internal style extraction that feeds project/composition/composition-manifest.json#art_direction and the hand-authored project/composition/index.html.

Do not use it for vague adjectives like "modern", "clean", "premium", "dynamic", or "more polished" when no source is named. In those cases, let frontend-design choose the aesthetic thesis directly from the video brief.

Reference Intent Before Input Technique

For every supplied image or video, classify the requested relationship before extracting style:

• reproduce: preserve the declared content, identity, composition, structure, style, motion, timing, or audio axes.
• edit: use the media as the original, protect unaffected axes, and change only may_change.
• guide: borrow only declared roles without implying exact fidelity. This is the safe default when intent is unspecified.

Use intent_basis:"user" for explicit requirements and "inferred" only for a fallback. The contract depends on requested intent, not whether the pixels came from a camera, website, design tool, model, or another authoring format. Copy each inspected source into project/composition/assets/references/ and reference that stable local path.

Follow the requested reproduce/edit/guide relationship. Preserve user-owned or explicitly authorized assets when fidelity requires them; otherwise respect stated exclusions and ownership constraints. Do not force variation merely to appear original when the user asked to reproduce a source. Keep extraction small enough to fit inside the design contract. Do not load or recreate unrelated parts of an external design system.

Extract Compact Tokens

Write a style_source object into project/composition/composition-manifest.json#art_direction:

{
  "style_source": {
    "source_type": "brand_system | design_notes | reference_media | existing_product | named_reference",
    "source_basis": "file path, user note, or inspected artifact",
    "adaptation_boundary": "what must be preserved, may change, or is excluded",
    "observed_signature": "the concrete geometry, hierarchy, type, palette, and motion behavior seen in evidence",
    "confidence": "high | medium | low",
    "fidelity_mode": "exact | close | adapt"
  }
}

Then normalize the source into tokens that hand-authored HTML/CSS/SVG can consume:

• color_tokens: background, surface, text, muted, primary accent, optional secondary accent, plus intended contrast relationship.
• typography_tokens: display, body, data/label, caption roles; scale and weight intent; avoid relying on fonts that are not available.
• shape_tokens: radius, stroke, shadow, divider, border, and density.
• layout_language: grid, editorial, cinematic, dashboard, diagrammatic, poster, product-demo, or another concrete grammar.
• motion_language: entrance, transition, emphasis, data-build, and exit patterns; keep it compatible with GSAP timeline seeking.
• asset_rules: what images/icons/marks are allowed, need replacement, or must be avoided.
• excluded_elements: user exclusions and any assets that cannot be reused; do not invent blanket exclusions that contradict an explicit reproduce/edit request.

Keep the imported style small. If more than 6 chromatic colors or 3 font roles are needed, summarize the conflict and pick the smallest faithful subset.

Executable Media Contract

For every concrete reference, add art_direction.references with id, media_type, local path, intent, intent_basis, allowed roles, required, preserve, may_change, and target_scene_ids. Use only these roles: content, identity, composition, structure, style, motion, timing, and audio.

Add shared art_direction.reference_fidelity with mode: exact|close|adapt, non-overlapping preserve/may_change, normalized layout_anchors for composition/structure roles, and concrete observable comparison criteria. Video reproduce/edit/motion/timing references also need source-time-to-target-scene temporal_anchors.

exact preserves every declared axis except explicit may_change; close keeps the recognizable system while adapting named content or aspect constraints; adapt borrows only selected declared principles. Review with paired source/target frames and concrete findings, never a numeric similarity score.

Map To Video

Web and brand systems are not videos. Convert them for motion:

• First frame: choose the style's strongest thumbnail-friendly signal.
• Safe zones: enlarge type and spacing beyond web density.
• Scene variation: turn repeated web sections into distinct beats.
• Motion: make the brand grammar move with purpose; do not animate every component.
• Captions: keep ordinary subtitles in tracks.captions.lines, not in the style system.

Output

After extraction, the design contract must state:

• What source was used.
• Which tokens were adopted.
• Which tokens were deliberately simplified.
• Which elements are excluded and why.
• What observed visual signature must remain recognizable for the declared intent.
• Which reference intent, roles, protected/allowed changes, target scenes, anchors, and observable comparison criteria apply.