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: terminal-dominant. You talk through the product idea with Claude Code; a sidebar 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, ScalingRatio. Persona Home Cook. Tasks "scale a recipe", "save a favorite ratio".

3. Architecture

  • Captures: screen inventory + navigation. Each screen carries a template + variant directly. Edges are typed.
  • Writes: design/architecture.json.
  • Looks like: sitemap canvas with screens as silhouette thumbnails; navigation lens; tasks lens. See Architecture.

Recipe example: recipes-list (card_grid : with_filters), recipe-detail (detail_page : with_aside), preferences (settings : sectioned). Drill edge from list to detail.

4. Screens

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

Recipe example: One shell (top_nav), three compositions. The detail screen's body zone holds IngredientList + ScalingControl chips; the aside holds SavedRatios.

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 feed logs a hint: "Ontology changed. Architecture may be stale. Run /architecture to update." 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