pneuma-skills 2.4.9 → 2.4.10

package/modes/slide/skill/SKILL.md

@@ -16,7 +16,7 @@ You are a professional presentation creation and editing expert working in Pneum
 ## Core Principles
 
 1. **Design-first**: For new decks, always create a design outline before generating slides — jumping straight into HTML leads to inconsistent visual language and frequent rework
-2. **Design with intention**: Every visual choice should have a reason. Match the aesthetic to the content, audience, and purpose (see `{SKILL_PATH}/references/aesthetics.md`)
+2. **Design with intention**: Every visual choice should have a reason. Match the aesthetic to the content, audience, and purpose (see `{SKILL_PATH}/references/design-guide.md`)
 3. **Visual consistency**: All slides share the same visual language (theme.css) — one-off inline styles cause drift that's painful to fix later
 4. **Content fits canvas**: Every slide is {{slideWidth}}×{{slideHeight}}px — unlike web pages, slides have no scroll, so overflow content is simply invisible
 5. **Precision over speed**: Get each slide right in one pass; avoid iterative "let me try again" loops
@@ -97,15 +97,15 @@ Before writing any slide HTML, create `design_outline.md`:
 
 1. **Understand the brief**: What is the presentation about? Who is the audience? What tone?
 2. **Gather information**: Read any source files the user provides (documents, data, links)
-3. **Write the outline**: Create `design_outline.md` — reference `{SKILL_PATH}/design_outline_template.md` for the full template structure
+3. **Write the outline**: Create `design_outline.md` — reference `{SKILL_PATH}/references/design-outline.md` for the full template structure
 
 4. **Confirm with user** (for large decks): "I've created a design outline with N slides. Ready to generate?"
 
 ### Phase 2: Theme Setup
 
-If the user's workspace has no `theme.css`, create one. Reference `{SKILL_PATH}/style_reference.md` for the design system. Key decisions:
+If the user's workspace has no `theme.css`, create one. Read `{SKILL_PATH}/references/design-guide.md` for typography, color, spacing defaults, and design direction. Key decisions:
 - Color palette (light/dark mode, primary/accent colors)
-- Typography (heading and body fonts) — **must include CJK system fonts** in `--font-sans` for multilingual support (see style_reference.md)
+- Typography (heading and body fonts) — **must include CJK system fonts** in `--font-sans` for multilingual support
 - Spacing scale
 
 ### Phase 3: Scaffold All Slides
@@ -188,7 +188,7 @@ The viewer's export and print features capture a single-frame snapshot of each s
 
 ### Height Calculation Rules
 
-Overflow is the #1 quality issue because slides are fixed-viewport — there's no scroll, so anything beyond {{slideHeight}}px is simply clipped and invisible. Reference `{SKILL_PATH}/layout_patterns.md` for detailed examples. Key rules:
+Overflow is the #1 quality issue because slides are fixed-viewport — there's no scroll, so anything beyond {{slideHeight}}px is simply clipped and invisible. Reference `{SKILL_PATH}/references/layout-patterns.md` for detailed examples. Key rules:
 
 1. **Text height** = `font-size × line-height × number-of-lines`
    - Example: 24px × 1.5 × 3 lines = 108px
@@ -206,16 +206,16 @@ Overflow is the #1 quality issue because slides are fixed-viewport — there's n
 
 ### Design Principles
 
-> For deeper guidance on typography selection, color theory, visual hierarchy, and avoiding AI-generated aesthetics, consult `{SKILL_PATH}/references/aesthetics.md`.
-
 - **Whitespace**: Generous padding and margins. Slides should feel spacious, not cramped
-- **Typography hierarchy**: h1 for slide titles (32-48px), h2 for section headers (24-32px), body text 18-24px. Use fewer sizes with more contrast. See aesthetics.md § Typography.
+- **Typography hierarchy**: h1 for slide titles (32-48px), h2 for section headers (24-32px), body text 18-24px
 - **Bullet points**: Concise (< 10 words each), max 5-6 per slide
-- **Colors**: Use CSS custom properties from theme.css (`var(--color-primary)`, etc.). See aesthetics.md § Color for palette-building guidance.
+- **Colors**: Use CSS custom properties from theme.css (`var(--color-primary)`, etc.)
 - **Contrast**: Ensure text is always readable against its background
 - **Alignment**: Consistent alignment within and across slides
 - **Information density**: One key idea per slide. If a slide feels crowded, split it
 
+For deeper guidance on typography selection, color theory, and visual hierarchy, read `{SKILL_PATH}/references/design-guide.md`.
+
 ---
 
 ## Operations Reference
@@ -335,7 +335,7 @@ cd {SKILL_PATH} && node scripts/generate_image.mjs \
 
 ## Refinement Workflow
 
-When the user asks to improve, polish, refine, or critique a deck, follow the practices in `{SKILL_PATH}/references/aesthetics.md` § Refinement Practices. The available refinement approaches are:
+When the user asks to improve, polish, refine, or critique a deck, follow the practices in `{SKILL_PATH}/references/refinement.md`. The available refinement approaches are:
 
 | Request | Practice | What It Does |
 |---------|----------|-------------|
@@ -346,7 +346,7 @@ When the user asks to improve, polish, refine, or critique a deck, follow the pr
 | "tone it down" / "too busy" | **Quieter** | Reduce saturation, font weight, decorations. Refined, not boring. |
 | "add more color" / "too gray" | **Colorize** | Strategic color introduction — tinted neutrals, accent data, section coding |
 
-**Process**: Read the corresponding section in aesthetics.md, assess the current state, plan changes, then apply systematically across all affected slides. For deck-wide refinement, read all slides first (via manifest.json) to ensure consistent application.
+**Process**: Read the corresponding section in refinement.md, assess the current state, plan changes, then apply systematically across all affected slides. For deck-wide refinement, read all slides first (via manifest.json) to ensure consistent application.
 
 ---
 
@@ -412,10 +412,10 @@ The script checks:
 
 ## Supporting Reference Documents
 
-For detailed guidance, read these files from the skill directory:
+For detailed guidance, read these files from the skill directory on demand:
 
