slide-design

Slide Design

Create presentations with brand colors, typography, and assets baked in from the start, instead of picking a generic style and then replacing everything later.

This skill wraps two engines. It adds a brand setup phase before handing off to the engine's own workflow.

Phase 0: Source Discovery

Read the full source markdown end-to-end before touching anything else — brand setup included. This is the cheapest insurance against building the wrong deck. State explicitly in chat what you are treating as slide content vs. speaker notes vs. internal scaffolding, then confirm with the user via AskUserQuestion BEFORE generating any HTML. Even one round of "what's the source structure here?" beats a full rebuild.

0.A — Detect multi-section structure

Working drafts often split each slide into multiple sections by emoji or comment headers, and the LLM will cheerfully pull from all sections into the projected slide unless you intervene. This is the single most damaging silent failure for /slide-design — speaker notes get printed on the slide. Common patterns:

• 4-emoji split (very common in Chinese decks): **📝 這頁要做什麼** (meta description, NOT for slide) · **💻 ...** (live-demo state, NOT for slide) · **🖥️ 簡報文案** (THIS is slide content) · **📢 講稿** (speaker notes, NOT for slide)
• 2-section split: ## Slide + ## Notes, or <!-- slide --> + <!-- notes -->
• YAML frontmatter sections: slide:, notes:
• Bracketed inline annotations: [looks at audience], [pause here], （停頓）

If detected, ask the user explicitly: "Which section(s) go on the slide? Other sections are speaker notes / internal scaffolding?" Default to the most slide-like section name (🖥️, slide:, etc.) but CONFIRM before building. If the source is plain markdown with no sectioning, treat all body content as slide-eligible — don't invent the structure.

0.B — Strip internal scaffolding

Working drafts often label slides with planning scaffolding the audience never sees. The LLM treats these as part of the slide title or eyebrow; they are NOT. Strip before generation:

• Story-arc / framework tags — Act N · 平凡世界, Hero's Journey: Crossing the Threshold, narrative beats
• Slide IDs / version codes — v4-X, slide-42, r6-draft-3
• Time estimates and pacing notes — · 1.5 min, · 30 sec, (2 min)
• Speaker action meta — "ask the room", "transition to next", "pause", "現場調查", "自我介紹", "情緒高峰 #1", "橋接到下一頁"
• Author comments / TODOs / revision tags — R6 c4, R5 c12, TODO:, <!-- ... -->
• Section-divider intent — section headings like # Act 1 may be grouping markers in the source, not actual slides. Confirm with the user before auto-generating divider slides — those are a design choice, not source content.

0.C — Single confirmation gate

Before moving to Phase 1, package the above into one AskUserQuestion: (a) which section is slide content (if multi-section), (b) confirmation that the scaffolding above will be stripped, (c) whether section-divider slides should be auto-generated. One round is sufficient; skip entirely if the source is plain markdown with no structure.

Phase 1: Brand Setup

After source scope is confirmed, gather brand context. Ask these in a single AskUserQuestion call:

Question 1 — Brand Colors (header: "Brand"): How do you want to set定品牌色？

• "I have a design system file" — give me the path, I'll extract colors
• "I'll give you hex codes" — primary + secondary + background
• "No brand, use a preset" — fall through to the engine's default style picker

Question 2 — Assets (header: "Assets"): Do you have character images or background art?

• "Yes" — give me the folder path, I'll scan for usable images
• "No" — skip, use CSS-only visuals

Question 3 — Engine (header: "Engine"): Which engine do you want to use?

• "frontend-slides (Recommended)" — single HTML file, zero dependencies, animation-rich, scroll-based
• "reveal.js" — arrow-key navigation, fragment animations, speaker notes, vertical slide stacks, Chart.js

Processing Brand Input

If design system file is provided:

1. Read the file
2. Extract color tokens — look for hex codes, RGB values, or CSS custom properties
3. Map to presentation variables:
   • Darkest background color → --bg-primary / --background-color
   • Primary accent (often the brand's signature color) → --accent / --primary-color
   • Secondary accent → --accent-secondary / --secondary-color
   • Text colors (light for dark themes, dark for light themes)
4. Confirm with the user: "I found these brand colors: [show swatches]. Look right?"

If the design system describes colors in prose only (no hex codes):

• Ask the user to provide hex values directly
• OR sample from provided reference images (read images, pick from dominant tones)

If assets folder is provided:

1. Scan for image files (png, jpg, svg, webp)
2. View each image using the Read tool (Claude is multimodal)
3. Categorize: logo, character, background art, screenshot, other
4. Suggest placement: "I found [N] usable images. Here's how I'd use them: [list]"
5. Confirm with the user

SVG logo tinting trick

If you have a black / single-color SVG logo and want to match the brand primary color, use a CSS filter chain (no SVG editing needed):

.brand-mark {
  filter: brightness(0) saturate(100%) invert(77%) sepia(15%) saturate(1250%) hue-rotate(357deg) brightness(92%) contrast(87%);
  /* This chain tints black to ~#CD9D4F (warm gold). */
}

Use codepen.io/sosuke/pen/Pjoqqp or hex-to-css-filter to generate a chain for any target color.

Phase 1.5: Typography Scale

Apply a projection-optimized typography scale before writing any slide-specific CSS. See references/typography-scale.md.

Key rules:

• Any text the audience must read ≥ 17px. Use --fs-body-md as the floor for readable content.
• --fs-micro is for decoration only (slide numbers, step counters). Never for content.
• Define all 8 tokens in :root so slides can reference them consistently.

After brand colors + typography tokens are in place, move to Phase 2.

Phase 2: Hand Off to Engine

After brand + typography setup, invoke the appropriate skill:

• frontend-slides: Use the frontend-slides skill, but skip its Phase 2 (style discovery) — you already have the brand colors. Jump straight to Phase 3 (generation) with the brand palette pre-applied. For atmosphere (corner glows, scene illustrations, character cameos), apply the layered backdrop system — see references/backdrop-system.md.
• reveal.js: Use the revealjs skill. Generate the scaffold, then customize styles.css with the brand colors before filling in content. Use Google Fonts or Fontshare instead of system fonts.

In both cases, pass through all brand colors, typography tokens, and asset paths so the engine uses them from the start.

Phase 2.5: Icon System (Replace Emoji)

If the deck uses emoji as functional pictograms (pipeline icons, status markers, stage glyphs), replace them with vector icons from an inline SVG sprite. Emoji render fuzzy on projectors and differ per OS. See references/icon-system.md.

Three things matter:

• Default .icon-svg { width: 1em; height: 1em } — browsers render <svg> without size at 300×150px; this one rule prevents every icon from exploding
• Phosphor Icons via CDN — cdn.jsdelivr.net/npm/@phosphor-icons/[email protected]/assets/regular/<name>.svg
• Sprite pattern — one <symbol> per icon inside a top-of-body hidden <svg>, referenced via <use href="#icon-name">

Skip this phase if emoji only appear in casual speaker notes or decoration that won't project.

Phase 2.7: Comment-Review Compatibility

If the deck will be deployed via /preview for in-page comment review, bake these 4 things into the output. Without them, the comment markers, margin layer, and export modal can render in subtly broken ways (cards pile up after the last slide, "+ comment" button never appears, mandatory scroll-snap traps the reader before they reach low-anchored cards). See references/preview-overlay-css.md for the deck-specific overrides.

1. Wrap all slides in <main class="doc"> ... </main> — comment-overlay.js gates selection capture on document.querySelector("main.doc"). Slides as direct children of <body> never trigger the "+ comment" affordance.
2. Set <body class="cmt-full-bleed"> on the deck. This is an opt-in mode in /preview's template.html that switches the gutter reserve from margin-right to width: calc(100% - 332px), so viewport-wide slides don't overflow under the reserved gutter when comments exist.
3. Use scroll-snap-type: y proximity (not mandatory) on html. Mandatory snap traps the reader at slide boundaries and prevents scrolling past the last slide to read margin cards anchored low in the doc.
4. .slide { width: 100% } (not 100vw). With the gutter reserved, main.doc shrinks — slides should follow doc width, not the unreserved viewport.

Skip this phase if the deck won't be deployed via /preview for review.

Phase 3: Live Presentation Features (Optional)

If the deck is for a live speaker (not self-browsing), add a step-controlled reveal system so the speaker paces content with space / arrow keys. See references/reveal-system.md.

Covers:

• Keyboard-driven advance/reverse
• Per-slide .reveal elements revealed one at a time
• data-toggle markers for complex multi-element states (honeycomb builds, etc.)
• Global sync functions for SVG decorations tied to legend visibility
• Step counter UI + progress bar
• Headless screenshot pitfalls

Skip this phase if the deck is:

• Embedded in a webpage for self-browsing
• Being exported to PDF
• Simple bullet slides without multi-beat per slide

Background music (optional)

For a live-speaker deck, you can add a soft music bed that fades in when a tagged slide appears and fades out when it leaves. One shared Audio element, a smoothstep requestAnimationFrame fade, target volume ~0.25–0.35 so it sits under the voice — triggered by an IntersectionObserver (frontend-slides) or slidechanged (reveal.js). See references/background-music.md for the per-engine recipe and the autoplay / venue-PA / licensing caveats. The deck-framework-specific data-bgm implementation and a CDP fade-verification harness live in the hana-slides skill.

Phase 4: Content Review (Chinese / CJK)

After writing all slide text, run:

/humanly review slide content in [path]

See references/chinese-guidelines.md for slide-specific Chinese AI-slop patterns that /humanly will flag, plus prewrite guidance to avoid them. Key pitfalls:

• —— em-dash overuse (especially X —— Y reveal structure)
• 不是 X，是 Y negation parallelism repeated across slides
• 金句 / 對仗 taglines on closing lines
• Rule of three inflation
• 其實 / 才是 softener words

Apply all P1 findings from humanly. P2 is judgment call.

CSS Components Library

These are reusable components built for presentations. They're optional — use them when the content calls for it. See references/components.md for the full CSS and HTML.

Basic components

Component	When to use
Skill Card	Showing a named capability with description + tools used
Flow Steps	Sequential process (01 → 02 → 03) with descriptions
Swimlane	Two-party collaboration (left vs right, shared stages in center)
Background Art	Overlaying an image in the corner with gradient fade to background
HITL Bar	Human-in-the-loop divider between automated steps
Lifecycle Nodes	Horizontal chain of stages with arrows (circles + labels)

Advanced layouts

Component	When to use
Full-Bleed Diagonal Split	Before/after or conceptual contrast with two edge-to-edge images
3-2 Honeycomb	5-stage cycle with per-stage metadata (includes offset math to prevent overlap)
24-Hour Circular Clock	Temporal data like cron schedules, daily routines, time-distributed events
Modes × Phases Grid	Process with parallel variants sharing the same phase names
Closed-Loop Diagram	Cyclical process where the visual should loop back
QR Panel (Persistent Sidebar)	Downloadable resources promoted across multiple slides
Skill Card with Command Pill	/slash-command style tools with terminal-purple monospace badges
Equal-Width Pipeline	Horizontal pipeline where N steps stay visually equal-width even with uneven label lengths (grid 1fr auto 1fr auto...)

When generating a presentation, scan the content outline and suggest which components would work well. Don't force components where simple bullet points or text would be clearer.

Utility: PDF Export

When the user wants to export the deck to PDF (handout, archive, chat attachment), use the headless Chrome recipe in references/pdf-export.md. Needs a one-time @media print block in the deck's CSS — it forces 1920×1080 landscape pages and works around Chrome's print-pipeline bug that renders the .bg-art layered mask as black rectangles.

Utility: QR Code Generation

For decks with "scan to download" CTAs:

brew install qrencode
qrencode -o assets/qr.png -s 20 -m 2 "https://example.com"

• -s 20 — 20px per dot (large enough for 3m scan distance)
• -m 2 — 2-dot margin (prevents scanner edge issues)
• QR background must be white (#F2F2F2 or #FFFFFF) for scanner contrast — don't make transparent.

Reference Files

File	Purpose
references/typography-scale.md	8-token projection-optimized scale + application rules
references/icon-system.md	Phosphor sprite pattern + 1em default size + descendant-selector pitfalls
references/backdrop-system.md	Layered slide atmosphere — body grid + corner glow modifiers + .bg-art scene layer + .character cameos
references/reveal-system.md	Step-controlled reveal + data-toggle + SVG sync patterns
references/chinese-guidelines.md	Chinese AI-slop avoidance + /humanly integration
references/components.md	CSS / HTML for 13 reusable layout components
references/pdf-export.md	Headless Chrome recipe + @media print block for landscape 16:9 PDF export (with .bg-art mask workaround)
references/background-music.md	Fade-in/out background music — shared Audio + smoothstep ramp, per-engine triggers (IO / slidechanged) + autoplay / venue-PA / licensing caveats