slides-grab 1.2.2 → 1.2.4

package/scripts/html2pdf.js

@@ -16,6 +16,12 @@ const {
   getResolutionSize,
   normalizeResolutionPreset,
 } = require('../src/export-resolution.cjs');
+const {
+  DEFAULT_SLIDE_MODE,
+  getSlideModeChoices,
+  getSlideModeConfig,
+  normalizeSlideMode,
+} = require('../src/slide-mode.cjs');
 
 const DEFAULT_OUTPUT = 'slides.pdf';
 const DEFAULT_SLIDES_DIR = 'slides';
@@ -23,9 +29,7 @@ const DEFAULT_MODE = 'capture';
 const DEFAULT_CAPTURE_RESOLUTION = '2160p';
 const PDF_MODES = new Set(['capture', 'print']);
 const SLIDE_FILE_PATTERN = /^slide-.*\.html$/i;
-const FALLBACK_SLIDE_SIZE = { width: 960, height: 540 };
 const DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR = 2;
-const TARGET_ASPECT_RATIO = 16 / 9;
 const RENDER_SETTLE_MS = 120;
 const CSS_PIXELS_PER_INCH = 96;
 const PDF_POINTS_PER_INCH = 72;
@@ -40,6 +44,7 @@ function printUsage() {
       `  --output <path>      Output PDF path (default: ${DEFAULT_OUTPUT})`,
       `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
       `  --mode <mode>        PDF export mode: capture|print (default: ${DEFAULT_MODE})`,
+      `  --slide-mode <mode>  Slide mode: ${getSlideModeChoices().join('|')} (default: ${DEFAULT_SLIDE_MODE})`,
       `  --resolution <preset> Capture raster size preset: ${getResolutionChoices().join('|')}|4k (default: ${DEFAULT_CAPTURE_RESOLUTION}; ignored in print mode)`,
       '  -h, --help           Show this help message',
       '',
@@ -89,8 +94,8 @@ function cssPixelsToPdfPoints(value) {
   return Math.round((normalizeDimension(value, 0) * PDF_POINTS_PER_INCH) / CSS_PIXELS_PER_INCH);
 }
 
-async function normalizeCaptureRasterSize(pngBytes, resolution = '') {
-  const targetSize = getResolutionSize(resolution);
+async function normalizeCaptureRasterSize(pngBytes, resolution = '', slideMode = DEFAULT_SLIDE_MODE) {
+  const targetSize = getResolutionSize(resolution, slideMode);
   if (!targetSize) {
     return pngBytes;
   }
@@ -140,6 +145,7 @@ export function parseCliArgs(args) {
     output: DEFAULT_OUTPUT,
     slidesDir: DEFAULT_SLIDES_DIR,
     mode: DEFAULT_MODE,
+    slideMode: DEFAULT_SLIDE_MODE,
     resolution: DEFAULT_CAPTURE_RESOLUTION,
     help: false,
   };
@@ -185,6 +191,17 @@ export function parseCliArgs(args) {
       continue;
     }
 
+    if (arg === '--slide-mode') {
+      options.slideMode = normalizeSlideMode(readOptionValue(args, i, '--slide-mode'), { optionName: '--slide-mode' });
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--slide-mode=')) {
+      options.slideMode = normalizeSlideMode(arg.slice('--slide-mode='.length), { optionName: '--slide-mode' });
+      continue;
+    }
+
     if (arg === '--resolution') {
       options.resolution = normalizeResolutionPreset(readOptionValue(args, i, '--resolution'));
       i += 1;
@@ -209,6 +226,7 @@ export function parseCliArgs(args) {
   options.output = options.output.trim();
   options.slidesDir = options.slidesDir.trim();
   options.mode = normalizeMode(options.mode);
+  options.slideMode = normalizeSlideMode(options.slideMode, { optionName: '--slide-mode' });
   options.resolution = normalizeResolutionPreset(options.resolution);
   if (options.mode === 'print') {
     options.resolution = '';
@@ -226,9 +244,10 @@ export async function findSlideFiles(slidesDir = resolve(process.cwd(), DEFAULT_
 }
 
 export function buildPdfOptions(widthPx, heightPx) {
+  const fallbackSize = getSlideModeConfig(DEFAULT_SLIDE_MODE).framePx;
   return {
-    width: `${normalizeDimension(widthPx, FALLBACK_SLIDE_SIZE.width)}px`,
-    height: `${normalizeDimension(heightPx, FALLBACK_SLIDE_SIZE.height)}px`,
+    width: `${normalizeDimension(widthPx, fallbackSize.width)}px`,
+    height: `${normalizeDimension(heightPx, fallbackSize.height)}px`,
     printBackground: true,
     pageRanges: '1',
     margin: { top: '0px', right: '0px', bottom: '0px', left: '0px' },
@@ -236,22 +255,25 @@ export function buildPdfOptions(widthPx, heightPx) {
   };
 }
 
-export function buildPageOptions(mode = DEFAULT_MODE, resolution = '') {
-  const targetResolution = normalizeMode(mode) === 'capture' ? getResolutionSize(resolution) : null;
+export function buildPageOptions(mode = DEFAULT_MODE, resolution = '', slideMode = DEFAULT_SLIDE_MODE) {
+  const { framePx } = getSlideModeConfig(slideMode);
+  const targetResolution = normalizeMode(mode) === 'capture' ? getResolutionSize(resolution, slideMode) : null;
   return {
     viewport: {
-      width: FALLBACK_SLIDE_SIZE.width,
-      height: FALLBACK_SLIDE_SIZE.height,
+      width: framePx.width,
+      height: framePx.height,
     },
     deviceScaleFactor: normalizeMode(mode) === 'capture'
       ? targetResolution
-        ? targetResolution.height / FALLBACK_SLIDE_SIZE.height
+        ? targetResolution.height / framePx.height
         : DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR
       : 1,
   };
 }
 
-function chooseSlideFrame(metrics) {
+function chooseSlideFrame(metrics, slideMode = DEFAULT_SLIDE_MODE) {
+  const { framePx } = getSlideModeConfig(slideMode);
+  const targetAspectRatio = framePx.width / framePx.height;
   const viewportArea = Math.max(1, metrics.viewport.width * metrics.viewport.height);
   const bodyArea = Math.max(1, metrics.body.width * metrics.body.height);
   const bodyScrollArea = Math.max(1, metrics.body.scrollWidth * metrics.body.scrollHeight);
@@ -269,7 +291,7 @@ function chooseSlideFrame(metrics) {
     .map((candidate) => ({
       ...candidate,
       area: candidate.width * candidate.height,
-      aspectDelta: Math.abs(candidate.width / candidate.height - TARGET_ASPECT_RATIO),
+      aspectDelta: Math.abs(candidate.width / candidate.height - targetAspectRatio),
       coverage: (candidate.width * candidate.height) / viewportArea,
     }))
     .sort((left, right) => right.area - left.area);
@@ -359,7 +381,7 @@ export async function waitForSlideRenderReady(page, options = {}) {
   }, { settleMs, runReadySignal: shouldRunReadySignal });
 }
 
-export async function detectSlideFrame(page) {
+export async function detectSlideFrame(page, slideMode = DEFAULT_SLIDE_MODE) {
   const metrics = await page.evaluate(() => {
     function toBox(element) {
       const rect = element.getBoundingClientRect();
@@ -398,12 +420,13 @@ export async function detectSlideFrame(page) {
     };
   });
 
-  const frame = chooseSlideFrame(metrics);
+  const frame = chooseSlideFrame(metrics, slideMode);
+  const fallbackSize = getSlideModeConfig(slideMode).framePx;
   return {
     x: normalizeDimension(frame.x, 0),
     y: normalizeDimension(frame.y, 0),
-    width: normalizeDimension(frame.width, FALLBACK_SLIDE_SIZE.width),
-    height: normalizeDimension(frame.height, FALLBACK_SLIDE_SIZE.height),
+    width: normalizeDimension(frame.width, fallbackSize.width),
+    height: normalizeDimension(frame.height, fallbackSize.height),
     candidateIndex: Number.isInteger(frame.candidateIndex) ? frame.candidateIndex : null,
     source: frame.source,
   };
@@ -641,20 +664,22 @@ export async function renderSlideToPdf(page, slideFile, slidesDir, options = {})
   const slidePath = join(slidesDir, slideFile);
   const slideUrl = pathToFileURL(slidePath).href;
   const mode = normalizeMode(options.mode ?? DEFAULT_MODE);
+  const slideMode = normalizeSlideMode(options.slideMode ?? DEFAULT_SLIDE_MODE, { optionName: '--slide-mode' });
   const captureResolution = mode === 'capture' ? normalizeResolutionPreset(options.resolution ?? '') : '';
 
   await page.goto(slideUrl, { waitUntil: 'load' });
   await waitForSlideRenderReady(page, options);
 
-  const slideFrame = await detectSlideFrame(page);
+  const slideFrame = await detectSlideFrame(page, slideMode);
   const normalizedSlideFrame = await isolateSlideFrame(page, slideFrame);
   await normalizeBodyToSlideFrame(page, normalizedSlideFrame);
   await waitForSlideRenderReady(page, { ...options, runReadySignal: false });
 
   if (mode === 'capture') {
+    const fallbackSize = getSlideModeConfig(slideMode).framePx;
     const viewportSize = {
-      width: normalizeDimension(normalizedSlideFrame.width, FALLBACK_SLIDE_SIZE.width),
-      height: normalizeDimension(normalizedSlideFrame.height, FALLBACK_SLIDE_SIZE.height),
+      width: normalizeDimension(normalizedSlideFrame.width, fallbackSize.width),
+      height: normalizeDimension(normalizedSlideFrame.height, fallbackSize.height),
     };
     await page.setViewportSize(viewportSize);
     await waitForSlideRenderReady(page, { ...options, runReadySignal: false });
@@ -679,9 +704,10 @@ export async function renderSlideToPdf(page, slideFile, slidesDir, options = {})
         height: viewportSize.height,
       },
     });
-    const normalizedPngBytes = await normalizeCaptureRasterSize(pngBytes, captureResolution);
+    const normalizedPngBytes = await normalizeCaptureRasterSize(pngBytes, captureResolution, slideMode);
     return {
       mode,
+      slideMode,
       width: normalizedSlideFrame.width,
       height: normalizedSlideFrame.height,
       pngBytes: normalizedPngBytes,
@@ -692,6 +718,7 @@ export async function renderSlideToPdf(page, slideFile, slidesDir, options = {})
 
   return {
     mode,
+    slideMode,
     width: normalizedSlideFrame.width,
     height: normalizedSlideFrame.height,
     pdfBytes: await page.pdf(buildPdfOptions(normalizedSlideFrame.width, normalizedSlideFrame.height)),
@@ -740,14 +767,14 @@ async function main() {
   }
 
   const slidesDir = resolve(process.cwd(), options.slidesDir);
-  await ensureSlidesPassValidation(slidesDir, { exportLabel: 'PDF export' });
+  await ensureSlidesPassValidation(slidesDir, { exportLabel: 'PDF export', slideMode: options.slideMode });
   const slideFiles = await findSlideFiles(slidesDir);
   if (slideFiles.length === 0) {
     throw new Error(`No slide-*.html files found in: ${slidesDir}`);
   }
 
   const browser = await chromium.launch({ headless: true });
-  const page = await browser.newPage(buildPageOptions(options.mode, options.resolution));
+  const page = await browser.newPage(buildPageOptions(options.mode, options.resolution, options.slideMode));
   const diagnostics = createSlideDiagnostics();
   diagnostics.attach(page);
   const renderedSlides = [];
@@ -758,6 +785,7 @@ async function main() {
       try {
         const slideResult = await renderSlideToPdf(page, slideFile, slidesDir, {
           mode: options.mode,
+          slideMode: options.slideMode,
           resolution: options.resolution,
         });
         renderedSlides.push(slideResult);

package/scripts/html2pptx.js

@@ -10,6 +10,7 @@ import { ensureOutputDirectory, SLIDE_FILE_PATTERN, sortFigmaSlideFiles } from '
 
 const require = createRequire(import.meta.url);
 const html2pptx = require('../src/html2pptx.cjs');
+const { DEFAULT_SLIDE_MODE, getSlideModeChoices, getSlideModeConfig, normalizeSlideMode } = require('../src/slide-mode.cjs');
 
 const DEFAULT_SLIDES_DIR = 'slides';
 const DEFAULT_OUTPUT = 'output.pptx';
@@ -22,6 +23,7 @@ function printUsage() {
       'Options:',
       `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
       `  --output <path>      Output PPTX file (default: ${DEFAULT_OUTPUT})`,
+      `  --mode <mode>        Slide mode: ${getSlideModeChoices().join('|')} (default: ${DEFAULT_SLIDE_MODE})`,
       '  -h, --help           Show this help message',
       '',
       'Experimental / unstable PPTX export. Treat output as best-effort only.',
@@ -42,6 +44,7 @@ function parseArgs(args) {
   const options = {
     slidesDir: DEFAULT_SLIDES_DIR,
     output: DEFAULT_OUTPUT,
+    mode: DEFAULT_SLIDE_MODE,
     help: false,
   };
 
@@ -74,6 +77,17 @@ function parseArgs(args) {
       continue;
     }
 
+    if (arg === '--mode') {
+      options.mode = normalizeSlideMode(readOptionValue(args, i, '--mode'));
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--mode=')) {
+      options.mode = normalizeSlideMode(arg.slice('--mode='.length));
+      continue;
+    }
+
     throw new Error(`Unknown option: ${arg}`);
   }
 
@@ -87,6 +101,7 @@ function parseArgs(args) {
 
   options.slidesDir = options.slidesDir.trim();
   options.output = options.output.trim();
+  options.mode = normalizeSlideMode(options.mode);
   return options;
 }
 
@@ -118,7 +133,13 @@ async function main() {
   const files = getHtmlSlides(slidesDir);
 
   const pres = new PptxGenJS();
-  pres.layout = 'LAYOUT_WIDE';
+  const { pptxSizeIn } = getSlideModeConfig(options.mode);
+  pres.defineLayout({
+    name: 'SLIDES_GRAB_HTML2PPTX',
+    width: pptxSizeIn.width,
+    height: pptxSizeIn.height,
+  });
+  pres.layout = 'SLIDES_GRAB_HTML2PPTX';
 
   for (const file of files) {
     await html2pptx(resolve(slidesDir, file), pres);

package/scripts/validate-slides.js

@@ -2,6 +2,7 @@
 
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 import { chromium } from 'playwright';
 
 import {
@@ -20,6 +21,9 @@ import {
   selectSlideFiles,
 } from '../src/validation/core.js';
 
+const require = createRequire(import.meta.url);
+const { DEFAULT_SLIDE_MODE } = require('../src/slide-mode.cjs');
+
 export {
   DEFAULT_SLIDES_DIR,
   ensureSlidesPassValidation,
@@ -160,7 +164,7 @@ function peekValidateFormat(args = []) {
   return DEFAULT_VALIDATE_FORMAT;
 }
 
-export async function validateSlides(slidesDir, { selectedSlides = [] } = {}) {
+export async function validateSlides(slidesDir, { mode = DEFAULT_SLIDE_MODE, selectedSlides = [] } = {}) {
   const slideFiles = selectSlideFiles(await findSlideFiles(slidesDir), selectedSlides, slidesDir);
   if (slideFiles.length === 0) {
     throw new Error(`No slide-*.html files found in: ${slidesDir}`);
@@ -171,13 +175,26 @@ export async function validateSlides(slidesDir, { selectedSlides = [] } = {}) {
   const page = await context.newPage();
 
   try {
-    const slides = await scanSlides(page, slidesDir, slideFiles);
-    return createValidationResult(slides);
+    const slides = await scanSlides(page, slidesDir, slideFiles, mode);
+    return createValidationResult(slides, mode);
   } finally {
     await browser.close();
   }
 }
 
+function peekValidateMode(args = []) {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--mode') {
+      return args[i + 1] || DEFAULT_SLIDE_MODE;
+    }
+    if (arg.startsWith('--mode=')) {
+      return arg.slice('--mode='.length) || DEFAULT_SLIDE_MODE;
+    }
+  }
+  return DEFAULT_SLIDE_MODE;
+}
+
 export async function main(args = process.argv.slice(2)) {
   const options = parseValidateCliArgs(args);
   if (options.help) {
@@ -186,7 +203,7 @@ export async function main(args = process.argv.slice(2)) {
   }
 
   const slidesDir = resolve(process.cwd(), options.slidesDir);
-  const result = await validateSlides(slidesDir, { selectedSlides: options.slides });
+  const result = await validateSlides(slidesDir, { mode: options.mode, selectedSlides: options.slides });
   process.stdout.write(formatValidationResult(result, options.format));
   if (result.summary.failedSlides > 0) {
     process.exitCode = 1;
@@ -197,7 +214,7 @@ const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(imp
 
 if (isMain) {
   main().catch((error) => {
-    const failure = createValidationFailure(error);
+    const failure = createValidationFailure(error, peekValidateMode(process.argv.slice(2)));
     process.stdout.write(formatValidationResult(failure, peekValidateFormat(process.argv.slice(2))));
     process.exit(1);
   });

package/skills/slides-grab/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: slides-grab
-description: End-to-end presentation workflow for Codex. Use when making a full presentation from scratch — planning, designing slides, editing, and exporting. PDF is preferred; PPTX/Figma export is experimental / unstable.
+description: End-to-end presentation workflow for Codex. Use when making a full presentation from scratch — planning, designing slides, editing, and exporting. PDF and per-slide PNG are preferred; PPTX/Figma export is experimental / unstable.
 metadata:
-  short-description: Full pipeline from topic to PDF + experimental / unstable PPTX/Figma export
+  short-description: Full pipeline from topic to PDF/PNG + experimental / unstable PPTX/Figma export
 ---
 
 # slides-grab Skill (Codex) - Full Workflow Orchestrator
@@ -48,9 +48,13 @@ Use the installed **slides-grab-design** skill.
 Use the installed **slides-grab-export** skill.
 
 1. Confirm user wants conversion.
-2. Export to PPTX: `slides-grab convert --slides-dir <path> --output <name>.pptx` (**experimental / unstable**)
-3. Export to PDF (if requested): `slides-grab pdf --slides-dir <path> --output <name>.pdf`
-4. Report results.
+2. Pick the primary target:
+   - Card-news / Instagram-style decks → `slides-grab png --slides-dir <path> --slide-mode card-news --resolution 2160p` (see `slides-grab-card-news`).
+   - Widescreen decks → `slides-grab pdf --slides-dir <path> --output <name>.pdf`.
+3. Per-slide PNG (any mode): `slides-grab png --slides-dir <path> --output-dir <path>/out-png --resolution 2160p`.
+4. PPTX (optional, **experimental / unstable**): `slides-grab convert --slides-dir <path> --output <name>.pptx`.
+5. Figma-importable PPTX (optional, **experimental / unstable**): `slides-grab figma --slides-dir <path> --output <name>-figma.pptx`.
+6. Report results.
 
 ---
 

package/skills/slides-grab-card-news/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: slides-grab-card-news
+description: Generate square Instagram-style card news by reusing the slides-grab workflow with card-news mode enabled. Defaults to per-slide PNG export.
+metadata:
+  short-description: Square card-news workflow on top of slides-grab (PNG by default)
+---
+
+# slides-grab Card News Skill (Codex)
+
+Use this when the user wants card news instead of a widescreen presentation.
+
+## Goal
+Reuse the existing slides-grab plan/design/export workflow, but generate **square** outputs optimized for Instagram posts. Per-slide PNG is the default export since Instagram and most card-news distribution channels consume images, not PDFs.
+
+## Workflow
+1. Reuse the normal outline process from `slides-grab-plan`.
+2. During design and review, keep every card at **720pt x 720pt** and run:
+   - `slides-grab validate --slides-dir <path> --mode card-news`
+   - `slides-grab build-viewer --slides-dir <path> --mode card-news`
+   - `slides-grab edit --slides-dir <path> --mode card-news`
+3. During export, **default to per-slide PNG** for Instagram-ready output:
+   - `slides-grab png --slides-dir <path> --slide-mode card-news --resolution 2160p`
+   - Optional `--output-dir <path>/out-png` to choose the output folder (defaults to `<slides-dir>/out-png`).
+4. Only produce PDF/PPTX/Figma when the user explicitly asks for it:
+   - `slides-grab pdf --slides-dir <path> --slide-mode card-news --output <name>.pdf`
+   - `slides-grab convert --slides-dir <path> --mode card-news --output <name>.pptx` (**experimental / unstable**)
+   - `slides-grab figma --slides-dir <path> --mode card-news --output <name>-figma.pptx` (**experimental / unstable**)
+5. Remind the user that PPTX/Figma exports remain experimental / unstable.
+
+## Rules
+- Optimize layouts for square Instagram-style card news, not 16:9 slides.
+- Default the export to `slides-grab png --slide-mode card-news`; only switch to PDF/PPTX/Figma when the user explicitly requests it.
+- Reuse existing design, viewer, editor, and export policy wherever possible.
+- Do **not** implement SNS/Instagram publishing automation.
+- Use the packaged CLI and bundled skills only.

package/skills/slides-grab-design/SKILL.md

@@ -23,20 +23,21 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 ## Workflow
 1. Read approved `slide-outline.md` and extract the `style` field from its meta section.
 2. Load the chosen style's full spec from `src/design-styles-data.js` — colors, fonts, layout, signature elements, and things to avoid. If the meta specifies a custom direction instead of a bundled ID, use that custom direction as the design basis.
-3. Before generating slides, write a quick **visual thesis** (mood/material/energy), a **content plan** (opener → support/proof → detail/story → close/CTA), and the core design tokens (background, surface, text, muted, accent + display/headline/body/caption roles). Ground these tokens in the chosen style's spec.
+3. Before generating slides, write a quick **visual thesis** (mood/material/energy), a **content plan** (opener → support/proof → detail/story → close/CTA), a **system declaration** (reused layout patterns, max two background colors, max two typefaces, image-led vs text-led slides, where section dividers reset tempo), and the core design tokens (background, surface, text, muted, accent + display/headline/body/caption roles). Ground these tokens in the chosen style's spec. Follow `references/beautiful-slide-defaults.md` for the full working model, content discipline, color discipline, and AI slop tropes to avoid.
 4. If you need to confirm or revisit the approved bundled style before designing, re-run `slides-grab list-styles` and open the gallery from `slides-grab preview-styles` so the Stage 2 deck stays aligned with the Stage 1 direction.
 5. Generate slide HTML files with 2-digit numbering in selected `--slides-dir`.
-6. When a slide explicitly needs bespoke imagery, when the user asks for an image, or when stronger imagery would materially improve the slide, prefer `slides-grab image --prompt "<prompt>" --slides-dir <path>` to generate a local asset with Nano Banana Pro and save it under `<slides-dir>/assets/`.
-7. If the deck needs a complex diagram (architecture, workflows, relationship maps, multi-node concepts), create the diagram in `tldraw`, export it with `slides-grab tldraw`, and treat the result as a local slide asset under `<slides-dir>/assets/`.
-8. If the slide needs a local video, store the video under `<slides-dir>/assets/`, reference it as `./assets/<file>`, and prefer a `poster="./assets/<file>"` thumbnail so PDF export uses a stable still image.
-9. If the source video starts on YouTube or another supported page, use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly if needed) to download it into `<slides-dir>/assets/` before saving the slide HTML.
-10. Run `slides-grab validate --slides-dir <path>` after generation or edits.
-11. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
-12. Run the slide litmus check from `references/beautiful-slide-defaults.md` before presenting the deck for review.
-13. Launch the interactive editor for visual review: `slides-grab edit --slides-dir <path>`
-14. Iterate on user feedback by editing only requested slide files, then re-run validation after each edit round.
-15. When the user confirms editing is complete, suggest: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final read-only preview, or proceed to export (PDF/PPTX).
-16. Keep revising until user approves conversion stage.
+6. When a slide needs iconography, prefer Lucide as the default icon library. Use clean Lucide icons before falling back to emoji, and only use emoji when the brief explicitly calls for them.
+7. When a slide explicitly needs bespoke imagery, when the user asks for an image, or when stronger imagery would materially improve the slide, prefer `slides-grab image --prompt "<prompt>" --slides-dir <path>` to generate a local asset with Nano Banana Pro and save it under `<slides-dir>/assets/`.
+8. If the deck needs a complex diagram (architecture, workflows, relationship maps, multi-node concepts), create the diagram in `tldraw`, export it with `slides-grab tldraw`, and treat the result as a local slide asset under `<slides-dir>/assets/`.
+9. If the slide needs a local video, store the video under `<slides-dir>/assets/`, reference it as `./assets/<file>`, and prefer a `poster="./assets/<file>"` thumbnail so PDF export uses a stable still image.
+10. If the source video starts on YouTube or another supported page, use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly if needed) to download it into `<slides-dir>/assets/` before saving the slide HTML.
+11. Run `slides-grab validate --slides-dir <path>` after generation or edits.
+12. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
+13. Run the slide litmus check from `references/beautiful-slide-defaults.md` before presenting the deck for review.
+14. Launch the interactive editor for visual review: `slides-grab edit --slides-dir <path>`
+15. Iterate on user feedback by editing only requested slide files, then re-run validation after each edit round.
+16. When the user confirms editing is complete, suggest: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final read-only preview, or proceed to export (PDF/PPTX).
+17. Keep revising until user approves conversion stage.
 
 ## Rules
 - Keep slide size 720pt x 405pt.
@@ -44,6 +45,7 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 - Put local images and videos under `<slides-dir>/assets/` and reference them as `./assets/<file>`.
 - Allow `data:` URLs when the slide must be fully self-contained.
 - Do not leave remote `http(s)://` image URLs in saved slide HTML; download source images into `<slides-dir>/assets/` and reference them as `./assets/<file>`.
+- Prefer Lucide for default slide iconography. Avoid emoji as the default icon treatment unless the brief explicitly asks for emoji.
 - Prefer `slides-grab image` with Nano Banana Pro for bespoke slide imagery before reaching for remote URLs.
 - If `GOOGLE_API_KEY` (or `GEMINI_API_KEY`) is unavailable or the Nano Banana API fails, ask the user for a Google API key or fall back to web search + download into `<slides-dir>/assets/`.
 - Prefer local videos with a `poster="./assets/<file>"` thumbnail so PDF export uses the still image.
@@ -53,6 +55,10 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 - Treat opening slides and section dividers like posters, not dashboards.
 - Default to cardless layouts; only add a card when it improves structure or comprehension.
 - Use whitespace, alignment, scale, cropping, and contrast before adding decorative chrome.
+- Do not pad slides with filler copy, dummy stats, or decorative iconography — when a slide feels empty, solve it with layout and scale, not invented content.
+- Pull every color from the approved style spec or the user's brand tokens; extend only with harmonic `oklch()` neighbors. Do not invent fresh standalone hex colors mid-slide.
+- Keep body copy at 14pt minimum on a 720pt × 405pt slide and never render any text below the 10pt absolute floor.
+- Avoid AI slop tropes — aggressive gradient backgrounds, left-border accent cards, SVG-drawn imagery, generic font stacks (Inter/Roboto/Arial), and generic 3×2 icon-plus-blurb grids. See `references/beautiful-slide-defaults.md` for the full list.
 - Prefer `tldraw` for complex diagrams instead of recreating dense node/edge diagrams directly in HTML/CSS.
 - Use `slides-grab tldraw` plus `templates/diagram-tldraw.html` when that gives a cleaner, more export-friendly result.
 - Do not present slides for review until `slides-grab validate --slides-dir <path>` passes.
@@ -63,5 +69,5 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 For full constraints and style system, follow:
 - `references/design-rules.md`
 - `references/detailed-design-rules.md`
-- `references/beautiful-slide-defaults.md` — slide-specific art direction defaults adapted from OpenAI's frontend design guidance
+- `references/beautiful-slide-defaults.md` — slide-specific art direction defaults adapted from OpenAI's frontend design guidance and Anthropic's Claude design system guidance (content/color discipline, system declaration, AI slop tropes)
 - `references/design-system-full.md` — archived full design system, templates, and advanced pattern guidance

package/skills/slides-grab-design/references/beautiful-slide-defaults.md

@@ -1,16 +1,28 @@
 # Beautiful Slide Defaults
 
-Slide-specific art direction guidance adapted from OpenAI's frontend design guidance for GPT-5.4. Use it to make HTML slides feel deliberate, premium, and instantly scannable without breaking `slides-grab`'s export constraints.
+Slide-specific art direction guidance adapted from OpenAI's frontend design guidance for GPT-5.4, with additional distilled principles from Anthropic's Claude design system guidance. Use it to make HTML slides feel deliberate, premium, and instantly scannable without breaking `slides-grab`'s export constraints.
 
 ## Working Model
 
-Before building the deck, write two things:
+Before building the deck, write three things:
 
 - **visual thesis** — one sentence describing the mood, material, energy, and imagery treatment
 - **content plan** — opener → support/proof → detail/story → close/CTA or decision
+- **system declaration** — one short paragraph committing to the system you will reuse across the deck
 
 If the style direction is still open, gather visual references or a mood board first. Define the core tokens early: `background`, `surface`, `primary text`, `muted text`, `accent`, plus typography roles for `display`, `headline`, `body`, and `caption`.
 
+### Vocalize the System Before Designing
+
+After the visual thesis and tokens are set, write the system declaration out loud so the deck stays consistent and iteration stays cheap. Name:
+
+- the layout patterns you will reuse for titles, section headers, content, quotes, and closing slides
+- the two background colors (max) you will use to introduce intentional rhythm between sections and content slides
+- the two typefaces max, plus the one accent color that carries focus
+- which slides will be image-led, which will be text-led, and where section dividers reset tempo
+
+A deck without a declared system drifts. Committing to the system up front is the single cheapest way to make the deck feel deliberate.
+
 ## Beautiful Defaults for Slides
 
 - Start with composition, not components.
@@ -34,6 +46,35 @@ Use a narrative rhythm that feels intentional:
 
 Section dividers should reset the visual tempo. Alternate dense proof slides with simpler image-led or statement-led slides so the deck keeps breathing.
 
+## Content Discipline
+
+Every element must earn its place. When a slide feels empty, solve it with layout, scale, whitespace, and a stronger visual anchor — never by inventing filler content.
+
+- Do not pad slides with placeholder copy, dummy stats, or decorative iconography just to fill space.
+- Avoid data slop: invented numbers, vague percentages, and stat strips whose only purpose is to look informational.
+- If you believe a slide needs an extra section, example, page, or call-out beyond the approved outline, ask the user before adding it. The user knows the audience better than you do.
+- Say one thousand no's for every yes. Cutting is a design tool.
+
+## Color Discipline
+
+- Pull every color from the approved style spec in `src/design-styles-data.js` (or the user's brand tokens when they override the bundled style). Do not invent fresh standalone hex colors mid-slide.
+- If the approved palette is too restrictive for a specific slide, extend it harmonically with `oklch()` — derive neighbors from the existing accent or surface — rather than picking a fresh hex from scratch.
+- Keep one accent color per deck. Two background colors max across the entire deck; use them to introduce rhythm between section dividers and content slides, not to decorate individual slides.
+- Every color must trace back to the approved palette or a documented harmonic extension of it.
+
+## AI Slop Tropes to Avoid
+
+Common AI-generated patterns that cheapen a deck instantly. Treat these as anti-patterns unless the brief explicitly asks for them.
+
+- Aggressive full-slide gradient backgrounds used as the primary surface treatment.
+- Rounded-rectangle containers with a solid left-border accent stripe (the AI "accent card" default).
+- Drawing iconography or product imagery with inline SVG shapes — use a real asset or a `data-image-placeholder` box instead.
+- Overused, generic font families: Inter, Roboto, Arial, Fraunces, and OS system stacks. Prefer Pretendard or the style-specified typeface.
+- Emoji as default iconography. Prefer Lucide; emoji is only for briefs that explicitly call for a playful, native-emoji tone.
+- "Feature card grid" 3×2 layouts of icon + heading + two-line blurb used as the generic answer to any content slide.
+- Faux chrome: drop shadows, subtle gradients, and card borders added to decorate empty space instead of carrying meaning.
+- Placeholder-looking real imagery: stock photos that obviously do not match the topic, or AI-generated images with visible artifacts. Prefer a well-composed `data-image-placeholder` over a bad real image.
+
 ## Review Litmus
 
 Before showing the deck, ask:
@@ -43,3 +84,5 @@ Before showing the deck, ask:
 - Is there one real visual anchor, not just decoration?
 - Would this still feel premium without shadows, cards, or extra chrome?
 - Can any line of copy, badge, or callout be removed without losing meaning?
+- Does every color on the slide trace back to the approved style spec or a documented `oklch` harmonic extension of it?
+- Does any slide lean on an AI slop trope? If so, replace it with composition, typography, or real imagery before review.

package/skills/slides-grab-design/references/design-rules.md

@@ -19,6 +19,11 @@ These are the packaged design rules for installable `slides-grab` skills.
 - CSS colors must include `#`
 - Avoid CSS gradients for PPTX-targeted decks
 
+## Icon guidance
+- Prefer Lucide as the default icon library when a slide needs iconography.
+- Avoid emoji as the default icon treatment; only use emoji when the brief explicitly calls for them.
+- Keep icons visually consistent within a deck (stroke weight, size, and color should follow the slide's design tokens).
+
 ## Asset rules
 - Store deck-local assets in `<slides-dir>/assets/`
 - Reference deck-local assets as `./assets/<file>`

package/skills/slides-grab-design/references/detailed-design-rules.md

@@ -24,6 +24,24 @@
 - All text must be inside `<p>`, `<h1>`-`<h6>`, `<ul>`, `<ol>`, or `<li>`.
 - Never place text directly in `<div>` or `<span>`.
 
+## Typography Scale Rules
+- Body copy minimum is 14pt on a 720pt × 405pt slide; prefer 16-20pt so copy reads cleanly at presentation distance and on PDF export.
+- Absolute floor for captions, labels, footnotes, and meta text is 10pt. Never render any text below 10pt.
+- Display and title text should scale well above body copy — prefer 36pt or larger so the slide's main takeaway reads in 3-5 seconds.
+- If content does not fit at the minimum scale, cut content. Do not shrink type to accommodate more.
+- Keep at most two typefaces across the deck. One display/headline face plus one body face is enough.
+
+## Color Usage Rules
+- Pull every color from the approved style spec in `src/design-styles-data.js` or the user-provided brand tokens. Do not invent fresh standalone hex colors mid-slide.
+- If the approved palette cannot cover a specific slide, extend it harmonically with `oklch()` — derive the new color from the existing accent, surface, or background — rather than picking a fresh hex from scratch.
+- Keep one accent color per deck. Two background colors max across the entire deck, used to introduce rhythm between section dividers and content slides.
+- Every CSS color must keep the `#` prefix and survive raster export to PPTX/PDF; avoid non-sRGB values that will flatten unexpectedly.
+
+## Icon Usage Rules
+- Prefer Lucide as the default icon library for slide UI elements, callouts, and supporting visuals.
+- Do not default to emoji for iconography; reserve emoji for cases where the brief explicitly wants a playful or native-emoji tone.
+- Keep icon sizing, stroke weight, and color aligned with the deck's approved design tokens.
+
 ## Workflow (Stage 2: Design + Human Review)
 - After slide generation or edits, run `slides-grab validate --slides-dir <path>`.
 - After validation passes, run `slides-grab build-viewer --slides-dir <path>`.