-- `{SKILL_PATH}/references/aesthetics.md` — **Design intelligence**: typography selection, OKLCH color, visual hierarchy, AI slop avoidance, and refinement practices (polish, critique, distill, bolder, quieter, colorize)
-- `{SKILL_PATH}/design_outline_template.md` — Full template for creating design outlines
-- `{SKILL_PATH}/style_reference.md` — Design system reference (colors, typography, spacing, visual patterns)
-- `{SKILL_PATH}/layout_patterns.md` — Common layout patterns with height calculations and examples
-- `{SKILL_PATH}/layout_check.js` — Overflow detection script for browser-based validation
+- `{SKILL_PATH}/references/design-guide.md` — **Design direction**: typography, color (OKLCH), visual hierarchy, spacing, layout templates, and AI image usage. Read when creating themes or making design decisions.
+- `{SKILL_PATH}/references/refinement.md` — **Refinement practices**: critique, polish, distill, bolder, quieter, colorize. Read when the user wants to improve a completed deck.
+- `{SKILL_PATH}/references/design-outline.md` — Full template for creating design outlines. Read during Phase 1.
+- `{SKILL_PATH}/references/layout-patterns.md` — Common layout patterns with height calculations and examples. Read when dealing with overflow or complex layouts.
+- `{SKILL_PATH}/layout_check.js` — Overflow detection script for browser-based validation.

package/modes/slide/skill/references/{aesthetics.md → design-guide.md}

@@ -1,6 +1,6 @@
-# Presentation Aesthetics
+# Slide Design Guide
 
-Design thinking for slide decks. These are tools for making intentional choices — not rules for a specific look. A cold minimalist deck, a loud maximalist pitch, a warm editorial narrative, and a stark brutalist manifesto can all be excellent. The goal is coherence and intentionality, not convergence on one aesthetic.
+Design thinking and default values for slide decks. These are tools for making intentional choices — not rules for a specific look. A cold minimalist deck, a loud maximalist pitch, a warm editorial narrative, and a stark brutalist manifesto can all be excellent. The goal is coherence and intentionality, not convergence on one aesthetic.
 
 ---
 
@@ -42,14 +42,12 @@ These aren't bad in themselves — they're bad when they're the default rather t
 
 ---
 
-## Typography for Presentations
+## Typography
 
 ### Choosing Fonts with Intention
 
 The question isn't "which font is best?" — it's "what does this deck need to communicate, and which font carries that tone?"
 
-Consider what a font signals:
-
 | Quality | Font Direction | Examples (Google Fonts) | Example Context |
 |---------|---------------|------------------------|----------------|
 | Authority, tradition | Serif, high-contrast | Playfair Display, Lora, Newsreader | Legal, finance, academic |
@@ -69,31 +67,41 @@ These are starting points, not a definitive list. Google Fonts has 1600+ options
 
 **CJK requirement**: Always include CJK system fonts (`"PingFang SC"`, `"Noto Sans CJK SC"`, `"Microsoft YaHei"`) before `sans-serif` in your font stack. Without them, Chinese/Japanese/Korean text will be invisible in exported PDFs.
 
-### Hierarchy Through Scale
+### Default Font Stack
 
-The common mistake: too many font sizes that are too close together (24px, 22px, 20px, 18px). This creates muddy hierarchy where nothing stands out.
+```css
+--font-sans: "Inter", "SF Pro Display", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Microsoft YaHei", -apple-system, BlinkMacSystemFont, sans-serif;
+--font-mono: "JetBrains Mono", "SF Mono", "Fira Code", monospace;
+```
 
-**Use fewer sizes with more contrast.** On a slide, you typically need only 3-4 sizes. The gap between title and body should feel decisive, not incremental.
+### Type Scale
 
-| Role | Range | Purpose |
-|------|-------|---------|
-| Title | 36-56px | One per slide, unmistakable primary |
-| Subtitle/Section | 24-32px | Structure and grouping |
-| Body | 18-24px | Content text, readable at distance |
-| Caption | 14-16px | Metadata, footnotes, sparingly |
+Use fewer sizes with more contrast. The gap between title and body should feel decisive, not incremental.
 
-**Minimum readable size**: 18px for body text projected on screen. Anything smaller is decoration, not content.
+| Element | Size | Weight | Line Height | Use |
+|---------|------|--------|-------------|-----|
+| Slide title (h1) | 48px (3rem) | 700 | 1.2 | Cover page main title |
+| Page heading (h1) | 36px (2.25rem) | 700 | 1.2 | Content page title |
+| Section header (h2) | 28px (1.75rem) | 600 | 1.3 | Subsections |
+| Subheading (h3) | 22px (1.375rem) | 600 | 1.4 | Card headers, labels |
+| Body text (p) | 20px (1.25rem) | 400 | 1.7 | Paragraphs, descriptions |
+| List items (li) | 20px (1.25rem) | 400 | 1.8 | Bullet points |
+| Caption/label | 14-16px | 500 | 1.5 | Tags, metadata, footnotes |
+| Small text | 12-14px | 400 | 1.5 | Barely used — minimum readable |
 
 ### Typographic Details
 
+- **Minimum body text**: 18px — anything smaller is hard to read on projected slides
+- **Maximum title**: 56px — larger titles on cover pages only
 - **Weight contrast**: Use enough gap between heading and body weight that the difference is obvious, not subtle
-- **Letter spacing**: Tighter tracking on large headings often looks more polished; default tracking on body text is usually best
+- **Letter spacing**: -0.02em for headings, default for body. Tighter tracking on large headings often looks more polished.
 - **Line height**: Tighter for headings (1.1-1.2), looser for body (1.5-1.8). Light text on dark backgrounds benefits from slightly more line height.
+- **Font smoothing**: Always use `-webkit-font-smoothing: antialiased`
 - **OpenType features**: `font-variant-numeric: tabular-nums` makes numbers align in data slides. `font-variant-caps: all-small-caps` works for elegant labels when it fits the aesthetic.
 
 ---
 
-## Color for Presentations
+## Color
 
 ### Color as Communication
 
@@ -128,21 +136,62 @@ Mood–hue associations as a starting intuition (not rules):
 
 **Key insight regardless of color space**: As colors approach white or black, reduce saturation. High saturation at extreme lightness looks garish.
 
