AGENTS.md

1# design-templates
2 
3This directory holds **design templates** — packaged "shapes" the agent
4renders into a project artifact (decks, prototypes, image/video/audio
5templates, …). Each entry is a folder with a `SKILL.md` (same shape as
6functional skills) plus rendering side files (`example.html`,
7`assets/`, `references/`, …).
8 
9If the entry primarily *does work* on user input — utilities, briefs,
10asset packagers, fidelity audits — it belongs under `../skills/`
11instead. See `specs/current/skills-and-design-templates.md` for the
12full split.
13 
14## Daemon plumbing
15 
16- Listed under `/api/design-templates`. The shape mirrors `/api/skills`
17  (same `SkillSummary`/`SkillDetail` types) so the web client can
18  reuse a single `SkillSummary[]` consumer for both surfaces.
19- Asset and example routes (`/api/skills/:id/example`,
20  `/api/skills/:id/assets/*`) intentionally span both registries — the
21  example HTML rewrites to `/api/skills/<id>/...` regardless of which
22  root owns the folder, so URLs keep resolving after the split.
23- Surfaced in the New-project panel's per-mode "Start from" rail as the
24  rendering catalogue; the redesigned home has no top-level Templates tab.
25 
26## Adding a design template
27 
281. Create `design-templates/<my-template>/SKILL.md` with `name`,
29   `description`, `triggers`, and an explicit `od.mode` (one of
30   `prototype`, `deck`, `template`, `image`, `video`, `audio`).
312. Ship a baked `example.html` (and any side files) so the shared example and
32   asset routes have preview content to serve.
333. Optionally drop additional baked samples under `examples/<key>.html`
34   to surface them as derived `<parent>:<key>` cards.
35 
36## Deck preview navigation contract
37 
38Any template with `od.mode: deck` must make its baked `example.html`
39usable inside the gallery iframe without relying on the host app to add
40navigation. Use a shared deck runtime where one is available; otherwise
41ship a tiny local runtime with the same minimum behavior.
42 
43- **Keyboard:** `ArrowRight` / `ArrowDown` / `PageDown` / `Space` move to
44  the next slide; `ArrowLeft` / `ArrowUp` / `PageUp` move to the previous
45  slide; `Home` and `End` jump to the first and last slide. Ignore events
46  from inputs, selects, textareas, and editable regions.
47- **Wheel / trackpad:** accumulated `deltaX + deltaY` past a small threshold
48  moves exactly one slide, then resets quickly so a single gesture does not
49  overshoot.
50- **Touch:** a horizontal swipe of roughly 50px or more, greater than the
51  vertical movement, moves previous / next.
52- **Dots:** render one clickable button per slide, update the active dot on
53  every navigation path, and mark it with `aria-current="true"`.
54- **Active slide state:** keep the visible slide marked with
55  `.slide.active`; adding `.is-active` as a compatibility alias is fine.
56  Open Design's preview bridge reads this state for the host slide counter,
57  so it must stay in sync with keyboard, wheel, touch, and dot navigation.
58- **Iframe safety:** focus the deck on load / pointer interaction so keyboard
59  navigation works after the gallery preview appears. Avoid
60  `scrollIntoView()` because it can move the parent page instead of the deck.
61- **Fallbacks:** no-script and print output should still expose every slide.
62  Hide non-active slides only after the runtime has booted.
63