---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "foundations-design-video-qa-field-guide"
title: "Design, Video, and QA Story Field Guide"
---

# Design, Video, and QA Story Field Guide

> Original source pages and recordings require authorized access. The full article text here is public.

Convert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories.

Use this when words are weak and Codex needs visual requirements plus browser-verifiable acceptance criteria.

## Choose the right mechanism

| Mechanism | Use when | Agent responsibility | Artifact |
|---|---|---|---|
| design.md | Durable taste contract | Style DNA, type, color, layout | design.md |
| Image reference | Human-selected direction | Implement one concrete look | .notes/design/reference.png |
| Video requirements | Narrated UX behavior | Extract acceptance criteria and edge cases | .goals/<feature>-video.md |
| QA swarm | Weird-path exploration | Personas, broken paths, browser receipts | .notes/qa/ |

## Agent-ready prompt

```text
Treat the visual artifact as requirements, not decoration.
Extract acceptance criteria, user stories, responsive states, and proof moves.
Implement only the selected direction.
Verify in browser with screenshots/logs.
Write the durable contract to design.md, .goals/<feature>.md, or .notes/qa/<flow>.md depending on the task.
```

## Applied stories

### Reference image to UI

**Role:** Product engineer

The team can recognize the desired look but cannot write the CSS spec.

**Agent brief:** Ask Codex to distill the selected image into design.md, implement one route, then browser-proof the result.

**Done when:**

- design.md update
- implemented route
- desktop/mobile screenshots
- diff review

### Narrated bug report

**Role:** Full-stack developer

A PM records cart behavior that is faster to show than explain.

**Agent brief:** Extract requirements from video into a goal file, implement behavior, and prove cart states in browser.

**Done when:**

- video-derived goal
- acceptance criteria
- browser proof
- test/typecheck log

### 5 Monkeys QA swarm

**Role:** QA-minded frontend lead

Happy path passes, but users hit weird navigation and state sequences.

**Agent brief:** Launch persona-based QA workers that write reproducible findings, then collate only high-signal bugs.

**Done when:**

- persona findings
- dedupe summary
- screenshots
- repro steps

## Tips and gotchas

- Do not ask Codex to invent taste from nothing; hand it references and constraints.
- A video should become acceptance criteria, not a brittle click macro.
- Keep visual QA disposable until the flow stabilizes; promote only stable checks to tests.
- Every visual/design story should end with browser proof across relevant viewports.

## References

- [Impeccable](https://impeccable.style/)
- [Inspiration board](https://inspiration-board.pages.dev/)
- [OpenAI Codex Figma/frontend post](https://developers.openai.com/codex)
- [Playwright screenshots](https://playwright.dev/docs/screenshots)

## Related principles

- [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)
- [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)
- [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/)
- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)

## Original references

- [Agent foundations: Trust current source and capture design decisions (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-04.html)
- [Agent foundations: Explore software through perspectives and runtime QA (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-05.html)
- [Agent foundations: Use images, video, and task-shaped model routing (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-06.html)
- [Agent foundations: Preserve contracts and state machines while code changes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-11.html)
