rsc-universal 0.1.1

package/skills/presentations/references/slide-design.md

@@ -0,0 +1,261 @@
+# Slide Design — Communication Design, Visual System, Data Viz & Motion
+
+How a slide *communicates*, *looks*, and *moves*. The brand's visual system from `../design/SKILL.md`,
+re-tuned for the worst viewing conditions a deck faces: a projector, a bright room, the back row, a glance.
+Defer the token *system* (OKLCH palette, type pairing, spacing scale, motion personality) to `design`; this
+file is the deck-specific application. Good/Bad contrasts throughout.
+
+The first half is the **communication layer** — assertion-evidence structure, cognitive load, and what you
+*show* vs *say*. The second half is the **visual layer** — grid, type, color, data viz, motion. Get the
+communication right first; a beautiful slide that says nothing still fails.
+
+## Design first: audience, message, evidence
+
+Before a grid or a color, answer six planning questions. The deck serves the *audience's* understanding,
+not the presenter's comfort — that is the one principle every other rule descends from.
+
+1. **Who, specifically, is the audience?** Their existing knowledge sets the floor and ceiling for what you can assume.
+2. **What is the ONE main message?** One sentence they should remember a week later. If you can't write it, the deck has no spine.
+3. **What 3–5 supporting points** carry that message, and in what order do they build?
+4. **What evidence** (a number, a chart, a demo, an example) proves each point?
+5. **What action** should the audience take — the single call-to-action the deck climbs toward?
+6. **What is essential vs. expandable** under time pressure? Mark each point so a 30-minute deck collapses to 10 without losing the spine.
+
+This maps onto the deck arc and slide skeleton in `storytelling-and-decks.md`: the one message is the
+thesis, the supporting points are the act beats, the CTA is the closing ask. Plan here, storyboard there.
+
+## Assertion-evidence: the headline IS the slide
+
+The single highest-leverage structural move in the whole skill. **Each slide is one assertion (a complete
+sentence stating the point) plus the visual evidence that proves it** — never a topic label over a bullet list.
+
+- **Assertion** = the slide title, written as a full claim: *"User engagement rose 43% after the redesign"*, not *"Engagement"* or *"Key findings"*.
+- **Evidence** = the visual that backs it: the chart, the diagram, the screenshot, the one number. The body proves the headline; it does not repeat it.
+- If a slide's content is a bullet list, ask whether it should be a slide at all, or whether each bullet is really its own assertion-evidence slide.
+
+> **Good:**
+> ```text
+> Title:  "User engagement rose 43% after the redesign"
+> Body:   [line chart, pre→post, the post point highlighted]
+> ```
+> **Bad:**
+> ```text
+> Title:  "Key findings"
+> Body:   • Data shows an increase
+>         • Users engaged more
+>         • Revenue improved
+> ```
+
+## Cognitive load: one concept per slide
+
+Working memory is tiny and the audience is also listening to you. Every slide must pass one test: *"What
+is the ONE thing I want them to take from this?"* If there are two answers, it is two slides.
+
+- **One concept per slide.** A slide that needs two breaths to explain is two slides.
+- **Progressive disclosure** when a concept genuinely has sequential parts: show the initial state, then add element one with context, then element two building on it. Build order *is* the explanation — the audience looks where you are, not three bullets ahead. (This is the legitimate use of motion; see the Motion section.)
+- **Text density is a ceiling, not a target** (see the limits table below). Less on the slide means more attention on you.
+- **Code on technical slides:** always syntax-highlight; highlight the one critical line; build complex examples up; strip boilerplate that isn't the point.
+
+## Spoken vs. shown
+
+The slide and your mouth are two channels, not one. Redundancy wastes both. Reading the slide verbatim is
+the fastest way to lose a room — they read faster than you talk, finish, and tune out.
+
+| Put on the slide | Say out loud |
+| --- | --- |
+| The assertion (headline) | The elaboration and nuance |
+| The visual evidence | The context and the how |
+| The critical number | Its interpretation — why it matters |
+| The next step / CTA | The story that earns it |
+
+> **Good:** slide shows a chart and one claim; you narrate the backstory, the caveat, and the implication.
+> **Bad:** slide holds your full script in bullets; you read it aloud; the audience read it 20 seconds ago.
+
+## The core constraint: legible from the back of the room
+
+A web page is read at 50cm. A deck is read at 3–10 metres, often off a washed-out projector, sometimes for 5
+seconds before you click. Design for the *worst* case.
+
+- **Body text ≥ 24pt; ≥ 28–32pt for a conference talk.** Title 40–60pt. Caption ≥ 18pt. Never shrink text to fit — split the slide.
+- **~6 words per line, ~6 lines per slide** as a *ceiling*. Less is more. A keynote slide is often one line.
+- **Contrast ≥ 4.5:1** for text (the WCAG AA floor), higher is better on a projector. Check both your dark and light themes.
+- **One focal point per slide.** The eye should land in one place. If everything is bold, nothing is.
+- **Negative space is not wasted space** — it's what makes the one thing readable. Crowded slides read as filler.
+
+> **Good:** `OnboardingChurn-40%` in 54pt over a clean field, one supporting chart.
+> **Bad:** a 14pt 9-bullet slide the presenter reads aloud while the back row squints.
+
+## Layout grid for 16:9
+
+- **12-column grid**, consistent gutters, generous outer margin (~7% / ~0.9"). Define a **safe area**; keep all important content inside it so nothing clips on a projector or in PPTX export.
+- **One layout family**, reused: title, section divider, statement, content (headline + one visual), two-column (text|visual), full-bleed image, big-number, chart, quote, agenda/closing. Consistency reads as polish.
+- **Align to the grid.** Ragged left edges and floating boxes read as amateur. Snap to columns.
+- **Headline anchored top-left** (or centered for statements); visual occupies the focal zone; caption/source small and quiet at the bottom.
+
+## Type for projection
+
+- **Two type roles max:** a display face for headlines (personality) + a clean sans for body (legibility). Pull the exact pairing from the design tokens; don't introduce new fonts per deck.
+- **A real type scale** (e.g. display 60 / h1 44 / h2 32 / body 26 / caption 18) — steps, not arbitrary sizes. One scale across the whole deck.
+- **Weight for hierarchy**, not just size: bold the assertion, regular the support. Avoid all-caps for long strings (hard to read at distance); reserve it for short labels.
+- **Numbers are the message** in data decks — set big numbers in display size; the label small beside them.
+
+> **Good:** one display font for headlines, one sans for body, four sizes total.
+> **Bad:** four fonts, random sizes, italic + underline + color all at once.
+
+## Color: dark vs light decks, allocated for a room
+
+- **Dark deck** (dark surface, light text): better for dark rooms, big LED/LCD screens, on-stage; reduces glare; feels premium. Default for keynotes/launches.
+- **Light deck** (light surface, dark text): better for **printed handouts**, bright rooms, documents that double as leave-behinds, and projectors that wash out darks. Default for board/QBR leave-behinds.
+- **Build both from the same tokens** (a `.dark` / `.handout` class in Marp/Slidev; two masters in PPTX). Keep contrast ≥ 4.5:1 in each.
+- **60-30-10 allocation:** ~60% surface, ~30% ink/text, ~10% one accent for emphasis. The accent marks the *one* thing that matters per slide.
+- **Never encode meaning by color alone** (color-blind audiences, washed-out projectors): pair color with label, position, or shape.
+
+> **Good:** dark navy deck, off-white text, a single amber accent on the one number that matters.
+> **Bad:** five competing brand colors per slide, a gradient behind every headline, low-contrast gray-on-gray.
+
+## Data visualization: one chart, one point
+
+The single biggest credibility lever in a data deck. **Every chart makes exactly one point, and that point is
+the slide's headline.** If the chart needs a legend decoder ring, it's failing.
+
+- **Name the takeaway in the headline** ("Revenue 3×'d in four quarters"), then let the chart prove it.
+- **Pre-attentive emphasis:** gray out everything, highlight the **one** bar/line/point in the accent color. The eye goes there first.
+- **Strip the clutter:** no gridlines (or one faint baseline), no chart border, no redundant legend for a single series, minimal axis ticks. Maximize data-ink.
+- **Direct-label** lines/bars instead of forcing a legend lookup. Put the value at the end of the line.
+- **Honest axes:** start bars at zero; don't truncate to exaggerate; one axis, not dual axes; consistent scales across comparable slides.
+- **Pick the right chart:** trend over time → line; comparison across categories → bar; part-of-whole (≤ 4 parts) → a single bar or simple pie; correlation → scatter. **Never a 3-D chart, never a rainbow palette, never a pie with 8 slices.**
+- **Big-number slide** for a single hero metric: the number in display size, one line of context, source in the caption. Often more powerful than any chart.
+
+> **Good:** one line chart, four labeled points, the final point in accent, no gridlines, headline states the result.
+> **Bad:** a 3-D stacked bar with 7 series, a rainbow legend, dual y-axes, and a title that just says "Metrics".
+
+In Marp/Slidev, draw charts as SVG/chart-lib/images; in python-pptx use **native editable charts** (see
+`pptx-python.md`) so the data lives in the file.
+
+## Imagery
+
+- **Full-bleed and intentional**, not decorative stock. One strong image > three small clip-art ones.
+- **Always put a legibility scrim** (a dark/light gradient or solid overlay) behind text on a photo, or the text disappears against busy areas.
+- **Resolution matters at 4K** — use images large enough not to pixelate on a big projector; prefer SVG for logos, icons, and diagrams (infinite scale, tiny file).
+- **Consistent treatment** — one duotone/filter/crop style across the deck, from the brand imagery mood in the design tokens. Mixed photo styles read as a collage, not a brand.
+- **Diagrams over screenshots** when explaining a system; a labeled, simplified diagram beats a dense UI capture nobody can read from row 10.
+
+> **Good:** one full-bleed product shot, dark gradient scrim bottom-left, white headline over it.
+> **Bad:** three pixelated stock photos of "teamwork", logos at random sizes, a screenshot too small to read.
+
+## Motion & transitions — with restraint (a deck is not a video)
+
+Motion clarifies sequence and state change; it does not fill time. Applies to HTML pipelines (Marp/Slidev
+presenting) and to the build order you control in PPTX.
+
+- **One transition family** for the whole deck (e.g. a quick `fade` or a subtle slide), ≤ 300ms. Mixing transition types per slide is noise.
+- **Builds reveal one idea at a time.** Use `v-click` (Slidev) / fragment reveals to show bullets or chart series sequentially when sequence *is* the point — so the audience looks where you're talking, not ahead. Don't animate for the sake of it.
+- **Animate to explain, not to decorate:** a value changing, a step being added, an old→new comparison. If the motion doesn't carry meaning, cut it.
+- **Honor `prefers-reduced-motion`** in HTML decks — disable non-essential animation. (Irrelevant in the static PDF, which is why PDF is the safe leave-behind.)
+- **Pacing:** statement slides reset attention after a heavy data slide; don't run ten dense slides in a row.
+
+Borrowed-from-motion-tools ideas, applied to slides (NOT to turn this into a video):
+- **Progressive reveal** of a diagram (show the current state, then the optimized state) — clarifies a transformation.
+- **One highlighted element** entering/emphasizing — directs the eye, the slide equivalent of pre-attentive color.
+- **Spring/ease on the single transition** for a premium feel — subtle, fast, consistent.
+
+> **Good:** one fade transition deck-wide; a 3-step diagram builds one step per click; reduced-motion honored.
+> **Bad:** spin/zoom/bounce transitions varying per slide, every bullet flying in from a different edge, 1.5s animations that make the audience wait.
+
+## Content density limits (ceilings, not targets)
+
+| Slide type | Limit |
+| --- | --- |
+| Title | 1 headline + 1 subtitle (+ optional tagline) |
+| Statement | 1 line, big |
+| Content | 1 assertion headline + ≤ 3 support points / 1 visual |
+| Two-column | headline + text (≤ 4 points) \| one visual |
+| Big number | 1 metric (display size) + 1 line context + source |
+| Chart | 1 chart, 1 takeaway (named in headline), source caption |
+| Quote | 1 quote + attribution |
+| Image | 1 full-bleed image + scrim + ≤ 1 line of text |
+
+## Diagnostic rubric (score 1–5, aim ≥ 4 each)
+
+Use this to *evaluate* a deck — your own draft or one you're asked to review. Score each criterion 1
+(failing) to 5 (exemplary); anything below 4 is a fix before shipping. The four axes match the QA gate
+the `verify.sh` checklist points back to.
+
+**1. Audience-centered design** — *does every choice serve the audience?*
+
+| Criterion | 1–5 |
+| --- | --- |
+| Content matches the audience's knowledge level | |
+| One clear main message + a value proposition for *them* | |
+| Adaptable to time constraints (essential vs. expandable marked) | |
+| Structure/order aids understanding rather than the presenter's notes | |
+
+Red flags: presenter-focused not audience-focused; no read on existing knowledge.
+
+**2. Visual clarity** — *does the eye land on the point?*
+
+| Criterion | 1–5 |
+| --- | --- |
+| Assertion-evidence structure (claim + visual), not topic + bullets | |
+| Visual elements balance text; one focal point per slide | |
+| Visual hierarchy guides attention (weight, size, accent) | |
+| Consistent layouts/treatment; deliberate whitespace | |
+
+Red flags: bullet-point overuse; text-heavy slides; cluttered layouts.
+
+**3. Cognitive load** — *can working memory keep up while listening?*
+
+| Criterion | 1–5 |
+| --- | --- |
+| One key concept per slide | |
+| Text density under the ceiling; slide ≠ script | |
+| Animation judicious (disclosure/emphasis only) | |
+| Code formatted; critical line highlighted (if applicable) | |
+| Supporting detail accessible (appendix/notes), not crowding the slide | |
+
+Red flags: multiple complex concepts per slide; text competing with speech; animation overuse.
+
+**4. Accessibility** — *does it work for everyone, on any screen?*
+
+| Criterion | 1–5 |
+| --- | --- |
+| Works across display sizes; reads from the back row | |
+| Color contrast ≥ 4.5:1; meaning never color-only | |
+| Inclusive imagery and language | |
+| Font sizes appropriate (body ≥ 24pt; ≥ 28–32 for a talk) | |
+
+Red flags: poor contrast; too-small fonts; non-inclusive content.
+
+**Prioritize fixes:** (1) critical — blocks understanding, accessibility failure, message unclear;
+(2) important — cognitive load, visual inconsistency, structure; (3) polish — animation, custom styling.
+
+## Implementation checklist (build pass)
+
+- **Structure:** main message clear in the first 2 minutes; supporting points in logical order; essential-vs-expandable marked; structure aids understanding.
+- **Content:** assertion-evidence throughout; visual evidence backs each assertion; one concept per slide; code formatted and highlighted.
+- **Visual:** consistent palette (3–5 colors); typography hierarchy (2–3 roles); deliberate whitespace; everything aligned to the grid.
+- **Accessibility:** contrast verified; font sizes appropriate; alt text for key images; works across display sizes.
+
+## Communication anti-patterns
+
+These sit alongside the visual anti-patterns in `SKILL.md`; they fail at the *message* layer, before pixels.
+
+| Anti-pattern | Why it fails | Fix |
+| --- | --- | --- |
+| **Data dump** — every slide raw data/charts, no interpretation | Audiences can't analyze in real time; without a stated conclusion they're doing your job; most is forgotten | One insight per slide; state the conclusion, show the proof; they grasp the point before the data |
+| **Script reader** — slides hold the full spoken script as "bullets" | Audiences read faster than you talk, read ahead, then tune out | Slides show what you can't say; you say what you can't show |
+| **Template trap** — content poured into a generic template | Design should serve comprehension, not just look professional; generic template → generic communication | Start from the communication need: what structure helps *this* audience understand *this* content? |
+| **Animation circus** — transitions/builds/effects everywhere | Animation is attention; when everything animates, nothing stands out | Animate only for progressive disclosure or emphasis; default to none |
+| **Bullet-point disease** — list after list as the default | Bullets are for documents; equal weight for unequal ideas; passive reading not active viewing | Assertion-evidence; if you truly need a list, question whether it earns a slide |
+
+## Slide-design QA (the visual subset)
+
+- [ ] Body ≥ 24pt (≥ 28–32 for a talk); reads at 3 metres; contrast ≥ 4.5:1.
+- [ ] One focal point per slide; ≤ ~6 lines; generous negative space.
+- [ ] Aligned to the grid; consistent safe-area; nothing clips on export.
+- [ ] Two type roles, one scale, weight-for-hierarchy; no font soup.
+- [ ] Colors from tokens, 60-30-10, one accent marks the one thing; meaning never color-only.
+- [ ] Each chart makes one point named in the headline; decluttered; honest axes; no 3-D/rainbow.
+- [ ] Imagery full-bleed + scrim, high-res, consistent treatment; SVG for logos/diagrams.
+- [ ] One transition family ≤ 300ms; builds reveal meaning; reduced-motion honored (HTML).
+- [ ] Dark/light variant chosen for the room (dark = stage, light = print/handout).

package/skills/presentations/references/storytelling-and-decks.md

@@ -0,0 +1,150 @@
+# Storytelling & Deck Structure — Arcs + Slide-by-Slide Skeletons
+
+The deck is an argument, not a document. Every deck proves **one thesis**; every slide advances it by
+exactly one step. This file holds the narrative frameworks, the proven arc per deck type, and concrete
+slide-by-slide skeletons you can fill from the brand study. The visual layout of each slide → `slide-design.md`;
+the words → `../marketing/SKILL.md`.
+
+## First principles
+
+- **One thesis.** Write the single sentence the whole deck must make the audience believe. If a slide doesn't serve it, cut the slide. Tape the thesis to the top of the skeleton.
+- **One idea per slide.** A slide is a single assertion + its proof. Two ideas = two slides.
+- **Assertion headlines.** Title every slide with the point ("Onboarding v2 cut churn 40%"), never the topic ("Churn"). A reader skimming only the headlines should get the full argument.
+- **Tension → resolution.** Decks persuade by opening a gap (problem, stakes, "why now") and closing it (your solution, proof, ask). No tension = no attention.
+- **The Rule of the Spine:** title slides → one-liners that, read in sequence, ARE the pitch. Build the spine first; decorate second.
+- **Pacing.** Vary slide "weight": a heavy data slide earns a light statement slide. Big-number and full-bleed statement slides reset attention. Aim ~1–2 min/slide when presenting.
+- **Cut to the ask.** Every deck ends by telling the audience exactly what to do next, with one primary CTA.
+
+## Narrative frameworks (pick one as the spine)
+
+| Framework | Shape | Best for |
+| --- | --- | --- |
+| **Problem → Solution → Proof → Ask** | Classic persuasion | Pitch, sales, investor |
+| **SCR (Situation → Complication → Resolution)** | McKinsey "Pyramid" | Board, QBR, exec memos |
+| **Hero's journey (audience = hero)** | Status quo → call → struggle → guide (you) → win | Keynote, brand/vision |
+| **Before → After → Bridge** | Pain now → world with you → how to get there | Sales, product launch |
+| **What / So What / Now What** | Fact → meaning → action | QBR, research readout, internal update |
+| **PAS (Problem → Agitate → Solve)** | Sharpen the pain before relieving it | Cold sales, demand-gen decks |
+| **STAR moment** | Build to one Something They'll Always Remember | Keynote, launch reveal |
+
+Whichever you pick, the *micro*-structure of each content slide is the same: **assertion headline →
+single supporting visual/point → (talk track in notes)**.
+
+## Deck arc by type (slide-by-slide skeletons)
+
+Each skeleton is a *starting* spine — reorder/merge for the specific audience, but keep the tension→resolution.
+Numbers in brackets are typical slide counts.
+
+### Pitch / Investor deck [10–15 core, + appendix]
+
+The fundraising standard (problem-first, traction-forward). Mirrors what investors expect to see.
+
+1. **Title / company one-liner** — name + the single sentence: "We help [who] [outcome] by [mechanism]."
+2. **The problem** — a real, expensive, urgent pain, in the customer's words. Make it ache.
+3. **Why now** — the shift (tech/regulatory/behavioral) that makes this possible/inevitable today.
+4. **The solution** — your wedge, one sentence + one visual. What you do, simply.
+5. **Product / demo** — show it working; a screenshot/flow, not a feature list.
+6. **Market size** — TAM/SAM/SOM with *stated assumptions* (bottom-up beats a giant top-down circle).
+7. **Business model** — how you make money; pricing; unit economics if strong.
+8. **Traction** — the slide investors lean in for: growth chart, revenue, retention, logos. Real numbers.
+9. **Competition / differentiation** — a 2×2 or feature matrix; the one thing only you can say.
+10. **Go-to-market** — how you acquire customers repeatably and cheaply.
+11. **Team** — why *this* team wins (relevant, earned secrets), not headshots-as-decoration.
+12. **The ask** — raise size, instrument, and use of funds → milestones it buys.
+13. **Vision / closing** — the big "if this works" world. End on ambition.
+14. **Appendix** — financials, cohort detail, FAQs, the model. Defend, don't front-load.
+
+**Golden rule (from investor materials): every number agrees across deck, one-pager, and model.** Build a
+single source of truth (traction, pricing, raise, use of funds, team titles, milestones) and cross-check
+every figure before delivery. A conflicting number is a hard stop. Mark anything aspirational `[[NEEDS PROOF]]`.
+
+### Sales deck [8–12]
+
+Customer is the hero; you are the guide. Lead with their world, not your company.
+
+1. **Hook / their world today** — name the customer's status quo and its hidden cost.
+2. **The problem & its stakes** — what it costs them to keep doing it this way (quantify).
+3. **The shift / "why change now"** — what makes the old way untenable.
+4. **The promised land** — the after-state; the outcome they actually want.
+5. **Your solution as the bridge** — how you get them there (mechanism, one visual).
+6. **Proof it works** — case study with a hard number, logos, a quote with a metric.
+7. **How it works** — the 3-step "so it's easy to adopt" path; de-risk the switch.
+8. **Pricing / packages** — clear, anchored; the recommended option highlighted.
+9. **Objection handling** — the top 2–3 "yeah but…" answered head-on.
+10. **The ask / next step** — one CTA: "book the pilot", "start the trial". Make it small and clear.
+
+### Product launch / announcement [6–10]
+
+1. **The change** — what's new, in one line. Lead with the headline benefit, not the feature name.
+2. **Why it matters** — the problem it removes / the leverage it adds.
+3. **The reveal** — show it (full-bleed product shot / short loop).
+4. **How it works** — 3 beats, each one idea.
+5. **Proof / early results** — beta numbers, design-partner quotes.
+6. **Availability & pricing** — when, where, how much.
+7. **Call to action** — "get access", "upgrade", "join the waitlist".
+
+### Keynote / conference talk [variable, statement-heavy]
+
+Maximize memorability, minimize on-slide text. Slides are punctuation for your voice.
+
+1. **Cold open / provocation** — a question, a surprising stat, a story. Earn attention in 30s.
+2. **The big idea (thesis)** — one sentence the talk will prove.
+3–N. **Acts (3 is classic):** each act = setup → tension → turn, built from statement slides + one image/chart each. One STAR moment per talk (the line/visual they'll quote).
+- **Recap** — the one thing to remember.
+- **Close / call to think or act** — what changes Monday morning.
+
+Keynote slides skew to *one statement or one image* per slide; the argument lives in your delivery, the
+slide reinforces. Big type, lots of negative space, no bullet walls.
+
+### Board / QBR / exec review [10–20, dense-but-scannable]
+
+Executives skim; lead with the answer (SCR / Pyramid Principle: conclusion first, then support).
+
+1. **Executive summary** — the 3 things the room must know, as headlines. (If they read one slide, this is it.)
+2. **Scorecard** — KPIs vs target/last-period; green/amber/red, honest.
+3. **What's working** — wins with numbers.
+4. **What's not** — risks/misses, owned plainly, with the plan.
+5. **Deep-dives** — one per priority topic; each is *What / So What / Now What*.
+6. **Asks / decisions needed** — explicit decisions you want from the board, each with a recommendation.
+7. **Appendix** — the supporting detail you'll pull up if asked.
+
+Board decks tolerate more text than a keynote because they double as a read-ahead leave-behind. Even so:
+assertion headlines, one idea per slide, every number sourced.
+
+## Presenter vs leave-behind (two variants, one narrative)
+
+The same deck serves two jobs badly unless you split them. Decide which you're shipping; build both when needed.
+
+| | **Presenter deck** | **Leave-behind deck** |
+| --- | --- | --- |
+| When | You're in the room narrating | Sent as PDF; read alone, unnarrated |
+| On-slide text | Minimal — headline + one visual + 0–3 points | Self-contained — enough to follow without you |
+| Where the argument lives | In your mouth + the speaker notes | On the slides themselves + appendix |
+| Risk if wrong | Wall-of-text presenter slide → you read aloud, audience tunes out | Sparse leave-behind → reader can't reconstruct the point |
+| Build tactic | Write the full talk track into **speaker notes**; keep slides sparse | Promote key notes onto the slide; expand the appendix |
+
+Practical move: build the **presenter** deck first (sparse + rich notes), then derive the **leave-behind** by
+promoting notes onto slides and adding context. In Markdown pipelines, speaker notes (`<!-- notes -->` /
+`notes:`) export to PDF presenter notes and to PPTX notes — write the talk track there, not on the slide.
+
+## Storyboarding before you build
+
+1. **Write the thesis** (one sentence).
+2. **Pick the arc** (table above).
+3. **Outline assertion headlines only** — one line per slide. Read them top-to-bottom: do they tell the story alone? If not, the structure is broken — fix it before any pixels.
+4. **Attach the proof** to each headline (the chart, the quote, the screenshot, the number + its source).
+5. **Mark slide weight** (heavy data / light statement) and check pacing.
+6. **Get the skeleton approved** before designing. Re-laying-out a wrong structure is the most expensive mistake.
+7. Only then: theme + layout (`slide-design.md`) and build (`markdown-decks.md` or `pptx-python.md`).
+
+## Common storytelling failures (and the fix)
+
+| Failure | Fix |
+| --- | --- |
+| Company-first ("About us" slide 1) | Audience-first; their problem opens the deck |
+| Feature tour with no narrative | Pick an arc; features become proof of the thesis |
+| Every slide same weight → monotone | Alternate heavy/light; add statement slides to breathe |
+| No tension → no attention | Open a real gap (problem/stakes/why-now) before resolving it |
+| Burying the ask | One explicit CTA near the end; in board decks, decisions stated up front |
+| Numbers that don't agree across assets | One source of truth; cross-check every figure (investor golden rule) |
+| Reading slides aloud | Slide = visual; talk track in notes; never duplicate |

package/skills/presentations/scripts/verify.sh

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+#
+# verify.sh — deck build/lint gate for the `presentations` skill.
+#
+# WHAT IT DOES (read-only; detect-or-skip every tool)
+#   1. python-pptx: if a build script exists (build_deck.py / a *.py that imports pptx),
+#      check `python -c "import pptx"` works.
+#   2. Marp: if marp-cli is reachable AND a Marp deck (`marp: true`) exists, print the
+#      version and do a DRY PDF export of one sample deck to a temp file.
+#   3. Slidev: if a Slidev deck (slides.md with a slidev marker) exists, report whether the
+#      CLI is reachable.
+#   4. markdownlint of deck sources, if markdownlint is available.
+#   5. Static deck-hygiene greps (warn-only): tiny font sizes, 3-D charts, ban-list words.
+#
+# Everything is WARN-by-default; missing tools are SKIPPED with a yellow notice, never failed.
+# Use --strict to turn warnings into failures (CI gate).
+#
+# HOW TO RUN (inside YOUR deck project, not the skills repo)
+#   ./verify.sh
+#   ./verify.sh --dir ./decks
+#   ./verify.sh --strict
+#
+# EXIT CODES
+#   0  no real failures (warnings allowed unless --strict)
+#   1  a real failure (e.g. import pptx fails, marp dry-export fails), or --strict with any warning
+#   2  bad usage
+
+set -euo pipefail
+
+# --- portability: runs on stock macOS bash 3.2 -----------------------------
+# Avoids bash 4+ features: no `mapfile`/`readarray`, no associative arrays, no
+# unguarded `${arr[@]}` under set -u. Scalar counters + `read` loops only.
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (any version >= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+# --- color helpers (no escape codes when not a TTY) ------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() {
+  sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse -------------------------------------------------------------
+DIR="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir)    DIR="${2:?--dir needs a value}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -d "$DIR" ]; then
+  printf '%sNo such directory: %s%s\n' "$RED" "$DIR" "$NC"; exit 2
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Find first file matching a grep pattern, or empty. Prints one path.
+first_with() {
+  # $1 = file glob (find -name), $2 = grep pattern
+  find "$DIR" -type f -name "$1" 2>/dev/null | while IFS= read -r f; do
+    if grep -lqE "$2" "$f" 2>/dev/null; then printf '%s\n' "$f"; break; fi
+  done | head -n 1
+}
+
+# ---------------------------------------------------------------------------
+# 1. python-pptx — only if a build script that imports pptx exists
+# ---------------------------------------------------------------------------
+check_pptx() {
+  local script
+  script="$(first_with '*.py' 'import +pptx|from +pptx')"
+  if [ -z "$script" ]; then
+    skip "no python-pptx build script found (no *.py importing pptx) — skipping import check"
+    return
+  fi
+  local py=""
+  if have python3; then py=python3; elif have python; then py=python; fi
+  if [ -z "$py" ]; then
+    skip "python not found — cannot verify python-pptx for $script"
+    return
+  fi
+  if "$py" -c 'import pptx' >/dev/null 2>&1; then
+    local ver
+    ver="$("$py" -c 'import pptx;print(pptx.__version__)' 2>/dev/null || echo '?')"
+    ok "python-pptx importable (v$ver); build script: $script"
+  else
+    fail "python-pptx build script present ($script) but \`import pptx\` fails — pip install python-pptx"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# 2. Marp — only if a Marp deck exists; print version + DRY pdf export
+# ---------------------------------------------------------------------------
+MARP_CMD=""
+marp_cmd() {
+  if have marp; then MARP_CMD="marp"; return 0; fi
+  if have npx;  then MARP_CMD="npx --no-install @marp-team/marp-cli"; return 0; fi
+  return 1
+}
+check_marp() {
+  local deck
+  deck="$(first_with '*.md' '^marp: *true')"
+  if [ -z "$deck" ]; then
+    skip "no Marp deck found (no markdown with 'marp: true') — skipping Marp checks"
+    return
+  fi
+  if ! marp_cmd; then
+    skip "marp-cli not found (install @marp-team/marp-cli or have npx) — found Marp deck: $deck"
+    return
+  fi
+  local ver
+  ver="$($MARP_CMD --version 2>/dev/null | head -n 1 || echo '?')"
+  ok "marp-cli available ($ver); Marp deck: $deck"
+
+  local tmp out
+  tmp="$(mktemp -d)"; out="$tmp/_verify.pdf"
+  printf 'Dry PDF export of %s ...\n' "$deck"
+  if $MARP_CMD "$deck" --pdf -o "$out" >/dev/null 2>&1 && [ -s "$out" ]; then
+    ok "marp --pdf dry export succeeded ($deck)"
+  else
+    warn "marp --pdf dry export did not produce a PDF for $deck (Chromium/Chrome installed? remote fonts reachable?)"
+  fi
+  rm -rf "$tmp"
+}
+
+# ---------------------------------------------------------------------------
+# 3. Slidev — report presence + CLI reachability (no full export in CI)
+# ---------------------------------------------------------------------------
+check_slidev() {
+  local deck
+  deck="$(first_with 'slides.md' 'layout:|^---|theme:')"
+  [ -z "$deck" ] && deck="$(first_with '*.md' '@slidev|slidev')"
+  if [ -z "$deck" ]; then
+    skip "no Slidev deck found — skipping Slidev checks"
+    return
+  fi
+  if have slidev; then
+    ok "slidev CLI on PATH; Slidev deck: $deck"
+  elif have npx; then
+    ok "slidev runnable via npx; Slidev deck: $deck (export needs playwright-chromium installed)"
+  else
+    skip "slidev CLI not found (install @slidev/cli) — found Slidev deck: $deck"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# 4. markdownlint of deck sources
+# ---------------------------------------------------------------------------
+check_markdownlint() {
+  local linter=""
+  if have markdownlint; then linter="markdownlint"
+  elif have markdownlint-cli2; then linter="markdownlint-cli2"
+  else
+    skip "markdownlint not found — skipping deck source lint"
+    return
+  fi
+  local any
+  any="$(find "$DIR" -type f -name '*.md' 2>/dev/null | head -n 1)"
+  if [ -z "$any" ]; then
+    skip "no markdown deck sources to lint"
+    return
+  fi
+  if find "$DIR" -type f -name '*.md' -print0 2>/dev/null | xargs -0 "$linter" >/dev/null 2>&1; then
+    ok "markdownlint clean on deck sources"
+  else
+    warn "markdownlint reported issues in deck sources (run '$linter \"$DIR\"/**/*.md' for detail)"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# 5. Static deck-hygiene greps (warn-only)
+# ---------------------------------------------------------------------------
+search() {
+  if have rg; then rg -n --no-heading "$@" "$DIR" 2>/dev/null
+  else grep -rnE "${*: -1}" "$DIR" 2>/dev/null; fi
+}
+static_checks() {
+  local hits
+
+  # tiny font sizes in themes/build scripts (legibility floor ~24pt body)
+  hits="$(search 'font-size: *([1-9]|1[0-9]|2[0-3])px|Pt\(([1-9]|1[0-9]|2[0-3])\)' 2>/dev/null || true)"
+  if [ -n "$hits" ]; then
+    warn "possible sub-24 font sizes (legibility from the back of the room):"
+    printf '%s\n' "$hits" | head -n 5
+  fi
+
+  # 3-D / rainbow chart smells
+  hits="$(search '_3D|THREE_D|3-?D (pie|chart|bar)' 2>/dev/null || true)"
+  if [ -n "$hits" ]; then
+    warn "3-D chart usage found (banned — use flat charts, one highlighted series):"
+    printf '%s\n' "$hits" | head -n 5
+  fi
+
+  # ban-list marketing words in deck copy
+  hits="$(search 'revolutionary|game-?changer|cutting-edge|supercharge|seamless|unlock|world-class' 2>/dev/null \
+          | grep -iE '\.(md|mdx|py|html)' || true)"
+  if [ -n "$hits" ]; then
+    warn "ban-list marketing words in deck copy (replace with a number / mechanism):"
+    printf '%s\n' "$hits" | head -n 5
+  fi
+}
+
+# --- run -------------------------------------------------------------------
+check_pptx
+check_marp
+check_slidev
+check_markdownlint
+static_checks
+
+cat <<'EOF'
+
+Manual deck QA (mechanical checks above don't cover these):
+  [ ] Brand study located, complete, and cited.
+  [ ] One idea per slide; assertion headlines, not topic labels.
+  [ ] Body >= 24pt (>= 28-32 for a talk); contrast >= 4.5:1; reads at 3 metres.
+  [ ] Colors / type / spacing from design tokens, not per-slide hex.
+  [ ] Deliberate arc + single thesis; opens with a hook, ends with one ask.
+  [ ] Every number sourced; gaps marked [[NEEDS PROOF]]; none invented.
+  [ ] Each chart makes one point named in the headline; no 3-D/rainbow/dual-axis.
+  [ ] Motion = one family <= 300ms; reduced-motion honored (HTML); builds reveal meaning.
+  [ ] 16:9; PDF vector with fonts embedded (pdffonts -> emb yes); PPTX opens clean.
+  [ ] PPTX editability matches the promise (python-pptx if "editable", not flattened images).
+
+  Score the deck on the 1-5 design rubric (>= 4 each before shipping) ->
+  references/slide-design.md "Diagnostic rubric":
+  [ ] Audience-centered design (one main message, right knowledge level, time-flexible).
+  [ ] Visual clarity (assertion-evidence; visuals balance text; one focal point).
+  [ ] Cognitive load (one concept/slide; spoken-vs-shown split; restrained motion).
+  [ ] Accessibility (contrast, font size, inclusive imagery/language, scales across displays).
+EOF
+
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0