Slidev presentation skills: strategy, branding, interactive demos, markdown slides, syntax, code blocks, export, and troubleshooting

version
0.2.11
GitHub stars
27

Install

/plugin install slidev@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 8

Slidev Code Blocks

Code presentation features including highlighting, editor integration, and animated transitions.

For code block syntax, highlighting options, and editor configuration, see references/code.md.

Anti-fabrication

This skill follows core:anti-fabrication. Verified claim-by-claim against live slidevjs/slidev source (claude-skills-223, 2026-08-05) — line-highlighting and Magic Move against docs/features/line-highlighting.md and docs/features/shiki-magic-move.md (added the undocumented {hide}/{none} line values and Magic Move's {at:}/duration/ title-bar options); code groups against docs/features/code-groups.md (corrected: groups require comark: true, not mdc: true — mdc is a deprecated-but-working alias); Monaco editor against docs/features/monaco-editor.md and packages/types/src/ frontmatter.ts (all confirmed, no changes); import-snippet against docs/features/ import-snippet.md (confirmed exact match including the "since v0.47.0" version claim). The finally code-block option was independently re-verified against source (CodeBlockWrapper.vue's prop declaration) after two earlier revisions of this pass wrongly called it nonexistent from a docs-only search. Re-verify against a fresh slidevjs/slidev clone before asserting a code-block feature this skill doesn't cover.

Slidev Export

Export presentations to PDF, PPTX, PNG, and build static SPA sites.

For export commands, format options, CLI flags, and build configuration, see references/export.md.

Anti-fabrication

This skill follows core:anti-fabrication. Verified claim-by-claim against live slidevjs/slidev source (claude-skills-223, 2026-08-05): the export CLI flags against packages/slidev/node/commands/export.ts (getExportOptions) — all existing defaults confirmed (format=pdf, timeout=30000, dark=false, omit-background=false, wait-until=networkidle), --wait's documented default corrected from blank to 0, and --per-slide/--scale added as real flags the skill previously omitted; the dev/ build/eject CLI against packages/slidev/node/cli.ts — added the entirely undocumented export-notes command plus --base/--log/--inspect/--tunnel for the dev server and --router-mode for build. Re-verify against slidev export --help / slidev build --help on a current install before asserting a flag this skill doesn't cover — Slidev's CLI surface grows between minor versions.

Slidev Interactive Demos

Guide for embedding interactive demos, mock UIs, and animated workflows in Slidev presentations.

Two Integration Paths

Choose based on portability and integration requirements:

ConcernVue ComponentsIframe / HTML5
Slidev integrationTight — shares state, v-click, themesLoose — isolated sandbox
PortabilityRequires Slidev projectSelf-contained HTML file
ReactivityFull Vue 3 reactivityVanilla JS or any framework
StylingInherits slide themeIndependent CSS
Hot reloadYes (Vite HMR)Requires manual refresh
Best forDemos that respond to clicks, slide contextStandalone prototypes, third-party widgets

For Vue component patterns, see references/vue-components.md. For iframe and standalone HTML patterns, see references/iframe-mocks.md. For animation patterns, see references/animation-patterns.md.

Vue Component Path

Auto-Import

Place .vue files in components/ — Slidev auto-imports them by filename:

components/
├── LoginForm.vue
├── ApiExplorer.vue
└── DashboardWidget.vue

Use directly in slides without import statements:

---
layout: default
---

# Live Demo

<LoginForm />

Reactive State with Vue 3

Use the Composition API for state management:

<script setup>
import { ref, computed } from 'vue'

const step = ref(0)
const steps = ['Input', 'Validate', 'Submit', 'Success']
const currentStep = computed(() => steps[step.value])

function advance() {
  if (step.value < steps.length - 1) step.value++
}
function reset() {
  step.value = 0
}
</script>

Integration with v-click

Wrap components in v-click for progressive reveal, or use $clicks for step-aware behavior:

<v-click>
  <ApiExplorer />
</v-click>

<!-- Or bind clicks inside the component -->
<WorkflowDemo :step="$clicks" />

Inside the component, receive step as a prop and render accordingly:

<script setup>
const props = defineProps({ step: { type: Number, default: 0 } })
</script>

<template>
  <div class="workflow">
    <StepItem v-for="(s, i) in steps" :key="i"
              :active="i === props.step"
              :done="i < props.step" />
  </div>
</template>

Scoped Styles

Use <style scoped> to prevent leaking styles into the slide:

<style scoped>
.demo-container {
  border: 1px solid #e2e8f0;
  border-radius: 8px;
  padding: 1.5rem;
}

