Design and Stacks

Design and Stacks

Before an agent builds a UI change, Nautelle can draw it. A design is a set of self-contained HTML mockups in your project's own look. You review them in a full-screen viewer, pin comments, ask for revisions and approve. The worker then builds from the approved frames. A stack goes one step further: a group of staged cards that share one design.

The design stage

flowchart LR
  P["UI profile<br/>(built once, cached)"] --> G["Generate"]
  G --> R["Revision: named frames"]
  R --> C["Comments: general, screen, pins"]
  C --> V["Revise design"]
  V --> R
  R --> A["Approve"]
  A --> B["Frames committed<br/>to the card's branch"]
  B --> W["Worker reads them"]

Loading

1. Turn the design on for a card. The intake suggests it when it fits, and you can switch it on or off on any card until it is approved. A card with a design wears a Design badge: on, drawing, in review or approved.
2. Generate. In the viewer's generate panel, choose the number of variants (1–3), the design skills, and the Claude profile and model the design runs on. The model defaults to the design recommendation.
3. A read-only planner turn on the runner draws each variant as one or more named frames. Each frame is a separate HTML document, for example one per screen or state.
4. Review and comment. Comments accumulate on the current revision.
5. Revise design redraws every frame of the variants still in play, with all open comments, as the next revision. Earlier revisions stay viewable.
6. Approve a variant with all its frames. Each frame is committed as design/<variant>/<frame>.html into the card's branch, and the worker's prompt lists them under ## Design.

While a card's design is needed and not approved, Run is replaced by Approve & run, which approves the design and starts the worker in one step.

Note

A mockup fixes layout, states and copy. It is not code to copy: the worker builds it with the project's real components.

The UI profile

Mockups look like your product because of the project's UI profile. It is built the first time a design is generated, or on demand under Settings › Design. It holds:

• a summary of the UI: libraries, styling approach, tokens, components with their import paths, screen patterns, theme support;
• a style kit: CSS custom properties for the tokens, base typography and styles for the key components;
• HTML snippets for the key components.

The profile is versioned, can be edited, and is rebuilt when the files it was built from change on the base branch. A project with no user interface is marked as such.

The viewer

The viewer opens full screen from a card, a stack or an earlier plan task.

Control	What it does
Viewport presets	Desktop 1440×900 and Mobile 390×844 by default; editable per project
Width	type a width, or drag the frame's edge
Theme	light or dark
Zoom	fit by default; Ctrl/Cmd + wheel over the mockup
Variant / revision	switch between variants and earlier revisions
Frame strip	move between the named frames of a revision
Pin mode	click a point in the mockup to leave a comment there

Comments come in three kinds: general (the whole design), screen (one viewport and theme) and pin (one point and the element under it). A comment on a frame carries the frame's name into the next revision.

The viewer works on phones: comments and the pin composer open in a bottom sheet, the toolbar keeps the presets and zoom, and Approve works at 375 px.

What a mockup may contain

Mockups run in a sandboxed frame with no access to Nautelle: no cookies, no storage, no network calls, no forms that submit and no navigation. External scripts, styles and fonts load only from a fixed allowlist of CDNs, at exact versions. A mockup that breaks a rule fails its turn with the reason.

Stacks

A stack, S-<n>, groups cards into ordered stages under one shared design.

flowchart LR
  D["Stack design<br/>approved"] -.reference.-> A1 & A2 & B1 & B2
  subgraph S1["Stage 1 — Foundations"]
    A1["C-41"]
    A2["C-42"]
  end
  subgraph S2["Stage 2 — Features"]
    B1["C-43"]
    B2["C-44"]
  end
  A1 --> B1
  A1 --> B2
  A2 --> B1
  A2 --> B2

Loading

• Stages are dependencies. Every card of a stage depends on every card of the stage before it. Cards of one stage may run in parallel. Ready, Waiting and Auto-run when ready work for stacks without special handling.
• Design first. While the stack's design is needed and not approved, Run on any of its cards is refused, and so is Generate on a card's own design.
• One shared look. Once approved, the stack's design is the reference for every card's own design turn. A stack card's first round commits the stack's frames into its branch and names them in the worker prompt under ## Stack.
• On the Board, a stack is one face. It sits in the column of its least advanced unfinished card, shows its progress (accepted / total) and its current stage, and expands in place. Open goes to the stack's page.

Making a stack

• From an intake. The intake proposes a stack when the parts must happen in order and share one look. Several UI changes to one surface also become a stack with a design, foundations first. → New Work Intake
• By hand. Select two or more existing cards and group them. A manual stack has one stage, no dependencies between its cards, and the design off by default. A card can be in only one stack, and Inbox cards cannot join one.

Turning the design off

On the stack's page, Stack design required turns the shared design off or on. Off lifts the design-first gate. On holds Run until the design is approved and offers Generate design.

Settings

Under Settings › Design:

• the UI profile: view, edit, rebuild;
• Viewport presets;
• Default design skills: applied to every new design until you edit a design's skills by hand. Save as project default in the generate panel updates them.

See also

• How Work Flows · Board and Cards · Card Workers and Shipping · Project Settings

Decisions: ADR-0022 · ADR-0025 · ADR-0041 · ADR-0044 · ADR-0054 · Spec: #223, #441, #480, #502, #519, #527, #588, #604