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
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.