open-design/docs/modes.md

# Modes

**Parent:** [`spec.md`](spec.md) · **Siblings:** [`architecture.md`](architecture.md) · [`skills-protocol.md`](skills-protocol.md) · [`agent-adapters.md`](agent-adapters.md)

OD exposes four user-facing modes. Modes are not arbitrary; each maps to a distinct **skill type** (see [`skills-protocol.md`](skills-protocol.md) §4) and a distinct **workflow shape**. Keeping them separate lets us tune UI affordances, export pipelines, and default skills per mode.

| Mode | What you get | Time to first result | Skill type |
|---|---|---|---|
| **Prototype** | A single editable screen (HTML/JSX) | ~60–120s | `prototype-skill` |
| **Deck** | Multi-slide HTML presentation | ~90–180s | `deck-skill` |
| **Template** | Populated copy of a curated template | ~20–40s | `template-skill` |
| **Design System** | A `DESIGN.md` + sample preview | ~60–180s | `design-system-skill` |

Modes compose: Design System first → everything else reads from it. Template reuse is the fast path; Prototype/Deck are the generative path.

---

## 1. Prototype mode

### Purpose
One high-fidelity screen or flow. User brief → working HTML/JSX in a sandboxed iframe.

### UX flow
```
[ mode picker: Prototype ]
[ skill picker: saas-landing | dashboard | login-flow | … ]
[ inputs form (if skill declares od.inputs) ]
[ free-text prompt box ]
[ generate ]
    ↓
[ streaming tool-call feed · artifact tree · preview iframe ]
    ↓
[ comment mode (if adapter supports surgicalEdit) ]
[ parameter sliders (if skill declares od.parameters) ]
[ export: html · pdf · zip ]
```

### Inputs
- Skill selection (defaults to first matching trigger)
- Optional structured inputs from skill (e.g. `product_name`, `has_pricing`)
- Optional free-text prompt
- Active DESIGN.md (auto-injected if skill requires it)

### Outputs
- `index.html` (primary) or `Prototype.jsx` (if skill outputs JSX)
- `assets/` (images, fonts generated by skill)
- `artifact.json` metadata

### Preview
- HTML → `<iframe sandbox="allow-scripts" srcdoc>` with hot-reload on writes.
- JSX → iframe with vendored React 18 + Babel standalone.
- Multi-frame toggle: desktop / tablet / phone widths (borrowed from Open CoDesign).

### Refinement surfaces
- **Chat:** free-text "move the CTA above the fold."
- **Comment mode:** click an element → popover → "make this card glassmorphic." Only available if `capabilities.surgicalEdit === true`.
- **Sliders:** any `od.parameters` the skill declared. Slider movements re-prompt with the parameter value only; no full regeneration.

### Default v1 skills
- `saas-landing`
- `dashboard`
- `login-flow`
- `empty-state-pack`
- `pricing-page`

### Failure modes
- Skill requires DESIGN.md but none is set → UI prompts to create one (offers Design System mode).
- Agent times out mid-generation → partial artifact preserved; "resume" button if adapter supports it, else "regenerate."
- Preview iframe fails to render (JSX parse error) → show raw code with error annotation.

---

## 2. Deck mode

### Purpose
Multi-slide presentation. Sliding, magazine, minimal, dark, whatever — as long as the skill supports it.

### UX flow
Same as Prototype, but:
- Skill picker shows only `mode: deck` skills
- Preview renders the full deck with arrow-key navigation (keyboard, scrollwheel, touch) — the deck skill's own navigation
- Export adds `pptx` and `pdf` as first-class options

