studiograph 1.3.48-next.89 → 1.3.48-next.90

package/dist/agent/skills/create-deck/content-guide.md

@@ -0,0 +1,238 @@
+# Content Guide — Content Limits & Best Practices
+
+Every measurement here comes from the actual slide dimensions (1920×1080px). Content limits are approximate and depend on the configured font. Structural limits (max items, columns) are fixed by the layout.
+
+## General Rules
+
+1. **Less text, more slides.** If you're hitting the limit, split into two slides.
+2. **Slides are billboards, not documents.** The audience reads in 3-5 seconds.
+3. **Never fabricate image paths.** Only reference images that exist in the deck's `images/` folder.
+4. **One idea per slide.** If you need "and" between concepts, it's two slides.
+5. **Front-load meaning.** The first 5 words should carry the point.
+6. **Use proper typography.** Always use curly quotes (" " ' ') and apostrophes ('), never straight/ASCII quotes (" ') or inch/foot marks.
+
+---
+
+## Cover
+- **Title (H1):** **2-3 words per line**, single line preferred. Two words is ideal.
+- **Subtitle (H2):** **3-5 words per line**, single line. "Phase 2: Design Concepts" is the model.
+- **Theme:** Follows the deck theme (light by default). Override with `<!-- theme: dark -->` or `<!-- theme: light -->`.
+- **Common mistake:** Long project names. Abbreviate or use a short form.
+
+## Schedule
+- **Phase names:** **1-2 words** each. Appears in the cascade boxes.
+- **Phase items:** 2-4 items per phase, **3-4 words** each.
+- **Total phases:** 3-6. More than 6 gets cramped.
+
+## Introductions
+- **Names:** Full name, **2-3 words**.
+- **Titles:** **3-4 words**. Keep to one line.
+- **People per column:** 3-6. More than 6 overflows.
+- **Columns:** 2 (client + Schema). Don't add more.
+
+## Agenda
+- **Items:** 4-7 items. Fewer feels thin, more gets cramped.
+- **Item text:** **3-4 words** each. These render large — keep them short.
+- **Active highlight:** Use `<!-- active: N -->` to mark current section during the presentation.
+- **Items should match section titles** that follow in the deck.
+
+## Section
+- **Title:** **1-3 words per line**, 1-2 lines total.
+- **These are wayfinding, not content.** "Research Recap" not "Summary of Our Research Findings."
+- **Theme:** Dark by default. No footer. Deck title appears as header label.
+
+## Statement
+- **Label (H1):** **2-3 words**. "Key Insight", "Our Approach", etc.
+- **Body (blockquote):** **1-2 lines** (~15-20 words). One paragraph only.
+- **This is your billboard slide.** If it needs more than two lines, it belongs on text-body.
+- **Common mistake:** Writing a paragraph. Distill to one punchy sentence.
+
+## Pullquote
+- **Label (H1):** **2-3 words**.
+- **Quote (blockquote):** **2-3 lines** (~25-35 words). Smart quotes added automatically by CSS — **do NOT add quotation marks in the markdown**. Write `> The text here` not `> "The text here"`.
+- **Attribution:** **3-5 words**. Format: "— Name, Title" or "— Name, Organization"
+- **Gap between quote and attribution:** 20px (automatic).
+
+## Statement Light
+- Same limits as **Statement**. Uses light (300) weight; bold maps to semibold (600).
+- Use for conceptual or reflective content — softer feel than standard statement.
+
+## Text-Body
+- **Label (H1):** **3-4 words**.
+- **Body:** 2-5 bullet points, each **1-2 lines** (~12-15 words per bullet).
+- **Or** 1-2 paragraphs, **4-6 lines** total.
+- **Body width:** Constrained to ~1500px. Long lines wrap.
+- **Common mistake:** Treating this as a document slide. Keep it scannable.
+
+## Text-Body Light
+- Same limits as **Text-Body**. Uses light (300) weight; bold maps to semibold (600).
+- Ideal for **label → description** patterns and structured explanations.
+
+## List / Next-Steps
+- **Title (H1):** **2-3 words**.
+- **Items:** 3-6 bullet points, each **1-2 lines** (~8-10 words per item). Vertically centered.
+- **For next-steps:** Include dates or owners. "Review concepts with stakeholders by Friday" not "Review concepts."
+- **Common mistake:** Too many items. 7+ loses the audience.
+
+## Columns
+- **Title (H1):** **3-4 words**.
+- **Section labels (H2):** **1-2 words**. Rendered as uppercase labels.
+- **Body per column:** **3-5 lines** (~30-40 words per column).
+- **Column count:** 2 or 3 per row (auto-detected, override with `<!-- columns: 2 -->`).
+- **Total sections:** 2-6. More than 3 wraps to next row.
+- **Common mistake:** Uneven columns. Aim for similar body lengths across columns.
+
+## Table
+- **Title (H1):** **2-3 words**.
+- **Columns:** Max **5**. More gets too narrow.
+- **Rows:** Max **6-8** depending on cell content.
+- **Column headers:** **1-2 words**.
+- **Row headers (first column):** **1-3 words**.
+- **Cell content:** **2-3 words**. Brief phrases, not sentences.
+- **Common mistake:** Trying to fit a spreadsheet. Tables are for comparison, not data dumps.
+
+## Blank
+- No content. Used as a breathing slide or for freestanding images dropped in later.
+- Has footer.
+
+## Stats
+- **Title (H1):** **2-3 words**.
+- **Stat number:** Max **6 characters** including units. "129M", "4.2s", "89%". Renders very large.
+- **Description:** **5-8 words**. Appears below the number.
+- **Count:** 2-3 stats in a row, or 4-6 in a grid (auto-detected).
+- **Format:** `- **73%** — Description text here`
+- **Common mistake:** Long numbers. "$1,234,567" doesn't fit. Round to "$1.2M".
+
+## Framework
+- **Title (H1):** **3-4 words**.
+- **Objective:** **1-2 lines** (~12-15 words). Single sentence after "Objective:" prefix.
+- **Pillars:** 3-5. Each pillar is an H2 with a short name.
+- **Pillar names:** **1-2 words**. "Clarity", "Speed", "Trust".
+- **Principles per pillar:** 2-4 bullet points.
+- **Principle format:** `- **Bold label** — Description` **6-8 words** total.
+- **Configurable labels:** `Objective Label:` and `Principles Label:` in markdown.
+- **Common mistake:** Too many pillars or principles. 5 pillars × 4 principles = 20 items = information overload.
+
+## Image-Browser
+- **Image:** One screenshot in browser chrome frame.
+- **Caption:** **5-7 words**. Renders as a pill overlay. `Caption: Description`
+- **No footer.** The image is the slide.
+
+## Image-Browser-2up
+- **Images:** Exactly 2 screenshots side by side.
+- **Per-image captions:** **4-6 words** each. Each image gets its own `Caption:` line directly below it.
+- **Use matching aspect ratios** for both images (e.g. both 16:9 or both 4:3). Mismatched ratios look uneven.
+- **Chrome:** Default shows browser chrome. Use `<!-- chrome: none -->` for photos/artwork.
+- **Has footer.** Good for before/after or comparison.
+
+## Image-Browser-6up
+- **Images:** Exactly 6 screenshots in a 3×2 grid.
+- **Per-image captions:** **3-4 words** each.
+- **Has footer.** Good for showing a flow or feature overview.
+
+## Image-Full / Video-Full
+- **Image:** One image covering the entire slide. Uses `object-fit: contain`.
+- **Video:** Also supports `.mp4`, `.webm`, `.mov`, `.ogg` — auto-detected from file extension.
+- **Portrait images supported:** centered on slide with black bars on sides. No need to crop to 16:9.
+- **Caption:** **5-7 words**. Pill overlay at bottom-left.
+- **Video directive:** `<!-- video: autoplay loop muted controls -->` (default: `autoplay muted`).
+- **No footer.** Let the image/video breathe.
+
+## Image-Split
+- **Image:** Left side, cropped to 960×1080.
+- **Title (H1):** **2-3 words**. Right side.
+- **Body:** **3-5 lines** (~30-40 words). Right side below title.
+- **No footer.**
+
+## Image-Split-Right
+- **Image:** Right side, cropped to 960×1080.
+- **Title (H1):** **2-3 words**. Left side.
+- **Body:** **3-5 lines** (~30-40 words). Left side below title.
+- **Has footer.** (Unlike image-split.)
+
+## Image-Bullets
+- **Image:** Screenshot in browser chrome.
+- **Caption:** **5-7 words**. Pill overlay.
+- **Bullets:** 2-4 items. Format: `- **Bold label** — Description`
+- **Bullet text:** **1-2 lines** (~8-10 words) per item.
+- **No footer.**
+
+## Image-Mobile-3up
+- **Images:** Exactly 3 phone screens.
+- **Caption:** **5-7 words**. Pill overlay.
+- **No footer.**
+
+## Image-Device-Pair
+- **Images:** Exactly 2 — desktop + mobile.
+- **Caption:** **5-7 words**. Pill overlay.
+- **No footer.**
+
+## Image-Grid-2x2
+- **Images:** Exactly 4 images in a 2×2 grid.
+- **Caption:** **5-7 words**. Pill overlay.
+- **No footer.**
+
+## Diagram
+- **SVG viewBox:** 1600×800 recommended.
+- **Colors:** Use Schema palette only: `#111111`, `#e9e9e9`, `#696969`, `#c9c9c9`.
+- **Keep it simple.** Boxes, lines, arrows, text labels. Not illustrations.
+- **Label text:** **1-3 words** per label. 16-24px font size in SVG.
+
+## End
+- **Fixed text:** "Thank you" — no customization.
+- **Left-aligned** at x=97, y=442. 185px light weight.
+
+---
+
+## Deck-Level Limits
+
+- **Total slides:** 15-30 is the sweet spot. Under 10 feels thin, over 40 loses the audience.
+- **Content slides per section:** 3-5. More means the section should split.
+- **Consecutive text slides:** Never more than 2. Follow text with an image or data slide.
+- **Image slides need real files.** Don't generate slides referencing images that don't exist.
+
+## Diagram — Concentric Circles
+
+- **Categories:** 2–5 items.
+- **Label length:** **1-3 words** for centered and bottom variants. **One word only** for eccentric variant (narrow horizontal zones).
+- **Title:** **2-3 words**.
+
+## Diagram — Venn
+
+- **Sets:** 3–6 items.
+- **Label length:** **1-2 words** — labels sit outside circles (4-6 set) or inside (3-set). Keep short for clean layout.
+- **Title:** **2-3 words**.
+
+## Diagram — Matrix (2×2)
+
+- **Axes:** 4 labels (top, right, bottom, left) via bullet list with directional prefix.
+- **Entities:** Table with `| Entity | X | Y |` header. X: 0=left, 1=right. Y: 0=bottom, 1=top.
+- **Variant:** `<!-- diagram: trend -->` adds a diagonal arrow from bottom-left to top-right.
+- **Axis label length:** **1-2 words**.
+- **Entity name length:** **1-2 words** — labels sit next to small dots.
+- **Entity count:** 3–8 recommended. More gets cluttered.
+
+## Diagram — Pyramid
+
+- **Tiers:** 2–5 items.
+- **Variants:** `up` (default, hierarchy), `down` (funnel/inverted).
+- **Label length:** **1-3 words** — labels sit inside the triangle and must not look disproportionate to their tier width. Shorter is better for the top tier (narrowest).
+- **Title:** **2-3 words**.
+
+## Diagram — Sitemap
+
+- **Structure:** Nested bullet list, 3 levels max (root → sections → pages).
+- **Sections:** Min **2**, max **5** — center-clustered with consistent spacing.
+- **Pages per section:** Max **6** — stacked vertically. More will clip the footer.
+- **Node label length:** **1-3 words** — nodes are 225px wide; longer labels get clipped.
+- **Root node:** Single item at level 1 (e.g., "Home").
+- **Sections without pages are fine** (rendered as leaf nodes with no children).
+
+## Theme Directive
+
+The default deck theme is `light`. Set `theme: dark` in frontmatter for a dark deck. Override per-slide with `<!-- theme: dark -->` or `<!-- theme: light -->`.
+
+- Light (default): bg `#e9e9e9`, text `#111111`, muted `#696969`
+- Dark: bg `#111111`, text `#e9e9e9`, muted `#696969`
+
+Use theme overrides sparingly for emphasis or variety. Don't alternate every slide.

