274 lines
11 KiB
Markdown
274 lines
11 KiB
Markdown
# 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)
|