Presentation
Turn a technical specification into an interactive, persuasive web deck —
the kind at iii.dev/roadmap/. The output is a content layer inside the
repo's roadmap base (the shared component library, gallery, and markdown
spec viewer that build every deck into one static site — Astro routes of the
site package in iii, a standalone Vite project in other repos):
- helps engineers understand the spec — the architecture is a navigable
map, not prose;
- is interactive — steppable diagrams, a selectable system map, live
toggles; interactivity is what makes it stick;
- reads like marketing — it argues the why. if no one is convinced the
work should happen, the spec has not done its job;
- is build-in-public ready — each deck ships as a static page at
/roadmap/<slug>/, safe to share.
Comparable to
A product launch microsite generated from an RFC. Stripe-doc clarity meets a
keynote narrative, in a monospace drafting-sheet style.
Activation
Use For
- generating an interactive deck from a tech-spec directory
- refreshing or extending a presentation already generated by this skill
Do Not Use For
- writing the spec itself — use
/tech-spec
- static slide exports (pdf / keynote) — use a slide tool
- general UI work unrelated to a spec — use
/design
Load First
Read these before building (they are the law — do not re-derive them):
reference/design-system.md — the locked tokens, type, motion, layout
reference/archetypes.md — the interactive slide library + how to pick one
reference/component-standards.md — deck-local vs promoted components, the
promotion checklist, the registry format
reference/narrative-framework.md — the persuasive arc + outline rules
reference/quality-bar.md — the checklist to self-verify before finishing
reference/hosting.md — the two-tree layout, the pairing contract,
frontmatter registration, and deploy
- per repo:
<base>/COMPONENTS.md — the live registry of that repo's
shared components. It may exceed the bundled catalog; when it and
reference/archetypes.md disagree, the repo registry wins.
The skill bundles two scaffolds:
template/ — one deck's content layer (App, sections, pages, content
data, the spec-docs glob). Copy it per spec; everything visual comes from the
base's shared src/ via the @lib alias. You generate only content.
base/ — the whole per-repo presentations site: the shared component
library + design tokens, the gallery, the md-only spec viewer, and the build
glue (build.mjs, vite.config.ts, one package.json). Copy once per repo
(in iii it already lives at website/roadmap/); per-deck runs never
modify it except additive component promotion per
reference/component-standards.md.
Progress Updates
Emit one short line before each phase: ingesting spec → reading the component registry → proposing outline → scaffolding → generating slides (k/N) → registering spec frontmatter → verifying.
Workflow
Phases are gated. Do not skip Phase 2's approval or Phase 5's verification.
0. Resolve inputs
- The argument is a tech-spec directory:
<repo>/tech-specs/<slug>/ —
markdown only (README.md + domain docs; frontmatter in README.md). If
given a path elsewhere, resolve into the spec tree or ask.
- The slug is the spec directory's basename (e.g.
2026-06-21-devexp —
YYYY-MM-DD-<name>; the day prefix orders the roadmap timeline). It is
the deck directory name AND the URL segment — the pairing contract in
reference/hosting.md. Fix it now and use it everywhere; never prettify it.
- Resolve the base project: read
<repo>/tech-specs/README.md — the
pointer names the base dir (in iii: website/roadmap/). Fallback:
search for a dir containing both COMPONENTS.md and a shared src/.
Detect its shape:
- integrated base (shared
src/ + scripts/manifest.mjs, no
package.json or build.mjs of its own — iii's shape: the site's Astro
pages at website/src/pages/roadmap/ render each deck's src/App.tsx
as a React island via the base's src/DeckHost.tsx; deps live in the
iii-website package) → use it, and scaffold content layers only;
- standalone base (
build.mjs + own package.json, one index.html
per deck — the base/ snapshot's shape) → use it;
- absent → first run in this repo: pick the location with the user
(default
website/roadmap/ when website/ exists, else
roadmap/ at the repo root) and scaffold it in Phase 3;
- legacy layout (
tech-specs/build.mjs + _gallery/ — per-deck
standalone projects) → stop and offer the port procedure in
reference/hosting.md before generating anything new.
- Output location is
<base>/<slug>/. If it exists and is non-empty, ask:
overwrite, update in place, or abort. Never write a non-markdown file
under tech-specs/.
- Detect the install mode: workspace (repo
pnpm-workspace.yaml lists the
base) vs standalone (pnpm install --ignore-workspace inside the base).
1. Deep ingest (read, do not skim)
- Read the spec
README.md in full first: thesis, architecture, principles,
cross-cutting contracts, migration overview. Note whether it already has a
frontmatter block (title/tagline/date/tags/status).
- Read every domain doc. For each, capture: the one load-bearing phrase, the
pain it removes, the mechanism, any schema/fields, any sequence/lifecycle,
any numbers, any honest trade-off.
- Build a content inventory (architecture, protocol/wire contract,
lifecycle, state model, config schema, security, migration, …). This is the
raw material for archetype matching.
1b. Component awareness (before planning). Read <base>/COMPONENTS.md end
to end and list <base>/src/components/{schematic,diagrams}/ + src/hooks/.
The registry is the live catalog for this repo and supersedes the bundled
reference/archetypes.md where they disagree. Reuse-first mandate: a
slide may get a bespoke visual only after the catalog demonstrably has no fit
for its content shape. Name any planned new component in the Phase 2 outline,
marked local or promote (see reference/component-standards.md), so the
user approves it at the same gate.
2. Narrative plan — THE GATE
- Apply the arc in
reference/narrative-framework.md. Produce a deck outline:
an ordered slide list, each with { title, archetype (or reused registry component), the single claim, source section(s), the concrete data it pulls, interactivity, new component: <Name> (local|promote) — only when nothing fits }. Include candidate deep-dive pages.
- Derive the hero line + three-value subhead + stat strip. Choose the wordmark
label.
- Present the outline to the user for approval/edits before scaffolding.
This is the cheapest place to turn a dry spec into a story. Skip only if the
user explicitly says "just build it".
3. Scaffold (mechanical)
The deck:
mkdir -p <base>/<slug>/ and copy template/ into it — in an
integrated base (iii) copy template/src/ only and skip index.html
and src/main.tsx (the site's [slug]/index.astro route provides the
document shell and mounts src/App.tsx; the page title/description come
from the spec frontmatter).
- Substitute the
__SPEC_MD_GLOB__ literal in src/spec-docs.ts with the
computed relative path from <base>/<slug>/src/ to
<specs-dir>/<slug>/*.md (in iii: ../../../../tech-specs/<slug>/*.md);
in a standalone base also __TITLE__ / __DESCRIPTION__ in index.html.
- No per-deck install, no per-deck config, no lockfile. Ensure deps once:
workspace mode →
pnpm install at the repo root (only if the base's deps
are missing); standalone mode → pnpm install --ignore-workspace in
<base> (commit the generated lockfile).
Registration: write or update the YAML frontmatter block at the top of
tech-specs/<slug>/README.md (schema in reference/hosting.md): title +
tagline from the approved hero, date: YYYY-MM-DD (day precision — the
roadmap timeline orders and labels by it), 0–4 tags, status: draft.
There is no central manifest — the build aggregates every spec's frontmatter,
so this run touches nothing shared. If frontmatter already exists, update only
the fields this run owns (tagline polish, status).
The base project (first run in a repo only): copy base/ into the chosen
dir (never its node_modules/dist). Fill the identity once: __REPO__ in
package.json; the __GALLERY_*__ / __WORDMARK_LABEL__ / __HERO_*__ /
__ATTRIBUTION__ / __SITE_HOST__ tokens in index.html,
src/gallery/site.ts, and README.md; write the tech-specs/README.md
pointer. The gallery page is a roadmap: hero copy in roadmap voice
(__HERO_TITLE__ ≈ "what we're working on"; __HERO_LEAD__ hints at the
current priority and what already landed, without naming specs), and the spec
list renders as a one-column timeline, newest first, grouped by month. In a workspace repo, add the base to pnpm-workspace.yaml with
user confirmation (a repo-level file). Never touch build.mjs,
vite.config.ts, tsconfigs, or src/ beyond this copy.
4. Generate the content layer
Edit only these — the write surface is <base>/<slug>/** plus the spec's
frontmatter block (and an approved promotion):
src/content/deck.ts — DECK_META.wordmarkLabel, NAV, FOOTER.
src/content/<topic>.ts — the typed data arrays each archetype consumes
(map nodes/edges/info, sequence lanes/steps, reveal stages, cli tracks,
metrics, rows). Keep data here, out of components.
src/sections/<Name>.tsx — one thin section per slide: import the matching
archetype from @lib, feed it data, wrap it in <Section>. Replace the
example sections; delete src/content/example.ts and pages/ExamplePage.tsx.
src/pages/<Name>.tsx — deep dives via @lib <PageShell>.
src/App.tsx — wire the ordered SECTIONS array and the PAGES map.
The component protocol (when a load-bearing concept has no fit in
COMPONENTS.md):
- Default: build it deck-local in
<base>/<slug>/src/diagrams/<Name>.tsx,
following @lib/components/diagrams/SequencePlayer.tsx conventions.
- Promote into
<base>/src/components/ only when all three hold: (a) it
is generic over its data — nothing spec-specific inside, everything arrives
via typed props; (b) it maps to a recurring spec shape (a lifecycle, a
tree, a timeline, a fan-out…) future decks will plausibly need; (c) it
passes the checklist in reference/component-standards.md without
deck-specific hacks.
- A promotion = the component file plus its
COMPONENTS.md entry in the
same change. An unregistered shared component is a defect (the base's
registry check warns — scripts/validate-roadmap.ts in iii, build.mjs
standalone; strict mode makes it fatal).
- Never fork a shared component into the deck to tweak it — extend it via
additive, non-breaking props, or build a genuinely different deck-local
one. Modifying an existing shared component requires explicit user
approval (it re-renders every other deck).
Built-in spec viewer — do not delete. Every deck ships the #/spec page:
the template wires spec-docs.ts (the compile-time glob over the paired
spec's markdown) into @lib/pages/SpecPage via PAGES.spec, and the shared
TopNav renders the spec link. The shared markdown renderer strips the
frontmatter block. It needs no per-deck content — leave the wiring in place.
5. Verify — THE SECOND GATE
All commands run from <base>'s package (iii: `pnpm --filter iii-website
1---
2name: presentation
3description: >-
4 Turn a tech-spec directory into an interactive, marketing-grade web
5 presentation — built so engineers understand the design, the reader is
6 convinced of the why, and the result is shareable in public. Use when someone
7 wants a spec turned into a deck.
8metadata:
9 source: https://skillmd.com/skills/iii-hq/presentation
10---
11
12# Presentation
13
14Turn a technical specification into an interactive, persuasive web deck —
15the kind at iii.dev/roadmap/. The output is a **content layer** inside the
16repo's roadmap base (the shared component library, gallery, and markdown
17spec viewer that build every deck into one static site — Astro routes of the
18site package in iii, a standalone Vite project in other repos):
19
201. helps engineers **understand** the spec — the architecture is a navigable
21 map, not prose;
222. is **interactive** — steppable diagrams, a selectable system map, live
23 toggles; interactivity is what makes it stick;
243. reads like **marketing** — it argues the *why*. if no one is convinced the
25 work should happen, the spec has not done its job;
264. is **build-in-public ready** — each deck ships as a static page at
27 `/roadmap/<slug>/`, safe to share.
28
29## Comparable to
30
31A product launch microsite generated from an RFC. Stripe-doc clarity meets a
32keynote narrative, in a monospace drafting-sheet style.
33
34## Activation
35
36### Use For
37
38- generating an interactive deck from a tech-spec directory
39- refreshing or extending a presentation already generated by this skill
40
41### Do Not Use For
42
43- writing the spec itself — use `/tech-spec`
44- static slide exports (pdf / keynote) — use a slide tool
45- general UI work unrelated to a spec — use `/design`
46
47## Load First
48
49Read these before building (they are the law — do not re-derive them):
50
51- `reference/design-system.md` — the locked tokens, type, motion, layout
52- `reference/archetypes.md` — the interactive slide library + how to pick one
53- `reference/component-standards.md` — deck-local vs promoted components, the
54 promotion checklist, the registry format
55- `reference/narrative-framework.md` — the persuasive arc + outline rules
56- `reference/quality-bar.md` — the checklist to self-verify before finishing
57- `reference/hosting.md` — the two-tree layout, the pairing contract,
58 frontmatter registration, and deploy
59- **per repo:** `<base>/COMPONENTS.md` — the live registry of that repo's
60 shared components. It may exceed the bundled catalog; when it and
61 `reference/archetypes.md` disagree, **the repo registry wins**.
62
63The skill bundles two scaffolds:
64
65- `template/` — one deck's **content layer** (App, sections, pages, content
66 data, the spec-docs glob). Copy it per spec; everything visual comes from the
67 base's shared `src/` via the `@lib` alias. You generate only content.
68- `base/` — the whole per-repo presentations site: the shared component
69 library + design tokens, the gallery, the md-only spec viewer, and the build
70 glue (`build.mjs`, `vite.config.ts`, one `package.json`). Copy once per repo
71 (in iii it already lives at `website/roadmap/`); per-deck runs never
72 modify it except **additive component promotion** per
73 `reference/component-standards.md`.
74
75## Progress Updates
76
77Emit one short line before each phase: `ingesting spec` → `reading the
78component registry` → `proposing outline` → `scaffolding` → `generating slides
79(k/N)` → `registering spec frontmatter` → `verifying`.
80
81## Workflow
82
83Phases are gated. Do not skip Phase 2's approval or Phase 5's verification.
84
85### 0. Resolve inputs
86
87- The argument is a tech-spec directory: `<repo>/tech-specs/<slug>/` —
88 **markdown only** (README.md + domain docs; frontmatter in README.md). If
89 given a path elsewhere, resolve into the spec tree or ask.
90- The **slug is the spec directory's basename** (e.g. `2026-06-21-devexp` —
91 `YYYY-MM-DD-<name>`; the day prefix orders the roadmap timeline). It is
92 the deck directory name AND the URL segment — the pairing contract in
93 `reference/hosting.md`. Fix it now and use it everywhere; never prettify it.
94- Resolve the **base project**: read `<repo>/tech-specs/README.md` — the
95 pointer names the base dir (in iii: `website/roadmap/`). Fallback:
96 search for a dir containing both `COMPONENTS.md` and a shared `src/`.
97 Detect its shape:
98 - **integrated base** (shared `src/` + `scripts/manifest.mjs`, no
99 package.json or build.mjs of its own — iii's shape: the site's Astro
100 pages at `website/src/pages/roadmap/` render each deck's `src/App.tsx`
101 as a React island via the base's `src/DeckHost.tsx`; deps live in the
102 `iii-website` package) → use it, and scaffold content layers only;
103 - **standalone base** (`build.mjs` + own `package.json`, one `index.html`
104 per deck — the `base/` snapshot's shape) → use it;
105 - **absent** → first run in this repo: pick the location with the user
106 (default `website/roadmap/` when `website/` exists, else
107 `roadmap/` at the repo root) and scaffold it in Phase 3;
108 - **legacy layout** (`tech-specs/build.mjs` + `_gallery/` — per-deck
109 standalone projects) → stop and offer the port procedure in
110 `reference/hosting.md` before generating anything new.
111- Output location is `<base>/<slug>/`. If it exists and is non-empty, ask:
112 overwrite, update in place, or abort. **Never write a non-markdown file
113 under `tech-specs/`.**
114- Detect the install mode: workspace (repo `pnpm-workspace.yaml` lists the
115 base) vs standalone (`pnpm install --ignore-workspace` inside the base).
116
117### 1. Deep ingest (read, do not skim)
118
119- Read the spec `README.md` in full first: thesis, architecture, principles,
120 cross-cutting contracts, migration overview. Note whether it already has a
121 frontmatter block (title/tagline/date/tags/status).
122- Read every domain doc. For each, capture: the one load-bearing phrase, the
123 pain it removes, the mechanism, any schema/fields, any sequence/lifecycle,
124 any numbers, any honest trade-off.
125- Build a **content inventory** (architecture, protocol/wire contract,
126 lifecycle, state model, config schema, security, migration, …). This is the
127 raw material for archetype matching.
128
129**1b. Component awareness (before planning).** Read `<base>/COMPONENTS.md` end
130to end and list `<base>/src/components/{schematic,diagrams}/` + `src/hooks/`.
131The registry is the live catalog for this repo and supersedes the bundled
132`reference/archetypes.md` where they disagree. **Reuse-first mandate:** a
133slide may get a bespoke visual only after the catalog demonstrably has no fit
134for its content shape. Name any planned new component in the Phase 2 outline,
135marked `local` or `promote` (see `reference/component-standards.md`), so the
136user approves it at the same gate.
137
138### 2. Narrative plan — THE GATE
139
140- Apply the arc in `reference/narrative-framework.md`. Produce a deck outline:
141 an ordered slide list, each with `{ title, archetype (or reused registry
142 component), the single claim, source section(s), the concrete data it pulls,
143 interactivity, new component: <Name> (local|promote) — only when nothing
144 fits }`. Include candidate deep-dive pages.
145- Derive the hero line + three-value subhead + stat strip. Choose the wordmark
146 label.
147- **Present the outline to the user for approval/edits before scaffolding.**
148 This is the cheapest place to turn a dry spec into a story. Skip only if the
149 user explicitly says "just build it".
150
151### 3. Scaffold (mechanical)
152
153**The deck:**
154
155- `mkdir -p <base>/<slug>/` and copy `template/` into it — in an
156 **integrated base (iii)** copy `template/src/` only and skip `index.html`
157 and `src/main.tsx` (the site's `[slug]/index.astro` route provides the
158 document shell and mounts `src/App.tsx`; the page title/description come
159 from the spec frontmatter).
160- Substitute the `__SPEC_MD_GLOB__` literal in `src/spec-docs.ts` with the
161 computed relative path from `<base>/<slug>/src/` to
162 `<specs-dir>/<slug>/*.md` (in iii: `../../../../tech-specs/<slug>/*.md`);
163 in a standalone base also `__TITLE__` / `__DESCRIPTION__` in `index.html`.
164- **No per-deck install, no per-deck config, no lockfile.** Ensure deps once:
165 workspace mode → `pnpm install` at the repo root (only if the base's deps
166 are missing); standalone mode → `pnpm install --ignore-workspace` in
167 `<base>` (commit the generated lockfile).
168
169**Registration:** write or update the YAML frontmatter block at the top of
170`tech-specs/<slug>/README.md` (schema in `reference/hosting.md`): title +
171tagline from the approved hero, `date: YYYY-MM-DD` (day precision — the
172roadmap timeline orders and labels by it), 0–4 tags, `status: draft`.
173There is no central manifest — the build aggregates every spec's frontmatter,
174so this run touches nothing shared. If frontmatter already exists, update only
175the fields this run owns (tagline polish, status).
176
177**The base project** (first run in a repo only): copy `base/` into the chosen
178dir (never its `node_modules`/`dist`). Fill the identity once: `__REPO__` in
179`package.json`; the `__GALLERY_*__` / `__WORDMARK_LABEL__` / `__HERO_*__` /
180`__ATTRIBUTION__` / `__SITE_HOST__` tokens in `index.html`,
181`src/gallery/site.ts`, and `README.md`; write the `tech-specs/README.md`
182pointer. The gallery page is a **roadmap**: hero copy in roadmap voice
183(`__HERO_TITLE__` ≈ "what we're working on"; `__HERO_LEAD__` hints at the
184current priority and what already landed, without naming specs), and the spec
185list renders as a one-column timeline, newest first, grouped by month. In a workspace repo, add the base to `pnpm-workspace.yaml` **with
186user confirmation** (a repo-level file). Never touch `build.mjs`,
187`vite.config.ts`, tsconfigs, or `src/` beyond this copy.
188
189### 4. Generate the content layer
190
191Edit only these — the write surface is `<base>/<slug>/**` plus the spec's
192frontmatter block (and an approved promotion):
193
194- `src/content/deck.ts` — `DECK_META.wordmarkLabel`, `NAV`, `FOOTER`.
195- `src/content/<topic>.ts` — the typed data arrays each archetype consumes
196 (map nodes/edges/info, sequence lanes/steps, reveal stages, cli tracks,
197 metrics, rows). Keep data here, out of components.
198- `src/sections/<Name>.tsx` — one thin section per slide: import the matching
199 archetype from `@lib`, feed it data, wrap it in `<Section>`. Replace the
200 example sections; delete `src/content/example.ts` and `pages/ExamplePage.tsx`.
201- `src/pages/<Name>.tsx` — deep dives via `@lib` `<PageShell>`.
202- `src/App.tsx` — wire the ordered `SECTIONS` array and the `PAGES` map.
203
204**The component protocol** (when a load-bearing concept has no fit in
205`COMPONENTS.md`):
206
2071. **Default: build it deck-local** in `<base>/<slug>/src/diagrams/<Name>.tsx`,
208 following `@lib/components/diagrams/SequencePlayer.tsx` conventions.
2092. **Promote into `<base>/src/components/` only when all three hold:** (a) it
210 is generic over its data — nothing spec-specific inside, everything arrives
211 via typed props; (b) it maps to a recurring spec shape (a lifecycle, a
212 tree, a timeline, a fan-out…) future decks will plausibly need; (c) it
213 passes the checklist in `reference/component-standards.md` without
214 deck-specific hacks.
2153. A promotion = the component file **plus its `COMPONENTS.md` entry in the
216 same change**. An unregistered shared component is a defect (the base's
217 registry check warns — `scripts/validate-roadmap.ts` in iii, `build.mjs`
218 standalone; strict mode makes it fatal).
2194. Never fork a shared component into the deck to tweak it — extend it via
220 additive, non-breaking props, or build a genuinely different deck-local
221 one. **Modifying an existing shared component requires explicit user
222 approval** (it re-renders every other deck).
223
224**Built-in spec viewer — do not delete.** Every deck ships the `#/spec` page:
225the template wires `spec-docs.ts` (the compile-time glob over the paired
226spec's markdown) into `@lib/pages/SpecPage` via `PAGES.spec`, and the shared
227`TopNav` renders the `spec` link. The shared markdown renderer strips the
228frontmatter block. It needs no per-deck content — leave the wiring in place.
229
230### 5. Verify — THE SECOND GATE
231
232All commands run from `<base>`'s package (iii: `pnpm --filter iii-website
233<script>` from the repo root; standalone: inside `<base>`):
234
235- `pnpm type-check` — the whole roadmap project (shared src + gallery + every
236 deck) must pass strict; fix every error.
237- The build must succeed with zero frontmatter-validation or registry-parity
238 warnings — iii: `pnpm build` (the site build runs the roadmap contract
239 checks and emits `dist/roadmap/<slug>/`); standalone: `node build.mjs
240 --only=<slug>`.
241- `pnpm dev` in the background, then dogfood with the **`/browse` skill**
242 (never `mcp__claude-in-chrome__*`): load
243 `http://localhost:4321/roadmap/<slug>/` (standalone: `:5173/<slug>/`),
244 click the map, run a stepper, toggle the theme, open a deep-dive, open
245 `#/spec` and confirm every markdown file renders (mermaid fences live, no
246 raw frontmatter). Zero console errors; no horizontal body scroll at 375px.
247- `pnpm build && pnpm preview`, then `/browse
248 http://localhost:4321/roadmap/` (standalone: `:4173/`): the spec appears on
249 the roadmap timeline in date order under its month, its card shows the
250 frontmatter title/tagline/tags with the day marker in the timeline gutter,
251 and clicking it lands on `/roadmap/<slug>/`. If the spec previously served
252 the md-only viewer, confirm the deck replaced it at the same URL.
253- **If anything under `<base>/src/` was touched (a promotion): run the full
254 site build** — a shared change must not break sibling decks.
255- Run `reference/quality-bar.md` end to end; fix anything red.
256
257### 6. Hand off
258
259Report: the deck path (`<base>/<slug>/`), the dev URL, the slide list, which
260interactions are live, the frontmatter written, and any promoted components
261(with their registry entries). Offer to flip `status: draft` → `live`.
262Deploy is not a step: **in iii, merging to main ships everything via
263`.github/workflows/deploy-website.yml` to `iii.dev/roadmap/<slug>/`**; in
264other repos `dist/` is a portable static site for whatever CI they use. Do
265**not** commit, push, or configure hosting unless asked. Never run `vercel`.
266
267## Rules
268
269- **The shared layer is law**: never edit `<base>/src/**`, the base's build
270 glue (iii: `website/src/pages/roadmap/` and `scripts/validate-roadmap.ts`;
271 standalone: `build.mjs` and `vite.config.ts`), tsconfigs, `package.json`,
272 or the gallery in a deck run.
273 Sole exception: additive component promotion under
274 `reference/component-standards.md`, always paired with a `COMPONENTS.md`
275 entry.
276- A deck run's write surface is `<base>/<slug>/**` plus the frontmatter block
277 of `tech-specs/<slug>/README.md`. Nothing else.
278- `tech-specs/` holds markdown only. Never write a non-md file there; never
279 create a `presentation/` directory inside it.
280- Reuse first: consult `COMPONENTS.md` before building any visual; the repo
281 registry outranks the bundled catalog.
282- Slug = the spec directory basename, used identically as the deck dir and the
283 URL. Never prettify it. `slug` is never a frontmatter field.
284- One claim per slide. Put depth behind a `<SpecSheet>` (`<details>`), closed
285 by default — execs skim, engineers drill.
286- Ration the accent (success / active / CTA only). Lowercase copy; identifiers
287 keep their casing. No em-dashes. No "robust / comprehensive / crucial /
288 seamless / unlock".
289- Ground every claim in the spec. Keep one honest trade-offs/open-questions
290 beat — honesty reads as credibility.
291- Quantify the win: use the spec's numbers verbatim; if you compute one, say so.
292
293## Decisions
294
295Ask the user: the narrative outline (Phase 2, always); output location when
296occupied; audience tilt (execs vs engineers; default balanced); fonts offline
297vs CDN (default CDN); scope cap when a spec has many domain docs; first-run
298base location + gallery identity + the `pnpm-workspace.yaml` edit; any
299**modification** to an existing shared component; flipping `status` to `live`.
300
301Decide yourself: which archetype each slide uses; slide order within the arc;
302hero line and stats; SVG coordinates and step counts; what goes behind a
303`<details>`; copy voice; the frontmatter field values; deck-local vs promote
304per the component protocol (announce promotions in the outline and hand-off —
305don't ask). Everything under `<base>/src/` and the build glue is settled —
306never re-litigate it in a deck run.
307
308## Verify
309
310`pnpm type-check` and the roadmap build (iii: `pnpm --filter iii-website
311build`; standalone: `node build.mjs --only=<slug>`) are green with zero
312registry/frontmatter warnings; `/browse` shows zero console errors, working
313interactions, and a frontmatter-free `#/spec`; the roadmap timeline lists the
314spec in date order, its card rendered from the frontmatter; `reference/quality-bar.md` passes; a promotion ran the full
315build (`reference/hosting.md` has the layout this all serves).