### Inputs
- Slide count (skill usually declares `od.inputs.slide_count`)
- Topic / outline (free text or structured)
- Theme preset (skill-defined enum; e.g. `editorial | minimal | brutalist`)
- DESIGN.md (optional — many deck skills don't need one because they have their own theme system)

### Outputs
- `index.html` — single-file deck, self-contained
- `slides.json` — optional machine-readable outline, used by PPTX export
- `assets/` — images, fonts

### Preview
Just an iframe loading `index.html`. Navigation is the skill's own responsibility. We add a minimal overlay with slide count and keyboard hints.

### Refinement
- **Chat:** "add a slide about pricing between 4 and 5."
- **Per-slide comment:** click a slide → popover → "make this more data-heavy." Translates to surgical edit of that slide's section.
- **Theme slider:** if skill exposes theme parameters (e.g. `accent_hue`), adjustable post-generation.

### Default v1 skills
- `magazine-web-ppt` (fork of [guizang-ppt-skill](https://github.com/op7418/guizang-ppt-skill))
- `pitch-deck` (minimal, investor-oriented)
- `product-demo-deck` (screenshot-heavy)

### Failure modes
- Agent produces deck with `slides.json` missing → PPTX export falls back to page-capture (uglier output). Document per-skill.
- Too many slides → context blown for small-context agents. Skill declares `max_slides` in front-matter; we warn before generating.

---

## 3. Template mode

### Purpose
Skip generation entirely. Curated templates with proven aesthetics. Agent only personalizes content. This is the fastest path and the highest floor — good for users who don't want to prompt.

### UX flow
```
[ template gallery: cards showing thumbnail + name + inferred design system ]
[ pick one ]
[ inputs form: what to personalize (brand name, content blocks, links) ]
[ generate ]
    ↓
[ preview with populated content ]
[ optional: "restyle to match my DESIGN.md" button ]
[ export ]
```

### Inputs
- Template selection (from bundled gallery + user-added templates)
- Structured content inputs (template declares what slots need filling)
- Optional: re-skin to a target DESIGN.md

### Outputs
Same shape as Prototype mode — the template is just a higher-quality starting artifact.

### How it differs from Prototype
- **No design decisions from the agent.** Layout, spacing, typography all pre-decided.
- **Faster.** Typically 20–40s because the agent only fills text.
- **Lower ceiling.** You can't go off-script without falling back to Prototype mode.

### Template format
A template is a special kind of skill (`mode: template`) with this layout:

```
<template-root>/
├── SKILL.md                   # declares inputs; workflow says "copy and fill"
├── preview.png                # gallery thumbnail
├── assets/
│   └── base.html              # the template HTML with {{ handlebars }} slots
└── references/
    └── DESIGN.md              # template's own inferred design system (for re-skin)
```

### Default v1 templates
- `stripe-ish-landing`
- `linear-ish-docs`
- `notion-ish-workspace`
- `vercel-ish-pricing`
- (Names are nods to inspirations, not copies; we don't ship infringing clones.)

### Failure modes
- User-provided content violates template constraints (e.g. too-long heading) → agent auto-truncates with a warning in the artifact metadata.
- Re-skin to DESIGN.md produces ugly result → keep the original; re-skin is non-destructive.

---

## 4. Design System mode

### Purpose
Produce a `DESIGN.md` file. This is the *meta* mode: the output is the input for other modes.

### UX flow
```
[ choose input source ]
  → option A: screenshot upload
  → option B: brand guide PDF upload
  → option C: public URL ("analyze airbnb.com")
  → option D: free-text brief ("warm editorial, terracotta accent…")
[ skill picker: design-system-from-screenshot | … ]
[ generate ]
    ↓
[ preview: rendered DESIGN.md + sample components demo ]
[ edit the DESIGN.md inline or via chat ]
    ↓
[ "Set as active design system" button → writes to ./DESIGN.md ]
```

### Inputs
- One of: screenshot, PDF, URL, free-text brief
- Optional: existing DESIGN.md to refine

### Outputs
- `DESIGN.md` — the canonical 9-section format
- `preview.html` — a sample components page rendered against the new design system (hero, buttons, card, form, table)
- `tokens.json` — optional, machine-readable version of the color/typography tokens (for devs who want to import into code)

### Preview
Split view:
- Left: editable DESIGN.md in a Markdown editor
- Right: `preview.html` rendering sample components

### 9-section DESIGN.md format (per [awesome-claude-design](https://github.com/VoltAgent/awesome-claude-design))

1. Visual Theme & Atmosphere
2. Color Palette & Roles
3. Typography Rules
4. Component Stylings
5. Layout Principles
6. Depth & Elevation
7. Do's and Don'ts
8. Responsive Behavior
9. Agent Prompt Guide

This format is not ours. We adopt it because awesome-claude-design has already shipped 68 of them — immediate ecosystem compatibility.

### Default v1 skills
- `design-system-from-screenshot` (vision-capable agent required)
- `design-system-from-brief` (text-only)
- `design-system-refine` (takes existing DESIGN.md + notes)

### Failure modes
- Screenshot upload but active agent has no vision (e.g. older Codex) → suggest switching agent or fall back to "describe the screenshot in text."
- DESIGN.md parse errors when set as active → validator highlights which section is malformed; user edits and retries.

---

## 5. Mode selection & heuristics

### Explicit
User picks a mode from the top-level navigation. Each mode shows only compatible skills.

### Inferred (chat-first flow)
If the user just types a prompt without selecting a mode:

```
prompt contains "slide" | "deck" | "ppt" | "presentation" → Deck
prompt contains "design system" | "tokens" | "brand"     → Design System
prompt contains "template" + named template              → Template
else                                                      → Prototype
```

Inference is a hint; user can override via a mode picker on the artifact page.

## 6. Cross-mode composition examples

- **Design System → Prototype:** run Design System mode once; every Prototype/Deck/Template run after that picks it up from `./DESIGN.md`.
- **Template → Prototype:** pick a template, export as starting artifact, re-open in Prototype mode for free-form edits.
- **Prototype → Design System:** if a generated prototype hits a good aesthetic, we plan a "freeze as design system" action in v1.5. Not in MVP.

## 7. Keyboard & UI affordances (cross-mode)

| Action | Shortcut | Available in |
|---|---|---|
| Generate | ⌘/Ctrl+Enter | all |
| Cancel run | Esc | all |
| Toggle comment mode | ⌘/Ctrl+; | Prototype, Deck |
| Cycle preview frame | ⌘/Ctrl+\\ | Prototype |
| Export | ⌘/Ctrl+E | all |
| Set active design system | n/a (button) | Design System |

## 8. What mode ≠

Modes are **workflow containers**, not product subscriptions or pricing tiers. They all run on the same infrastructure, the same skills protocol, and the same agent adapters. A user can move between modes freely at zero cost.

## 9. Out of scope for MVP

- Hybrid modes (e.g. "deck with a prototype-screen embedded")
- Auto-mode-switching mid-session
- Collaborative multi-user mode
- Mobile-first layouts for the modes themselves (the web UI is desktop-only in MVP)