Skip to content
Docs

The four layers overview

The four layers are the stages of Denote's pipeline, each capturing a different class of structural decision. Move through them in order: Vision → Ontology → Architecture → Screens. Each is a checkpoint; each writes one file to design/. When you're ready to hand off, /spec rolls everything into design/SPEC.md — the design specification an implementer reads to build.

Why split it

The pipeline decomposes "what should this product be?" into smaller, independently reviewable questions.

Trying to answer everything at once produces a black box. You prompt, the tool renders a screen, the structure is whatever the model decided. There's no point where you can review the structure on its own without visuals getting in the way.

Splitting lets you review and edit one thing at a time: the vision, the objects + governance, the screen inventory, the composition inside each screen.

The four layers at a glance

1. Vision

  • Captures: goals, constraints, audience, non-goals, open questions. The scratchpad for the evolving idea.
  • Writes: design/vision.json.
  • Looks like: conversation-led. You talk through the product idea with Claude Code; the canvas accumulates the items worth keeping. See Vision.

Recipe example: "Home cook needs to scale recipes by serving count. Phone, one-handed. Save favorite ratios per recipe."

2. Ontology

  • Captures: intent, entities (with inline visual cues), personas, tasks, priority rules.
  • Writes: design/ontology.json.
  • Looks like: entity cards with attributes / states / cue chips; relationship diagram on canvas; persona cards; task flow graphs. See Ontology.

Recipe example: Entities Recipe, Ingredient, Scaling Ratio. Persona Home Cook. Tasks "scale a recipe", "save a favorite ratio".

3. Architecture

  • Captures: screen inventory + navigation. Each screen carries a level (its content scope), a template + variant for every surface it appears on, a purpose, and a written reason for the template. Edges are typed. Contained multi-step flows are captured as Mini Apps.
  • Writes: design/architecture.json.
  • Looks like: sitemap canvas with screens as silhouette thumbnails; navigation lens; tasks lens. See Architecture.

Recipe example: Recipes (card_grid : with_filters), Recipe (detail_page : with_aside), Preferences (settings : sectioned). A local navigation edge from the list into each recipe.

4. Screens

  • Captures: spatial composition at chip fidelity. Shells (chrome), per-page compositions (zones filled with content chips), global overlay rules — one composition per page per surface.
  • Writes: design/screens.json.
  • Looks like: home grid (Shells / Pages / Mini Apps / Overlays) with drill-down to the compose canvas for each page. See Screens.

Recipe example: One shell (top_nav), three compositions. The Recipe page's body zone holds ingredient-list and scaling chips; the aside holds saved ratios.

The Spec output

Once the four layers are filled (or partially filled), you run /spec. Claude Code reads every design/*.json file and writes a single design/SPEC.md — a complete design specification covering entities, personas, tasks, screen inventory, per-screen compositions.

The Spec panel inside Denote renders it as Markdown. You don't edit it by hand. If something's wrong, refine the relevant upstream layer and regenerate.

The Spec is a design specification, not an implementation plan. It stays in design vocabulary — entities, states, templates, zones. It deliberately doesn't pick a tech stack, prescribe a database schema, or define API endpoints. Implementer territory. See Spec.

How the layers connect

Each layer is derived from the one above by running a skill:

  • /vision → fills design/vision.json.
  • /ontology reads vision → writes design/ontology.json.
  • /architecture reads ontology → writes design/architecture.json. Also writes task.screenTouchpoints[] back into ontology.
  • /screens reads architecture + ontology → writes design/screens.json.
  • /spec reads everything → writes design/SPEC.md.

You don't have to run them in strict order. Edit any layer any time. When an upstream layer changes, the activity hub notes what downstream work may be stale. No forced cascade — you decide when to re-run.

You don't need every layer to build

A simple utility might only need Vision and Ontology. A complex app might go through all four. The pipeline is a ladder, not a gate.

/spec works from whatever exists. If design/screens.json is empty, the spec writes what it can from Ontology and Architecture and notes the gap in a Missing Design Data section. A partial spec is better than no spec. The further up the pipeline you've filled, the more of the structural decision is yours rather than the implementer's.

Where to next