docs: explain design and frame spec attachments by dpakkia · Pull Request #71 · nexu-io/html-video

dpakkia · 2026-06-26T08:15:51Z

Summary

Closes #64 by documenting what design.md and frame.md are, how Studio detects them, and how users can
write their own.

Changes

Add docs/design-frame-specs.md explaining:
- what design.md / frame.md are
- when to use them
- how they differ from normal content attachments
- how Studio recognizes them
- practical writing tips
Add starter examples:
- docs/examples/design.md
- docs/examples/frame.md
Link the new docs from the README quick start section.

Why

Studio tells users they can drop a design.md / frame.md to lock brand and motion, but the repository
did not explain the convention or provide a starting point.

Verification

Docs-only change.
git diff --check passed for the changed files.

nettee

Reviewed the new design/frame-spec docs against the current Studio attachment handling. I found two places where the wording over-promises behavior relative to studio-server.ts, so I left inline notes to narrow the contract to what ships today.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

nettee · 2026-06-26T08:24:55Z

+
+`design.md` is best for a portable visual system. It usually describes brand tokens, typography, composition rules, and reusable components.
+
+`frame.md` is best for a specific motion frame or shot pattern. It usually describes timing, pacing, transitions, animation beats, and what should happen during a single frame or scene.


frame.md is described here as if it scopes to one scene ("what should happen during a single frame or scene"), but the current implementation does not have a frame-local attachment path. partitionAttachments() / renderDesignSpecBlock() inject every detected frame.md into the global storyboard prompt and again into every per-frame prompt, so one uploaded frame.md steers the whole video. That mismatch gives users the wrong mental model and makes multi-frame runs look incorrect even when Studio is following the current contract. Please reword this section to say that frame.md is still applied project-wide today, or document a real per-frame workflow if one already exists.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

Updated. I clarified that frame.md is applied project-wide today because Studio injects detected specs into the storyboard prompt and every per-frame prompt. The docs no longer imply a per-frame-local attachment workflow.

nettee · 2026-06-26T08:24:55Z

+4. Describe the video content normally.
+5. Generate. The agent receives the spec before ordinary content and is instructed to obey it for palette, typography, layout, and motion.
+
+You can attach a spec together with an article, repo link, screenshot, logo, or CSV. The spec controls look and motion; the other sources provide the subject matter.


This sentence says a spec can be combined with a screenshot, logo, or CSV and those other attachments provide the subject matter, but the default split multi-frame flow only forwards content attachments with inlineText as source material. Non-text attachments like screenshots/logos never become SOURCE MATERIAL in the storyboard or per-frame prompts, so users can follow this doc and still have their image reference ignored. Please narrow this example to text-like sources that are actually consumed today, or add an explicit note that image/reference assets are not yet used as subject matter in the split generation path.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

Updated. I narrowed the subject-source examples to text/data inputs and added an explicit note that screenshots/logos can be uploaded as assets/references, but non-text attachments are not currently used as storyboard source material in the split multi-frame path.

nettee

I found one remaining docs-to-implementation mismatch in the spec-detection section; the detailed note is inline.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

nettee · 2026-06-26T08:37:51Z

+- Its filename is `design.md` or `frame.md`, or
+- Its headings look like a design/motion spec, such as `## System`, `## Theme`, `## Tokens`, `## Motion`, `## Pacing`, or `## Composition`.


This section currently documents filename or heading matches as sufficient for Studio to treat an attachment as a required spec, but the live path is narrower than that. In POST /messages, uploads only get inlineText when the text/data file is <= 20_000 chars, and partitionAttachments() only classifies attachments with a.inlineText && isDesignSpec(a) as specs. That means a longer design.md or frame.md silently falls back to ordinary content even if the filename and headings match, so users can follow this contract and still lose the promised style enforcement. Please either narrow the wording here to the current behavior or fix the pipeline so filename-based detection still works when the file is too large to inline.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

Updated. I narrowed the recognition contract to match the current upload path: design.md / frame.md are treated as required specs only when the text/data file is inlined, and the docs now call out the current 20,000-character inline cap.

nettee

I found two remaining docs-to-implementation mismatches in the newly added spec guidance: one in the 20k-size note, and one in the README quick-start summary. The detailed fixes are inline.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

nettee · 2026-06-26T08:56:33Z

+
+Today, both `design.md` and `frame.md` apply project-wide: Studio injects detected specs into the storyboard prompt and every per-frame prompt. A single uploaded `frame.md` does not target only one generated scene. Use it to define the motion language for the whole video, not to attach instructions to one specific frame.
+
+The Studio treats both as required style/motion specs when the uploaded text/data file is small enough to be inlined into the prompt. Today that inline path is capped at 20,000 characters. Keep spec files concise; larger files may be treated as ordinary attachments instead of required style guidance.


