first-commit

docs/modes.md

@@ -0,0 +1,273 @@
+# 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)