.active-step {
  background: var(--slidev-theme-primary, #4f46e5);
  color: white;
}
</style>

Slide-Aware Behavior with $slidev

Access navigation state inside components using the useSlideContext composable:

<script setup>
import { useSlideContext } from '@slidev/client'

const { $slidev } = useSlideContext()

// Current slide number
const slideNo = computed(() => $slidev.nav.currentPage)

// Total clicks on this slide
const clicks = computed(() => $slidev.nav.clicks)

// Check if presenting (vs. browsing)
const isPresenting = computed(() => $slidev.nav.isPresenter)
</script>

Iframe / HTML5 Path

Directory Structure

Place self-contained mocks in public/mocks/:

public/
└── mocks/
    ├── dashboard/
    │   ├── index.html
    │   ├── style.css
    │   └── app.js
    └── login-flow/
        └── index.html   # inline CSS/JS preferred for portability

Slidev iframe Layouts

Use built-in layouts to embed mocks:

---
layout: iframe
url: /mocks/dashboard/index.html
---

Split layouts for side-by-side content:

---
layout: iframe-right
url: /mocks/login-flow/index.html
---

## Login Flow

Walk through the authentication steps:

1. User enters credentials
2. Client validates format
3. Server returns JWT
4. Redirect to dashboard

Importing Existing Mocks

To embed an existing standalone HTML prototype:

  1. Copy the mock to public/mocks/<name>/
  2. Fix relative asset paths — all paths must work from /mocks/<name>/index.html
  3. Bundle external CSS/JS inline or copy dependencies into the mock directory
  4. Reference via url: /mocks/<name>/index.html in slide frontmatter

Asset path checklist:

  • ./style.css works when style.css is in the same directory
  • ../shared/reset.css works if the shared/ directory is within public/
  • Absolute CDN URLs work if network is available during presentation
  • Prefer inline styles/scripts for fully offline presentations

postMessage Communication

Send data from the iframe to the parent slide:

// Inside the mock (iframe)
function notifyParent(event, payload) {
  window.parent.postMessage({ event, payload }, '*')
}

// Example: notify parent when user completes a step
document.querySelector('#submit-btn').addEventListener('click', () => {
  notifyParent('form-submitted', { user: 'demo@example.com' })
})

Listen in the slide (embed in a Vue component):

<script setup>
import { onMounted, onUnmounted, ref } from 'vue'

const lastEvent = ref(null)

function handleMessage(e) {
  if (e.data?.event) lastEvent.value = e.data
}

onMounted(() => window.addEventListener('message', handleMessage))
onUnmounted(() => window.removeEventListener('message', handleMessage))
</script>

Common Mock Templates

Login Flow

Demonstrate authentication UX with three states: input, loading, success.

<!-- components/LoginDemo.vue -->
<script setup>
import { ref } from 'vue'
const state = ref('idle') // idle | loading | success | error
const email = ref('')
const password = ref('')

async function submit() {
  state.value = 'loading'
  await new Promise(r => setTimeout(r, 1200))
  state.value = email.value.includes('@') ? 'success' : 'error'
}
</script>

<template>
  <form class="login-demo" @submit.prevent="submit"
        aria-label="Login demonstration form">
    <div v-if="state === 'success'" role="status" aria-live="polite">
      Signed in as {{ email }}
    </div>
    <template v-else>
      <label for="demo-email">Email</label>
      <input id="demo-email" v-model="email" type="email"
             :disabled="state === 'loading'"
             aria-required="true" />
      <label for="demo-password">Password</label>
      <input id="demo-password" v-model="password" type="password"
             :disabled="state === 'loading'"
             aria-required="true" />
      <button type="submit" :disabled="state === 'loading'"
              :aria-busy="state === 'loading'">
        {{ state === 'loading' ? 'Signing in…' : 'Sign in' }}
      </button>
      <p v-if="state === 'error'" role="alert" class="error">
        Invalid email address — include an @ symbol
      </p>
    </template>
  </form>
</template>

Dashboard Widget

Display metric cards with live-updating values:

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
const metrics = ref([
  { label: 'Requests/s', value: 0 },
  { label: 'Error rate', value: 0 },
  { label: 'P95 latency', value: 0, unit: 'ms' },
])
let interval

onMounted(() => {
  interval = setInterval(() => {
    metrics.value[0].value = Math.floor(800 + Math.random() * 400)
    metrics.value[1].value = (Math.random() * 2).toFixed(2)
    metrics.value[2].value = Math.floor(45 + Math.random() * 60)
  }, 1500)
})
onUnmounted(() => clearInterval(interval))
</script>

<template>
  <div class="dashboard" role="region" aria-label="Live metrics dashboard">
    <div v-for="m in metrics" :key="m.label"
         class="metric-card" aria-live="polite" aria-atomic="true">
      <span class="label">{{ m.label }}</span>
      <span class="value">{{ m.value }}<span v-if="m.unit" class="unit">{{ m.unit }}</span></span>
    </div>
  </div>
</template>

API Request/Response

Show an HTTP interaction step by step:

<script setup>
import { ref } from 'vue'
const phase = ref('idle') // idle | request | response | error
const responseData = ref(null)

async function sendRequest() {
  phase.value = 'request'
  await new Promise(r => setTimeout(r, 900))
  responseData.value = { id: 42, name: 'Widget', status: 'active' }
  phase.value = 'response'
}
</script>

<template>
  <div class="api-demo" role="region" aria-label="API request demonstration">
    <div class="request-panel">
      <code>GET /api/widgets/42</code>
      <button @click="sendRequest" :disabled="phase === 'request'">Send</button>
    </div>
    <div v-if="phase !== 'idle'" class="response-panel"
         aria-live="polite" :aria-busy="phase === 'request'">
      <span v-if="phase === 'request'">Sending…</span>
      <pre v-else>{{ JSON.stringify(responseData, null, 2) }}</pre>
    </div>
  </div>
</template>

Multi-Step Wizard

<script setup>
import { ref, computed } from 'vue'
const steps = ['Account', 'Profile', 'Review', 'Done']
const current = ref(0)
const isLast = computed(() => current.value === steps.length - 1)

function next() { if (!isLast.value) current.value++ }
function back() { if (current.value > 0) current.value-- }
</script>

<template>
  <div class="wizard" role="region" aria-label="Multi-step form">
    <nav aria-label="Progress">
      <ol>
        <li v-for="(s, i) in steps" :key="s"
            :aria-current="i === current ? 'step' : undefined">
          {{ s }}
        </li>
      </ol>
    </nav>
    <div :key="current" class="step-content">
      <h3>Step {{ current + 1 }}: {{ steps[current] }}</h3>
      <p>Demo content for {{ steps[current] }} step.</p>
    </div>
    <div class="wizard-nav">
      <button @click="back" :disabled="current === 0">Back</button>
      <button @click="next" :disabled="isLast">
        {{ isLast ? 'Finish' : 'Next' }}
      </button>
    </div>
  </div>
</template>

Mermaid + Interactive Demo Pairing

Pair a Mermaid workflow diagram with an interactive demo — diagram shows structure, demo lets audience walk through it.

---
layout: two-cols
---

## Auth Flow Diagram

```mermaid
sequenceDiagram
    Client->>Server: POST /login
    Server->>DB: Validate credentials
    DB-->>Server: User record
    Server-->>Client: JWT token
  • Client sends credentials over HTTPS
  • Server validates against hashed password in DB
  • JWT issued with 24h expiry and refresh token
  • Client stores JWT in memory (not localStorage)

::right::

Try It Live

```

Always add annotation bullets below each Mermaid block:

  • Explain what each arrow or node represents
  • Call out constraints, failure modes, or non-obvious design decisions
  • Relate diagram elements to real code or infrastructure

Accessibility Requirements

All interactive demos must meet these requirements. Load design:accessibility for full WCAG guidance.

Keyboard Navigation

  • All interactive controls (buttons, inputs, links) reachable via Tab
  • Custom interactive elements use tabindex="0" and handle keydown for Enter/Space
  • Focus moves logically through the demo without trapping (unless intentional modal)
  • Provide a visible focus indicator — do not remove CSS outline without a replacement
<div role="button" tabindex="0"
     @click="activate"
     @keydown.enter="activate"
     @keydown.space.prevent="activate">
  Activate
</div>

ARIA Roles and Live Regions

  • Use role="region" with aria-label on demo containers
  • Use aria-live="polite" for updates that don't interrupt (metric changes, status)
  • Use aria-live="assertive" only for critical errors requiring immediate attention
  • Use role="alert" for error messages
  • Use role="status" for success confirmations
  • Mark decorative elements with aria-hidden="true"

Form Controls

  • Every input must have an associated <label> via for/id or aria-label
  • Required fields use aria-required="true"
  • Loading states use aria-busy="true" on the button or container
  • Error messages use aria-describedby to link error text to its input

Color Contrast

  • Text must meet 4.5:1 contrast ratio against background (WCAG AA)
  • Interactive component borders and focus indicators must be visible
  • Never use color alone to convey state — pair with text, icon, or pattern

Animation and Motion

  • Wrap animations in @media (prefers-reduced-motion: reduce) checks
  • Provide non-animated fallback for all transitions
  • Avoid content that flashes more than 3 times per second

See references/animation-patterns.md for motion-safe animation examples.

Export Considerations

  • Vue components render during PDF/PPTX export — use $slidev.nav.isPrintMode to detect export/print mode and disable timers. isPresenter is a different flag (true in the presenter dual-window view) and does not indicate export rendering; isExporting does not exist on the nav context at all — verified against packages/client/composables/useNav.ts on the slidevjs/slidev GitHub repo
  • Iframes do not render in exported PDFs — add a static screenshot or description as fallback
  • Use <v-if="!$slidev.nav.isPrintMode"> to hide demo-only elements from exports

References

  • references/vue-components.md — Detailed Vue 3 component patterns, worked examples
  • references/iframe-mocks.md — Standalone HTML5 mock patterns and postMessage examples
  • references/animation-patterns.md — CSS transitions, Vue Transition, reduced-motion patterns

Presentation Strategy and Best Practices

Structured frameworks for planning, structuring, and designing effective presentations for any audience.

Core Frameworks

Problem-First Framing (Pyramid Principle)

Lead with the answer or recommendation first, then supporting evidence. Never open with "how we did it" — open with "what the problem is and what we recommend."

SCQA Structure:

  1. Situation — the stable context the audience already knows
  2. Complication — what changed or went wrong
  3. Question — the question the complication raises
  4. Answer — the recommendation (state this first, then support it)

Apply SCQA to the opening slide before revealing methodology or detail.

See references/frameworks.md for worked SCQA examples and Pyramid Principle depth.

Rule of Threes

Limit each presentation to 3 key messages. Structure each key message with 3 supporting arguments. Use a 3-act arc: setup → confrontation → resolution.

  • Cognitive basis: working memory handles 3 items reliably
  • Apply at the deck level (3 sections) and the slide level (3 bullets max)
  • When you have more than 3 points, find the grouping pattern, not more slides

Assertion-Evidence Slide Design

Every slide follows this structure:

  • Top of slide: A single declarative assertion — 2 lines maximum, ~10-15 words
  • Body: Visual evidence supporting the assertion (diagram, chart, image, table)
  • Target ~20 words total per slide (assertion + any labels)
  • Replace bullet lists with visual evidence wherever possible

Bad assertion (topic label): "Q3 Performance" Good assertion (claim): "Q3 latency dropped 40% after cache rollout"

Guy Kawasaki 10/20/30 Rule

  • Maximum 10 slides per deck
  • Maximum 20 minutes of speaking time
  • Minimum 30pt font size

Apply as a constraint check after structuring the deck. If a draft exceeds 10 slides, identify which slides can merge, become appendix, or be cut.

Nancy Duarte Sparkline

Frame the narrative as a contrast between "what is" (current reality) and "what could be" (future vision). Make the audience the hero of the transformation, not the presenter or product.

Arc: begin at "what is" → rise through "what could be" → call to action.

Presentation Zen Principles

  1. Simplicity — remove everything that does not serve the message
  2. Clarity — one idea per slide, no ambiguity
  3. Restraint — fewer elements, more impact
  4. Harmony — visual consistency across all slides
  5. Connection — design for the audience, not the presenter

Diagram Annotation Requirement

Every mermaid diagram and every .jsx page component MUST include:

  • Accompanying bullet points or a legend explaining each block/node/element
  • %% comment annotations inside the mermaid code block for each major element
  • A note block or annotation slide immediately following complex diagrams

No orphan diagrams. A diagram without explanation is inaccessible to any audience.

Example mermaid with required annotations:

```mermaid
flowchart LR
    %% User initiates the request from their browser
    A[User Browser] -->|HTTPS| B[Load Balancer]
    %% Load balancer distributes across two app instances
    B --> C[App Server 1]
    B --> D[App Server 2]
    %% Both app servers share a single Postgres instance
    C --> E[(Postgres)]
    D --> E
  • User Browser: Client entry point, all traffic over HTTPS
  • Load Balancer: Round-robin distribution, no sticky sessions
  • App Server 1/2: Stateless instances, horizontally scalable
  • Postgres: Single primary, read replicas not shown

## Audience Routing

Detect audience type from context clues (job titles, meeting name, stated goals) and route to the appropriate template guidance.

| Audience | Primary Driver | Template |
|----------|---------------|----------|
| Developers / Engineers | Technical correctness, design rationale | `references/audience-templates.md` → Developer section |
| Non-Technical Stakeholders | Business impact, ROI, clear ask | `references/audience-templates.md` → Stakeholder section |
| Mixed (technical + business) | Progressive disclosure by layer | `references/audience-templates.md` → Mixed section |
| Executive (C-suite) | Decision, risk, cost, timeline | Apply 10/20/30 + Pyramid Principle strictly |

See `references/audience-templates.md` for content structure, tone, and visual approach per audience.

## One-Pager Selection

Choose format based on delivery context:

- **Executive Summary PDF** (`references/one-pagers.md`): Multi-section document, printed or emailed. Use when the audience reads before the meeting or when no live presentation occurs.
- **Single-Slide Overview** (`references/one-pagers.md`): Dense single slide designed for sharing or screen display. Use when the deck will be referenced live or dropped into a chat.

See `references/one-pagers.md` for structure and design guidance for both formats.

## Cognitive Load Principles

- One idea per slide — if two ideas compete, split the slide
- Progressive disclosure — reveal information in the order the audience needs it
- Visual hierarchy — the most important element dominates (size, position, color)
- Whitespace — empty space is not wasted space; it reduces cognitive noise
- Consistency — use the same visual language for the same type of information throughout

## Deck Checklist

Before finalizing any presentation:

1. Does the first slide state the problem and recommendation? (Pyramid Principle)
2. Are there 3 or fewer key messages? (Rule of Threes)
3. Does each slide have a declarative assertion at the top? (Assertion-Evidence)
4. Are all diagrams annotated? (Diagram Annotation Requirement)
5. Does font size stay at or above 30pt? (Kawasaki)
6. Does the narrative contrast current state with future state? (Duarte Sparkline)
7. Is every element on each slide earning its place? (Presentation Zen)

## Templates

Ready-to-use Slidev markdown templates are in `templates/`:

- `developer-deck.md` — Technical audience deck with architecture diagrams and code walkthrough
- `stakeholder-deck.md` — Business audience deck with ROI and call-to-action structure
- `executive-summary.md` — One-pager export template for PDF
- `single-slide-overview.md` — Dense single slide for sharing

## References

- `references/frameworks.md` — Pyramid Principle, SCQA, Assertion-Evidence, Duarte Sparkline, Presentation Zen depth
- `references/audience-templates.md` — Per-audience content structure, tone, and visual approach
- `references/one-pagers.md` — Executive summary PDF and single-slide overview formats

Slidev Presentation Framework

Entry point for Slidev development. Provides an overview and routes to focused skills.

Available Skills

This plugin provides focused skills for specific Slidev topics:

Content Strategy

  • slidev:presentations - Presentation strategy, problem-first framing, rule of threes, audience templates, one-pagers, assertion-evidence design
  • slidev:styles - Brand discovery with Playwright MCP, theme generation, compliance validation, WCAG contrast checks
  • slidev:interactive - Interactive demos, Vue components, iframe mocks, workflow animations, clickable prototypes

Technical Reference

  • slidev:syntax - Slide separators, frontmatter, layouts, MDC syntax, presenter notes, clicks, transitions
  • slidev:code - Code blocks: Shiki highlighting, line highlighting, Monaco editor, Magic Move, TwoSlash, code groups
  • slidev:export - Export to PDF, PPTX, PNG, SPA build, CLI flags
  • slidev:troubleshooting - Common errors, export failures, font issues, configuration debugging

Available Agents

Three agents compose into a pipeline for end-to-end presentation creation:

  • content-strategist (haiku) - Questionnaire for audience, tone, problem framing, key messages. Outputs a content strategy brief
  • brand-discoverer (haiku) - Extracts brand tokens (colors, fonts, spacing) from websites using Playwright MCP. Outputs brand config JSON
  • slide-builder (sonnet) - Builds complete Slidev decks from strategy brief + brand config, applying presentation best practices

Each agent works independently or in sequence. The recommended pipeline:

  1. Run content-strategist to define what the presentation needs
  2. Run brand-discoverer if brand compliance is required
  3. Run slide-builder to construct the deck from both outputs

Quick Start

# Create a new Slidev project
npm init slidev@latest

# Or start from an existing markdown file
npx slidev slides.md

Minimal Slide Deck

---
theme: default
title: My Presentation
---

# Welcome

First slide content

---

# Second Slide

More content here

---
layout: center
---

# Centered Slide

This slide uses the center layout

Project Structure

my-presentation/
├── slides.md          # Main slide content
├── package.json       # Dependencies
├── components/        # Custom Vue components (auto-imported)
├── layouts/           # Custom layouts
├── pages/             # Additional slide files
├── public/            # Static assets
├── styles/            # Custom CSS/UnoCSS
└── snippets/          # External code snippets

Key Concepts

  • Markdown-first: Write slides in Markdown with YAML frontmatter for configuration
  • Vue 3 powered: Use Vue components directly in slides
  • Vite-based: Hot module replacement for instant preview updates
  • Theme ecosystem: Install themes via npm packages (slidev-theme-*)
  • Code-focused: Built-in syntax highlighting, Monaco editor, and animated code transitions
  • Presenter mode: Dual-window mode with notes, timer, and slide navigation

Configuration

Global configuration goes in the first slide's frontmatter:

---
theme: default
title: My Talk
info: |
  Description of the presentation
author: Your Name
download: true
exportFilename: my-talk
highlighter: shiki
lineNumbers: true
drawings:
  persist: false
transition: slide-left
comark: true
---

comark (formerly mdc, still a working but deprecated alias — see the syntax skill) enables Comark/MDC-style component syntax.

See templates/mise.toml for project task definitions.

Slidev Styles

Brand discovery, theme generation, and style validation for Slidev presentations.

Brand Discovery Pipeline Overview

The full brand discovery workflow has four stages:

  1. Navigate to the brand site using Playwright MCP tools
  2. Extract CSS variables and computed styles via browser_evaluate
  3. Parse extracted values into a brand config JSON object
  4. Generate the Slidev theme from the brand config

For step-by-step Playwright extraction details, see references/discovery-pipeline.md. For theme generation details, see references/theme-generation.md. For validation details, see references/validation-checklist.md.

Playwright MCP Tools

Use these tools during brand extraction:

ToolPurpose
browser_navigateOpen the brand site URL
browser_evaluateRun JavaScript to extract CSS vars and computed styles
browser_take_screenshotCapture rendered slides or pages for visual validation
browser_snapshotGet accessibility tree snapshot for structural inspection
browser_closeClose the browser session when extraction is complete

Always call browser_close after extraction to release resources.

Brand Config JSON Schema

Produce a brand config JSON object after extraction. All fields are optional; populate what is available.

{
  "colors": {
    "primary": "#hex",
    "secondary": "#hex",
    "accent": "#hex",
    "background": "#hex",
    "text": "#hex",
    "error": "#hex",
    "success": "#hex"
  },
  "fonts": {
    "heading": "Font Name",
    "body": "Font Name",
    "code": "Monospace Font"
  },
  "spacing": {
    "slide-padding": "value",
    "section-gap": "value"
  },
  "logo": {
    "url": "path/to/logo",
    "position": "top-left|top-right"
  }
}

Save the brand config as brand-config.json in the project root before proceeding to theme generation.

Theme Generation Overview

Convert the brand config to a Slidev theme by:

  1. Creating styles/index.css with CSS custom properties mapped from brand config colors and spacing
  2. Configuring UnoCSS theme extensions in uno.config.ts (or vite.config.ts) with brand colors and font stacks
  3. Adding UnoCSS shortcut classes for common slide patterns (headings, callouts, code blocks)
  4. Loading fonts via Google Fonts import in styles/index.css or placing font files in public/fonts/
  5. Creating a global components/Logo.vue component for logo placement

For complete theme generation with code examples, see references/theme-generation.md.

Validation Overview

After applying a theme, validate compliance by:

  1. Taking screenshots of rendered slides with browser_take_screenshot
  2. Running contrast ratio checks using the WCAG AA formula via browser_evaluate
  3. Verifying rendered font families match the brand spec
  4. Checking all colors against the brand palette within a tolerance of ±5 hex units per channel
  5. Confirming logo placement and sizing

WCAG 2.2 AA requirements (per design:accessibility) — these contrast success criteria (1.4.3, 1.4.11) are unchanged from 2.1:

  • Normal text (< 18pt): minimum contrast ratio 4.5:1
  • Large text (≥ 18pt or ≥ 14pt bold): minimum contrast ratio 3:1
  • UI components and graphical objects: minimum contrast ratio 3:1

For the full validation workflow and automated checks, see references/validation-checklist.md.

Manual Brand Input

When no website is available, gather brand information using this questionnaire:

Brand Color Questionnaire
--------------------------
1. Primary brand color (main CTA, headings): ___
2. Secondary brand color (accents, highlights): ___
3. Background color (slides): ___
4. Body text color: ___
5. Accent/success color (callouts): ___
6. Error/warning color: ___

Font Questionnaire
------------------
7. Heading font (name and weight): ___
8. Body text font: ___
9. Code/monospace font: ___
10. Are fonts hosted on Google Fonts, or do you have local files?

Spacing Questionnaire
---------------------
11. Slide padding (distance from edge to content): ___
12. Gap between major sections: ___

Logo Questionnaire
------------------
13. Logo file URL or local path: ___
14. Logo placement: top-left / top-right / none

Populate the brand config JSON from questionnaire answers, then proceed to theme generation.

Integration with design:accessibility

Load design:accessibility when:

  • Validating contrast ratios for slide text and UI components
  • Reviewing color combinations for color-blindness considerations
  • Checking that information is not conveyed by color alone

Key WCAG requirements that apply to slide presentations:

  • Text on slide backgrounds must meet 4.5:1 contrast ratio (AA)
  • Heading text at large sizes must meet 3:1 contrast ratio
  • Charts and diagrams must have text labels or patterns, not only color
  • Slide transitions and animations must not flash more than 3 times per second

Slidev Theme File Structure

A self-contained brand theme lives in a slidev-theme-brand/ directory:

slidev-theme-brand/
├── package.json          # Theme package with name "slidev-theme-brand"
├── styles/
│   └── index.css         # CSS custom properties and base styles
├── uno.config.ts         # UnoCSS theme extensions and shortcuts
└── components/
    └── Logo.vue          # Global logo component for all slides

Reference the theme from the presentation frontmatter:

---
theme: ./slidev-theme-brand
---

References

  • references/discovery-pipeline.md — Step-by-step Playwright MCP extraction workflow with JavaScript snippets
  • references/theme-generation.md — Converting brand config to UnoCSS theme and CSS variables
  • references/validation-checklist.md — Contrast validation, font verification, and compliance checklist

Slidev Syntax

Slide structure, frontmatter configuration, layouts, and presentation features.

For syntax reference, frontmatter properties, layout catalog, and animation patterns, see references/syntax.md.

Slidev Troubleshooting

Common errors, debugging techniques, and solutions for Slidev development issues.

For error catalogs, debugging patterns, and common solutions, see references/troubleshooting.md.

Agents 3

Load the /slidev:styles skill before any work.

Brand Discoverer Agent

Role: Brand token extraction agent. Visit websites and extract visual identity tokens for use in Slidev themes.

Extraction Workflow

  1. Accept URL(s) from the user or from a content-strategist brief.

  2. Navigate to each URL with mcp__playwright__browser_navigate.

  3. Take a screenshot for reference with mcp__playwright__browser_take_screenshot.

  4. Extract brand tokens with mcp__playwright__browser_evaluate using JavaScript. Run this extraction script:

(() => {
  const root = document.documentElement;
  const computed = getComputedStyle(root);

  // CSS custom properties from :root
  const cssVars = {};
  for (const sheet of document.styleSheets) {
    try {
      for (const rule of sheet.cssRules) {
        if (rule.selectorText === ':root') {
          for (const prop of rule.style) {
            if (prop.startsWith('--')) {
              cssVars[prop] = rule.style.getPropertyValue(prop).trim();
            }
          }
        }
      }
    } catch (e) { /* cross-origin sheet, skip */ }
  }

  // Computed colors from key elements
  const body = document.body;
  const h1 = document.querySelector('h1');
  const link = document.querySelector('a');
  const btn = document.querySelector('button, [class*="btn"], [class*="button"]');
  const header = document.querySelector('header, nav, [class*="header"], [class*="nav"]');

  const getStyle = (el, prop) => el ? getComputedStyle(el).getPropertyValue(prop).trim() : null;

  // Font families
  const fonts = {
    body: getStyle(body, 'font-family'),
    h1: getStyle(h1, 'font-family'),
    h2: getStyle(document.querySelector('h2'), 'font-family'),
  };

  // Colors
  const colors = {
    background: getStyle(body, 'background-color'),
    text: getStyle(body, 'color'),
    heading: getStyle(h1, 'color'),
    link: getStyle(link, 'color'),
    button: getStyle(btn, 'background-color'),
    buttonText: getStyle(btn, 'color'),
    header: getStyle(header, 'background-color'),
  };

  // Logo candidates
  const logos = Array.from(document.querySelectorAll('header img, nav img, [class*="logo"] img, [class*="brand"] img'))
    .map(img => ({ src: img.src, alt: img.alt, width: img.naturalWidth, height: img.naturalHeight }))
    .slice(0, 3);

  // SVG logos
  const svgLogos = Array.from(document.querySelectorAll('header svg, nav svg, [class*="logo"] svg'))
    .map(svg => svg.outerHTML.slice(0, 500))
    .slice(0, 2);

  // Spacing samples
  const spacing = {
    bodyPadding: getStyle(body, 'padding'),
    sectionPadding: getStyle(document.querySelector('section, main, article'), 'padding'),
  };

  return { cssVars, fonts, colors, logos, svgLogos, spacing };
})()
  1. If multiple URLs are provided (e.g., main site + style guide page), run extraction on each and merge results. Prioritize values from the style guide URL over the main site.

  2. Parse the extracted values into brand config JSON matching the schema from the styles skill.

  3. Take a final screenshot for visual reference after extraction.

Fallback Handling

  • CSS vars not available: Use computed styles from the colors section of the extraction result. Do not fabricate values.
  • Async web fonts: If font-family returns a generic family (serif, sans-serif), note "web font — requires manual identification" in the output.
  • Authentication required: Report the barrier to the user and ask for help (e.g., credentials, session cookies). Do not attempt to bypass authentication.
  • Cross-origin stylesheets: The script skips them silently. Note in output if CSS vars section is empty.

Output

Produce two artifacts:

1. Brand Config JSON

{
  "primary": "#hex",
  "secondary": "#hex",
  "background": "#hex",
  "text": "#hex",
  "heading": "#hex",
  "link": "#hex",
  "accent": "#hex",
  "fonts": {
    "sans": "Font Family Name, fallback",
    "mono": "Mono Font, monospace"
  },
  "logo": {
    "url": "https://...",
    "alt": "Brand name"
  }
}

Fill only fields that were successfully extracted. Mark unresolved fields with "requires-manual-check" rather than fabricating values.

2. Extraction Summary

## Brand Extraction Summary

- **URL(s) visited**: [list]
- **CSS custom properties found**: [count] variables
- **Colors extracted**: [list of extracted colors with hex values]
- **Fonts extracted**: [list]
- **Logo found**: [yes/no, source]
- **Gaps requiring manual input**: [list any fields marked requires-manual-check]
- **Screenshots**: [note that screenshots were taken]

Load the /slidev:presentations skill before any work.

Content Strategist Agent

Role: Content strategy questionnaire agent. Discover what the presentation needs before building it.

Questionnaire Workflow

Ask these questions in order. Use the AskUserQuestion tool if available, otherwise ask conversationally. Wait for each answer before proceeding.

  1. Problem: "What problem does this presentation solve?" — Require a clear problem statement before proceeding. Do not continue without one.

  2. Audience: "Who is the primary audience?" — Options: developers/engineers, non-technical stakeholders, mixed, other.

  3. Key Messages: "What are the 3 key messages?" — Enforce the rule of threes. If the user provides more than 3, help them prioritize down to the top 3.

  4. Tone: "What tone is appropriate?" — Options: technical, executive, conversational, educational.

  5. Format: "What format?" — Options: full slide deck, executive summary one-pager, single-slide overview, presentation with interactive demos.

  6. Duration: "Any time constraints?" — Apply 10/20/30 rule guidance based on their answer.

  7. Brand: "Is there a brand guide or website to match?" — If yes, recommend running the brand-discoverer agent and provide the URL(s) to it.

Output

Produce a structured content strategy brief in markdown with all answers organized as a consumable document for the slide-builder agent.

Brief Structure

# Content Strategy Brief

## Problem Statement
[The problem this presentation solves]

## Audience Profile
- Primary audience: [answer]
- Approach: [any special considerations, e.g., progressive disclosure for mixed audiences]

## Key Messages (Rule of Threes)
1. [Message 1]
2. [Message 2]
3. [Message 3]

## Presentation Parameters
- Tone: [answer]
- Format: [answer]
- Duration guidance: [10/20/30 rule applied to their constraints]
- Recommended slide count: [derived from duration]

## Narrative Arc
- Recommended structure: [SCQA or Sparkline — chosen based on audience and problem type]
- Arc rationale: [brief explanation of why this structure fits]

## Brand
- Brand source: [URL or "none"]
- Brand agent needed: [yes/no]

Decision Rules

  • If audience is mixed: recommend a progressive disclosure approach — lead with executive summary slides, follow with technical detail slides that can be skipped if needed.
  • If format is one-pager: note in the brief so slide-builder produces a single-page template.
  • If format includes interactive demos: flag for slide-builder to create Vue components or HTML mocks.
  • Narrative arc selection:
    • SCQA (Situation-Complication-Question-Answer): use for problem-solution presentations to stakeholders.
    • Sparkline (alternating current state / future state): use for change management, product pitches, or motivational content.
  • Reference the presentations skill frameworks when making structural recommendations.

Load these skills before any work:

  • /slidev:presentations (presentation strategy and frameworks)
  • /slidev:syntax (Slidev markdown syntax)
  • /slidev:styles (brand theming — if brand config provided)
  • /slidev:interactive (interactive demos — if mocks needed)
  • /design:accessibility (ensure accessible output)

Slide Builder Agent

Role: Deck construction agent. Build complete Slidev presentations following best practices.

Input Sources

Accept any combination of:

  • Content strategy brief from the content-strategist agent
  • Brand config JSON from the brand-discoverer agent
  • Direct user instructions

Construction Workflow

Step 1: Read Inputs

Read the content strategy brief if provided. Extract:

  • Problem statement
  • Audience type
  • 3 key messages
  • Tone
  • Format (full deck / one-pager / single-slide / interactive)
  • Duration guidance and recommended slide count
  • Narrative arc (SCQA or Sparkline)
  • Brand source URL or "none"

Read the brand config JSON if provided.

Step 2: Set Up Theme

If brand config is provided, create styles/custom.css with CSS variables matching the brand config using the styles skill schema.

If no brand config is provided, use the default Slidev theme without modification.

Step 3: Select Template

Choose audience-appropriate template from the presentations skill:

  • Technical audience: code-heavy template with syntax highlighting, diagram slides
  • Executive audience: minimal text, large assertions, data visualization slides
  • Mixed audience: progressive disclosure layout — exec summary section first, technical detail section second
  • One-pager: single-page condensed layout covering all key messages

Step 4: Build Slide Deck

Construct slides.md following these rules:

Problem-first ordering: First slides establish the problem or need before presenting solutions.

Rule of threes: Structure in 3 sections. Each section has 3 key points. Each point has 3 supporting items.

Assertion-evidence format: Every content slide has:

  • A header that is an assertion (a complete sentence stating the point)
  • A body that provides visual evidence (chart, diagram, code, data — not a restatement of the header)

Narrative arc: Follow SCQA or Sparkline as specified in the brief:

  • SCQA: Slide 1-2 = Situation, Slide 3-4 = Complication, Slide 5 = Question, Slide 6+ = Answer
  • Sparkline: Alternate slides between "current state" and "future state" throughout

Annotated diagrams: Every Mermaid diagram must have a bullet list on the same slide (or notes) explaining each block. No orphan diagrams without explanation.

Presenter notes: Include what to say in every slide's notes section using HTML comment syntax:

<!--
Talking point: [what to say here]
Transition: [how to move to next slide]
-->

Step 5: Handle Special Formats

One-pager format: Build a single slide using a custom layout with a grid of all sections compressed into one view.

Interactive demos: Create Vue components in components/ or HTML mock files in public/mocks/. Reference them in slides with <ComponentName /> or iframe embeds. Load the interactive skill for detailed guidance.

Step 6: Set Up Project Structure

Write these files to disk:

<output-dir>/
├── slides.md              # Main presentation file
├── package.json           # If not present in target dir
└── styles/
    └── custom.css         # Only if brand config provided

Minimal package.json if needed:

{
  "name": "presentation",
  "private": true,
  "scripts": {
    "dev": "slidev",
    "build": "slidev build",
    "export": "slidev export"
  },
  "dependencies": {
    "@slidev/cli": "^0.49.0",
    "@slidev/theme-default": "latest"
  }
}

Step 7: Verify Accessibility

Apply the accessibility skill rules:

  • Color contrast ratio ≥ 4.5:1 for normal text, ≥ 3:1 for large text
  • All images and diagrams have alt text or aria-labels
  • Slide titles are unique and descriptive
  • Do not rely on color alone to convey meaning

Output Confirmation

After writing all files, report:

  • Files written (with absolute paths)
  • Slide count
  • Sections and key messages covered
  • Brand theme applied (yes/no)
  • Run command: npx slidev <path-to-slides.md>
  • Any gaps that require manual input (missing content, unresolved brand fields)

Sponsors

Details

Marketplace
vinnie357/claude-skills
Source
plugins/tools/slidev
Category
Tools
License
MIT
Keywords
slidev, presentation, slides, markdown, vite, branding, interactive, strategy

More from vinnie357/claude-skills

All 33