This new size-limit paragraph still overstates the current contract. The upload path only inlines text/data files up to 20_000 chars, but renderDesignSpecBlock() then truncates every detected spec to its first 6_000 chars before it reaches either the storyboard prompt or the per-frame prompts, and partitionAttachments() only promotes attachments with a.inlineText && isDesignSpec(a). That means a spec over 20k chars does not remain ordinary style guidance in the split path; it drops out of required-spec handling entirely, while even qualifying specs only have their first 6k chars enforced. Please tighten this paragraph to describe the real behavior explicitly, for example by saying users should keep specs under 6,000 chars for full prompt coverage and that files over 20,000 chars are not promoted into required spec handling.
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

Updated. I tightened this paragraph to describe both limits: files over 20,000 characters are not promoted into required spec handling, and detected specs are passed to the agent as a 6,000-character slice, so users should keep specs under 6,000 chars for full coverage.

nettee · 2026-06-26T08:56:33Z


+### Optional style specs
+
+Drop a `design.md` or `frame.md` file into the Studio composer when you want the agent to follow a specific brand, layout, or motion system. These files are style/motion specs, not video content: the subject still comes from your prompt, article, repo, or other attachments.


This quick-start sentence still says the video's subject can come from “other attachments,” but the split generation path only grounds the storyboard from prompt text plus attachments that have inlineText (uploaded text/data files, fetched articles, fetched repo markdown). Binary attachments like screenshots and logos are available as assets, not source material, so this wording sends readers down a path Studio will ignore. Please mirror the narrower wording from docs/design-frame-specs.md here, for example “your prompt, article, repo, or uploaded text/data content.”
_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

Updated. The README quick-start wording now mirrors the narrower docs language: the subject comes from the prompt, article, repo, or uploaded text/data content.

nettee

@dpakkia I re-checked the final docs and examples against the current Studio attachment pipeline. The updated wording now accurately documents the project-wide scope for frame.md, the text-only source-material limitation, and the current 20,000-character inline gate plus 6,000-character enforced slice for spec files. Nice job tightening the guidance to match the shipped behavior and adding clear starter examples for users.

_{🔁 Powered by Looper · runner=reviewer · agent=codex · An autonomous AI dev team for your GitHub repos.}

docs: explain design and frame spec attachments

d4fcb0c

lefarcen requested a review from nettee June 26, 2026 08:18

lefarcen added size/M Size M (100-299 LOC) risk/low Low risk type/docs Documentation labels Jun 26, 2026

lefarcen mentioned this pull request Jun 26, 2026

What are design.md / frame.md and where do I get them? #64

Open

nettee reviewed Jun 26, 2026

View reviewed changes

docs: clarify current frame spec behavior

008332a

nettee reviewed Jun 26, 2026

View reviewed changes

docs: note spec attachment inline limit

2f794b0

nettee reviewed Jun 26, 2026

View reviewed changes

docs: tighten spec attachment limits

9b7d60e

nettee approved these changes Jun 26, 2026

View reviewed changes


		`design.md` is best for a portable visual system. It usually describes brand tokens, typography, composition rules, and reusable components.

		`frame.md` is best for a specific motion frame or shot pattern. It usually describes timing, pacing, transitions, animation beats, and what should happen during a single frame or scene.

		- Its filename is `design.md` or `frame.md`, or
		- Its headings look like a design/motion spec, such as `## System`, `## Theme`, `## Tokens`, `## Motion`, `## Pacing`, or `## Composition`.


		Today, both `design.md` and `frame.md` apply project-wide: Studio injects detected specs into the storyboard prompt and every per-frame prompt. A single uploaded `frame.md` does not target only one generated scene. Use it to define the motion language for the whole video, not to attach instructions to one specific frame.

		The Studio treats both as required style/motion specs when the uploaded text/data file is small enough to be inlined into the prompt. Today that inline path is capped at 20,000 characters. Keep spec files concise; larger files may be treated as ordinary attachments instead of required style guidance.


		### Optional style specs

		Drop a `design.md` or `frame.md` file into the Studio composer when you want the agent to follow a specific brand, layout, or motion system. These files are style/motion specs, not video content: the subject still comes from your prompt, article, repo, or other attachments.

Uh oh!

Conversation

dpakkia commented Jun 26, 2026

Summary

Changes

Why

Verification

Uh oh!

nettee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nettee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nettee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nettee left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants