slides-grab 1.2.5 → 1.3.0

package/skills/slides-grab-plan/references/design-md-to-slides-conversion.md

@@ -0,0 +1,135 @@
+# DESIGN.md → DESIGN.slides.md Conversion
+
+Web-flavored `DESIGN.md` files (Google Stitch / voltagent/awesome-design-md
+convention) describe **marketing websites**: top-nav, hero-band, CTA buttons,
+pricing cards, footer-band, multi-section scrolling pages.
+
+A slide is a **720pt × 405pt single frame, no scroll, no clicks, no nav**.
+Pasting a web design system into slides produces deck pages that look like
+landing pages — wrong slot.
+
+This document is the canonical reference the agent uses to translate a
+DESIGN.md into a sibling `DESIGN.slides.md` that fits the slide medium.
+
+## Output contract
+
+The agent MUST produce a file named `DESIGN.slides.md` next to the source
+`DESIGN.md` at the deck root. The original `DESIGN.md` MUST be left untouched.
+
+`DESIGN.slides.md` MUST contain the following sections, in this order:
+
+```markdown
+---
+version: alpha
+name: <inherited from DESIGN.md `name`>
+description: <one-sentence slide-flavored mood — not a marketing paragraph>
+derived-from: <relative path to source DESIGN.md, e.g. ./DESIGN.md>
+medium: slides-16x9
+colors:
+  <token-name>: <#hex>
+---
+
+## Overview
+One short paragraph describing the slide deck's atmosphere — material, energy,
+typographic voice. No mention of pages, scroll, nav, CTA, pricing, or routes.
+
+## Background
+Solid fills only. List 1-3 canvas modes that alternate across slides.
+
+## Colors
+Markdown table of the slide-active palette. Drop any role that exists only
+for hover/focus/disabled states (those don't apply to static slides).
+
+## Typography
+Two faces: a display face for headlines and a body face for everything else.
+Optionally a mono face for eyebrows / IDs / code motifs. Include working
+font-stack fallbacks (Google Fonts that render in Playwright capture).
+
+## Slide Layouts
+Enumerate the slide archetypes this design system supports. ALWAYS include
+at least these five:
+- **Cover** — single dominant headline, no nav, no CTA buttons
+- **Section divider** — short anchor headline, optional eyebrow
+- **Content** — copy + single supporting visual (60/40 or 50/50 split)
+- **Statistic** — one oversized number, one short caption
+- **Closing** — final thesis line, footer/page-number strip
+
+For each layout, describe the dominant rhythm in 1-3 bullets — what scale
+carries the slide, what's allowed in the corners, what's NOT allowed.
+
+## Signature Motifs
+Two-to-five small visual elements that make the deck recognizably this brand.
+Examples: a colored underline, a strike-through wordmark, a dot cluster,
+a serif italic accent on one word per slide. Each motif MUST be reproducible
+purely with inline HTML + CSS on a single slide.
+
+## Avoid
+Explicit list of web-only patterns the slides MUST NOT carry. ALWAYS include:
+- top-nav bars, sticky headers, menu rows
+- clickable CTA buttons ("Sign up", "Start free trial", "Read docs")
+- multi-column footer-bands beyond a single thin strip with attribution + page number
+- pricing tier grids
+- hover/focus/active state styling
+- atmospheric multi-stop gradients (unless the source spec mandates them)
+Plus any AVOID rules carried over from the source DESIGN.md.
+
+## Source mapping (for traceability)
+A short bullet list showing how each web concept was mapped. Format:
+- `<web concept from DESIGN.md>` → `<slide concept in DESIGN.slides.md>` OR `dropped`
+```
+
+## Web → slide mapping rules
+
+Apply these mappings while converting. The left column is what DESIGN.md
+contains; the right column is the slide-appropriate replacement.
+
+| DESIGN.md (web) | DESIGN.slides.md (slide) |
+|---|---|
+| `top-nav` / sticky header | A 12pt-tall mono **eyebrow strip** at the top of each slide with section number + brand wordmark — never a horizontal menu of items |
+| `hero-band` (h1 + sub + dual CTA + illustration card) | **Cover layout** — single oversized headline, single sub, footer strip with page number. CTA buttons → discarded (no clicks possible). Illustration card → optional single visual anchor |
+| `feature-card grid (3-up / 4-up)` | **Content layout** with 3-up grid OK, but cards must be cardless-leaning (whitespace-driven) — drop the marketing icon + blurb pattern, prefer pull quotes or per-track/per-member rows |
+| `pricing tier grid` | **Discard entirely** — pricing has no slide analogue |
+| `connector tile grid` | **Discard or convert to small badge row** — never a 4×4 grid of generic logos |
+| `CTA banner` (full-bleed coral / brand) | **Section divider** or **closing** layout — keep the full-bleed color, replace CTA buttons with a thesis sentence and a page number |
+| `product-mockup-card-dark` (code editor screenshot card) | **Content motif** — fine to keep as a single dark surface inside a content slide, but it can NOT dominate every slide |
+| `footer-band` (4-column legal/sitemap) | **Single thin footer strip** — at most 1 line: brand wordmark left, page number right |
+| `button-primary` / `button-secondary` | **Kicker text only** — write the verb as plain text ("Read the next issue") without box/border/click affordance |
+| Hover / focus / pressed / disabled states | **Drop all of them** — slides are static |
+| Multi-stop atmospheric gradients | **Drop unless source spec calls for one or two** — convert to a single accent shape |
+| Spike-mark / asterisk-style brand glyph | **Keep as a small motif** — inline SVG at the slide eyebrow or footer |
+
+## Preservation rules (do NOT translate away)
+
+The conversion MUST carry over from DESIGN.md unchanged:
+
+- The **color palette** (canvas, surface, ink, primary accent, secondary accents)
+- The **type pairing** — display face vs body face vs mono face
+- The **mood / atmosphere** — warm-editorial vs dark-product vs pastel-pop is the
+  whole reason the user imported this DESIGN.md; the slide deck must still feel
+  like the source brand
+- **Brand-specific signature motifs** (spike-mark, hard offset shadow, slab-serif italic
+  accent, etc.) — translate the surface, not the identity
+
+## Process checklist for the agent
+
+1. Read `./DESIGN.md` in full.
+2. Identify which sections are web-only and slot them through the mapping table.
+3. Identify the design tokens (colors, type, spacing) that survive unchanged.
+4. Draft `./DESIGN.slides.md` using the Output Contract template.
+5. Show the user a short summary: 5–10 lines covering kept tokens + dropped
+   web sections + new slide layouts inferred.
+6. Wait for explicit user approval ("looks good" or specific edits) before
+   moving to outline / slide generation.
+7. Once approved, record `style: ./DESIGN.slides.md` in `slide-outline.md`.
+
+## When DESIGN.slides.md should be re-converted
+
+Suggest a re-conversion when:
+- The source `DESIGN.md` is replaced / re-imported with a different brand
+- The user explicitly asks for a different deck flavor (e.g. "more editorial",
+  "less code-heavy")
+- A slide deck visibly carries web-only artifacts (nav bars, CTAs, footers
+  with link columns) that the current DESIGN.slides.md doesn't forbid
+
+A `DESIGN.slides.md` is never regenerated automatically. It is the agent's
+job, in conversation with the user.

