@troshab/slidev-theme-troshab 0.1.6 → 0.1.8

package/components/Callout.vue

@@ -45,7 +45,6 @@ defineProps<{
   padding: 1rem 1rem 1rem 1.25rem;
   margin-block: 1rem;
   background-color: var(--color-bg-soft);
-  color: var(--color-text);
   border-left: var(--border-accent) solid var(--color-info);
   border-radius: 0 0.375rem 0.375rem 0;
 }

package/components/Metric.vue

@@ -123,7 +123,10 @@ const sizeClasses: Record<string, string> = {
 
 .metric-value {
   font-weight: var(--font-weight-bold);
-  line-height: 1.1;
+  /* IBM Plex Sans glyph box ~1.275 + tabular-nums + bold add ~5% — at h1*1.5 (lg)
+     and gradient text (background-clip: text), browser computes scrollH 5-7% above
+     line-height. 1.4 absorbs the rounding without visible spacing change. */
+  line-height: 1.4;
   font-variant-numeric: tabular-nums;
   white-space: nowrap;
   overflow: hidden;

package/components/Stepper.vue

@@ -267,6 +267,12 @@ function isUpcoming(index: number) {
 .stepper-step {
   display: flex;
   align-items: center;
+  /* Reserve horizontal space for .stepper-marker's transform: scale(1.15) on
+   * active state. Scaled marker's visible box extends ~6px past its layout
+   * box; without padding, step.scrollWidth exceeds clientWidth by 1-3px on
+   * short labels. Per CSS spec, transformed descendants count toward parent
+   * scrollable overflow. */
+  padding: 0 var(--transform-scale-comp);
 }
 
 .stepper-horizontal .stepper-step {

package/components/StyledList.vue

@@ -16,7 +16,7 @@ import type { SemanticColor } from '../composables/useColors'
 import { semanticColorVar } from '../composables/useColors'
 
 const props = withDefaults(defineProps<{
-  marker?: 'disc' | 'number' | 'check' | 'arrow' | 'star' | 'none'
+  marker?: 'disc' | 'number' | 'check' | 'cross' | 'arrow' | 'star' | 'none'
   color?: SemanticColor
   size?: 'sm' | 'md' | 'lg'
   columns?: 1 | 2
@@ -81,6 +81,15 @@ const props = withDefaults(defineProps<{
   font-weight: var(--font-weight-bold);
 }
 
+/* Marker: cross (pairs with check — semantic "mistake/don't/anti-pattern") */
+.styled-list-cross li::before {
+  content: '\2717';
+  position: absolute;
+  left: 0;
+  color: var(--marker-color);
+  font-weight: var(--font-weight-bold);
+}
+
 /* Marker: arrow */
 .styled-list-arrow li::before {
   content: '\2192';
@@ -115,7 +124,7 @@ const props = withDefaults(defineProps<{
   left: 0;
   color: var(--marker-color);
   font-weight: var(--font-weight-bold);
-  font-size: var(--font-size-base);
+  font-size: inherit;
   width: 1.5em;
   text-align: center;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@troshab/slidev-theme-troshab",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "A minimal, universal Slidev theme with flexible layouts and ready-to-use slide templates",
   "author": "troshab",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -39,6 +39,14 @@
     "slidev-addon-fancy-arrow": "^0.16.0",
     "slidev-addon-preload-images": "^0.2.0"
   },
+  "peerDependencies": {
+    "shiki": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "shiki": {
+      "optional": true
+    }
+  },
   "scripts": {
     "dev": "npx concurrently -n dark,light -c magenta,cyan \"slidev example_dark.md --port 30303\" \"slidev example_white.md --port 31313\"",
     "dev:dark": "slidev example_dark.md --port 30303",

package/scripts/generate-component-docs.mjs

@@ -0,0 +1,759 @@
+#!/usr/bin/env node
+/**
+ * generate-component-docs.mjs — Sync component API docs from `.vue` source
+ *
+ * Reads `components/*.vue` entry stubs, extracts:
+ *   1. JSDoc header comment before `defineProps` (component description + prop @params)
+ *   2. `defineProps<{...}>()` / `withDefaults(defineProps<{...}>(), {...})` — props
+ *   3. `<slot name="X" />` usages in template + `useSlots()` refs — slot list
+ *
+ * Updates the matching `.md` file in the visualise-content skill (by default,
+ * `~/.claude/plugins/marketplaces/troshab-own-claude-code/plugins/troshab-own/skills/
+ *  slidev-visualise-content/components/{Name}.md`) between auto-markers:
+ *
+ *   <!-- BEGIN AUTO PROPS -->  …generated Props table…  <!-- END AUTO PROPS -->
+ *   <!-- BEGIN AUTO SLOTS -->  …generated Slots table…  <!-- END AUTO SLOTS -->
+ *   <!-- SCHEMA  …JSON…  -->
+ *
+ * Human-authored sections (## Usage, ## Notes, ## Examples in theme) are never
+ * touched. Missing .md → skeleton is created. Orphan .md (no matching .vue) →
+ * warning printed.
+ *
+ * Flags:
+ *   --theme-dir DIR     (default ~/slidev-theme-troshab)
+ *   --skill-dir DIR     (default visualise-content components folder)
+ *   --check-only        Exit 1 if any .md would change; print diff summary.
+ *   --only NAMES        Comma-separated component names (e.g. Stepper,Callout).
+ *                       Handy when debugging a single component.
+ *   --no-write          Print intended changes to stdout; don't touch files.
+ *
+ * Exit codes:
+ *   0 — all docs in sync (or write succeeded)
+ *   1 — drift detected with --check-only, or orphan/missing component
+ *   2 — fatal parsing error
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs'
+import { join, resolve, dirname, basename } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2)
+function flag(name) { return argv.includes(name) }
+function opt(name, fallback) {
+  const i = argv.indexOf(name)
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : fallback
+}
+function expandTilde(p) { return p.startsWith('~') ? join(homedir(), p.slice(1)) : p }
+
+const THEME_DIR = resolve(expandTilde(opt('--theme-dir', join(__dirname, '..'))))
+const DEFAULT_SKILL_DIR = join(
+  homedir(),
+  '.claude', 'plugins', 'marketplaces', 'troshab-own-claude-code',
+  'plugins', 'troshab-own', 'skills', 'slidev-visualise-content', 'components',
+)
+const SKILL_DIR = resolve(expandTilde(opt('--skill-dir', DEFAULT_SKILL_DIR)))
+const CHECK_ONLY = flag('--check-only')
+const NO_WRITE = flag('--no-write')
+const ONLY = opt('--only', null)
+const ONLY_SET = ONLY ? new Set(ONLY.split(',').map(s => s.trim())) : null
+
+// ─── .vue parser ──────────────────────────────────────────────────────────────
+
+/**
+ * Extract the `<script setup lang="ts">` or plain `<script>` block, the template,
+ * and any top-of-file HTML comment (acts like JSDoc on entry-stub files).
+ * Returns { scriptSrc, templateSrc, headerComment } or null.
+ */
+function splitSfc(src) {
+  const scriptSetupMatch = src.match(/<script\s+setup(?:\s+[^>]*)?>([\s\S]*?)<\/script>/)
+  const plainScriptMatch = src.match(/<script(?:\s+[^>]*)?>([\s\S]*?)<\/script>/)
+  const scriptSrc = scriptSetupMatch ? scriptSetupMatch[1] : (plainScriptMatch ? plainScriptMatch[1] : '')
+  // Greedy + last `</template>` — avoids truncation at inner `<template v-if>`.
+  const templateMatch = src.match(/<template(?:\s[^>]*)?>([\s\S]*)<\/template>/)
+  const headerMatch = src.match(/^\s*<!--([\s\S]*?)-->/)
+  if (!scriptSrc && !headerMatch) return null
+  return {
+    scriptSrc,
+    templateSrc: templateMatch ? templateMatch[1] : '',
+    headerComment: headerMatch ? headerMatch[1] : '',
+    isSetup: !!scriptSetupMatch,
+  }
+}
+
+/**
+ * If the entry-stub does `import X from '../components_base/X.vue'; export default X`,
+ * return the resolved path to the real implementation .vue. Otherwise null.
+ */
+function resolveReExport(scriptSrc, currentFile) {
+  const importMatch = scriptSrc.match(/import\s+\w+\s+from\s+['"]([^'"]+\.vue)['"]/)
+  if (!importMatch) return null
+  const exportMatch = scriptSrc.match(/export\s+default\s+\w+/)
+  if (!exportMatch) return null
+  const rel = importMatch[1]
+  return resolve(dirname(currentFile), rel)
+}
+
+/**
+ * Extract the JSDoc header block right before the first `defineProps` or
+ * `withDefaults(defineProps`. Returns { description, paramDocs } where paramDocs
+ * maps propName → description string.
+ *
+ * If `fallbackHtmlComment` is provided (from an entry-stub <!-- … -->), it's
+ * parsed with the same Props:/Slots:/Usage: rules.
+ */
+function extractHeaderDoc(scriptSrc, fallbackHtmlComment) {
+  const defineIdx = scriptSrc.search(/(?:withDefaults\s*\(\s*)?defineProps\s*</)
+
+  let raw = ''
+  if (defineIdx >= 0) {
+    // Look backward for /** … */ ending just before defineProps.
+    const before = scriptSrc.slice(0, defineIdx)
+    const jsdocMatch = before.match(/\/\*\*[\s\S]*?\*\/(?=\s*(?:const\s+\w+\s*=\s*)?(?:withDefaults\s*\(\s*)?defineProps\s*<|\s*$)/)
+    const allMatches = [...before.matchAll(/\/\*\*[\s\S]*?\*\//g)]
+    raw = jsdocMatch ? jsdocMatch[0] : (allMatches.length ? allMatches[allMatches.length - 1][0] : '')
+  }
+  if (!raw && fallbackHtmlComment) {
+    // Treat the HTML comment as a JSDoc body (lines already look like " * foo"
+    // but may also just be plain lines — normalise accordingly).
+    raw = `/**\n${fallbackHtmlComment}\n*/`
+  }
+  if (!raw) return { description: '', paramDocs: {} }
+
+  // Clean leading " * " and trailing "*/".
+  const lines = raw
+    .replace(/^\s*\/\*\*\s*/, '')
+    .replace(/\*\/\s*$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*\s?/, '').trimEnd())
+
+  const paramDocs = {}
+  const descLines = []
+  let inDescription = true
+
+  for (const line of lines) {
+    const paramMatch = line.match(/^@param\s+\{?[^}]*\}?\s*(\w+)\s*[-—]?\s*(.*)$/)
+    if (paramMatch) {
+      inDescription = false
+      paramDocs[paramMatch[1]] = paramMatch[2].trim()
+      continue
+    }
+    // Some JSDocs list props inline like "value: number — Target number".
+    const inlineParamMatch = line.match(/^\s*(\w+):\s*[^—\-]+[—\-]\s+(.+)$/)
+    if (inlineParamMatch && !inDescription) {
+      paramDocs[inlineParamMatch[1]] = inlineParamMatch[2].trim()
+      continue
+    }
+    // "Props:" section header switches into prop-list mode.
+    if (/^\s*Props:\s*$/i.test(line)) { inDescription = false; continue }
+    if (/^\s*Slots?:\s*$/i.test(line)) { inDescription = false; continue }
+    if (/^\s*Usage:?\s*$/i.test(line)) { inDescription = false; continue }
+    // Stop accumulating once we see a usage example, a code block, or a blank
+    // followed by an HTML-tag line — otherwise multi-line descriptions get
+    // concatenated with embedded `<Component …>` examples.
+    if (inDescription) {
+      const trimmed = line.trim()
+      if (!trimmed) { if (descLines.length) inDescription = false; continue }
+      if (/^</.test(trimmed)) { inDescription = false; continue }
+      descLines.push(trimmed)
+    }
+  }
+
+  // Pass 2 for "Props:" block style ("value: number — description").
+  const propsSectionMatch = raw.match(/Props:\s*\n([\s\S]*?)(?:\n\s*(?:Slots?|Usage|Notes?|Example)s?:|\*\/)/i)
+  if (propsSectionMatch) {
+    for (const line of propsSectionMatch[1].split('\n')) {
+      const m = line.replace(/^\s*\*\s?/, '').match(/^\s*(\w+)[?!:]?\s*(?:[:\-]\s*)?[^—\-]*[—\-]\s+(.+)$/)
+      if (m && !paramDocs[m[1]]) paramDocs[m[1]] = m[2].trim()
+    }
+  }
+
+  return {
+    description: descLines.join(' ').replace(/\s+/g, ' ').trim(),
+    paramDocs,
+  }
+}
+
+/**
+ * Find defineProps<{...}>() or withDefaults(defineProps<{...}>(), {...}).
+ * Returns { propsBlock: string, defaultsBlock: string | null }.
+ */
+function extractPropsBlocks(scriptSrc) {
+  // Locate `defineProps<`.
+  const propsStart = scriptSrc.indexOf('defineProps<')
+  if (propsStart < 0) return null
+
+  // Balanced `<...>` extraction starting at the `<` after defineProps.
+  const openAngle = scriptSrc.indexOf('<', propsStart)
+  if (openAngle < 0) return null
+  let depth = 0
+  let typeStart = openAngle + 1
+  let typeEnd = -1
+  for (let i = openAngle; i < scriptSrc.length; i++) {
+    const c = scriptSrc[i]
+    if (c === '<') depth++
+    else if (c === '>') {
+      depth--
+      if (depth === 0) { typeEnd = i; break }
+    }
+  }
+  if (typeEnd < 0) return null
+  const typeLiteral = scriptSrc.slice(typeStart, typeEnd).trim()
+
+  // Check if wrapped in withDefaults(..., {...}).
+  const withDefaultsIdx = scriptSrc.lastIndexOf('withDefaults', propsStart)
+  let defaultsBlock = null
+  if (withDefaultsIdx >= 0 && withDefaultsIdx < propsStart) {
+    // Locate the comma after defineProps<...>() and the { that starts defaults.
+    const afterClose = scriptSrc.indexOf(')', typeEnd)
+    if (afterClose > 0) {
+      const commaIdx = scriptSrc.indexOf(',', afterClose)
+      if (commaIdx > 0) {
+        const defBraceStart = scriptSrc.indexOf('{', commaIdx)
+        if (defBraceStart > 0) {
+          let bDepth = 0
+          let defEnd = -1
+          for (let i = defBraceStart; i < scriptSrc.length; i++) {
+            const c = scriptSrc[i]
+            if (c === '{') bDepth++
+            else if (c === '}') {
+              bDepth--
+              if (bDepth === 0) { defEnd = i; break }
+            }
+          }
+          if (defEnd > 0) defaultsBlock = scriptSrc.slice(defBraceStart + 1, defEnd).trim()
+        }
+      }
+    }
+  }
+
+  return { propsBlock: typeLiteral, defaultsBlock }
+}
+
+/**
+ * Parse `propName?: type` entries from the props-type literal. Handles union
+ * types (a|b|c), generics, nested arrays.
+ * Returns [{ name, type, required }].
+ */
+function parsePropsBlock(block) {
+  // Strip single-line "// …" and multi-line "/* … */" comments.
+  let stripped = block
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|\s)\/\/[^\n]*/g, (_, p) => p)
+    .trim()
+
+  // Remove outer `{...}` if present — defineProps<{ ... }>() passes the literal
+  // as `{ type?: '...'; title?: string }`; we need to walk inside the object.
+  if (stripped.startsWith('{') && stripped.endsWith('}')) {
+    stripped = stripped.slice(1, -1)
+  }
+
+  const entries = []
+  let depth = 0
+  let current = ''
+  for (let i = 0; i < stripped.length; i++) {
+    const c = stripped[i]
+    if (c === '[' || c === '{' || c === '(') depth++
+    else if (c === ']' || c === '}' || c === ')') depth--
+    // `<` / `>` are tricky: `<T>` increases/decreases depth, but `|`/`>` in
+    // union/comparison contexts would too. For our case the prop-type literal
+    // usually stays balanced with the existing depth tracking.
+    if (c === '<' && /\w/.test(stripped[i - 1] || '')) depth++
+    else if (c === '>' && depth > 0 && stripped[i + 1] !== '=' && stripped[i - 1] !== '=') depth--
+    if ((c === ',' || c === ';' || c === '\n') && depth === 0) {
+      const piece = current.trim()
+      if (piece) entries.push(piece)
+      current = ''
+      continue
+    }
+    current += c
+  }
+  if (current.trim()) entries.push(current.trim())
+
+  const props = []
+  for (const entry of entries) {
+    // propName?: type
+    const m = entry.match(/^(\w+)(\??)\s*:\s*([\s\S]+)$/)
+    if (!m) continue
+    const [, name, optional, rawType] = m
+    props.push({ name, type: rawType.trim(), required: optional !== '?' })
+  }
+  return props
+}
+
+/**
+ * Parse defaults block. Returns propName → default-value (as raw string).
+ */
+function parseDefaultsBlock(block) {
+  if (!block) return {}
+  const out = {}
+  let depth = 0
+  let current = ''
+  for (let i = 0; i < block.length; i++) {
+    const c = block[i]
+    if (c === '<' || c === '[' || c === '{' || c === '(') depth++
+    else if (c === '>' || c === ']' || c === '}' || c === ')') depth--
+    if ((c === ',' || c === '\n') && depth === 0) {
+      addDefault(out, current)
+      current = ''
+      continue
+    }
+    current += c
+  }
+  addDefault(out, current)
+  return out
+}
+function addDefault(out, piece) {
+  const trimmed = piece.trim().replace(/^\/\/.*$/gm, '').trim()
+  if (!trimmed) return
+  const m = trimmed.match(/^(\w+)\s*:\s*([\s\S]+?)$/)
+  if (!m) return
+  out[m[1]] = m[2].trim()
+}
+
+/**
+ * Slots: grep static `<slot name="X" />` + dynamic `<slot :name="`step${i}`" />` +
+ * `slots.XXX` / `slots[`step${i}`]` refs. Dynamic names are emitted in their
+ * raw template form (e.g. "step${i}") so collapseSlots() can render them.
+ * Returns sorted array of unique slot names.
+ */
+function extractSlots(scriptSrc, templateSrc) {
+  const slots = new Set()
+  const staticSlotRe = /<slot(?:\s+name=["']([\w-]+)["'])?[\s\S]*?(?:\/>|>)/g
+  let m
+  while ((m = staticSlotRe.exec(templateSrc))) {
+    slots.add(m[1] || 'default')
+  }
+
+  // Dynamic: <slot :name="`step${...}`" /> or <slot :name="'step' + idx" />.
+  const dynSlotRe = /<slot\s+:name=["']\s*`?([^`"'$]+)(?:\$\{[^}]+\}|[+\s]+[\w.]+)/g
+  while ((m = dynSlotRe.exec(templateSrc))) {
+    slots.add(`${m[1].trim()}N`)
+  }
+
+  // slots[`stepN`] / slots.stepN / $slots.stepN access patterns in script.
+  const accessRe = /(?:\$?slots)[\s]*\[[\s]*`([^`${]+)(?:\$\{[^}]+\})?`[\s]*\]/g
+  while ((m = accessRe.exec(scriptSrc))) {
+    slots.add(`${m[1].trim()}N`)
+  }
+  const dotRe = /(?:\$?slots)\.(\w+)/g
+  while ((m = dotRe.exec(scriptSrc))) slots.add(m[1])
+
+  const noise = new Set(['name', 'value', 'length', 'forEach', 'map'])
+  return [...slots].filter(s => !noise.has(s)).sort()
+}
+
+// ─── Collapse long slot lists (e.g. step1..stepN) ────────────────────────────
+
+function collapseSlots(slots) {
+  // Group patterns like step1, step2, step3 → "step1..step3".
+  const groups = new Map()
+  const singles = []
+  for (const s of slots) {
+    const m = s.match(/^([a-zA-Z]+)(\d+)$/)
+    if (!m) { singles.push(s); continue }
+    const [, prefix, num] = m
+    const arr = groups.get(prefix) || []
+    arr.push(parseInt(num, 10))
+    groups.set(prefix, arr)
+  }
+  const out = [...singles]
+  for (const [prefix, nums] of groups) {
+    nums.sort((a, b) => a - b)
+    if (nums.length === 1) out.push(`${prefix}${nums[0]}`)
+    else out.push(`${prefix}${nums[0]}..${prefix}${nums[nums.length - 1]}`)
+  }
+  return out.sort()
+}
+
+// ─── Markdown table renderers ────────────────────────────────────────────────
+
+function renderPropsTable(props, paramDocs, defaults) {
+  if (!props.length) return '_No props._'
+  const rows = props.map(p => {
+    const def = defaults[p.name] ?? (p.required ? '—' : '—')
+    const desc = (paramDocs[p.name] || '').replace(/\|/g, '\\|')
+    return `| \`${p.name}\` | \`${p.type.replace(/\|/g, '\\|')}\` | \`${def.replace(/\|/g, '\\|')}\` | ${p.required ? 'yes' : 'no'} | ${desc} |`
+  })
+  return [
+    '| Prop | Type | Default | Required | Description |',
+    '|------|------|---------|----------|-------------|',
+    ...rows,
+  ].join('\n')
+}
+
+/**
+ * Scan example_slides/*.md for usages of `<ComponentName`. Returns sorted
+ * array of { file, heading } tuples. `file` is relative to example_slides/.
+ */
+function findExamplesInTheme(themeDir, componentName) {
+  const dir = join(themeDir, 'example_slides')
+  if (!existsSync(dir)) return []
+  const out = []
+  for (const f of readdirSync(dir).sort()) {
+    if (!f.endsWith('.md')) continue
+    let src
+    try { src = readFileSync(join(dir, f), 'utf8') } catch { continue }
+    // Component tag: `<ComponentName` followed by whitespace, `/`, `>`, or end.
+    // Must not be inside a code fence — example_slides occasionally ship
+    // snippets showing wrong usage, but in practice the files are ~10-20 lines
+    // and any occurrence is a demo. So simple match is good enough.
+    const re = new RegExp('<' + componentName + '[\\s/>]', 'm')
+    if (!re.test(src)) continue
+    const headingMatch = src.match(/^#\s+(.+?)\s*$/m)
+    out.push({ file: f, heading: headingMatch ? headingMatch[1] : '(no heading)' })
+  }
+  return out
+}
+
+function renderExamplesTable(examples) {
+  if (!examples.length) return '_No theme example slides reference this component yet._'
+  const rows = examples.map(e => `| [\`${e.file}\`](@../../../../slidev-theme-troshab/example_slides/${e.file}) | ${e.heading.replace(/\|/g, '\\|')} |`)
+  return [
+    '| File | Heading |',
+    '|------|---------|',
+    ...rows,
+  ].join('\n')
+}
+
+function renderSlotsTable(slots, slotDescs = {}) {
+  if (!slots.length) return '_No slots._'
+  const rows = slots.map(s => {
+    const desc = (slotDescs[s] || '').replace(/\|/g, '\\|')
+    return `| \`${s}\` | ${desc} |`
+  })
+  return [
+    '| Slot | Description |',
+    '|------|-------------|',
+    ...rows,
+  ].join('\n')
+}
+
+function renderSchema(name, props, defaults, slots) {
+  const obj = {
+    name,
+    props: Object.fromEntries(props.map(p => {
+      const item = { type: p.type, required: p.required }
+      // Detect pure literal-union enum: `'a' | 'b' | 'c'` (no mixed `string` etc.).
+      const literalMatches = [...p.type.matchAll(/['"]([^'"]+)['"]/g)].map(x => x[1])
+      const residue = p.type.replace(/['"][^'"]+['"]/g, '').replace(/\s*\|\s*/g, '').trim()
+      if (literalMatches.length > 0 && residue === '') {
+        item.enum = literalMatches
+      }
+      if (defaults[p.name] !== undefined) item.default = defaults[p.name]
+      return [p.name, item]
+    })),
+    slots,
+  }
+  return JSON.stringify(obj, null, 2)
+}
+
+// ─── .md updating ────────────────────────────────────────────────────────────
+
+const MARKERS = {
+  propsBegin: '<!-- BEGIN AUTO PROPS -->',
+  propsEnd:   '<!-- END AUTO PROPS -->',
+  slotsBegin: '<!-- BEGIN AUTO SLOTS -->',
+  slotsEnd:   '<!-- END AUTO SLOTS -->',
+  examplesBegin: '<!-- BEGIN AUTO EXAMPLES -->',
+  examplesEnd:   '<!-- END AUTO EXAMPLES -->',
+  schemaBegin: '<!-- SCHEMA',
+  schemaEnd:  '-->',
+}
+
+function replaceBetween(src, begin, end, replacement) {
+  const s = src.indexOf(begin)
+  const e = src.indexOf(end, s + begin.length)
+  if (s < 0 || e < 0) return null
+  return src.slice(0, s + begin.length) + '\n' + replacement + '\n' + src.slice(e)
+}
+
+function upsertSchema(src, jsonBody) {
+  const block = `${MARKERS.schemaBegin}\n${jsonBody}\n${MARKERS.schemaEnd}`
+  const idx = src.indexOf(MARKERS.schemaBegin)
+  if (idx < 0) return src.trimEnd() + '\n\n' + block + '\n'
+  // Replace from schemaBegin up to the next `-->` line.
+  const afterBegin = src.indexOf('\n', idx)
+  const endIdx = src.indexOf(MARKERS.schemaEnd, afterBegin)
+  if (endIdx < 0) return src.trimEnd() + '\n\n' + block + '\n'
+  const trail = src.slice(endIdx + MARKERS.schemaEnd.length)
+  return src.slice(0, idx) + block + trail
+}
+
+function generateSkeleton(name, description, propsTable, slotsTable, examplesTable, schema) {
+  return `# ${name}
+${description ? `\n${description}\n` : ''}
+## Props
+
+${MARKERS.propsBegin}
+${propsTable}
+${MARKERS.propsEnd}
+
+## Slots
+
+${MARKERS.slotsBegin}
+${slotsTable}
+${MARKERS.slotsEnd}
+
+## Usage
+
+_TODO: add representative usage example(s)._
+
+## Notes
+
+_TODO: add constraints, common mistakes, layout tips._
+
+## Examples in theme
+
+${MARKERS.examplesBegin}
+${examplesTable}
+${MARKERS.examplesEnd}
+
+${MARKERS.schemaBegin}
+${schema}
+${MARKERS.schemaEnd}
+`
+}
+
+/**
+ * Pull `| propName | type | default | ... | Description |` tables out of an
+ * existing `.md` so we can preserve the hand-written Description column even
+ * when the schema otherwise gets regenerated.
+ * Returns { propName → description }. Empty if no table found.
+ */
+function readExistingPropDescriptions(md, heading) {
+  const headingIdx = md.search(new RegExp(`^##\\s+${heading}\\s*$`, 'm'))
+  if (headingIdx < 0) return {}
+  const lines = md.slice(headingIdx).split('\n')
+  const out = {}
+  // Find the first header row: `| Prop | ... | Description |`
+  for (let i = 0; i < lines.length; i++) {
+    const row = lines[i]
+    if (!/^\|.*Description\s*\|?$/i.test(row) && !/^\|.*Description\s*\|/i.test(row)) continue
+    // Header row found at i; data rows start at i+2 (i+1 is `|---|---|` separator).
+    for (let j = i + 2; j < lines.length; j++) {
+      const r = lines[j].trim()
+      if (!r.startsWith('|')) break
+      const cells = r.split('|').map(c => c.trim()).filter(c => c.length > 0 || true)
+      // Leading and trailing | create empty cells; strip them.
+      const inner = r.replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => c.trim())
+      if (inner.length < 2) continue
+      const propName = inner[0].replace(/^`|`$/g, '').trim()
+      const desc = inner[inner.length - 1]
+      if (propName && desc) out[propName] = desc
+    }
+    break
+  }
+  return out
+}
+
+function readExistingSlotDescriptions(md) {
+  const headingIdx = md.search(/^##\s+Slots\s*$/m)
+  if (headingIdx < 0) return {}
+  const lines = md.slice(headingIdx).split('\n')
+  const out = {}
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\|\s*Slot\s*\|/i.test(lines[i])) continue
+    for (let j = i + 2; j < lines.length; j++) {
+      const r = lines[j].trim()
+      if (!r.startsWith('|')) break
+      const inner = r.replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => c.trim())
+      if (inner.length < 2) continue
+      const slotName = inner[0].replace(/^`|`$/g, '').trim()
+      const desc = inner[inner.length - 1]
+      if (slotName && desc) out[slotName] = desc
+    }
+    break
+  }
+  return out
+}
+
+function updateMd(currentMd, name, description, props, paramDocs, defaults, slots, slotDescs, examples, schema) {
+  const mergedParamDocs = { ...paramDocs }
+  const mergedSlotDescs = { ...slotDescs }
+  if (currentMd) {
+    const prev = readExistingPropDescriptions(currentMd, 'Props')
+    for (const [k, v] of Object.entries(prev)) {
+      if (!mergedParamDocs[k] || mergedParamDocs[k].length < v.length) mergedParamDocs[k] = v
+    }
+    const prevSlots = readExistingSlotDescriptions(currentMd)
+    for (const [k, v] of Object.entries(prevSlots)) {
+      if (!mergedSlotDescs[k] || mergedSlotDescs[k].length < v.length) mergedSlotDescs[k] = v
+    }
+  }
+
+  const propsTable = renderPropsTable(props, mergedParamDocs, defaults)
+  const slotsTable = renderSlotsTable(slots, mergedSlotDescs)
+  const examplesTable = renderExamplesTable(examples)
+
+  if (!currentMd) return generateSkeleton(name, description, propsTable, slotsTable, examplesTable, schema)
+
+  let out = currentMd
+  out = upsertTableBlock(out, 'Props', MARKERS.propsBegin, MARKERS.propsEnd, propsTable)
+  out = upsertTableBlock(out, 'Slots', MARKERS.slotsBegin, MARKERS.slotsEnd, slotsTable)
+  out = upsertTableBlock(out, 'Examples in theme', MARKERS.examplesBegin, MARKERS.examplesEnd, examplesTable)
+  out = upsertSchema(out, schema)
+  return out
+}
+
+/**
+ * Replace an existing `## Heading` table (|-rows) with a managed BEGIN/END block
+ * that contains the freshly-rendered table. Leaves non-table prose inside the
+ * section untouched (e.g. Stepper's `StepperItem: { … }` note lives on).
+ *
+ * If the markers already exist — simple replace-between.
+ * If the heading exists but no markers — find the first consecutive |-row run
+ * and wrap it with markers, replacing just those lines.
+ * If the heading is missing — append a new section after the previous managed
+ * block (or at EOF).
+ */
+function upsertTableBlock(md, heading, beginMarker, endMarker, table) {
+  // Fast path: markers exist.
+  const replaced = replaceBetween(md, beginMarker, endMarker, table)
+  if (replaced !== null) return replaced
+
+  const headingRe = new RegExp(`^##\\s+${heading}\\s*$`, 'm')
+  const headingMatch = md.match(headingRe)
+  if (headingMatch) {
+    const headingIdx = md.indexOf(headingMatch[0])
+    const afterHeading = md.indexOf('\n', headingIdx) + 1
+    const rest = md.slice(afterHeading)
+    const lines = rest.split('\n')
+    // Find start of the table (first line starting with `|`).
+    let tableStart = -1
+    let tableEnd = -1
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i].trim()
+      if (trimmed.startsWith('##')) break
+      if (tableStart < 0 && trimmed.startsWith('|')) tableStart = i
+      if (tableStart >= 0 && !trimmed.startsWith('|') && tableEnd < 0) {
+        tableEnd = i
+        break
+      }
+    }
+    if (tableStart >= 0) {
+      if (tableEnd < 0) tableEnd = lines.length
+      const before = lines.slice(0, tableStart).join('\n')
+      const after = lines.slice(tableEnd).join('\n')
+      const block = `${beginMarker}\n${table}\n${endMarker}`
+      const rebuilt = [before.trimEnd(), block, after.trimStart()].filter(Boolean).join('\n\n')
+      return md.slice(0, afterHeading) + rebuilt
+    }
+    // Heading exists but no table — inject block right after heading line.
+    const block = `\n${beginMarker}\n${table}\n${endMarker}\n`
+    return md.slice(0, afterHeading) + block + rest
+  }
+
+  // No heading — append at EOF (before any schema comment) as a new section.
+  const schemaIdx = md.indexOf(MARKERS.schemaBegin)
+  const newSection = `\n## ${heading}\n\n${beginMarker}\n${table}\n${endMarker}\n`
+  if (schemaIdx < 0) return md.trimEnd() + '\n' + newSection
+  return md.slice(0, schemaIdx).trimEnd() + '\n' + newSection + '\n' + md.slice(schemaIdx)
+}
+
+// ─── Orchestrate ─────────────────────────────────────────────────────────────
+
+function listVueComponents() {
+  const dir = join(THEME_DIR, 'components')
+  if (!existsSync(dir)) { console.error(`[gen-docs] missing ${dir}`); process.exit(2) }
+  return readdirSync(dir).filter(f => f.endsWith('.vue')).map(f => ({
+    name: basename(f, '.vue'),
+    path: join(dir, f),
+  }))
+}
+
+function listMdDocs() {
+  if (!existsSync(SKILL_DIR)) { mkdirSync(SKILL_DIR, { recursive: true }) }
+  return readdirSync(SKILL_DIR).filter(f => f.endsWith('.md'))
+}
+
+function diffSummary(oldSrc, newSrc) {
+  if (oldSrc === newSrc) return null
+  const oldLines = (oldSrc || '').split('\n').length
+  const newLines = newSrc.split('\n').length
+  return `${oldLines} → ${newLines} lines`
+}
+
+function main() {
+  const components = listVueComponents()
+  const existingMds = new Set(listMdDocs())
+  let changed = 0
+  let errors = 0
+  const orphans = []
+
+  for (const { name, path } of components) {
+    if (ONLY_SET && !ONLY_SET.has(name)) continue
+    const vueSrc = readFileSync(path, 'utf8')
+    const parts = splitSfc(vueSrc)
+    if (!parts) {
+      console.error(`[gen-docs] ${name}: could not parse SFC`)
+      errors++
+      continue
+    }
+
+    // Parse props from this file; if missing and it's a re-export, follow the
+    // import to the real implementation (components_base/X.vue).
+    let propsBlocks = extractPropsBlocks(parts.scriptSrc)
+    let slotsScriptSrc = parts.scriptSrc
+    let slotsTemplateSrc = parts.templateSrc
+    if (!propsBlocks) {
+      const reExport = resolveReExport(parts.scriptSrc, path)
+      if (reExport && existsSync(reExport)) {
+        const baseSrc = readFileSync(reExport, 'utf8')
+        const baseParts = splitSfc(baseSrc)
+        if (baseParts) {
+          propsBlocks = extractPropsBlocks(baseParts.scriptSrc)
+          slotsScriptSrc = baseParts.scriptSrc
+          slotsTemplateSrc = baseParts.templateSrc
+        }
+      }
+    }
+
+    const { description, paramDocs } = extractHeaderDoc(parts.scriptSrc, parts.headerComment)
+    const props = propsBlocks ? parsePropsBlock(propsBlocks.propsBlock) : []
+    const defaults = propsBlocks ? parseDefaultsBlock(propsBlocks.defaultsBlock) : {}
+    const slotsRaw = extractSlots(slotsScriptSrc, slotsTemplateSrc)
+    const slots = collapseSlots(slotsRaw)
+    const examples = findExamplesInTheme(THEME_DIR, name)
+
+    const schema = renderSchema(name, props, defaults, slots)
+
+    const mdPath = join(SKILL_DIR, `${name}.md`)
+    const existingMd = existsSync(mdPath) ? readFileSync(mdPath, 'utf8') : ''
+    existingMds.delete(`${name}.md`)
+
+    const newMd = updateMd(existingMd, name, description, props, paramDocs, defaults, slots, {}, examples, schema)
+    const diff = diffSummary(existingMd, newMd)
+    if (diff) {
+      changed++
+      if (CHECK_ONLY) console.log(`[drift] ${name}.md — ${diff}`)
+      else if (NO_WRITE) console.log(`[would-write] ${name}.md — ${diff}`)
+      else { writeFileSync(mdPath, newMd, 'utf8'); console.log(`[write] ${name}.md — ${diff}`) }
+    }
+  }
+
+  // Orphans — .md files in skill-dir with no matching .vue.
+  for (const md of existingMds) {
+    if (ONLY_SET) continue
+    orphans.push(md)
+  }
+  if (orphans.length) {
+    console.log(`[orphan] ${orphans.length} .md file(s) without matching .vue in theme:`)
+    for (const o of orphans) console.log(`  ${o}`)
+  }
+
+  if (CHECK_ONLY) {
+    if (changed > 0 || errors > 0 || orphans.length > 0) process.exit(1)
+    console.log('[gen-docs] All docs in sync')
+    process.exit(0)
+  }
+
+  console.log(`[gen-docs] ${components.length} components, ${changed} updated, ${errors} error(s), ${orphans.length} orphan(s)`)
+  process.exit(errors > 0 ? 2 : 0)
+}
+
+main()

package/setup/shiki.ts

@@ -15,9 +15,10 @@ const theme = createCssVariablesTheme({
 })
 
 /**
- * Transformer that adds `data-lang` attribute to <pre> elements.
- * CSS in base.css uses `::before { content: attr(data-lang) }` to render
- * a language label bar above every code block.
+ * Transformer that adds `data-lang` and `data-filename` attributes to <pre>.
+ * CSS in base.css uses:
+ *   ::before { content: attr(data-lang) }     — language label, left
+ *   ::after  { content: attr(data-filename) }  — filename label, right
  */
 const langLabelTransformer: ShikiTransformer = {
   name: 'lang-label',
@@ -26,6 +27,14 @@ const langLabelTransformer: ShikiTransformer = {
     if (lang && lang !== 'text') {
       node.properties['data-lang'] = lang
     }
+    // Parse {filename="..."} from code block meta
+    const meta = this.options.meta?.__raw
+    if (meta) {
+      const match = meta.match(/filename=["']([^"']+)["']/)
+      if (match) {
+        node.properties['data-filename'] = match[1]
+      }
+    }
   },
 }
 

package/styles/base.css

@@ -52,19 +52,24 @@
   --font-weight-semibold: 600;
   --font-weight-bold: 700;
 
-  /* --- Line Heights (role-based) --- */
-  --line-height-heading: 1.15;    /* tight for 1-2 line headings */
-  --line-height-body: 1.35;       /* slides with short text blocks */
-  --line-height-reading: 1.5;     /* longer paragraphs, BDA recommended */
-  --line-height-list: 1.4;
-  --line-height-code: 1.4;
+  /* --- Line Heights (role-based) ---
+     Chung (2004, Vision Research): optimal 1.25-1.5 for body.
+     Bringhurst "Elements of Typographic Style": headings 1.1-1.25, body 1.3-1.5.
+     Kolers et al. (1981): reading speed U-curve — extremes reduce speed. */
+  --line-height-heading: 1.3;     /* IBM Plex Sans glyph box (1.275) + safety margin */
+  --line-height-body: 1.4;        /* Chung mid — comfortable for slides */
+  --line-height-reading: 1.5;     /* Chung upper — BDA recommended for paragraphs */
+  --line-height-list: 1.4;        /* matches body for consistency */
+  --line-height-code: 1.5;        /* mono needs more room due to fixed glyph width */
 
   /* --- Letter & Word Spacing (dyslexia-friendly) ---
-     Zorzi et al. (2012, PNAS): letter-spacing reduces crowding.
-     BDA 2018: word/letter ratio >= 3.5x. Ours: 4.0x (above minimum). */
-  --letter-spacing-body: 0.02em;
-  --word-spacing-body: 0.08em;
-  --letter-spacing-heading: 0.01em;
+     Zorzi et al. (2012, PNAS 109:11455): letter-spacing +20% reading speed.
+     Pelli et al. (2007): crowding as dyslexic bottleneck → space symbols.
+     BDA 2018: word/letter ratio >= 3.5x. Ours: 4.0x (above minimum).
+     Presentation tradeoff: full BDA (0.12em/0.16em) too wide for large display type. */
+  --letter-spacing-body: 0.025em;        /* slight spacing — Zorzi crowding benefit */
+  --word-spacing-body: 0.1em;            /* word/letter ratio = 4.0x (BDA >= 3.5x) */
+  --letter-spacing-heading: 0.005em;     /* near-neutral — large headlines don't need extra spacing */
 
   /* --- Spacing System (8-point grid) ---
      Based on 8px base unit for visual rhythm.
@@ -94,15 +99,43 @@
   --slide-padding: var(--space-lg);
   --slide-gap: var(--space-sm);
 
-  /* --- Safe-zone for projectors/TV overscan (5% default) --- */
-  --safe-inset-x: 5%;
-  --safe-inset-y: 5%;
+  /* --- Safe-zone for projectors/TV overscan ---
+     SMPTE RP 27.3: 5% action-safe zone. Equal inset on all sides — asymmetric % causes
+     aspect-ratio dependent visual shift. Using rem keeps proportional across canvas sizes. */
+  --safe-inset-x: 3rem;           /* ~94px at 31.347px root */
+  --safe-inset-y: 3rem;           /* equal to x for symmetric safe zone */
 
   /* --- Border Width Tokens (rem-based, scale with canvas) --- */
   --border-thin: 0.0625rem;     /* ≈ 1px at 980 → ~2px at 1920 */
   --border-medium: 0.125rem;    /* ≈ 2px → ~4px */
   --border-thick: 0.1875rem;    /* ≈ 3px → ~6px */
   --border-accent: 0.25rem;     /* ≈ 4px → ~8px */
+
+  /* --- Fine spacing (< 8px, for tight UI elements) --- */
+  --space-3xs: 0.125rem;        /* 2px */
+  --space-2xs: 0.25rem;         /* 4px */
+  --space-xs-fine: 0.375rem;    /* 6px */
+  --space-tight: 0.75rem;       /* 12px — between xs and sm */
+  --space-code-pt: 2.25rem;     /* 36px — code block top padding (for lang label) */
+
+  /* --- Border Radius Tokens --- */
+  --radius-xs: 0.25rem;         /* 4px — inline code */
+  --radius-sm: 0.375rem;        /* 6px — buttons, small cards */
+  --radius-md: 0.5rem;          /* 8px — cards, panels */
+  --radius-pill: 9999px;        /* full pill shape */
+
+  /* --- Transform Compensation ---
+     Padding to compensate for transform: scale() visual overflow beyond layout box.
+     Calculated for scale(1.15) on medium elements (~63px markers).
+     Formula: (scale - 1) * element_size / 2 ≈ 4.7px per side. */
+  --transform-scale-comp: 0.1875rem;  /* 6px — for scale(1.15) on 63px elements */
+
+  /* --- Typography ratios (em-based, font-size relative) --- */
+  --font-size-smaller: 0.8em;           /* for <sup>, <sub>, <small> */
+  --letter-spacing-emphasis: 0.05em;    /* for small uppercase labels */
+  --underline-offset: 0.15em;           /* text-underline-offset */
+  --em-quarter: 0.25em;                 /* list item spacing */
+  --em-half: 1.5em;                     /* indent / nested */
 }
 
 /* ============================================
@@ -138,6 +171,17 @@
   text-align: left;
 }
 
+/* Mixed-font line-box fix: <p>/<li> containing inline <code> mix IBM Plex Sans
+ * and Plex Mono glyph metrics. Mono's effective descent is slightly larger
+ * than Sans at the same font-size, so the line box expands by ~1px — which
+ * rounds up to scrollHeight > clientHeight. Bumping line-height from 1.4 to
+ * 1.45 on these specific paragraphs absorbs the mixed-font rounding without
+ * visible impact on prose-only paragraphs. */
+.slidev-layout p:has(code),
+.slidev-layout li:has(code) {
+  line-height: 1.45;
+}
+
 /* --- Headings --- */
 .slidev-layout h1,
 .slidev-layout h2,
@@ -247,9 +291,9 @@
 }
 
 .slidev-layout pre {
-  border-radius: 0.5rem;
-  margin-top: 1rem;
-  margin-bottom: 1rem;
+  border-radius: var(--radius-md);
+  margin-top: var(--space-sm);
+  margin-bottom: var(--space-sm);
   white-space: pre-wrap;
   overflow-wrap: break-word;
 }
@@ -272,11 +316,21 @@
   border: none;
 }
 
+/* Slidev wraps code blocks in .slidev-code-wrapper (block, no BFC). Inner
+ * <pre> inherits 1rem top/bottom margin from the .slidev-layout pre rule
+ * (~31px at canvas font-size). When wrapper is a flex item (slide-col-body),
+ * those margins do not collapse with siblings or out of the flex container,
+ * inflating body height beyond column clientHeight. Zero margin inside the
+ * wrapper; outer spacing is handled by the wrapper itself. */
+.slidev-code-wrapper pre {
+  margin: 0;
+}
+
 /* Language label bar above code blocks (via Shiki transformer data-lang attribute) */
 .slidev-layout pre[data-lang] {
   position: relative;
   /* Override Slidev's --slidev-code-padding (applied with !important) to make room for the label */
-  --slidev-code-padding: 2.25rem 0.5rem 0.5rem 0.5rem;
+  --slidev-code-padding: var(--space-code-pt) 0.5rem 0.5rem 0.5rem;
 }
 
 .slidev-layout pre[data-lang]::before {
@@ -285,7 +339,7 @@
   top: 0;
   left: 0;
   right: 0;
-  padding: 0.25rem 0.75rem;
+  padding: var(--space-2xs) 0.75rem;
   font-family: var(--font-mono);
   font-size: 0.8em;
   font-weight: var(--font-weight-medium);
@@ -294,15 +348,29 @@
   color: var(--color-text-tertiary);
   border-bottom: var(--border-thin) solid var(--color-border);
   background: var(--shiki-color-background, var(--color-bg-muted));
-  border-radius: 0.5rem 0.5rem 0 0;
+  border-radius: var(--radius-md) var(--radius-md) 0 0;
+}
+
+/* Filename label (right side of header bar) — via {filename="..."} in code fence meta */
+.slidev-layout pre[data-filename]::after {
+  content: attr(data-filename);
+  position: absolute;
+  top: 0;
+  right: 0;
+  padding: var(--space-2xs) 0.75rem;
+  font-family: var(--font-mono);
+  font-size: 0.8em;
+  font-weight: var(--font-weight-normal);
+  color: var(--color-text-muted);
+  opacity: 0.7;
 }
 
 .slidev-layout code {
-  padding-left: 0.375rem;
-  padding-right: 0.375rem;
-  padding-top: 0.125rem;
-  padding-bottom: 0.125rem;
-  border-radius: 0.25rem;
+  padding-left: var(--space-xs-fine);
+  padding-right: var(--space-xs-fine);
+  padding-top: var(--space-3xs);
+  padding-bottom: var(--space-3xs);
+  border-radius: var(--radius-xs);
   background-color: var(--color-bg-muted);
 }
 
@@ -317,18 +385,18 @@
 
 .slidev-layout table {
   width: 100%;
-  margin-top: 1rem;
-  margin-bottom: 1rem;
+  margin-top: var(--space-sm);
+  margin-bottom: var(--space-sm);
   border-collapse: collapse;
   font-variant-numeric: tabular-nums;
 }
 
 .slidev-layout th,
 .slidev-layout td {
-  padding-left: 1rem;
-  padding-right: 1rem;
-  padding-top: 0.5rem;
-  padding-bottom: 0.5rem;
+  padding-left: var(--space-sm);
+  padding-right: var(--space-sm);
+  padding-top: var(--space-xs);
+  padding-bottom: var(--space-xs);
   border: var(--border-thin) solid var(--color-border);
   text-align: left;
 }
@@ -343,9 +411,9 @@
    ============================================ */
 
 .slidev-layout blockquote {
-  padding-left: 1rem;
-  margin-top: 1rem;
-  margin-bottom: 1rem;
+  padding-left: var(--space-sm);
+  margin-top: var(--space-sm);
+  margin-bottom: var(--space-sm);
   border-left: var(--border-accent) solid var(--color-border-strong);
   color: var(--color-text-secondary);
   font-style: normal; /* No italic for readability */
@@ -564,10 +632,17 @@
   display: flex;
   flex-direction: column;
   flex: 1;
-  overflow: auto;
   min-height: 0;
 }
 
+/* Prevent last-child margin from leaking into scrollHeight (margin-collapse artifact) */
+.slide-single > *:last-child,
+.slide-panel-content > *:last-child,
+.slide-col > *:last-child,
+.slide-col-body > *:last-child {
+  margin-bottom: 0;
+}
+
 .slide-grid {
   display: flex;
   flex: 1;
@@ -575,7 +650,6 @@
 }
 
 .slide-col {
-  overflow: hidden;
   display: flex;
   flex-direction: column;
   min-width: 0;
@@ -601,13 +675,13 @@
 }
 
 /* Per-column backgrounds */
-.slide-col-bg-soft { background: var(--color-bg-soft); border-radius: 0.5rem; padding: 1rem; }
-.slide-col-bg-muted { background: var(--color-bg-muted); border-radius: 0.5rem; padding: 1rem; }
-.slide-col-bg-primary { background: var(--color-primary); color: var(--color-primary-foreground); border-radius: 0.5rem; padding: 1rem; }
-.slide-col-bg-success { background: var(--color-success); color: var(--color-success-foreground); border-radius: 0.5rem; padding: 1rem; }
-.slide-col-bg-warning { background: var(--color-warning); color: var(--color-warning-foreground); border-radius: 0.5rem; padding: 1rem; }
-.slide-col-bg-danger { background: var(--color-danger); color: var(--color-danger-foreground); border-radius: 0.5rem; padding: 1rem; }
-.slide-col-bg-info { background: var(--color-info); color: var(--color-info-foreground); border-radius: 0.5rem; padding: 1rem; }
+.slide-col-bg-soft { background: var(--color-bg-soft); border-radius: var(--radius-md); padding: var(--space-sm); }
+.slide-col-bg-muted { background: var(--color-bg-muted); border-radius: var(--radius-md); padding: var(--space-sm); }
+.slide-col-bg-primary { background: var(--color-primary); color: var(--color-primary-foreground); border-radius: var(--radius-md); padding: var(--space-sm); }
+.slide-col-bg-success { background: var(--color-success); color: var(--color-success-foreground); border-radius: var(--radius-md); padding: var(--space-sm); }
+.slide-col-bg-warning { background: var(--color-warning); color: var(--color-warning-foreground); border-radius: var(--radius-md); padding: var(--space-sm); }
+.slide-col-bg-danger { background: var(--color-danger); color: var(--color-danger-foreground); border-radius: var(--radius-md); padding: var(--space-sm); }
+.slide-col-bg-info { background: var(--color-info); color: var(--color-info-foreground); border-radius: var(--radius-md); padding: var(--space-sm); }
 
 .slide-col-bg-primary h1, .slide-col-bg-primary h2, .slide-col-bg-primary h3,
 .slide-col-bg-success h1, .slide-col-bg-success h2, .slide-col-bg-success h3,
@@ -616,7 +690,7 @@
 .slide-col-bg-info h1, .slide-col-bg-info h2, .slide-col-bg-info h3 { color: inherit; }
 
 /* Per-column border */
-.slide-col-border { border: var(--border-thin) solid var(--color-border); border-radius: 0.5rem; padding: 1rem; }
+.slide-col-border { border: var(--border-thin) solid var(--color-border); border-radius: var(--radius-md); padding: var(--space-sm); }
 
 /* --- 7c. Split Mode --- */
 .slide-split {
@@ -633,7 +707,6 @@
 
 .slide-panel {
   position: relative;
-  overflow: hidden;
 }
 
 .slide-panel-bg-only {
@@ -648,7 +721,6 @@
 
 .slide-panel-content {
   padding: var(--safe-inset-y) var(--safe-inset-x);
-  overflow: auto;
   display: flex;
   flex-direction: column;
   justify-content: center;
@@ -682,6 +754,15 @@
   margin-right: calc(var(--safe-inset-x) * -1);
 }
 
+/* When footer is present, reduce bottom padding to reclaim space */
+.slidev-layout:has(.slide-footer) {
+  padding-bottom: 0;
+}
+/* Split panels: reduce bottom padding when footer takes over that space */
+.slide-split:has(.slide-footer) .slide-panel-content {
+  padding-bottom: 1%;
+}
+
 /* ============================================
    8. Component Styles
    ============================================ */
@@ -690,17 +771,17 @@
 .tags-container {
   display: flex;
   flex-wrap: wrap;
-  gap: 0.5rem;
-  margin-top: 1rem;
-  margin-bottom: 1rem;
+  gap: var(--space-xs);
+  margin-top: var(--space-sm);
+  margin-bottom: var(--space-sm);
 }
 
 .tag {
-  padding-left: 0.75rem;
-  padding-right: 0.75rem;
-  padding-top: 0.25rem;
-  padding-bottom: 0.25rem;
-  border-radius: 9999px;
+  padding-left: var(--space-tight);
+  padding-right: var(--space-tight);
+  padding-top: var(--space-2xs);
+  padding-bottom: var(--space-2xs);
+  border-radius: var(--radius-pill);
   font-size: var(--font-size-small);
   background-color: var(--color-primary-soft);
   color: var(--color-primary);
@@ -709,8 +790,8 @@
 /* Button components */
 .btn {
   display: inline-block;
-  padding: 0.5rem 1rem;
-  border-radius: 0.375rem;
+  padding: var(--space-xs) 1rem;
+  border-radius: var(--radius-sm);
   font-weight: var(--font-weight-medium);
   text-decoration: none;
   cursor: pointer;
@@ -799,7 +880,7 @@ a.btn-secondary:hover {
   position: absolute;
   inset: 5% 5%;
   border: var(--border-thick) dashed var(--color-danger);
-  border-radius: 0.5rem;
+  border-radius: var(--radius-md);
   pointer-events: none;
 }
 
@@ -825,9 +906,9 @@ a.btn-secondary:hover {
 /* Enhanced blockquote callout base style */
 .slidev-layout blockquote:has(p:first-child strong:first-child) {
   border-left-width: var(--border-accent);
-  padding: 1rem 1rem 1rem 1.25rem;
+  padding: var(--space-sm) 1rem 1rem 1.25rem;
   background-color: var(--color-bg-soft);
-  border-radius: 0 0.375rem 0.375rem 0;
+  border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
 }
 
 /* Semantic callout classes — apply to blockquote */
@@ -862,7 +943,7 @@ a.btn-secondary:hover {
 
 /* Ensure focus is not obscured */
 .slidev-layout :focus-visible {
-  scroll-padding: 1rem;
+  scroll-padding: var(--space-sm);
 }
 
 /* (Old layout sections 12-27 removed - replaced by section 7 above) */
@@ -915,19 +996,19 @@ a.btn-secondary:hover {
 
 /* Ensure thought bubble circles are not clipped in overflow: auto containers */
 .bubble-thought.bubble-bottom {
-  margin-bottom: 1.5rem;
+  margin-bottom: var(--space-md);
 }
 
 .bubble-thought.bubble-top {
-  margin-top: 1.5rem;
+  margin-top: var(--space-md);
 }
 
 .bubble-thought.bubble-left {
-  margin-left: 2rem;
+  margin-left: var(--space-lg);
 }
 
 .bubble-thought.bubble-right {
-  margin-right: 2rem;
+  margin-right: var(--space-lg);
 }
 
 /* ============================================
@@ -935,7 +1016,7 @@ a.btn-secondary:hover {
    ============================================ */
 
 .device-mockup-placeholder {
-  padding: 2rem;
+  padding: var(--space-lg);
   text-align: center;
 }
 

package/styles/motion.css

@@ -313,7 +313,7 @@
   animation: entrance-slide-right var(--dur-moderate-02) var(--ease-enter) calc(var(--stagger-base) * 4) both;
 }
 
-.slide-grid > .slide-col:last-child:nth-last-child(2) {
+.slide-grid > .slide-col:nth-child(2):last-child {
   animation: entrance-slide-left var(--dur-moderate-02) var(--ease-enter) calc(var(--stagger-base) * 4) both;
 }