-### Neutral Colors
+### Default Palettes
 
-Neutrals (grays, near-whites, near-blacks) occupy the most area in most decks. Two valid approaches:
+Sensible defaults when the user has no explicit color preferences. Adapt or replace entirely to match the deck's direction.
 
-1. **Pure neutrals**: Clean, no-nonsense, lets content and accent colors do all the talking. Good for data-heavy or multi-brand contexts.
-2. **Tinted neutrals**: Add a tiny hint of your brand hue (chroma ~0.01 in OKLCH). Creates subtle warmth or coolness that feels cohesive. Good for narrative or branded decks.
+**Dark mode (default):**
+```css
+:root {
+  --color-bg: #0f0f0f;
+  --color-fg: #e8e6df;
+  --color-primary: #6ea8fe;     /* Blue accent */
+  --color-secondary: #a78bfa;   /* Purple secondary */
+  --color-accent: #34d399;      /* Green accent */
+  --color-muted: #6b7280;       /* Gray for secondary text */
+  --color-surface: #1a1a1a;     /* Card/container background */
+  --color-border: #2a2a2a;      /* Subtle borders */
+}
+```
 
-Neither is "better." Pure gray is a legitimate choice when neutrality IS the design intent. Tinted gray is a tool for when you want subconscious cohesion.
+**Light mode:**
+```css
+:root {
+  --color-bg: #ffffff;
+  --color-fg: #1e293b;          /* Slate-800 */
+  --color-primary: #2563eb;     /* Blue-600 */
+  --color-secondary: #64748b;   /* Slate-500 */
+  --color-accent: #0ea5e9;      /* Sky-500 */
+  --color-muted: #94a3b8;       /* Slate-400 */
+  --color-surface: #f8fafc;     /* Slate-50 */
+  --color-border: #e2e8f0;      /* Slate-200 */
+}
+```
 
 ### Color Proportion
 
 A useful mental model (not a rigid rule): most of the visual area should be calm (background, whitespace), a moderate portion carries the content (text, secondary elements), and a small portion draws attention (accent, key data).
 
+| Role | Usage | Proportion |
+|------|-------|-----------|
+| Background | Slide background, large areas | 60-70% |
+| Foreground | Primary text, headings | 20-25% |
+| Primary | Accent elements, key highlights | 5-10% |
+| Muted | Secondary text, captions, metadata | 5-10% |
+| Surface | Cards, containers, code blocks | As needed |
+| Border | Dividers, card borders | Minimal |
+
 The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work because they're rare. The more you use them, the less power they have.
 
+### Neutral Colors
+
+Neutrals (grays, near-whites, near-blacks) occupy the most area in most decks. Two valid approaches:
+
+1. **Pure neutrals**: Clean, no-nonsense, lets content and accent colors do all the talking. Good for data-heavy or multi-brand contexts.
+2. **Tinted neutrals**: Add a tiny hint of your brand hue (chroma ~0.01 in OKLCH). Creates subtle warmth or coolness that feels cohesive. Good for narrative or branded decks.
+
+Neither is "better." Pure gray is a legitimate choice when neutrality IS the design intent. Tinted gray is a tool for when you want subconscious cohesion.
+
 ### Dark and Light Decks
 
 Dark and light aren't just color swaps — they have different physics:
@@ -165,7 +214,7 @@ These commonly fail regardless of aesthetic direction:
 
 ---
 
-## Visual Hierarchy for Slides
+## Visual Hierarchy
 
 ### The Squint Test
 
@@ -222,73 +271,172 @@ On slides, whitespace is as important as content. A slide with generous margins
 - If a slide feels cramped, the answer is usually "split into two slides" not "make everything smaller"
 - Empty space is not wasted space — it directs attention to what remains
 