package/src/design-import.js

@@ -0,0 +1,164 @@
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const ALLOWED_PROTOCOLS = new Set(['https:']);
+
+function getHeader(headers, name) {
+  if (!headers) return '';
+  if (typeof headers.get === 'function') return headers.get(name) ?? '';
+  return headers[name] ?? headers[name.toLowerCase()] ?? '';
+}
+
+function validateFinalDesignUrl(rawUrl, { allowedProtocols = ALLOWED_PROTOCOLS } = {}) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch (cause) {
+    throw new DesignImportError(`Invalid final URL after redirects: ${rawUrl}`, { cause });
+  }
+  if (!allowedProtocols.has(url.protocol)) {
+    throw new DesignImportError(
+      `Redirect final URL protocol ${url.protocol} is not allowed. Allowed: ${[...allowedProtocols].join(', ')}`,
+    );
+  }
+  return url;
+}
+
+async function readResponseBody(response, { maxBytes }) {
+  if (response.body && typeof response.body.getReader === 'function') {
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const chunk = Buffer.from(value);
+        total += chunk.byteLength;
+        if (total > maxBytes) {
+          if (typeof reader.cancel === 'function') {
+            await reader.cancel().catch(() => {});
+          }
+          throw new DesignImportError(
+            `DESIGN.md exceeds max size (${total} > ${maxBytes} bytes).`,
+          );
+        }
+        chunks.push(chunk);
+      }
+    } finally {
+      if (typeof reader.releaseLock === 'function') reader.releaseLock();
+    }
+    return Buffer.concat(chunks, total);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (buffer.byteLength > maxBytes) {
+    throw new DesignImportError(
+      `DESIGN.md exceeds max size (${buffer.byteLength} > ${maxBytes} bytes).`,
+    );
+  }
+  return buffer;
+}
+
+export class DesignImportError extends Error {
+  constructor(message, { cause } = {}) {
+    super(message);
+    this.name = 'DesignImportError';
+    if (cause) this.cause = cause;
+  }
+}
+
+export function validateDesignUrl(rawUrl, { allowedProtocols = ALLOWED_PROTOCOLS } = {}) {
+  if (typeof rawUrl !== 'string' || rawUrl.trim() === '') {
+    throw new DesignImportError('Design URL is required.');
+  }
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch (cause) {
+    throw new DesignImportError(`Invalid URL: ${rawUrl}`, { cause });
+  }
+  if (!allowedProtocols.has(url.protocol)) {
+    throw new DesignImportError(
+      `URL protocol ${url.protocol} is not allowed. Allowed: ${[...allowedProtocols].join(', ')}`,
+    );
+  }
+  return url;
+}
+
+export async function fetchDesignMarkdown(rawUrl, options = {}) {
+  const {
+    fetchImpl = globalThis.fetch,
+    maxBytes = DEFAULT_MAX_BYTES,
+    timeoutMs = 15000,
+    allowedProtocols,
+  } = options;
+
+  if (typeof fetchImpl !== 'function') {
+    throw new DesignImportError('No fetch implementation available; Node.js >= 18 required.');
+  }
+  const url = validateDesignUrl(rawUrl, { allowedProtocols });
+
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+  let response;
+  try {
+    response = await fetchImpl(url.toString(), {
+      redirect: 'follow',
+      signal: controller.signal,
+      headers: { 'User-Agent': 'slides-grab/import-design (+https://github.com/NomaDamas/slides-grab)' },
+    });
+
+    const finalUrl = validateFinalDesignUrl(response.url ?? url.toString(), { allowedProtocols });
+
+    if (!response.ok) {
+      throw new DesignImportError(`Fetch returned HTTP ${response.status} for ${url}`);
+    }
+
+    const contentType = getHeader(response.headers, 'content-type');
+    const looksLikeText = contentType === '' ||
+      contentType.includes('text/') ||
+      contentType.includes('markdown') ||
+      contentType.includes('application/octet-stream');
+    if (!looksLikeText) {
+      throw new DesignImportError(
+        `Refusing to import non-text response (content-type: ${contentType}).`,
+      );
+    }
+
+    const buffer = await readResponseBody(response, { maxBytes });
+    const text = buffer.toString('utf8');
+    return {
+      url: finalUrl.toString(),
+      contentType,
+      bytes: buffer.byteLength,
+      fetchedAt: new Date().toISOString(),
+      text,
+    };
+  } catch (cause) {
+    if (cause instanceof DesignImportError) throw cause;
+    throw new DesignImportError(`Fetch failed for ${url}: ${cause.message}`, { cause });
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+
+export function formatImportedDesignMarkdown({ url, content, fetchedAt }) {
+  const banner = [
+    '<!--',
+    `  Imported by slides-grab import-design`,
+    `  source: ${url}`,
+    `  fetched-at: ${fetchedAt}`,
+    '-->',
+    '',
+  ].join('\n');
+  return `${banner}${content}\n`;
+}
+
+export function saveImportedDesign({ outputPath, markdown }) {
+  const absolutePath = resolve(outputPath);
+  writeFileSync(absolutePath, markdown, 'utf8');
+  return absolutePath;
+}