@taloswork/ose-shared 0.1.11 → 0.1.13

package/skills/document/deck-design.md

@@ -1,316 +1,198 @@
 # Deck design — html2pptx (hybrid) is THE deck engine
 
-**Every deck is built ONE way:** author slide HTML and render with `html2pptx` in
-its default **HYBRID** mode — `bin/html2pptx.cjs deck.html out.pptx --style <id>`
-(no `--editable`/`--rasterize`). Chromium gives you the full power of HTML/CSS
-(flexbox/grid, layering, per-element SVG) and converts to NATIVE editable pptx
-text boxes/shapes, with the decorative visual layer baked into one pixel-perfect
-backdrop — designed look **AND** editable words + editable `data-chart`. This is
-the path for every deck: pitch / keynote / report / design-y / plain alike.
-
-`doc-gen` makes no decks, and `doc-run` PptxGenJS is **NOT a deck-building path** —
-do not use it to build a deck. (It remains for NON-deck jobs only: structured
-data tables, batch/deterministic generation, shape-level one-offs.)
-
-html2pptx needs a browser — the app's Chromium service or the bundled Playwright.
-If neither is available, **say so and stop; never silently downgrade** to a lesser
-deck (no doc-gen fallback).
-
-**Compose from structure-only layouts + one skin, don't author from scratch.**
-`layouts/README.md` catalogs the structure-only slide layouts (cover / toc / section /
-big-stat / cards / comparison / chart-kpi / gantt / radar / stats-chart / …), each
-tagged role · structure · density · has-image. `styles/README.md` catalogs the skins
-(the paint). Those two READMEs are the source of truth for what exists — don't rely on
-counts quoted elsewhere. Pick layouts by **P1/P2/P3** (structure → density → **≤2 dedup**), paste
-each `layouts/<id>.tpl` into `deck.html`, fill real content (leave color to the skin),
-and render with `--style <skin>` — see the **⭐ PREFERRED workflow** below. A layout with a
-`{{#rows}}` block (gantt · radar · ring-progress · map-distribution · team-row ·
-brand-values · color-palette · steps-vertical · toc-panel) is filled through `deck-build`
-instead of by hand — it repeats the block per row and DERIVES the figure geometry from
-your numbers (see `layouts/README.md` → "How to fill"). Authoring
-every slide from zero is the #1 "AI-generated" tell; compose from the catalog first.
-
-## html2pptx — HTML/CSS is the layout engine
-
-```
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --style <id> [--theme-v2]  # DEFAULT = hybrid: paint layouts/ with the catalog entry
-node <skill>/bin/html2pptx.cjs deck.html --preview-dir <dir> --style <id>     # authoring preview: PNG per slide, no pptx
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --style <id> --editable     # plain native (effects flatten)
-node <skill>/bin/html2pptx.cjs deck.html out.pptx --style <id> --rasterize    # pixel-perfect, NOT editable
-node <skill>/bin/html2pptx.cjs snapshot.layout.json out.pptx                  # headless-safe input (always plain native)
-```
-
-### ⭐ PREFERRED workflow — structure/skin split (`--style`)
-
-**Build a deck this way by default.** Compose from **structure-only layouts** and
-paint with **one skin** at render — every layout × every skin, no duplicated
-templates, lint-guarded. Steps:
-
-1. **Pick ONE skin** for the whole deck from **`styles/README.md`** (the full list
-   with 适用场景 + light/dark) — e.g. `cool`(默认酷炫深色) · `black-gold`(黑金) ·
-   `mckinsey`(白底咨询) · `apple`(纯黑极简) · `anthropic`(奶油赤陶·衬线) ·
-   `hand-drawn`(手绘·马克笔) · `mono`(极简黑白); more in the catalog. Never mix skins.
-2. **Plan pages, pick layouts** from `layouts/README.md` by role + **P1/P2/P3**
-   (structure → density → **≤2 dedup**). Paste each `layouts/<id>.tpl` into `deck.html`
-   (they already carry `data-layout`), fill real content — leave the color to the skin
-   (never hardcode a brand hex; `lintHardcodedColors` will flag it).
-3. **Render:** `html2pptx deck.html out.pptx --style <name>`. It injects
-   `styles/<name>/skin.css`, fills each `.slide-backdrop` slot from the skin's
-   `backdrop.html`, and substitutes the chart accent (`__ACCENT__`) — so any layout
-   renders in that skin, text/charts stay native, decoration bakes.
-
-**Coverage** (see `layouts/README.md` for the full table + P1/P2 tags):
-- cover(4): cover · cover-centered · cover-statement · cover-image
-- toc(2): toc · toc-agenda · section · ending(2): ending · ending-contact
-- numbers/data: big-stat · two/three-kpi · chart-kpi · chart-full · **data-table** · **gantt** · **map-distribution** · **map-quad**
-- cards/list: cards-3 · cards-grid · list · bento · icon-row
-- compare/argue: comparison · problem-solution · versus · matrix-2x2
-- process/hierarchy: steps · steps-vertical · timeline · pyramid · concept-hub · **org-tree**
-- image: split-two-col · image-left · image-grid · image-full · quote
-
-**Extend:** add a skin = one `styles/<name>/skin.css` (define the full class contract,
-`deck-layouts` guard checks it); add a layout = one `layouts/<id>.tpl` (structure-only,
-tagged in README). Both get the other for free. `--style` and `--theme` combine (skin
-wins).
-
-### When the catalog doesn't fit — hand-author THAT ONE slide (the bespoke escape hatch)
-
-The catalog is the default for the **vast majority** of slides — breadth, consistency,
-and no "generated-from-scratch" tell. But the catalog is a **palette, not a cage**: a
-genuinely **bespoke structure it can't express** — a specific system/architecture
-diagram, a custom flow/topology/pipeline, a signature hero moment — is a legitimate
-reason to **hand-author that single slide** directly in `deck.html`. That is how you get
-template-grade polish without abandoning the model: **catalog for scale, bespoke for the
-one slide that earns it.** (The zero-color rule binds only `layouts/*.tpl`, the reusable
-library — your `deck.html` is free HTML and MAY use color; see below.)
-
-Reach for it ONLY when **no `layouts/` structure matches the content's inherent shape**
-and forcing a generic layout would flatten or misrepresent it — not because "custom
-looks nicer." Most slides do NOT earn a bespoke; a deck that hand-authors every slide is
-back to the #1 AI tell.
-
-A hand-authored bespoke slide MUST still:
-- be one `<section class="slide" …1280×720>`; text stays native; diagram parts are
-  inline `<svg>` (they rasterize per-element, the rest stays editable);
-- **paint from the skin, never random hex** — use the skin's classes (`.card`,
-  `.accent-bar`, `.eyebrow`, `.deck-title`…) and tokens `var(--accent|--title|--body|
-  --muted|--hair)` **plus the ramp `var(--c1..--c4)` for per-item color-coding**. The
-  ramp is exactly how you get "left legend color-matches the right boxes." Hardcoding a
-  brand hex reads as unfinished AND won't re-skin (`lintHardcodedColors` flags it);
-- obey the Design principles (one anchor, size hierarchy, ≥0.5" margins, **no crude
-  full-height accent bar**);
-- look **of the same deck** — same skin palette/type as the catalog slides around it, so
-  it never reads as pasted in.
-
-*Example:* a 4-layer architecture (left annotated L1–L4 list ↔ right vertical connected
-stages, each layer color-matched via `--c1..--c4`, dashed `<svg>` connectors, coder-style
-header). No catalog layout is that — hand-author it in the skin's tokens. **If the pattern
-recurs across decks, promote it to a real `layouts/<id>.tpl`** (+ any ramp selectors it
-needs) so it becomes reusable: bespoke first, then graduate the winners into the catalog.
-
-**Three delivery modes — the fidelity ⇄ editability dial:**
-- **hybrid** (DEFAULT): each slide's decorative VISUAL layer (gradients, glass,
-  glow, mesh, cards, shadows, art) is rasterized into ONE full-bleed backdrop
-  image; **TEXT and native CHARTS (`data-chart`) stay native/editable on top.**
-  **Pixel-perfect look AND editable words + editable chart data** — the sweet spot
-  for a cool deck you still want to tweak. (Gradient-clipped display text is baked
-  into the backdrop; solid text stays native. Note: gradients/shadows LOOK right
-  but live in the image — use `--editable` if you need them as editable shapes,
-  at the cost of effects the mapper can't express flattening.) Auto-falls back to
-  plain native if the backdrop capture is unavailable.
-- **`--editable`** (alias `--mode native`): text/boxes/`<img>`/`<hr>` → native
-  pptx; CSS gradients flatten to a solid, blur/glow are dropped. Fully editable.
-  Best when the design lives in layout + type, not effects, or when file size
-  matters (no backdrop images).
-- **`--rasterize`**: the whole slide (text included) becomes an image —
-  pixel-perfect but ZERO editability. Only when even the text must be exact.
-
-Contract (violations fail loudly, nothing degrades silently):
-
-- One `<section class="slide">` per slide, laid out on a **1280×720 px** canvas
-  (= 13.33×7.5 in). Color comes from the skin (`--style`), whose tokens every skin
-  defines: `var(--accent|--title|--body|--muted|--hair|--slide-bg|--title-color|
-  --body-color|--font-heading|--font-body)` plus the ramp `var(--c1..--c4)` — never
-  hardcode brand colors, and never use a name outside this set (`--primary`,
-  `--text`, `--card-bg`, `--border` are NOT defined by skins: they only exist under
-  the legacy `--theme` path, so on a `--style` deck they silently stick on their
-  fallback). html2pptx **warns** (`N hardcoded brand color(s) bypass theme vars`)
-  when a slide writes a hex instead of a `var(--…)` — that deck won't re-skin, so
-  fix it before shipping. (SVG diagram semantic colors are exempt.)
-- **Tailwind utility classes are available** (vendored offline — no CDN needed):
-  author like a modern web deck — `grid grid-cols-2 gap-16`, `flex items-center
-  justify-center`, `p-16`, `text-6xl font-bold`, `rounded-3xl`, `bg-blue-600`,
-  `space-y-6` all compute and map to native pptx. Prefer theme `var(--...)` for
-  brand colors; use Tailwind for layout/spacing/scale. A structural type scale is
-  also available: `<h1 size="1".."7">` → 12/14/16/24/32/48/72px (stay on-scale
-  instead of ad-hoc font sizes).
-- **Images must be `data:` URIs** — the render sandbox has no network.
-- **Icons = INLINE `<svg>` ONLY.** Never `<img src="…icon…">` for an icon — an
-  external/CDN icon URL fails in the no-network sandbox and Chromium bakes a
-  **broken-image glyph** (缺图红叉) into the hybrid backdrop. Paste the SVG markup
-  inline (lucide/heroicons path data), or a `data:image/svg+xml` URI at worst.
-- **No crude full-height accent bar.** A raw bright `var(--accent)` rectangle down
-  the left edge reads as an unfinished template — if a family wants a spine it is
-  baked into its `.tpl`; do not bolt a colored bar onto a bespoke slide.
-- Mapped to native pptx: text (per style run, editable/searchable), boxes
-  (background/border/radius), `<img>`, `<hr>`. **Inline `<svg>`/`<canvas>` are
-  rasterized per-element** — only that box becomes a PNG, everything else on the
-  slide stays native editable text. So a slide with an SVG icon/diagram + text
-  keeps its text editable; you do NOT need `--rasterize` for SVG anymore. Use
-  SVG freely for icons, logos, small diagrams, decorative shapes.
-- **Full-bleed photo covers stay editable**: an `<img>` with `object-fit:cover`
-  /`contain` maps to a NATIVE pptx crop/letterbox (aspect preserved — no need to
-  pre-crop to 16:9), and a semi-transparent `rgba(...)` fill maps to native fill
-  transparency, so a dark scrim over a photo no longer flattens to an opaque
-  block. Overlay a title + scrim on a photo and the text stays native/editable.
-- Still not mapped as native: CSS gradients (flatten to a solid backgroundColor
-  in the converter) and `<video>`. When a WHOLE slide relies on effects the
-  mapper can't express natively, `--rasterize` turns every slide into a
-  pixel-perfect **image** (zero text editability — say so when delivering).
-- HTML input renders in the app's Chromium when available, else a **bundled
-  headless Chromium** (Playwright) — so it works off-app too (CI/cloud/doc-run),
-  not only in-app. `.layout.json` snapshot input converts anywhere with no
-  browser. (CJK renders natively where the host has CJK fonts; a font-less Linux
-  CI may need a CJK font installed.)
-- **Speaker notes**: add a hidden `<div class="talos-notes" style="display:none">
-  …notes…</div>` (or `data-notes="…"` on the `<section>`) per slide → it becomes
-  the slide's pptx notesSlide (never rendered on the slide). Pass `--notes-doc
-  <out.md>` to also emit a standalone speaker-notes document.
-- Fonts are measured by Chromium but re-laid-out by PowerPoint — keep ~10%
-  slack in text boxes; don't butt text against box edges.
-
-After generating: the build reports `valid` and `qa` itself; sign off with
-`deck-qa --final` like any deck ("Verify before delivering").
-
-## HTML slide authoring — the design-first route
-
-This is the **toolbox for the bespoke escape-hatch slides** identified above (the
-one architecture diagram / hero the catalog can't express) — NOT a license to
-hand-author every slide (that's the #1 AI tell; compose the rest from the catalog).
-When a slide DOES earn it, you get the full CSS toolbox (flexbox/grid, layering,
-`position:absolute`, per-element SVG) and the output is still **native, editable**
-pptx — text boxes stay text, only SVG boxes rasterize. Author against the skin/theme
-CSS variables (incl. the ramp `var(--c1..--c4)`) so the same HTML re-skins for free.
-
-Every slide is `<section class="slide" style="position:relative;width:1280px;height:720px">`.
-Position with `absolute` inside it. Compose from these recipes (vary them across
-the deck — don't repeat one layout):
-
-- **Full-bleed cover** — `background:var(--primary)`; oversized title (64–96px)
-  bottom-left; one thin accent bar; presenter/date small at the very bottom.
-- **Two-column split** — 50/50 flex row: text column left (title + 3–4 short
-  lines), a visual right (an `<img>` data-URI, an SVG diagram, or a big stat).
-- **Half-bleed image** — image fills the left or right ~55% (`object-fit:cover`),
-  content overlaid on the other half with a solid or scrim panel behind the text.
-- **Big-stat hero** — one number at 140–200px in `var(--accent)`, a short label
-  under it, one supporting sentence. Nothing competes.
-- **Icon rows / 2×2 grid** — each cell: an SVG icon in a colored circle, a bold
-  header, one line of body. Equal cells, consistent gaps.
-- **Quote / statement** — one sentence at 40–56px, generous padding, attribution
-  small below. Let the type be the visual.
-- **Section divider** — `background:var(--primary)`; an oversized ghosted chapter
-  number; the section title beside it.
-
-Honor the **Design principles** below (dominant color, one visual anchor per
-slide, size hierarchy, ≥0.5" margins, NO accent line under a title). Icons: inline
-`<svg>` (stroke `currentColor`/theme vars) — they rasterize per-element, so the
-rest of the slide stays editable.
-
-**Charts — pick by where the deck will be OPENED (this is a real tradeoff, not a
-default):**
-- **Inline `<svg>` bar/line you hand-draw** = DEFAULT for a delivered deck. It
-  rasterizes into the backdrop, so it renders **everywhere** — Keynote, macOS
-  Preview / Quick Look, Google Slides, WPS, PowerPoint. The cost: the chart is a
-  picture, not editable data.
-- **Native `data-chart`** `<div class="talos-chart" style="position:absolute;
+Every deck is slide HTML rendered by `html2pptx` in its default **hybrid** mode: Chromium
+lays out the HTML (flexbox/grid, layering, per-element SVG), the decorative layer bakes
+into one pixel-perfect backdrop per slide, and text plus native `data-chart`s stay
+editable pptx objects on top. Pitch, keynote, report or plain — same path.
+
+- `doc-gen` makes no decks, and `doc-run` PptxGenJS is **not** a deck path (it remains for
+  non-deck jobs: data tables, batch generation, shape-level one-offs).
+- html2pptx needs a browser (the app's Chromium service or the bundled Playwright). With
+  neither, **say so and stop** — never downgrade to a lesser deck.
+
+Where things live: layout choice and fill contract → `layouts/README.md`; Theme V2 vs
+classic-v1 → `theme-system.md`; flags, outputs and exit codes → `bin-reference.md`;
+content and outline → `content-pipeline.md`.
+
+## Workflow
+
+1. **Plan, then fill.** The approved `plan.json` IS the outline (content-pipeline.md
+   Phase 3 — written once, `--outline` renders what the user approved) and runs
+   ```
+   node <skill>/bin/deck-plan.cjs plan.json spec.json   # → per slide: pick · alternatives · rejected[{layout, why}]
+   node <skill>/bin/deck-build.cjs spec.json deck.html
+   ```
+   `deck-plan` maps each slide's content onto every candidate layout's slots, checks
+   every string against the layout's capacity **measured under your style**
+   (`layouts/capacity.json`), applies P1/P2/P3 and drafts the spec (every slot filled,
+   charts as `chartRender:"svg"`). A slide with `pick: null` fits nothing as written —
+   change the content its `rejected[].why` names ("holds exactly 3 items, content has
+   4", "card2_body is ~58 wide but holds ≤42 — cut ~16"), or pin `layout` + `slots`, and
+   re-plan; do NOT render to find out. Edit `spec.json` freely afterwards — `deck-build`
+   re-checks capacity on every build, and its warnings (unfilled slot → demo copy) are
+   defects. Put the confirmed `scenario` in the plan (it decides motion, below). A
+   `\n` in a value is a line break (a typed `<br>` ships as text); a slide's `source`
+   ("IDC，2026") is its one short source line, in the footer.
+2. **Bespoke slides** (no layout fits, or approved generated-visual pages): author one
+   `<section class="slide">` in its own file and give the plan slide `file` — deck-build
+   puts it at its position (its `notes` too); every other slide stays catalog. **Never patch the built `deck.html`
+   with a script or regex**: capacity checks cannot see those edits. Change content
+   or slots and re-plan, or replace
+   that ONE slide with a bespoke `file`. Speaker notes are each slide's `notes`.
+3. **Preview, build, sign off** — "Verify before delivering" below.
+
+Hand-pasting a `layouts/<id>.tpl` skips the capacity check; a layout with a `{{#rows}}`
+block (gantt · radar · ring-progress · map-distribution · team-row · brand-values ·
+color-palette · steps-vertical · toc-panel) can only be filled through `deck-build`,
+which repeats the block and derives the figure geometry from your numbers.
+
+## Delivery modes — the fidelity ⇄ editability dial
+
+- **hybrid** (default — no flag): visuals (gradients, glass, glow, mesh, cards, shadows,
+  art, gradient-clipped display text) bake into the backdrop; solid text and
+  `data-chart`s stay native. Gradients/shadows *look* right but live in the image. If the
+  backdrop capture is unavailable it falls back to plain native and reports a
+  `layout (fallback)` engine.
+- **`--editable`** (alias `--mode native`): everything native; CSS gradients flatten to
+  a solid, blur/glow drop. Fully editable, smallest file. For designs that live in
+  layout + type. One exception: a Theme V2 art layer / generated-skin signature in
+  `.slide-backdrop` is one full-slide picture under the native content (its opacity,
+  blur and masks survive); the content on top stays native.
+- **`--rasterize`**: every slide one image — pixel-perfect, ZERO editability; only when
+  even the text must be exact, and say so when delivering.
+
+## The slide contract
+
+Violations fail loudly; nothing degrades silently.
+
+- One `<section class="slide">` per slide on a **1280×720 px** canvas (13.33×7.5 in).
+- **Colour only from the skin's tokens**: `var(--accent|--title|--body|--muted|--hair|
+  --slide-bg|--title-color|--body-color|--font-heading|--font-body)` and the ramp
+  `var(--c1..--c4)`. Any other name (`--primary`, `--text`, `--card-bg`, `--border`,
+  `--accent2`) exists only under the legacy `--theme` path, so on a `--style` deck it
+  silently sticks on its fallback. A raw hex triggers html2pptx's `N hardcoded brand
+  color(s) bypass theme vars` warning — that deck won't re-skin; fix it (SVG diagram
+  semantic colours are exempt). To recolour one element, override a token on its
+  `<section>`: `style="--accent:#b8292e"`.
+- **Tailwind utilities** are vendored offline (`grid grid-cols-2 gap-16`, `p-16`,
+  `rounded-3xl`…) and map to native pptx — use them for layout/spacing, tokens for
+  colour. Type scale: `size="1".."7"` → 12/14/16/24/32/48/72px.
+- **Images**: `src` accepts an absolute path, a path relative to deck.html, or HTTPS;
+  html2pptx inlines assets before rendering. Mark required content with
+  `<img data-required-image src="…" alt="…">`: unreadable or undecodable images fail
+  export and previews. Unmarked images retain best-effort loading. For useful `gen`
+  pages, follow generated-visuals.md.
+- **Icons = inline `<svg>` only** (lucide/heroicons path data, or a
+  `data:image/svg+xml` URI at worst). An icon `<img>` that fails to load bakes a
+  broken-image glyph into the backdrop.
+- **No crude full-height accent bar** down an edge, and **no thin accent line under a
+  title** — the two loudest "template" tells. A family that wants a spine bakes it into
+  its `.tpl`.
+- Native mapping: text (per style run), boxes (background/border/radius), `<img>`
+  (`object-fit:cover|contain` → native crop/letterbox, no pre-cropping), `<hr>`,
+  `rgba()` fills (native transparency — a scrim over a photo stays a scrim).
+  Inline `<svg>`/`<canvas>` rasterize **per element**; the rest of the slide stays
+  editable, so SVG icons/diagrams never need `--rasterize`. Not mapped: CSS gradients
+  in `--editable`, `<video>`.
+- **Speaker notes**: `<div class="talos-notes" style="display:none">…</div>` (or
+  `data-notes="…"` on the `<section>`) → the slide's notes page; `--notes-doc
+  <out.md>` also writes a standalone notes document.
+- PowerPoint re-lays out what Chromium measured: keep ~10% slack in multi-line text
+  boxes (single-line boxes are widened automatically — see CJK notes).
+- Runs in the app's Chromium or a bundled headless Chromium, so it works off-app; a
+  `.layout.json` snapshot converts with no browser. A font-less Linux host may need a
+  CJK font installed.
+
+## Bespoke slides — the escape hatch
+
+The catalog is a palette, not a cage: a structure no layout expresses (a specific
+architecture diagram, a custom flow/topology, a signature hero moment) earns a
+hand-authored slide. Approved generated-visual pages also use this route; other pages
+stay catalog. A bespoke slide must:
+
+- be one `<section class="slide" style="position:relative;width:1280px;height:720px">`,
+  positioned with `absolute`, text native, diagram parts inline `<svg>`;
+- paint from the skin: its classes (`.card`, `.eyebrow`, `.deck-title`, `.accent-bar`…)
+  and tokens, with the ramp `--c1..--c4` for per-item colour-coding (that is how a
+  legend colour-matches its boxes). The zero-colour rule binds only the reusable
+  `layouts/*.tpl`; deck.html may use colour, but through tokens;
+- write sizes and gutters on the skin's scale — `calc(48px * var(--type-scale,1))`,
+  `calc(96px * var(--space-scale,1))` — or it ignores the skin's density;
+- pass the Design principles below and look of the same deck.
+
+Composition recipes (vary them): **full-bleed statement** (the skin's background or
+`.slide-inverse`, oversized title bottom-left, presenter/date small at the bottom) ·
+**two-column split** (text left, visual right) · **half-bleed image** (~55% image with
+`object-fit:cover`, text on a scrim/panel on the other half) · **big stat** (one number
+at 140–200px in `var(--accent)`, a label, one sentence) · **icon rows / 2×2** (SVG icon,
+bold header, one line each; equal cells) · **quote** (one sentence at 40–56px) ·
+**section divider** (oversized ghost chapter number + title). Example: a 4-layer
+architecture — annotated L1–L4 list left, connected stages right colour-matched via
+`--c1..--c4`, dashed `<svg>` connectors. A pattern that recurs across decks graduates
+into a real `layouts/<id>.tpl`.
+
+## Charts — pick by where the deck will be OPENED
+
+- **Inline `<svg>` drawn FROM DATA** — the default. It bakes into the backdrop, so it
+  renders everywhere (Keynote, macOS Preview / Quick Look, Google Slides, WPS,
+  PowerPoint); its labels stay native text, but the data is not editable.
+  **Never hand-write the chart's SVG** (scales, stacking and axes are where hand-drawn charts go wrong): in a catalog
+  chart layout give the spec `"chartRender":"svg"` (or one chart `"render":"svg"`) and
+  `deck-build` draws it for that layout's measured chart box; on a bespoke slide run
+  `bin/deck-chart.cjs chart.json --width W --height H` and paste the printed `<svg>`
+  into a W×H box. Types `bar` · `barH` · `line` · `area` · `pie` · `doughnut` (+
+  `stacked`, `unit`, `highlight` (category index → accent), `showValues`,
+  `centerLabel`, `zeroBaseline` (line axis from 0)); ≤4 series (a 5th+ slice folds into 其他); painted only with skin
+  variables, so it re-skins. `radar`: 3–8 `labels`, 1–3 series of 0..`max` scores (the
+  `radar` layout draws it from its rows); `scatter`: `series[].points` `[x,y]`/`{x,y,label}`
+  + `xLabel`/`yLabel`.
+- **Native `data-chart`** — `<div class="talos-chart" style="position:absolute;
   left/top/width/height" data-chart='{"type":"bar|line|pie|doughnut|area","labels":
-  […],"series":[{"name":"…","values":[…]}],"colors":["#2563eb",…]}'></div>` becomes
-  a real editable `c:chart` (double-click to edit the data sheet) — **but it only
-  renders in PowerPoint / WPS / LibreOffice; it shows BLANK in Keynote, macOS
-  Preview, Quick Look and Google Slides.** Use it only when you KNOW the deck stays
-  in PowerPoint and the client needs to edit the numbers.
-- Never Chart.js/`<canvas>` (rasterizes with no control, like Manus).
-
-When unsure, ship the SVG — a chart nobody can see in Preview is worse than one
-nobody can edit.
-
-## Premium craft — the 8-layer finish (raise "fine" to "agency-grade")
-
-The Design principles below are the *floor* (don't look AI-generated). This is the
-*ceiling*: the layered finish that makes a slide read like a paid studio made it.
-Build **every hero slide** (cover / section / big-stat / ending) by stacking these
-bottom-to-top; content slides use layers 1–2 + 6–8. Spend the boldness in ONE
-place (layer 5) and keep everything else quiet.
-
-1. **Tonal base, not flat fill.** Background is a low-angle `linear-gradient`
-   (`160deg`) between two near-neighbors of the base color, not a solid — it gives
-   the slide an implicit light direction. (Dark example: `#0a0a0a→#141008`.)
-2. **Grain.** One full-bleed `feTurbulence` fractal-noise `<svg>` at
-   `opacity:.03; mix-blend-mode:multiply`. This is the single biggest "cheap→
-   premium" lever — film/paper grain kills the plastic look of a clean digital
-   gradient. Give each slide's filter a **unique `id`** (`gcv`/`gsc`/…) so multiple
-   slides in one file don't collide.
-3. **Light (hero pages only).** ONE soft light per hero page, chosen from a fixed
-   set — `spotlight` (top radial), `bloom` (offset soft disc), `duotone` (two
-   corner washes), `aurora` (bottom multi-stop glow), `frosted` (corner falloff),
-   `rimlight` (edge gradient + thin bright rim). All are **pure background-gradient
-   divs — no text, no `background-clip`** (so they're ghost-safe, see layer 8).
-   Dark themes take full strength; light themes use low-alpha versions or they blow
-   out the white. Vary WHICH light per page so a deck isn't monotone.
-4. **Depth: vignette + edge highlight.** A corner/edge `radial-gradient` that darkens
-   toward the frame pulls the eye inward; a top `inset` light hairline on cards
-   fakes a lit glass/metal edge. Subtle — you should feel thickness, not see the trick.
-5. **One signature motif.** Each style gets exactly ONE recurring decorative mark —
-   concentric rings + star-dots (black-gold), a sweeping aurora arc (cool), an
-   oversized ghost chapter number (editorial). This is where the deck earns its
-   identity; everything else stays restrained. Never put content inside the motif.
-6. **Chrome (the print-binding).** Treat the slide as a page in a bound report:
-   **running header** (report title left · chapter right) + a 1px **hairline**
-   under it + a **footer** (report / chapter) + a **page number**. This four-piece
-   frame is what makes ten slides feel like ONE document — the strongest
-   "consulting-grade" signal.
-7. **Refined type: three-tier contrast.** An **eyebrow** — tracked (`letter-
-   spacing:.28em`) small-caps label with a short lead rule (`— MARKET RESEARCH
-   REPORT`); a **display** title (cover 82–96px); a **micro-label** at 12–14px. Big
-   size jumps + deliberate tracking is the line between "designed" and "typed".
-8. **Ghost-safe export (hybrid rules).** Two hard rules for html2pptx hybrid:
-   - **Solid text only.** NEVER `-webkit-background-clip:text` gradient text — the
-     backdrop-hide pass zeroes `color`/`-webkit-text-fill-color` but NOT
-     `background`, so a gradient-clipped glyph renders TWICE (a ghost behind the
-     native text). Use a solid `color:`.
-   - **Charts follow the cross-viewer rule above** (SVG by default).
-
-The shipped `layouts/*.tpl` are this recipe applied as structure-only slides —
-paste the nearest one and paint it with a skin (`--style`) rather than rebuilding
-the stack by hand; each already carries the 8 layers correctly wired.
-
-**Every catalog entry ships a motion preset; the scenario decides whether
-`deck-build` applies it.** (`motion/<id>.json`, named by the entry's `motion` field.)
-Put the confirmed scenario in the spec as `"scenario"`: a **presented** deck (pitch /
-路演 / 发布会 / keynote / 大会 / 讲座 / 销售) gets the preset — `data-anim*` /
-`data-transition*` injected per slide by the layout's role; a **read** deck (内审 /
-评审 / 报告 / 汇报 / 讲义 / 培训 / 述职) gets none; no or an unknown scenario keeps the
-preset. `"motion": true|false` overrides the scenario. The build's JSON says which
-applied and why (`motion: {on, reason}`). Hand-written `data-anim` /
-`data-transition` always wins — `deck-build` only adds an attribute an element does
-not already have, and a deck authored straight into `deck.html` animates only
-where you write `data-anim`.
-
-## Motion — entrance animation + slide transitions
-
-### Entrance animation (`data-anim`) — opt-in, hero pages only
-
-html2pptx emits **native PowerPoint entrance animations** (a real `<p:timing>`
-build sequence — not a video, not a GIF). Mark an element with `data-anim` and it
-becomes one build step; the deck then plays like a keynote instead of appearing
-all at once.
-
-**The attribute itself is opt-in.** No `data-anim` on the page → no `<p:timing>`.
-Write your own when the scenario is a **stage** — 发布会 / 路演 / pitch / 主题演讲;
-for 内审 / 报告 / 讲义 decks that people read rather than watch, add none beyond
-what the preset already injects.
-
-#### The attribute contract
+  […],"series":[{"name":"…","values":[…]}]}'></div>` becomes an editable `c:chart`,
+  **but it only renders in PowerPoint / WPS / LibreOffice and shows BLANK in Keynote,
+  macOS Preview, Quick Look and Google Slides.** Only when you KNOW the deck stays in
+  PowerPoint and the client must edit the numbers.
+- Never Chart.js/`<canvas>`. One insight per chart, highlight the key datapoint, no junk.
+  When unsure, ship the SVG — a chart nobody can see is worse than one nobody can edit.
+
+## Premium craft — the 8-layer finish
+
+The shipped layouts already wire these layers; this is what to reproduce on a bespoke
+hero slide (cover / section / big-stat / ending: all eight; content slides: 1–2 and 6–8).
+Spend the boldness in ONE place (layer 5).
+
+1. **Tonal base** — a low-angle (`160deg`) gradient between two near-neighbours of the
+   base colour, not a flat fill.
+2. **Grain** — one full-bleed `feTurbulence` noise `<svg>` at `opacity:.03;
+   mix-blend-mode:multiply`; give each slide's filter a unique `id`.
+3. **Light (hero only)** — ONE of `spotlight` · `bloom` · `duotone` · `aurora` ·
+   `frosted` · `rimlight`, as plain background-gradient divs (no text, no
+   `background-clip`); full strength on dark skins, low alpha on light ones; vary it
+   per page.
+4. **Depth** — an edge vignette and a top inset hairline on cards; felt, not seen.
+5. **One signature motif** per style (rings + star-dots, an aurora arc, a ghost chapter
+   number); never put content in it.
+6. **Chrome** — running header (title · chapter) + 1px hairline + footer + page number:
+   what makes ten slides read as one document.
+7. **Three-tier type** — tracked (`letter-spacing:.28em`) eyebrow with a lead rule, a
+   display title, 12–14px micro-labels.
+8. **Ghost-safe export** — solid text only: NEVER `-webkit-background-clip:text`
+   (the backdrop pass hides `color` but not `background`, so the glyph renders twice).
+   Charts follow the rule above.
+
+## Motion — presets, entrance animation, transitions
+
+**Every catalog entry ships a motion preset (`motion/<id>.json`); the scenario decides
+whether `deck-build` applies it.** Put the confirmed scenario in the spec as
+`"scenario"`: a **presented** deck (pitch / 路演 / 发布会 / keynote / 大会 / 讲座 / 销售)
+gets the preset — `data-anim*` / `data-transition*` injected per slide by role; a
+**read** deck (内审 / 评审 / 报告 / 汇报 / 讲义 / 培训 / 述职) gets none; no or an unknown
+scenario keeps the preset. `"motion": true|false` overrides; the build reports
+`motion: {on, reason}`. Hand-written attributes always win (deck-build only adds what an
+element lacks), and a deck written straight into `deck.html` animates only where you
+write `data-anim`. Add your own only on a stage deck, never on a read deck.
+
+html2pptx emits native PowerPoint builds (`<p:timing>`). Attribute contract:
 
 | attribute | value | default |
 |---|---|---|
@@ -320,85 +202,36 @@ what the preset already injects.
 | `data-anim-delay` | ms before this step | `0` first step, `200` after |
 | `data-anim-dur` | ms the effect runs | `500` |
 
-`fade-up` and `float` are the same gentle 5%-rise fade — the house default.
-`fly-*` travels 30% of the slide and is loud; spend it once, on a cover. `appear`
-is a hard cut with no fade (use for a punchline that should snap in).
-
-Put the attribute on a **container** and the text inside inherits it — the walker
-resolves each text run to its nearest `[data-anim]` ancestor, so one attribute on
-a `.card` animates the whole card as a unit. That is almost always what you want:
-animate BLOCKS, not individual words.
-
-#### Playback model
-
-The first step fires when the presenter advances to the slide's build; every later
-step chains **after-previous**, so its `data-anim-delay` reads as the stagger
-between items. One click plays the whole page — you never click per element.
-
-#### Hard constraints (silent failure if ignored)
-
-- **Only native shapes animate.** Anything baked into the raster backdrop is one
-  flat image and cannot be a step. That includes every `--talos-bake:1` title —
-  **`cinereel` and `ivory-gold` bake ALL their title classes**, so on those two
-  skins a `data-anim` on `.cover-title`/`.section-title` is silently dropped.
-  Animate the eyebrow, body, cards and image instead, or pick another skin.
-  **Same rule for a motion preset's `entrance.<role>[].sel`** — `deck-build` writes
-  `data-anim*` onto whatever the selector matches by class, so a preset step aimed
-  at a title class on a bake-everything skin drops just as silently; a family's
-  `motion/<id>.json` has to know its own skin's `--talos-bake` list.
-- **`background-clip:text` is baked too** (layer 8 above) — same silent drop.
-- **PDF flattens everything.** `doc-convert` / LibreOffice / Gotenberg ignore
-  `<p:timing>`; the animation exists only in the .pptx opened in PowerPoint,
-  Keynote or Impress. Never promise animation on a PDF deliverable.
-- **Charts and images animate**, as whole objects — a `data-chart` cannot animate
-  series-by-series.
-
-#### Recipes (paste onto the layout you already picked)
-
-**Cover** — one statement, one beat:
+`fade-up` = `float` (gentle 5% rise — the house default); `fly-*` travels 30% of the
+slide and is loud (once, on a cover); `appear` is a hard cut for a punchline. Put the
+attribute on a **container** — text inside inherits its nearest `[data-anim]`
+ancestor, so one attribute on a `.card` animates the card as a unit. The first step
+fires when the presenter advances; later steps chain after-previous, so
+`data-anim-delay` is the stagger — one click plays the page.
 
 ```html
 <h1 class="cover-title" data-anim="fade-up" data-anim-seq="1" data-anim-dur="700">…</h1>
 <div class="cover-sub" data-anim="fade-up" data-anim-seq="2" data-anim-delay="120">…</div>
-```
-
-**Section divider** — the number lands, then the title:
-
-```html
-<div class="section-ghost" data-anim="fade" data-anim-seq="1">03</div>
-<h2 class="section-title" data-anim="fly-up" data-anim-seq="2" data-anim-delay="150">…</h2>
-```
-
-**Card grid / TOC** — stagger the blocks, never the words. One attribute per card,
-`seq` in reading order, a short even delay:
-
-```html
-<div class="card" data-anim="fade-up" data-anim-seq="1">…</div>
-<div class="card" data-anim="fade-up" data-anim-seq="2" data-anim-delay="140">…</div>
 <div class="card" data-anim="fade-up" data-anim-seq="3" data-anim-delay="140">…</div>
-```
-
-**Big stat** — the label sets up, the number pays off:
-
-```html
-<div class="stat-lead" data-anim="fade" data-anim-seq="1">…</div>
 <div class="stat-num" data-anim="appear" data-anim-seq="2" data-anim-delay="260">…</div>
 ```
 
-#### Discipline
+Silent-failure constraints:
 
-- **≤4 steps per slide.** A build with eight steps is a slide with too much on it.
-- **Hero pages only** — cover, section, big-stat, ending, and at most one content
-  page per chapter. A deck where *every* page builds is exhausting to present.
-- **Never animate the chrome** (header/footer/page number/hairline) — the frame is
-  supposed to be constant; animating it makes the deck feel unstable.
-- **Keep durations short** (500–700ms). Anything slower reads as lag on a projector.
+- **Only native shapes animate.** Baked text is part of the backdrop image: every
+  class a skin marks `--talos-bake:1` drops its `data-anim` silently. Many skins bake
+  their titles (`cinereel` and `ivory-gold` bake all title classes; check the skin's
+  `skin.css` for `--talos-bake:1`) — animate the eyebrow, body, cards and images
+  instead. A preset's `entrance.<role>[].sel` obeys the same rule, so a family's
+  `motion/<id>.json` must know its skin's bake list. `background-clip:text` is baked too.
+- **PDF flattens everything** (doc-convert / LibreOffice / Gotenberg ignore timing and
+  transitions): never promise animation on a PDF.
+- Charts and images animate as whole objects — never series-by-series.
 
-### Slide transitions (`data-transition`)
+Discipline: ≤4 steps per slide; hero pages only (cover, section, big-stat, ending, at
+most one content page per chapter); never animate the chrome; 500–700ms.
 
-Where `data-anim` builds content WITHIN a slide, `data-transition` sets how the deck
-moves BETWEEN slides. Put it on the `<section class="slide">` — it describes the move
-**into** that slide.
+**Transitions** go on the `<section class="slide">` and describe the move INTO it:
 
 | attribute | value | default |
 |---|---|---|
@@ -406,272 +239,179 @@ moves BETWEEN slides. Put it on the `<section class="slide">` — it describes t
 | `data-transition-dir` | `l` · `r` · `u` · `d` (wipe/push/cover) · `in` · `out` (zoom/split) | per-effect default |
 | `data-transition-dur` | ms | the `med` speed bucket |
 
-```html
-<section class="slide" data-transition="fade" data-transition-dur="600">…</section>
-<section class="slide" data-transition="push" data-transition-dir="u">…</section>
-```
-
-**`morph` is the one that makes a deck look produced** — PowerPoint tweens shapes that
-persist across two slides instead of cutting. Two caveats before you reach for it:
-it needs **PowerPoint 2016+** (older consumers get the fade fallback we emit), and in
-hybrid mode most of each slide is a single baked backdrop image, so morph has little
-to tween — it reads as a soft cross-dissolve unless the two slides share **native**
-shapes (text/charts) in similar positions. Use it between slides that genuinely
-continue one another (a title that moves, a stat that grows); elsewhere `fade` is more
-honest and costs nothing.
-
-**Pick one transition for the deck and stay with it** — a different effect per slide is
-the single loudest "amateur deck" signal. `fade` for almost everything; `push` or
-`cover` when chapters should feel like turning a page; `cut` (or nothing) for dense
-analytical decks where motion is noise; `morph` for the two or three slides that
-actually continue each other.
-
-Same two constraints as animation: **PDF export flattens transitions** (they exist only
-in the .pptx opened in PowerPoint/Keynote/Impress), and an unknown name degrades to
-`fade` rather than failing.
-
-## Type & space scale — how a skin sets its own rhythm
-
-Every `font-size` and page gutter in `layouts/*.tpl` is written as a scalable value:
-
-```html
-font-size:calc(23px * var(--type-scale,1))    left:calc(96px * var(--space-scale,1))
-```
-
-A skin sets `--space-scale` / `--type-scale` in its `:root` and the whole deck retimes —
-**without touching a single layout**, and keeping each layout's internal hierarchy intact
-(everything scales together). Both default to `1`, so a skin that ignores them renders
-exactly as before. The shipped range runs from `mckinsey` at `0.86` (board-pack density)
-to `apple` at `1.22` (keynote-stage air).
+Pick ONE transition for the deck — a different effect per slide is the loudest amateur
+signal: `fade` for almost everything, `push`/`cover` for page-turn chapters, `cut` (or
+none) for dense analytical decks. `morph` needs PowerPoint 2016+ (older apps get the
+emitted fade fallback) and only tweens **native** shapes in similar positions on both
+slides — in hybrid most of a slide is one baked image, so use it only between slides
+that genuinely continue each other. An unknown name degrades to `fade`.
 
-Two rules:
+## Type & space scale
 
-- **Hand-authoring a bespoke slide?** Write your sizes the same way
-  (`calc(48px * var(--type-scale,1))`) or that one slide will ignore the skin's rhythm
-  and sit at a different density than the rest of the deck.
-- **Changed a scale? Re-run `deck-qa`.** Scaling reflows text; push it too far and content
-  runs off-canvas or collides. That is a mechanical check — never eyeball it.
+Every `font-size` and gutter in `layouts/*.tpl` is `calc(Npx * var(--type-scale,1))` /
+`calc(Npx * var(--space-scale,1))`; a skin sets the two scales in `:root` and the whole
+deck retimes with its hierarchy intact (from `mckinsey` 0.86 to `apple` 1.22; both
+default 1). A bespoke slide writes its sizes the same way. **Changed a scale? Re-export
+(`html2pptx deck.html out.pptx`) and read its `qa`** — scaling reflows text and can push
+it off-canvas; never eyeball it. (`deck-qa` takes the .pptx only.)
 
 ## Fonts — bundled faces reach the render, not the native text layer
 
-`assets/fonts/fonts.json` is the single source of truth for the skill's font set.
-`html2pptx` base64-injects every face from it at render; `scripts/deck/deck-skin-samples.mjs`
-and `scripts/deck/deck-fidelity.mjs` serve the same files from disk. **Add a face there and
-drop the `.woff2` beside it — never inline a base64 `@font-face` into a `skin.css`.**
-
-The part that trips people up: an injected `@font-face` styles the **browser** render —
-the raster backdrop, any `--talos-bake:1` text, `--rasterize` output, and the skin
-preview cards. It does **not** reach the **native pptx text layer**. There a run carries
-only a typeface *name*, and PowerPoint / Keynote / LibreOffice substitute whatever they
-have installed. So a skin can name a face, we can bundle it, and the audience still sees
-a substitute.
-
-Three ways a non-system face actually survives into the delivered deck:
-
-1. **Bake it** (`--talos-bake:1` on the class) — what `cinereel` and `ivory-gold` do for
-   their Anton titles. Guaranteed correct; the text becomes part of the backdrop image,
-   so it is no longer editable, searchable, `deck-qa`-checkable, or animatable.
-2. **Embed it** — `bin/pptx-embed-fonts.cjs` writes an OOXML font embed. Needs a TTF
-   (we bundle woff2), and is only sane for small Latin faces, never CJK.
-3. **Ask for a system face** — Helvetica Neue / Georgia / Arial and the CJK families are
-   everywhere; that is why most skins lead with them.
-
-A face that is bundled but neither baked nor embedded is *still worth bundling* (the
-backdrop and the picker previews come out right), just don't assume the native text
-followed. `hand-drawn`'s Gochi Hand heading is exactly that case today.
-
-## Design principles (the constraint EVERY deck honors)
-
-This is the "design ideas" bar for a freeform deck. The catalog layouts
-(`layouts/*.tpl`) already bake most of it in (dominant accent, contrast-picked
-text, motif, no under-title lines); when you hand-build slides YOU are responsible for it.
-Not a menu — treat it as a checklist the deck must pass.
-
-**Color — commit, don't sprinkle.**
-- Pick ONE dominant color from the theme and let it own the deck (roughly 60–70%
-  of the colored area). Accent is a spark, not an equal partner; a palette where
-  three colors fight for attention reads busy and amateur.
-- Alternate value: sandwich full-bleed dark slides (covers, section breaks,
-  a punchy stat) between light content slides. The rhythm is the design.
-- Do NOT default to generic corporate blue because it's "safe" — let the topic
-  inform the hue. Use the theme; the theme already made this choice deliberately.
-
-**Layout — every slide earns a visual anchor.**
-- No slide is a wall of text. Each one gets a structural element: a colored band,
-  a big number, an icon row, a 2×2, a chart, or a supporting image. A title +
-  bullets on white is the classic AI tell — restructure it (this is exactly what
-  the build's `qa` flags as `text-only-slide`).
-- Reach for the strong composition patterns: two-column split, icon+label rows,
-  a 2×2 grid, a half-bleed image with text on the other half, one hero figure.
-- Vary the layout slide-to-slide. Ten identical bullet slides is the single
-  biggest "generated by a machine" signal — pick different archetypes.
-- Generous margins (≥0.5"), real breathing room. If a slide feels full at 60%,
-  stop adding — whitespace is structure, not waste.
-
-**Typography — scale and pairing.**
-- Exactly one focal element per slide. A clear size ladder: title 24–28pt bold,
-  body 14–16pt, captions 10–11pt. Never more than 3 sizes on one slide.
-- Contrast heading vs. body deliberately (weight or family), don't run everything
-  in one flat size. Use the theme's font pairing.
-
-**Alignment & consistency.**
-- Everything snaps to the grid. Mixed left/center in one zone reads amateur —
-  pick one per zone, and never center running body text (left-align it).
-- Same corner radius (0.06–0.1"), same 1pt border, same accent placement across
-  every card of a family. Filled boxes ≥0.15" internal padding; siblings ≥0.25"
-  apart.
-- **6×6 discipline**: ≤6 bullets, ≤6 words each. Past it, redesign as cards/graphic
-  — don't shrink the font.
-
-**Contrast — readability is non-negotiable.**
-- Text on fills must clear ~4.5:1 (large/bold ~3:1). Dark fills → light text
-  (`F1FAEE`/`FFFFFF`); light fills → the `text` color. When unsure compute
-  luminance. The build's `qa` flags the worst offenders as `low-contrast-text`.
-
-**The AI tells to avoid** (these scream "template"):
-- A thin accent LINE under the title. Never. It's the #1 giveaway; use space,
-  weight, or color for hierarchy instead.
-- Repeating the same layout every slide; centering body copy; defaulting to blue;
-  equal-weight color soup; a slide that is only text.
-
-## Picking layouts & snippets — deterministic selection
-
-Choose layouts like a **matcher**, not by vibe. Two decisions:
-
-**Style — decide once, lock the whole deck.** From the prompt keywords pick ONE
-**skin** (`--style <skin>`, see `styles/README.md`) and use it on every page. Never
-mix skins mid-deck.
-
-**Layout — match on description, then dedup.** Every layout carries a one-line
-description of `role · structure · density · has-image` (see `layouts/README.md`).
-For each planned page match by priority:
-- **P1 Layout structure** (most important): has image? image left/right? text-only?
-  → pick a template whose description matches (`image-left`, `text-only`, …).
-- **P2 Content density**: 1–2 points → `minimal`/`hero`/`centered`; 3–4 →
-  `two-column`/`balanced`; 5+ → `grid`/`dense`/`cards`.
-- **P3 Diversity (ENFORCED)**: never the same content template twice **in a row**;
-  **≤2 times total** across the deck. This dedup rule is the real source of
-  "not machine-made" — honor it over a marginally better P1/P2 fit.
-
-Per page type: **cover** — one that fits the theme; **toc** — by chapter count (3–4
-`centered` / 5–6 `grid` / 7+ `dense`); **transition** — reuse ONE across all section
-breaks; **ending** — by purpose (thanks / Q&A / contact).
-
-Plan it explicitly before authoring — list each page as
-`type · title · density · image? · chosen-template` so the ≤2 dedup constraint is
-visible while you assign.
-
-**Functional & decorative snippets — self-serve, NOT planned.** These are not matched
-per page; add them as the deck needs. Catalogs in `assets/snippets/`:
-- **`functional.md`** — `nav-bar` / `breadcrumb` / `footer-pageno` / `cta-row`. Put a
-  footer (`org · page N/total`) on nearly every content page and a nav-bar on
-  section/content pages — the cheapest "produced" signal. `cta-row` on the ending.
-- **`motifs.md`** — `seal` / `gold-flourish` / `neon-dot` / `corner-frame` /
-  `thin-geo` / `grid-dots`. Sprinkle **≤2 per slide** as a style signature; match the
-  motif family to the style. Never put content in a motif.
-- **`decorations.md`** — full-slide decorations (`neural-net` / `data-pipeline` /
-  `code-editor` / `cube-3d` / `radar` / `glow-cover` / `chinese-seal`) for
-  diagram/hero pages.
-
-All snippets are hybrid-native: chips, rules, frames, gradients, SVG **bake into the
-backdrop**; labels, page numbers, chart data stay **native/editable**. Route every
-color through the skin tokens (`var(--accent, …)`) so one skin reskins them — the same
-`footer-pageno` fragment becomes tech-cyan or 国风-朱红 by swapping `--accent`.
-
-**Pairing a snippet with the theme** — two independent dimensions:
-- **Color = automatic.** Snippets read only the skin tokens listed in the slide
-  contract above (`--accent --title --body --muted --hair --slide-bg --title-color
-  --body-color --font-heading --font-body --c1..--c4`). Pick the skin and every
-  snippet recolors for free; the value after the comma is just the fallback. Any
-  OTHER var name (e.g. `--accent2`, `--primary`) is not defined → it silently sticks
-  on its fallback, so **only use those names**. Need one snippet in an off-skin
-  color? Override on its `<section>`: `style="--accent:#b8292e;--muted:#9a8b76"`.
-- **Form = your choice.** The theme supplies the palette, NOT the shape. A `neon-dot`
-  on a 侘寂 light theme reads wrong even recolored — pick the motif/functional family
-  that matches the style's aesthetic (seal→chinese, gold-flourish→black-gold,
-  neon/corner-frame→tech).
-- **Exception — semantic colors don't follow the theme.** Multi-color ramps that
-  encode meaning (`neural-net` layer colors, `cube-3d` Layer 1/2/3, `radar` severity)
-  are intentionally hardcoded; the theme reskins their title/bg/accent but the ramp
-  stays so the hierarchy reads.
-
-## Verify before delivering (MANDATORY automated visual-QA loop)
-
-**Assume there are problems — your job is to find them.** Treat QA as a bug hunt,
-not a confirmation step. Use the cheapest faithful surface for each stage: HTML
-screenshots while authoring, the build's own checks on every build, and one
-Office-rendered sign-off at the end. Do not launch LibreOffice after every edit.
-
-**Machine checks come with the build.** Every `html2pptx … out.pptx` run prints,
-next to the build result, `valid` (does the file open — `false` exits 1: never
-deliver) and `qa: { ok, findings:[{slide,code,message}] }` — deck-qa's lint:
-**off-canvas**, **tiny-font** (<10pt), **shape-overlap**, **text-only-slide**,
-**low-contrast-text**, **placeholder-text** (替换为…/占位/在这里写/Lorem left in a
-slide) and **font-mismatch** (CJK in a Latin-only font → 豆腐; language defaults to
-the system locale, override with `TALOS_DECK_LANG`). **Fix every finding before
-anything else** — they are objective and free, so they must never reach the
-vision pass or delivery. No separate `doc-validate` / `deck-qa` call is needed
-after a build.
-
-**The loop** (≤2 delivery rounds, then report residuals — never silently ship):
-
-1. **Author against the HTML preview.** `html2pptx.cjs deck.html --preview-dir
-   <dir> --style <id> …` renders every slide the first time; after a fix,
-   `--preview-pages 3,7-8` renders only the changed ones. Read these images and
-   iterate until the composition is clean.
-2. **Build and fix the build's findings** (`html2pptx … deck.pptx`, see above).
-3. **Sign off once: `deck-qa.cjs deck.pptx --final`.** One call runs strict XSD
-   validation (a failure exits 1), the lint, an Office render (LibreOffice via
-   `doc-convert`, cached), and the render check: `render-overflow` (text Office
-   re-wrapped onto more lines than its box holds, or past its side) and
-   `render-collision` (text that grew out of its box onto another). It returns
-   `review` — the slides with such a finding or a native chart (Office draws
-   charts; the preview never showed them) — and `previews`, a ≈72dpi image of
-   each. **Read only `previews`.** Every other slide already passed your eyes in
-   the HTML preview, and in the default hybrid mode its visuals are baked from
-   that same render; Office only re-lays the native text, which was just
-   measured. Re-wrapping at a different word, spacing CJK and Latin apart or a
-   substituted Latin face is normal, not a defect.
+`assets/fonts/fonts.json` is the single source of the font set: html2pptx base64-injects
+every face from it (sample/fidelity scripts serve the same files). Add a face there with
+its `.woff2` — never inline a base64 `@font-face` into a `skin.css`. An injected face
+styles only the **browser** render (backdrop, baked text, `--rasterize`, previews); a
+native pptx run carries just a typeface *name*, and PowerPoint / Keynote / LibreOffice
+substitute what they have. A non-system face survives into the delivered deck only if:
+
+1. **baked** (`--talos-bake:1` on the class) — exact, but that text is no longer
+   editable, searchable, `deck-qa`-checkable or animatable;
+2. **embedded** — `bin/pptx-embed-fonts.cjs` (needs a TTF; small Latin faces only, never
+   CJK); or
+3. **a system face** (Helvetica Neue / Georgia / Arial, the CJK families) — why most
+   skins lead with them.
+
+## Design principles (the bar EVERY deck passes)
+
+The catalog layouts bake most of this in; on a bespoke slide it is yours.
+
+- **Colour — commit.** One dominant colour (~60–70% of the coloured area), accent as a
+  spark; let the skin's palette choose the hue, never a "safe" corporate blue. The
+  background comes from the skin — don't paint your own. Alternate value: put dark
+  slides (cover, section breaks, a punchy stat — via a dark layout or `.slide-inverse`
+  where the skin defines it) between light content slides.
+- **Every slide earns a visual anchor** — a colour band, big number, icon row, 2×2,
+  chart or image, plus ≥2 visual elements in all (anchor, motif, chrome). Title +
+  bullets on a plain ground is the classic AI tell (`qa` flags `text-only-slide`). Vary the layout slide to slide; ≥0.5" margins; if a slide feels
+  full at 60%, stop adding.
+- **Type.** One focal element per slide; ≤3 sizes per slide; ≤2 font families; contrast
+  by weight or family. Catalog layouts already set the ladder — don't override their
+  sizes. Bespoke: title `size 6–7` (48–72px), section headings `size 5–6`, body 14–24px,
+  labels ≥13px; `qa` flags anything under 10pt as `tiny-font`. Never shrink type to fit
+  — split or cut instead (≤6 items, each ≤2 lines; past that, cards or a graphic).
+- **Alignment.** Snap to a grid; one alignment per zone; never centre running body
+  text. Siblings share radius, border and accent placement (use the skin's classes);
+  filled boxes keep ≥0.15" inner padding, siblings ≥0.25" apart.
+- **Contrast.** Text on fills clears ~4.5:1 (large/bold ~3:1): `var(--title)` /
+  `var(--body)` on the skin's own surfaces; `qa` flags `low-contrast-text`.
+
+## Snippets — self-serve, not planned
+
+`assets/snippets/`: **`functional.md`** (`nav-bar` · `breadcrumb` · `footer-pageno` ·
+`cta-row` — a footer on nearly every content page is the cheapest "produced" signal;
+`cta-row` on the ending) · **`motifs.md`** (`seal` · `gold-flourish` · `neon-dot` ·
+`corner-frame` · `thin-geo` · `grid-dots`; ≤2 per slide, never content inside) ·
+**`decorations.md`** (full-slide `neural-net` · `data-pipeline` · `code-editor` ·
+`cube-3d` · `radar` · `glow-cover` · `chinese-seal` for diagram/hero pages). They read
+only the contract tokens, so colour follows the skin automatically; FORM is your choice —
+match the family's aesthetic (seal→chinese, gold-flourish→black-gold,
+neon/corner-frame→tech). Exception: meaning-bearing ramps (`neural-net` layers,
+`cube-3d` levels, `radar` severity) stay hardcoded on purpose.
+
+## Custom skins
+
+When the user picks 其他/自定义 or 使用我的模板文件 in the style picker, clarify the route —
+**prefer B**:
+
+- **B — derive a bespoke look (PREFERRED).** From an **existing deck** (the picker's
+  使用我的模板文件): learn its STYLE — what every page shows (logo, bars, footer,
+  page number, palette, fonts) — with `template-skin <deck.pptx> <name> --label "<a short name the user would recognise, e.g. 太平洋证券研报>"`, not its
+  photos/tables/text. The template's look **is** the style: it overrides an earlier
+  深色/浅色 ask — do not ask how to blend them. Confirm the two `samples` + `uncertain`
+  list as an image card (relay any `warnings`); a fix is a re-run: `--exclude <kept key>`
+  — a brand logo, a disclaimer (read `kept[].hint`), a photo taken as logo —
+  `--include <uncertain key>`, `--content-page N`. Never rebuild the look as a
+  hand-written skin and never set `TALOS_DOC_STYLES_DIR` yourself (2026-10-09 a deck
+  dropped its learned template for a patched mckinsey copy). Then
+  author with `style: "<name>"`: titles go in the template's title bar, content in its
+  free area (a bespoke slide starts at top ≥210px); `deck-plan --layouts --style <name>`
+  lists what fits. Refilling its
+  ORIGINAL PAGES is a separate route, if asked (rewrite.md "Reuse an uploaded
+  deck"). From a **reference image / brand color**: sample the palette into a new skin.
+- **A — map to the nearest catalog family** (they only described a vibe): pick the
+  closest, render its sample, confirm.
+- **C — tweak an existing skin** ("刚才那个族但换绿色"): clone it, swap accent/palette or
+  flip light↔dark.
+
+Render a cover+content sample of the result and confirm (same image-card step as a
+normal pick) before authoring; save the preference to memory.
+
+A new skin is a user style: one `skin.css` defining the full class contract
+(`layouts/README.md`), saved at `$TALOS_DOC_STYLES_DIR/styles/<name>/skin.css` (the
+user's own styles, kept across sessions and shared by every expert) and rendered with
+`--style <name>`. Pick a name no catalog entry uses — catalog ids resolve first. The
+saved ones are `ls "$TALOS_DOC_STYLES_DIR/styles"`; offer them for "我之前那个风格". If
+`$TALOS_DOC_STYLES_DIR` is unset (CI / bare headless run), build it in the working folder
+and pass `--style ./styles/<name>`. Never write inside the skill directory: it is an
+integrity-checked install, reinstalled — and your file lost — once it changes.
+Start from the catalog skin of the same light/dark polarity
+(`styles/<id>/skin.css`) and replace its tokens with the sampled palette — every layout
+then works in it. To reuse an existing deck's palette, `pptx-theme` extracts it as JSON:
+copy its colours into those tokens. `html2pptx --theme` does not do this: on a
+`--style` deck the skin's tokens override the theme's.
+
+## Verify before delivering (MANDATORY)
+
+**Assume there are problems — your job is to find them.** Use the cheapest faithful
+surface per stage: HTML screenshots while authoring, the build's own checks on every
+build, one Office-rendered sign-off at the end.
+Do not launch LibreOffice after every edit.
+
+1. **Author against the HTML preview.** `html2pptx.cjs deck.html --preview-dir <dir>
+   --style <id> …` renders every slide the first time; after a fix,
+   `--preview-pages 3,7-8` renders only the changed ones. Iterate until clean.
+   **Look at each preview once:** after the first render read `sheet.png` (every slide
+   as a 640×360 tile, one image), then open a single `slide-NNN.png` only where the
+   sheet shows something to check, then only the pages you re-rendered. Never re-read an
+   image you already looked at — `deck-qa --final` (step 3) is the final check.
+2. **Build and fix the build's findings.** Every `html2pptx … out.pptx` prints `valid`
+   (`false` exits 1 — never deliver) and `qa: {ok, findings}` — deck-qa's lint (codes in
+   bin-reference.md). Fix every finding first; they are objective and free.
+   No separate `doc-validate` / `deck-qa` call is needed after a build.
+3. **Sign off once: `deck-qa.cjs deck.pptx --final`** — strict XSD validation (failure
+   exits 1), the lint, a cached Office render and its `render-overflow` /
+   `render-collision` check. It returns `review` (slides with a finding or a native
+   chart, which only Office draws) and `previews` (≈72dpi images of those).
+   **Read only `previews`.** For hybrid PPTX QA, other slides already passed the HTML
+   preview; their visuals come from that render. PDF delivery needs the final check below.
    - **Read every slide instead** (`pdf-render.cjs <deck>.office.pdf all 1`) when
-     `html2pptx` reported a `layout (fallback)` engine (no baked visuals, so the
-     preview no longer matches) or you changed the PPTX after building it
-     (`doc-xml`, `pptx-slide`, a script).
-   - `office.faithful: false` (no LibreOffice, only a Chromium reconstruction) or
-     `office.error`: there is no Office layout to check. The HTML preview stands;
-     say so when delivering.
-4. **Vision critic — the part only a model can do.** It judges the HTML preview
-   images (step 1) and the `previews` of step 3 — never a second full pass over
-   slides already judged. LOOK at every image you critique (not "glance").
-   **Either you critique a slide or a sub-agent does, not both:** with sub-agent
-   dispatch, hand slides to fresh-eyes critics in parallel and read their verdicts
-   instead of opening the images yourself. Give each critic the slide's findings
-   so it does NOT re-report them — it judges only what a machine can't: balance
-   and whitespace, hierarchy and focal point, a real visual anchor (not a text
-   wall), palette/motif consistency, image quality, crowding and uneven gaps,
-   misaligned sibling columns, decorative lines sized for one-line text when the
-   title wrapped, and leftovers the lint can't phrase-match (`{{tokens}}`,
-   "undefined", stray "xxx"). Each critic returns **{slide, verdict: pass|fail,
-   defects:[…]}**.
-5. **Regenerate only the failing slides.** Re-author that `<section>` (one section
-   per file lets a slide rebuild in isolation) and rebuild, or use `pptx-slide`
-   (dup/remove/reorder) / `pptx-clone` for template-driven slides. Then preview
-   the changed slides, rebuild and run `--final` again — one fix often creates
-   another. Stop when a pass finds nothing new **or** after 2 rounds; if defects
-   remain, **deliver with an explicit note listing them**.
-
-**Reading images is the most token-expensive step of the deck flow** (≈ w×h∕750
-tokens each; a 1280×720 slide ≈ 1.2k). Preview and `--final` images are ≈72dpi,
-¼ of the default render; `pdf-render … 2` only when fine print must be legible.
-
-**Do not declare done before at least one complete build→sign-off→critic cycle.**
+     html2pptx reported a `layout (fallback)` engine, or you changed the PPTX after
+     building it (`doc-xml`, `pptx-slide`, a script).
+   - `office.unavailable`: PPTX has no Office layout check; disclose this. A running
+     LibreOffice that fails exits 1; rerun `--final`. `--require-office` fails both.
+4. **Vision critic — you, not a sub-agent.** Judge the HTML previews (step 1) and the
+   `previews` of step 3; PDF delivery also requires the check below. LOOK at every image you critique.
+   Never dispatch the visual review to sub-agents: they may not see images at all, and
+   one deck lost 10 minutes to critics reading placeholders. Judge what a machine can't: balance and whitespace, hierarchy and
+   focal point, a real anchor, palette/motif consistency, image quality, crowding and
+   uneven gaps, misaligned sibling columns, decorative lines sized for one-line text when
+   the title wrapped, leftovers the lint can't phrase-match (`{{tokens}}`, "undefined",
+   "xxx"). Each critic returns `{slide, verdict: pass|fail, defects:[…]}`.
+5. **Regenerate only the failing slides** (re-author that `<section>`, or
+   `pptx-slide` / `pptx-clone` for template-driven slides), preview them, rebuild, run
+   `--final` again. Stop when a pass finds nothing new **or** after 2 rounds; deliver
+   with an explicit note of what remains.
+
+Images are the most token-expensive step (≈ w×h∕750 tokens; a 1280×720 slide ≈ 1.2k):
+previews and `--final` images are ≈72dpi; `pdf-render … 2` only when fine print must be
+legible. **Do not declare done before one complete build → sign-off → critic cycle.**
+
+**PDF delivery:** convert the exact final PPTX with `doc-convert.cjs deck.pptx out.pdf`,
+or reuse its final QA Office PDF if the PPTX is unchanged. Inspect every delivered PDF
+page once. If Office is unavailable or fails, do not deliver a substitute PDF.
+Use matching fonts in the Office environment; font substitution and different viewers
+can change wrapping. Fix visible differences in the source or font environment and
+re-export. HTML previews guide authoring; they are not the final PDF.
 
 ## CJK notes
 
-- Do NOT set `fontFace` to a Latin-only font for CJK text — omit it (platform
-  default renders CJK) or use the theme's font.
-- CJK line estimate ≈ width(inches) × 96 / fontSize(px) characters; wrap long 中文
-  manually with `\n` only when you must control the break.
-- **Single-line boxes are auto-widened** on conversion (+10% CJK / +5% Latin)
-  because PowerPoint re-lays-out text wider than Chromium measured — no need to
-  hand-pad single-line labels/titles. Multi-line boxes are untouched (still keep
-  ~10% slack there so wrapped text doesn't butt the edge).
+- html2pptx drops the typeface from CJK runs on purpose (any pinned family can render
+  blank somewhere), so a CJK title cannot be forced into a serif face natively — bake it
+  if the face matters. The runs are tagged zh-CN / zh-TW / ja-JP / ko-KR and a Chinese deck's
+  theme names Microsoft YaHei (Traditional: JhengHei) as its East Asian font, so bold Chinese
+  gets a real bold. Traditional is read from the text; `<html lang="zh-Hant">` (or zh-TW/HK) decides a deck whose text shows neither script.
+- Text boxes are widened automatically on conversion because PowerPoint lays text out
+  wider than Chromium: single-line boxes by ~22% (CJK) / ~16% (Latin), multi-line by
+  ~10% / ~6%. Don't hand-pad labels; do leave slack in multi-line boxes.
+- Slot capacity is measured (`layouts/capacity.json`) and enforced by deck-plan /
+  deck-build — trust their numbers over a character estimate.