open-design/docs/modes.md

Modes

Parent: spec.md · Siblings: architecture.md · skills-protocol.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 §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)
• 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)

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)