How It Works
The methodology behind Spec Canvas — formats, AI collaboration, and the discovery workflow.
Three Layers
Spec Canvas consists of three layers.
Methodology. Evolutionary Specification — an approach where you start with a rough idea, explore possibilities with AI, and refine the spec iteratively. Validation happens before implementation, not after.
Formats. Two documented formats — UI Spec Format and Data Spec Format — define how to describe an application. They are the blueprints that AI agents follow when creating specs.
Tool. Spec Canvas is a utility that makes it easier to work with these formats: creating specs through wizards, browsing screens and blocks, generating HTML previews, comparing variants. The formats work without it.
Two Formats
Spec Canvas defines two formats. Each format is a documented structure (YAML-based) that tells AI how to describe a specific layer of an application.
UI Spec Format defines how to describe the interface: screens, blocks within screens, their purpose, templates, navigation, theme, and palette. A document written according to this format is called a UI Spec.
Data Spec Format defines how to describe the data model: entities, fields with types, relationships between entities, and enumerations. A document written according to this format is called a Data Spec.
Both format descriptions are available directly from the app:
From Format to Spec to Code
The practical workflow is a chain: format → spec → code.
Step 1: Format tells AI how to write a spec. You give an AI agent the UI Spec Format description and your app idea. The agent returns a structured spec for your specific application — screens, blocks, purposes.
# AI generates a spec like this from your idea:
screens:
dashboard:
title: Dashboard
purpose: "Overview of user tasks and productivity"
blocks:
- id: stats
purpose: "Four metric cards: total, completed, in progress, overdue"
- id: task_list
purpose: "Sortable task list with status indicators and due dates"
- id: quick_actions
purpose: "Action bar with New Task and Filter buttons"Step 2: Spec tells AI what to build. You give the same or another AI agent the spec (or a single screen from it) and ask for an HTML implementation. The agent interprets each block's purpose and generates a working page.
The spec is specific enough that agents produce structurally similar results, while each may bring its own visual interpretation.
Step 3: Spec becomes the working artifact. The resulting spec is a compact, structured description of your application. You can refine it further, hand it to an AI coding agent to build the real application, or use it as shared context in any development workflow. The spec is yours — it works in Spec Canvas, in an AI chat, in an IDE, or in a repository.
Purpose: Intent, Not Implementation
The core building block of a UI Spec is purpose. It describes what a block should show and how it should behave — not how to implement it.
# This is a purpose:
- id: stats
purpose: "Four metric cards showing total, completed, in progress, and overdue tasks"
# This is NOT how you write a spec (too implementation-specific):
- id: stats
type: grid
columns: 4
gap: 16px
children:
- type: card
padding: 20pxAI interprets purpose semantically. How closely the results match depends on how much detail the spec provides — a rough one-line purpose leaves room for interpretation, while a detailed spec with theme, palette, and nested blocks produces consistent results across different agents. You control the level of precision.
You can start with a rough one-line purpose and add detail later, only where it matters. This is called progressive precision — it is covered in detail in Patterns & Practices.
Self-Describing Formats
Both formats are designed so that AI agents understand them without additional instructions. The structure is semantically obvious: screens contain blocks, blocks have a purpose, entities have fields with types.
In practice this means you can paste a UI Spec into any AI chat — without explaining what the format is — and ask the agent to generate an HTML page, a native app screen, a Figma layout, or even an image mockup. The agent will interpret the spec correctly because the format reads like natural structured language.
This also means the formats are not locked to Spec Canvas. They are plain YAML text files that any tool or agent can read.
Works Anywhere
Spec Canvas is one way to work with these formats. But because the formats are plain text, they work anywhere.
In an AI chat. Copy the format description and your idea into Claude, GPT, Gemini, or any other agent. The agent creates a spec. Copy the spec back — or paste it into Spec Canvas for visual browsing.
In an IDE. Give the spec to Cursor, Windsurf, or any AI-assisted editor. The agent uses it as context while generating or modifying application code.
In a terminal agent. Pass the spec to Claude Code or a similar tool. The agent can scaffold a full application from the spec — backend, frontend, database.
In a repository. Store the spec as a YAML file alongside your code. It serves as compact, readable documentation of the application structure.
The format is the portable layer. Spec Canvas accelerates the workflow, but the spec itself travels wherever you need it.
Discovery Before Commitment
The traditional approach is to define everything upfront, implement, and then discover what is wrong. Evolutionary Specification reverses this.
You start with a minimal spec and generate working previews in minutes. Based on what you see, you refine the spec and repeat — before writing any production code.
This means decisions are informed by real visual output, not guesswork. And because changing a spec costs nothing compared to changing code, you can iterate as many times as needed.
When you are confident in the direction, the spec becomes the handoff artifact — a compact, structured document that any AI agent or developer can use to build the real application.