Skip to content

modes.md

Latest commit

 

History

History
273 lines (212 loc) · 10.6 KB

modes.md

File metadata and controls

273 lines (212 loc) · 10.6 KB

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)