Skip to content
Docs

Vision

Vision is the layer where you think through the product idea. A living scratchpad — goals, constraints, non-goals, audience, competitive context, open questions, freeform notes. Vision never fully completes; it evolves as the project develops, and changes ripple forward.

What Vision captures

Seven categories, each a list of short written items:

  • Goals — what the product should achieve. Outcomes, not features.
  • Constraints — what limits the design. Time, budget, tech stack, accessibility, regulatory.
  • Non-goals — what the product explicitly won't do, so the goals stay sharp.
  • Audience — who it's for and their context.
  • Competitive context — what exists in this space and how this differs.
  • Open questions — unresolved decisions to return to.
  • Scratchpad — freeform thinking; the stuff that doesn't fit anywhere yet.

Each item has content, a status (proposed / confirmed), and a source (ai / manual).

The canvas

[Screenshot TODO: Vision layer with the terminal mid-conversation on the left, the seven-section canvas showing confirmed goals and constraints, and the Sources panel on the right.]

Vision is the one layer where the conversation is the primary surface and the canvas accumulates its output.

  • Terminal — where the thinking happens via /vision.
  • Canvas — the seven categories as sections, updating in real time as Claude Code proposes items.
  • Sources — the right panel, holding the reference materials the skills read.

Two capture paths feed the canvas:

  • Claude Code proposes during the /vision conversation; items show as proposed until you confirm or dismiss.
  • You capture terminal text — select any text in the terminal and an Add to Vision popover appears; pick a category. Saved as manual + confirmed.

Edit any item inline. Reorder within a section. Delete what you don't need.

Sources

Sources are the reference materials you bring: a PRD, research notes, competitive teardowns, anything. Two kinds:

  • Files — dropped or picked into design/sources/. Any file type; copied into the project and tracked in git, so they travel with the folder.
  • Linked folders — pointers to folders elsewhere on your machine (an existing codebase, a research archive). Explored in place, never copied.

Every design skill reads your sources for context before it reasons; /vision reads them first and draws proposals from them. Skills treat sources as read-only — they inform the thinking, they're never edited.

The file written

design/vision.json — single file, seven array properties, one object per item.

The skill

/vision populates the layer.

  • Reads: everything in design/sources/ (and any linked folders) first, then design/vision.json if it exists (merges, does not replace) + any context you pass.
  • Writes: design/vision.json.

Behavior:

  • First run is a kickoff conversation. Later runs refine.
  • Proposes items progressively, doesn't wait for a complete picture.
  • Pushes on ambiguity before committing.
  • Writes items as proposed so you stay in control.

The recipe example

A vision for a recipe-scaling tool after a short /vision session:

Goals

  • Scale any recipe to a target serving count, on a phone, under 30 seconds.
  • Saved scaling ratios per recipe so favorites don't get recalculated.

Constraints

  • Phone, one-handed while cooking.
  • No account or login. Local storage only.

Non-goals

  • Not a recipe-storage product. The cook brings the recipe.
  • No meal planning, shopping lists, or nutrition.

Open questions

  • Handle unit conversion (cups → grams), or stay portion-only?
  • How to round fractional results so "0.34 teaspoons" doesn't ship?

What Vision is not for

  • Entity modeling. That's Ontology.
  • Pattern decisions. That's Architecture (template + variant lives on each Screen).
  • Composition. That's Screens.
  • Copy or content. Vision is about direction.

The discipline: Vision stays high-level. Short items. No implementation. No layout.

Where to next