Skip to content

Giving an AI Coding Assistant Visual and Flow Input

Applies to all web frontend project types (currently only frontend-react). How to hand a coding assistant (e.g. Claude Code) enough visual and interaction detail to implement a screen correctly, without requiring the developer to be a designer or the assistant to guess.

Accepted Visual Input Formats

  • Screenshots or mockups as PNG/JPG. An assistant with image-reading tools can view these directly — no conversion needed.
  • Figma frames exported as PNG. Export the frame, don't share a Figma link — assistants cannot open proprietary design-tool files (Figma, Sketch, Adobe XD) directly.
  • Hand-drawn sketches, photographed. A phone photo of a whiteboard or paper sketch works as long as labels and layout intent are legible.
  • Store these under a design/ folder in the repository, referenced from the relevant Capability Specification in specs/capabilities/ — not left in chat history, which isn't part of the repository's living documentation.

Do not expect an assistant to parse .fig, .sketch, or .xd files, or to browse a live Figma project — export a static image first.

Describing Dialog and Navigation Flows

Prefer a Mermaid diagram over a long prose description for anything with more than two steps or branches — this repository already uses Mermaid for sequence diagrams in Use Case documents (see Technical Writing Guidelines), so no new tooling is needed:

  • stateDiagram-v2 for screen-to-screen navigation and multi-step flows (wizards, modals that can be dismissed or confirmed, auth redirects).
  • sequenceDiagram for interactions involving the backend (what triggers which API call, in what order).

Text is still the right choice for describing what a single screen looks like or which fields it has — reserve diagrams for flow, not layout.

Verifying Results in a Running Browser

An assistant can drive and inspect a real browser via a Playwright-based or Chrome DevTools MCP server: navigating the running dev server, reading the DOM, and checking console/network errors, the same way a developer would open devtools. This is a local, per-machine Claude Code configuration concern (an MCP server the developer sets up) — configure it once per development machine if you want the assistant to self-verify UI changes against a live server.

Directives

  • Provide visual input as PNG/JPG screenshots or exported mockups, not proprietary design-tool files
  • Store design references under design/, linked from the relevant Use Case document
  • Use Mermaid stateDiagram-v2/sequenceDiagram for flows with more than two steps or branches; prose for single-screen layout
  • A Playwright or Chrome DevTools MCP server lets the assistant inspect a running dev server directly — a local, per-machine setup choice