-{{#imageGenEnabled}}
 ---
 
-## Using Generated Images
+## Spacing
 
-CSS and SVG handle geometric shapes, gradients, icons, and simple charts better than images — code is more controllable and resolution-independent. But some things code can't do well. That's where generated images become a real weapon.
+### Slide Padding
 
-### The Finishing Touch, Not the Filler
+```css
+--slide-padding: 64px;  /* Default content page padding */
+```
 
-An image earns its place the same way a word does — not because there's empty space to fill, but because the slide genuinely needs it.
+- **Cover pages**: 0px or custom (full-bleed backgrounds)
+- **Content pages**: 64px all sides → 1152×592px available area (for 1280×720 canvas)
 
-**Worth generating**:
+### Gap Scale
 
-- **Mood-setting hero images on cover/divider slides.** A full-bleed background photo that matches the topic establishes atmosphere faster than any CSS gradient. A deck about ocean conservation with a single deep-sea light-and-shadow image puts the audience in the right headspace within the first second.
-- **Making abstract concepts tangible.** "Consistency in distributed systems" takes three paragraphs to explain in text. A carefully generated visual metaphor — a row of clocks all pointing to the same time — communicates it in one glance.
-- **Grounding data with reality.** A deck about user growth has numbers and charts, but a realistic scene — a crowded coffee shop where everyone is using your product — creates emotional impact that no bar chart can match.
-- **Textures and qualities that SVG can't reach.** Hand-drawn illustration styles, watercolor textures, photographic lighting, complex 3D renders — these are CSS and SVG's blind spots.
+| Token | Size | Use |
+|-------|------|-----|
+| xs | 8px | Between related inline items |
+| sm | 16px | Between list items, tight groups |
+| md | 24px | Between content sections |
+| lg | 32px | Between major blocks |
+| xl | 48px | Between split columns, hero spacing |
 
-**Not worth generating**:
+### Margin Patterns
 
-- Purely decorative geometric patterns — CSS does this better and it's easier to tweak
-- An image on every single slide — this isn't a photo album. Data-heavy and process slides work fine with just typography and layout.
-- Generic stock-photo-style images — a person in a suit standing at a whiteboard adds nothing to any deck
+- Between heading and first content: 16-24px
+- Between content paragraphs: 12-16px
+- Between cards in a grid: 16-24px
+- Between major sections: 32-48px
 
-### Image × CSS Integration
+---
 
-Generated images don't exist in isolation — they need CSS to blend into the slide's design language. Practical combinations:
+## Visual Elements
+
+### Cards
 
-**Gradient overlay for text readability.** Image as background, CSS gradient on top to control brightness and ensure text contrast.
 ```css
-.slide-hero {
-  background: linear-gradient(to right, rgba(0,0,0,0.7) 40%, transparent), url('assets/hero.jpg');
-  background-size: cover;
+.card {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 12px;
+  padding: 24px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.1); /* optional */
 }
 ```
-Text goes on the dark left side; the image bleeds through on the right. Far more readable than text placed directly over an uncontrolled image.
 
-**Non-rectangular cropping.** `clip-path` or creative `border-radius` breaks the rectangle monotony. `object-fit: cover` + `object-position` controls the focal point.
+### Tags / Badges
+
 ```css
-.feature-image {
-  clip-path: polygon(10% 0, 100% 0, 100% 100%, 0 100%);
-  object-fit: cover;
-  object-position: center 30%; /* keep the face in upper third */
+.tag {
+  display: inline-block;
+  padding: 4px 12px;
+  border-radius: 6px;
+  font-size: 13px;
+  font-weight: 500;
+  background: var(--color-primary);
+  color: white;
 }
 ```
 
-**Blend modes for color unity.** `mix-blend-mode` and `filter` make any image harmonize with the slide's palette. A desaturated image + `multiply` blend mode + brand-colored background = highly unified visual.
+### Dividers
 
-**Subtle texture backgrounds.** Generate a texture (paper grain, noise, fabric) and use it as a `background-image` with low `opacity`. Gives flat-color backgrounds a tactile quality that CSS noise patterns can approximate but rarely match.
+```css
+.divider {
+  height: 1px;
+  background: var(--color-border);
+  margin: 24px 0;
+}
+```
 
-### Style Coherence Across a Deck
+### Icons
 
-When multiple generated images appear in the same deck, they must look like they belong to the same world:
+- Use **Lucide icons** (CDN) or **inline SVG** for consistency
+- Icon size: 20-24px for inline, 32-48px for feature icons
+- **Never use emoji** for professional presentations
+- Color icons with `var(--color-primary)` or `var(--color-muted)`
 
-- **Consistent style descriptors in prompts**: If the first image uses "flat illustration, muted earth tones, thick outlines," every subsequent image should carry the same style language.
-- **Color temperature consistency**: A warm-toned deck with one cold-toned image looks like a collage, not a design.
-- **Don't mix rendering styles**: Photorealistic and illustration shouldn't coexist in the same deck unless the contrast itself is the design intent.
+### Charts (ECharts)
 
-### Restraint
+- Initialize with explicit width/height matching the container
+- Use the deck's color palette for chart colors
+- Include clear axis labels and legends
+- Prefer bar/line charts for trends, pie/donut for composition
+- Add a `<div id="chart-{n}" style="width: 100%; height: Xpx;"></div>` container
+- Initialize with `<script>` at the end of the slide fragment
 
-Image generation is a powerful tool, but overuse turns a deck into an AI art gallery. Some rules of thumb:
+---
 
-- **In most decks, the majority of slides don't need images.** Data slides, process slides, comparison slides — typography and charts carry these.
-- **One great image beats three filler images.** When you think "an image here would look nice," ask: would removing it make the slide communicate worse? If not, skip it.
-- **Fewer images = more weight per image.** In a 20-slide deck with 3 images, every image gets remembered. With 20 images, none of them do.
+## Layout Templates
 
-{{/imageGenEnabled}}
+### Cover Page
+
+Full-canvas, centered, minimal:
+```
+┌──────────────────────────────────────────┐
+│                                          │
+│              [Tag/Label]                 │
+│                                          │
+│         Main Title (48px)                │
+│                                          │
+│         Subtitle (20px, muted)           │
+│                                          │
+│                                          │
+└──────────────────────────────────────────┘
+```
+
+### Single Column Content
+
+Standard for text-heavy slides:
+```
+┌──────────────────────────────────────────┐
+│  Page Heading (h2)                       │
+│                                          │
+│  • Bullet point one                      │
+│  • Bullet point two                      │
+│  • Bullet point three                    │
+│  • Bullet point four                     │
+│                                          │
+│                                          │
+└──────────────────────────────────────────┘
+```
+
+### Two-Column Split
+
+For comparison, feature + detail, or text + image:
+```
+┌──────────────────────────────────────────┐
+│  Page Heading (h2)                       │
+│                                          │
+│  ┌──────────────┐  ┌──────────────┐     │
+│  │  Left Column │  │ Right Column │     │
+│  │  Text/list   │  │ Image/chart  │     │
+│  │              │  │              │     │
+│  └──────────────┘  └──────────────┘     │
+│                                          │
+└──────────────────────────────────────────┘
+```
+
+### Card Grid
+
+For 3-4 equal items (features, team, metrics):
+```
+┌──────────────────────────────────────────┐
+│  Page Heading (h2)                       │
+│                                          │
+│  ┌──────┐  ┌──────┐  ┌──────┐          │
+│  │ Card │  │ Card │  │ Card │          │
+│  │  1   │  │  2   │  │  3   │          │
+│  └──────┘  └──────┘  └──────┘          │
+│                                          │
+└──────────────────────────────────────────┘
+```
+
+### Full Visual
+
+Image or chart dominates, minimal text:
+```
+┌──────────────────────────────────────────┐
+│  ┌──────────────────────────────────┐    │
+│  │                                  │    │
+│  │        Large Image/Chart         │    │
+│  │                                  │    │
+│  └──────────────────────────────────┘    │
+│  Caption or source (small, muted)        │
+└──────────────────────────────────────────┘
+```
 
 ---
 
@@ -316,106 +464,70 @@ Every word on a slide should earn its place. Presentations are a spoken medium
 - Round numbers for impact: "~2 million users" beats "1,987,432 users"
 - Highlight the one number that matters — if everything is highlighted, nothing is
 
+{{#imageGenEnabled}}
 ---
 
-## Refinement Practices
-
-When a deck is functionally complete and the user wants to improve its quality, apply these practices. They're ordered from broad to specific — start with critique, then refine.
-
-### Critique: Evaluate Design Effectiveness
-
-Step back and evaluate the deck as a whole. Think like a design director giving feedback.
-
-**Process**:
-1. **Intentionality check** (first): Can you articulate the design direction? Does every major choice (color, font, layout, tone) serve that direction? Or does the deck feel like a collection of defaults?
-2. **Visual hierarchy**: On each slide, is it immediately obvious what matters most? Can you spot the key point in 2 seconds?
-3. **Consistency**: Do all slides feel like they belong to the same deck? Same fonts, colors, spacing patterns?
-4. **Composition**: Does each slide feel balanced? Is whitespace intentional or leftover?
-5. **Emotional resonance**: What emotion does this deck evoke? Is that the right one for the audience and content?
-6. **Flow**: Does the deck tell a story? Does the visual energy build, peak, and resolve?
-
-**Output**: Identify the top 3-5 issues, ordered by impact. For each: what's wrong, why it matters, and how to fix it.
-
-### Polish: The Final Quality Pass
-
-Fix the details that separate good from great. Only do this after the deck is content-complete.
-
-**Checklist**:
-- [ ] **Alignment**: All elements snap to a consistent grid. No random offsets.
-- [ ] **Spacing consistency**: All gaps follow the spacing scale. No arbitrary values.
-- [ ] **Typography hierarchy**: Same-role text uses same size/weight across all slides
-- [ ] **Widows**: No single words sitting alone on the last line of a heading or bullet
-- [ ] **Color token usage**: No hard-coded colors — everything uses CSS custom properties
-- [ ] **Icon consistency**: All icons from the same family, same size, same stroke weight
-- [ ] **Image treatment**: Consistent border-radius, shadow, and sizing for images across slides
-- [ ] **Capitalization**: Consistent across all headings, labels, and bullets
-- [ ] **Content fit**: Re-verify no slide overflows (mental height calculation or layout_check.js)
-
-**Optical adjustments**:
-- Text aligned to padding may look indented due to letterform whitespace — adjust visually if needed
-- Icons next to text may need slight vertical offset for optical alignment
-- Centered text groups may need slight upward offset to feel visually centered (mathematical center ≠ optical center)
-
-### Distill: Simplify Overcrowded Slides
+## Using Generated Images
 
-Strip unnecessary complexity to reveal what actually matters.
+CSS and SVG handle geometric shapes, gradients, icons, and simple charts better than images — code is more controllable and resolution-independent. But some things code can't do well. That's where generated images become a real weapon.
 
-**When to apply**: A slide feels cramped, has too many elements competing for attention, or tries to communicate multiple ideas at once.
+### The Finishing Touch, Not the Filler
 
-**Process**:
-1. **Identify the ONE key message** of the slide. If you can't, it needs splitting.
-2. **Remove elements** that don't serve the message — ornamental shapes, redundant icons, background patterns that add noise
-3. **Reduce variety** — fewer colors, fewer font sizes, fewer visual treatments per slide
-4. **Flatten structure** — remove wrapper elements that don't create meaningful grouping
-5. **Shorten text** — cut every line in half. Then do it again.
-6. **Add space** — let what remains breathe
+An image earns its place the same way a word does — not because there's empty space to fill, but because the slide genuinely needs it.
 
-**The test**: Cover half the slide with your hand. Does the other half still communicate the message? If not, the slide is too spread out. If yes, the covered half may be unnecessary.
+**Worth generating**:
 
-### Bolder: Amplify Visual Impact
+- **Mood-setting hero images on cover/divider slides.** A full-bleed background photo that matches the topic establishes atmosphere faster than any CSS gradient. A deck about ocean conservation with a single deep-sea light-and-shadow image puts the audience in the right headspace within the first second.
+- **Making abstract concepts tangible.** "Consistency in distributed systems" takes three paragraphs to explain in text. A carefully generated visual metaphor — a row of clocks all pointing to the same time — communicates it in one glance.
+- **Grounding data with reality.** A deck about user growth has numbers and charts, but a realistic scene — a crowded coffee shop where everyone is using your product — creates emotional impact that no bar chart can match.
+- **Textures and qualities that SVG can't reach.** Hand-drawn illustration styles, watercolor textures, photographic lighting, complex 3D renders — these are CSS and SVG's blind spots.
 
-Make a flat or forgettable deck more visually memorable.
+**Not worth generating**:
 
-**When to apply**: The deck is technically correct but feels generic, safe, or like every other deck on the same topic.
+- Purely decorative geometric patterns — CSS does this better and it's easier to tweak
+- An image on every single slide — this isn't a photo album. Data-heavy and process slides work fine with just typography and layout.
+- Generic stock-photo-style images — a person in a suit standing at a whiteboard adds nothing to any deck
 
-**Think about**:
-- **Scale contrast**: Is the difference between heading and body dramatic enough to feel intentional?
-- **Weight contrast**: Are you using enough range in font weight to create clear levels?
-- **Color confidence**: Is the palette committed to something, or hedging with muted everything?
-- **Composition**: Is every slide centered and symmetrical? Could asymmetry or unexpected proportions (70/30, 80/20 splits) create more visual interest?
-- **Negative space**: Could dramatic whitespace — leaving 30-40% of a slide empty — make the content feel more important, not less?
-- **Full-bleed**: Could hero images or colored backgrounds extend to the edges for impact?
+### Image × CSS Integration
 
-**The key question**: Does this deck look like it has an opinion? Or could it be about anything?
+Generated images don't exist in isolation — they need CSS to blend into the slide's design language. Practical combinations:
 
-### Quieter: Refine and Restrain
+**Gradient overlay for text readability.** Image as background, CSS gradient on top to control brightness and ensure text contrast.
+```css
+.slide-hero {
+  background: linear-gradient(to right, rgba(0,0,0,0.7) 40%, transparent), url('assets/hero.jpg');
+  background-size: cover;
+}
+```
+Text goes on the dark left side; the image bleeds through on the right. Far more readable than text placed directly over an uncontrolled image.
 
-Tone down overly aggressive or visually noisy decks.
+**Non-rectangular cropping.** `clip-path` or creative `border-radius` breaks the rectangle monotony. `object-fit: cover` + `object-position` controls the focal point.
+```css
+.feature-image {
+  clip-path: polygon(10% 0, 100% 0, 100% 100%, 0 100%);
+  object-fit: cover;
+  object-position: center 30%; /* keep the face in upper third */
+}
+```
 
-**When to apply**: The deck is overstimulating — too many colors, too much contrast, too many effects, elements competing for attention.
+**Blend modes for color unity.** `mix-blend-mode` and `filter` make any image harmonize with the slide's palette. A desaturated image + `multiply` blend mode + brand-colored background = highly unified visual.
 
-**Think about**:
-- **Saturation**: Could shifting to 70-85% of current saturation feel more sophisticated?
-- **Weight**: Could lighter heading weights create elegance instead of force?
-- **Decoration**: Is every gradient, shadow, and pattern earning its place? Remove those that don't.
-- **Space**: Could more whitespace reduce visual tension?
-- **Color count**: Could fewer colors, used more intentionally, have more impact?
+**Subtle texture backgrounds.** Generate a texture (paper grain, noise, fabric) and use it as a `background-image` with low `opacity`. Gives flat-color backgrounds a tactile quality that CSS noise patterns can approximate but rarely match.
 
-**The key question**: Does the design feel confident or anxious? Quiet design doesn't shout — it doesn't need to.
+### Style Coherence Across a Deck
 
-**Watch out**: Don't strip so far that the deck loses personality. Quiet ≠ boring. Refined ≠ generic. Hierarchy still matters — some things should stand out.
+When multiple generated images appear in the same deck, they must look like they belong to the same world:
 
-### Colorize: Add Strategic Color
+- **Consistent style descriptors in prompts**: If the first image uses "flat illustration, muted earth tones, thick outlines," every subsequent image should carry the same style language.
+- **Color temperature consistency**: A warm-toned deck with one cold-toned image looks like a collage, not a design.
+- **Don't mix rendering styles**: Photorealistic and illustration shouldn't coexist in the same deck unless the contrast itself is the design intent.
 
-Introduce color to monochromatic or visually flat decks.
+### Restraint
 
-**When to apply**: The deck feels too gray, too cold, or visually monotonous.
+Image generation is a powerful tool, but overuse turns a deck into an AI art gallery. Some rules of thumb:
 
-**Think about**:
-- **Purpose**: What should color *do* here? Draw attention to key data? Create section identity? Add warmth? Reinforce a brand?
-- **Where, not how much**: Coloring the one number or word that carries the slide's message is worth more than coloring every heading
-- **Backgrounds**: Subtle background tints can separate sections or add warmth without adding noise
-- **Chart and data colors**: Should match the deck's palette, not the charting library's defaults
-- **Neutral warmth**: Even without accent colors, shifting from pure gray to warm or cool tinted neutrals can make a deck feel less sterile
+- **In most decks, the majority of slides don't need images.** Data slides, process slides, comparison slides — typography and charts carry these.
+- **One great image beats three filler images.** When you think "an image here would look nice," ask: would removing it make the slide communicate worse? If not, skip it.
+- **Fewer images = more weight per image.** In a 20-slide deck with 3 images, every image gets remembered. With 20 images, none of them do.
 
-**The key question**: Is the lack of color a deliberate choice (and working well), or is it an oversight that's making the deck feel lifeless?
+{{/imageGenEnabled}}

package/modes/slide/skill/references/refinement.md

@@ -0,0 +1,113 @@
+# Refinement Practices
+
+When a deck is functionally complete and the user wants to improve its quality, apply these practices. They're ordered from broad to specific — start with critique, then refine.
+
+---
+
+## Critique: Evaluate Design Effectiveness
+
+Step back and evaluate the deck as a whole. Think like a design director giving feedback.
+
+**Process**:
+1. **Intentionality check** (first): Can you articulate the design direction? Does every major choice (color, font, layout, tone) serve that direction? Or does the deck feel like a collection of defaults?
+2. **Visual hierarchy**: On each slide, is it immediately obvious what matters most? Can you spot the key point in 2 seconds?
+3. **Consistency**: Do all slides feel like they belong to the same deck? Same fonts, colors, spacing patterns?
+4. **Composition**: Does each slide feel balanced? Is whitespace intentional or leftover?
+5. **Emotional resonance**: What emotion does this deck evoke? Is that the right one for the audience and content?
+6. **Flow**: Does the deck tell a story? Does the visual energy build, peak, and resolve?
+
+**Output**: Identify the top 3-5 issues, ordered by impact. For each: what's wrong, why it matters, and how to fix it.
+
+---
+
+## Polish: The Final Quality Pass
+
+Fix the details that separate good from great. Only do this after the deck is content-complete.
+
+**Checklist**:
+- [ ] **Alignment**: All elements snap to a consistent grid. No random offsets.
+- [ ] **Spacing consistency**: All gaps follow the spacing scale. No arbitrary values.
+- [ ] **Typography hierarchy**: Same-role text uses same size/weight across all slides
+- [ ] **Widows**: No single words sitting alone on the last line of a heading or bullet
+- [ ] **Color token usage**: No hard-coded colors — everything uses CSS custom properties
+- [ ] **Icon consistency**: All icons from the same family, same size, same stroke weight
+- [ ] **Image treatment**: Consistent border-radius, shadow, and sizing for images across slides
+- [ ] **Capitalization**: Consistent across all headings, labels, and bullets
+- [ ] **Content fit**: Re-verify no slide overflows (mental height calculation or layout_check.js)
+
+**Optical adjustments**:
+- Text aligned to padding may look indented due to letterform whitespace — adjust visually if needed
+- Icons next to text may need slight vertical offset for optical alignment
+- Centered text groups may need slight upward offset to feel visually centered (mathematical center ≠ optical center)
+
+---
+
+## Distill: Simplify Overcrowded Slides
+
+Strip unnecessary complexity to reveal what actually matters.
+
+**When to apply**: A slide feels cramped, has too many elements competing for attention, or tries to communicate multiple ideas at once.
+
+**Process**:
+1. **Identify the ONE key message** of the slide. If you can't, it needs splitting.
+2. **Remove elements** that don't serve the message — ornamental shapes, redundant icons, background patterns that add noise
+3. **Reduce variety** — fewer colors, fewer font sizes, fewer visual treatments per slide
+4. **Flatten structure** — remove wrapper elements that don't create meaningful grouping
+5. **Shorten text** — cut every line in half. Then do it again.
+6. **Add space** — let what remains breathe
+
+**The test**: Cover half the slide with your hand. Does the other half still communicate the message? If not, the slide is too spread out. If yes, the covered half may be unnecessary.
+
+---
+
+## Bolder: Amplify Visual Impact
+
+Make a flat or forgettable deck more visually memorable.
+
+**When to apply**: The deck is technically correct but feels generic, safe, or like every other deck on the same topic.
+
+**Think about**:
+- **Scale contrast**: Is the difference between heading and body dramatic enough to feel intentional?
+- **Weight contrast**: Are you using enough range in font weight to create clear levels?
+- **Color confidence**: Is the palette committed to something, or hedging with muted everything?
+- **Composition**: Is every slide centered and symmetrical? Could asymmetry or unexpected proportions (70/30, 80/20 splits) create more visual interest?
+- **Negative space**: Could dramatic whitespace — leaving 30-40% of a slide empty — make the content feel more important, not less?
+- **Full-bleed**: Could hero images or colored backgrounds extend to the edges for impact?
+
+**The key question**: Does this deck look like it has an opinion? Or could it be about anything?
+
+---
+
+## Quieter: Refine and Restrain
+
+Tone down overly aggressive or visually noisy decks.
+
+**When to apply**: The deck is overstimulating — too many colors, too much contrast, too many effects, elements competing for attention.
+
+**Think about**:
+- **Saturation**: Could shifting to 70-85% of current saturation feel more sophisticated?
+- **Weight**: Could lighter heading weights create elegance instead of force?
+- **Decoration**: Is every gradient, shadow, and pattern earning its place? Remove those that don't.
+- **Space**: Could more whitespace reduce visual tension?
+- **Color count**: Could fewer colors, used more intentionally, have more impact?
+
+**The key question**: Does the design feel confident or anxious? Quiet design doesn't shout — it doesn't need to.
+
+**Watch out**: Don't strip so far that the deck loses personality. Quiet ≠ boring. Refined ≠ generic. Hierarchy still matters — some things should stand out.
+
+---
+
+## Colorize: Add Strategic Color
+
+Introduce color to monochromatic or visually flat decks.
+
+**When to apply**: The deck feels too gray, too cold, or visually monotonous.
+
+**Think about**:
+- **Purpose**: What should color *do* here? Draw attention to key data? Create section identity? Add warmth? Reinforce a brand?
+- **Where, not how much**: Coloring the one number or word that carries the slide's message is worth more than coloring every heading
+- **Backgrounds**: Subtle background tints can separate sections or add warmth without adding noise
+- **Chart and data colors**: Should match the deck's palette, not the charting library's defaults
+- **Neutral warmth**: Even without accent colors, shifting from pure gray to warm or cool tinted neutrals can make a deck feel less sterile
+
+**The key question**: Is the lack of color a deliberate choice (and working well), or is it an oversight that's making the deck feel lifeless?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pneuma-skills",
-  "version": "2.4.9",
+  "version": "2.4.10",
   "type": "module",
   "description": "Co-creation infrastructure for humans and code agents — visual environment, skills, continuous learning, and distribution.",
   "license": "MIT",

package/modes/slide/skill/style_reference.md

@@ -1,267 +0,0 @@
-# Style Reference — Slide Design System
-
-Default design system for Pneuma Slide Mode presentations. Use these conventions when the user has no explicit style preferences.
-
-> **For aesthetic principles** — font selection philosophy, OKLCH color theory, visual hierarchy techniques, and refinement practices — see `{SKILL_PATH}/references/aesthetics.md`.
-
----
-
-## Default Design Philosophy
-
-**Intentional and coherent.** The default values below are a starting point, not a destination. Adapt them to match the deck's purpose, audience, and personality.
-
-- Generous whitespace over dense layouts
-- Clear visual hierarchy via multiple dimensions — size, weight, color, space (see aesthetics.md § Visual Hierarchy)
-- Consistent spacing scale throughout
-- Every visual choice should be deliberate (see aesthetics.md § Design Direction)
-
----
-
-## Color Palettes
-
-### Dark Mode (Default)
-
-These are sensible defaults. See aesthetics.md § Color for guidance on building palettes intentionally — including when to use OKLCH, how to handle neutrals, and dark vs light considerations.
-
-```css
-:root {
-  --color-bg: #0f0f0f;
-  --color-fg: #e8e6df;
-  --color-primary: #6ea8fe;     /* Blue accent */
-  --color-secondary: #a78bfa;   /* Purple secondary */
-  --color-accent: #34d399;      /* Green accent */
-  --color-muted: #6b7280;       /* Gray for secondary text */
-  --color-surface: #1a1a1a;     /* Card/container background */
-  --color-border: #2a2a2a;      /* Subtle borders */
-}
-```
-
-### Light Mode
-
-```css
-:root {
-  --color-bg: #ffffff;
-  --color-fg: #1e293b;          /* Slate-800 */
-  --color-primary: #2563eb;     /* Blue-600 */
-  --color-secondary: #64748b;   /* Slate-500 */
-  --color-accent: #0ea5e9;      /* Sky-500 */
-  --color-muted: #94a3b8;       /* Slate-400 */
-  --color-surface: #f8fafc;     /* Slate-50 */
-  --color-border: #e2e8f0;      /* Slate-200 */
-}
-```
-
-### Color Usage Rules
-
-| Role | Usage | Proportion |
-|------|-------|-----------|
-| Background | Slide background, large areas | 60-70% |
-| Foreground | Primary text, headings | 20-25% |
-| Primary | Accent elements, links, key highlights | 5-10% |
-| Muted | Secondary text, captions, metadata | 5-10% |
-| Surface | Cards, containers, code blocks | As needed |
-| Border | Dividers, card borders | Minimal |
-
----
-
-## Typography
-
-### Font Stack
-
-The default stack below is a safe starting point. See aesthetics.md § Typography for guidance on choosing fonts that match the deck's specific character.
-
-```css
---font-sans: "Inter", "SF Pro Display", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Microsoft YaHei", -apple-system, BlinkMacSystemFont, sans-serif;
---font-mono: "JetBrains Mono", "SF Mono", "Fira Code", monospace;
-```
-
-**CJK support**: Always include CJK system fonts (`"PingFang SC"` for macOS, `"Noto Sans CJK SC"` for Linux, `"Microsoft YaHei"` for Windows) **before** generic families (`sans-serif`). Without them, Chrome's print renderer cannot fall back to CJK glyphs and Chinese/Japanese/Korean text will be invisible in exported PDFs.
-
-### Size Scale
-
-| Element | Size | Weight | Line Height | Use |
-|---------|------|--------|-------------|-----|
-| Slide title (h1) | 48px (3rem) | 700 | 1.2 | Cover page main title |
-| Page heading (h1) | 36px (2.25rem) | 700 | 1.2 | Content page title |
-| Section header (h2) | 28px (1.75rem) | 600 | 1.3 | Subsections |
-| Subheading (h3) | 22px (1.375rem) | 600 | 1.4 | Card headers, labels |
-| Body text (p) | 20px (1.25rem) | 400 | 1.7 | Paragraphs, descriptions |
-| List items (li) | 20px (1.25rem) | 400 | 1.8 | Bullet points |
-| Caption/label | 14-16px | 500 | 1.5 | Tags, metadata, footnotes |
-| Small text | 12-14px | 400 | 1.5 | Barely used — minimum readable |
-
-### Typography Rules
-
-- **Minimum body text**: 18px — anything smaller is hard to read on projected slides
-- **Maximum title**: 56px — larger titles on cover pages only
-- **Letter spacing**: -0.02em for headings, default for body
-- **Font smoothing**: Always use `-webkit-font-smoothing: antialiased`
-
----
-
-## Spacing System
-
-### Slide Padding
-
-```css
---slide-padding: 64px;  /* Default content page padding */
-```
-
-- **Cover pages**: 0px or custom (full-bleed backgrounds)
-- **Content pages**: 64px all sides → 1152×592px available area (for 1280×720 canvas)
-
-### Gap Scale
-
-| Token | Size | Use |
-|-------|------|-----|
-| xs | 8px | Between related inline items |
-| sm | 16px | Between list items, tight groups |
-| md | 24px | Between content sections |
-| lg | 32px | Between major blocks |
-| xl | 48px | Between split columns, hero spacing |
-
-### Margin Patterns
-
-- Between heading and first content: 16-24px
-- Between content paragraphs: 12-16px
-- Between cards in a grid: 16-24px
-- Between major sections: 32-48px
-
----
-
-## Visual Elements
-
-### Cards
-
-```css
-.card {
-  background: var(--color-surface);
-  border: 1px solid var(--color-border);
-  border-radius: 12px;       /* rounded-lg */
-  padding: 24px;
-  /* Optional shadow for depth: */
-  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
-}
-```
-
-### Tags / Badges
-
-```css
-.tag {
-  display: inline-block;
-  padding: 4px 12px;
-  border-radius: 6px;        /* rounded-md */
-  font-size: 13px;
-  font-weight: 500;
-  background: var(--color-primary);
-  color: white;
-}
-```
-
-### Dividers
-
-```css
-.divider {
-  height: 1px;
-  background: var(--color-border);
-  margin: 24px 0;
-}
-```
-
-### Icon Usage
-
-- Use **Lucide icons** (CDN) or **inline SVG** for consistency
-- Icon size: 20-24px for inline, 32-48px for feature icons
-- **Never use emoji** for professional presentations
-- Color icons with `var(--color-primary)` or `var(--color-muted)`
-
-### Chart Guidelines (ECharts)
-
-When including data visualizations:
-- Initialize with explicit width/height matching the container
-- Use the deck's color palette for chart colors
-- Include clear axis labels and legends
-- Prefer bar/line charts for trends, pie/donut for composition
-- Add a `<div id="chart-{n}" style="width: 100%; height: Xpx;"></div>` container
-- Initialize with `<script>` at the end of the slide fragment
-
----
-
-## Layout Templates
-
-### Cover Page
-
-Full-canvas, centered, minimal:
-```
-┌──────────────────────────────────────────┐
-│                                          │
-│              [Tag/Label]                 │
-│                                          │
-│         Main Title (48px)                │
-│                                          │
-│         Subtitle (20px, muted)           │
-│                                          │
-│                                          │
-└──────────────────────────────────────────┘
-```
-
-### Single Column Content
-
-Standard for text-heavy slides:
-```
-┌──────────────────────────────────────────┐
-│  Page Heading (h2)                       │
-│                                          │
-│  • Bullet point one                      │
-│  • Bullet point two                      │
-│  • Bullet point three                    │
-│  • Bullet point four                     │
-│                                          │
-│                                          │
-└──────────────────────────────────────────┘
-```
-
-### Two-Column Split
-
-For comparison, feature + detail, or text + image:
-```
-┌──────────────────────────────────────────┐
-│  Page Heading (h2)                       │
-│                                          │
-│  ┌──────────────┐  ┌──────────────┐     │
-│  │  Left Column │  │ Right Column │     │
-│  │  Text/list   │  │ Image/chart  │     │
-│  │              │  │              │     │
-│  └──────────────┘  └──────────────┘     │
-│                                          │
-└──────────────────────────────────────────┘
-```
-
-### Card Grid
-
-For 3-4 equal items (features, team, metrics):
-```
-┌──────────────────────────────────────────┐
-│  Page Heading (h2)                       │
-│                                          │
-│  ┌──────┐  ┌──────┐  ┌──────┐          │
-│  │ Card │  │ Card │  │ Card │          │
-│  │  1   │  │  2   │  │  3   │          │
-│  └──────┘  └──────┘  └──────┘          │
-│                                          │
-└──────────────────────────────────────────┘
-```
-
-### Full Visual
-
-Image or chart dominates, minimal text:
-```
-┌──────────────────────────────────────────┐
-│  ┌──────────────────────────────────┐    │
-│  │                                  │    │
-│  │        Large Image/Chart         │    │
-│  │                                  │    │
-│  └──────────────────────────────────┘    │
-│  Caption or source (small, muted)        │
-└──────────────────────────────────────────┘
-```