package/dist/agent/skills/create-deck/deck-cadence.md

@@ -0,0 +1,105 @@
+# Deck Cadence — Structure Patterns
+
+## The Pulse
+
+Every deck alternates between **orientation** slides (where are we?) and **content** slides (what are we showing?). The rhythm is:
+
+```
+ORIENT → CONTENT → CONTENT → CONTENT → ORIENT → CONTENT → ...
+```
+
+Orient slides: cover, agenda, section, divider, next-steps, end
+Content slides: statement, text-body, stats, image-*, diagram, framework, table, pullquote
+
+**Never put two orient slides back-to-back** (except cover → agenda, which is standard).
+**Never put more than 4 content slides in a row** without an orient slide.
+
+## Deck Templates
+
+### Client Kickoff (15-20 slides)
+```
+cover → agenda → 
+  section "Introductions" → introductions →
+  section "Project Overview" → statement (vision) → text-body (scope) → schedule →
+  section "Process" → framework (approach) → stats (benchmarks) →
+  section "Next Steps" → next-steps →
+end
+```
+
+### Design Review (20-30 slides)
+```
+cover → agenda →
+  section "Recap" → statement (key finding) → stats (research data) →
+  section "Direction" → text-body (strategy) → diagram (system) →
+  section "Concepts" → image-browser → image-bullets → image-browser-2up → 
+    image-mobile-3up → image-device-pair →
+  section "System" → image-split → image-browser-6up →
+  section "Next Steps" → next-steps →
+end
+```
+
+### Strategy Presentation (15-25 slides)
+```
+cover → agenda →
+  section "Context" → statement (problem) → stats (evidence) → pullquote (stakeholder) →
+  section "Framework" → framework → text-body (pillar detail) → text-body (pillar detail) →
+  section "Roadmap" → schedule → next-steps →
+end
+```
+
+### Project Update (10-15 slides)
+```
+cover → agenda →
+  section "Progress" → stats (KPIs) → image-browser (current state) →
+  section "Decisions" → statement (key decision) → image-browser-2up (options) →
+  section "Next Steps" → next-steps →
+end
+```
+
+### Pitch / Capabilities (20-25 slides)
+```
+cover → agenda →
+  section "Who We Are" → statement (positioning) → two-column (team + approach) →
+  section "How We Work" → framework (process) → schedule (typical timeline) →
+  section "Work" → image-full → image-browser → image-split →
+    image-full → image-browser-6up →
+  section "Next Steps" → next-steps →
+end
+```
+
+## Slide Sequencing Rules
+
+### After a Section slide, start with the "why"
+- section → **statement** → supporting slides
+- The statement sets up the narrative. Supporting slides prove it.
+
+### Image slides follow a zoom pattern
+- Wide shot first (image-full or image-browser)
+- Then details (image-bullets, image-split)
+- Then variations (image-browser-2up, image-mobile-3up)
+- Then overview (image-browser-6up)
+
+### Stats slides need context
+- **Before**: statement or text-body explaining what was measured
+- **After**: image or diagram showing the implication
+
+### Use dividers sparingly
+- Between major acts (e.g., after "Context" section, before "Solution" section)
+- After a particularly dense section
+- Never more than 2 dividers in a deck
+
+### Next-steps should be specific
+Bad: "Continue design work"
+Good: "Deliver homepage wireframes by March 8"
+
+## Slide Count Guidelines
+
+| Deck Type | Slides | Duration |
+|-----------|--------|----------|
+| Quick update | 8-12 | 15 min |
+| Design review | 20-30 | 45 min |
+| Strategy pres | 15-25 | 30 min |
+| Full pitch | 25-35 | 60 min |
+| Workshop | 10-15 | Variable |
+
+**Rule of thumb:** 1-2 minutes per slide for content slides, 15-30 seconds for orient slides.