slidev-semantic-deck

name	slidev-semantic-deck
description	Use when editing Slidev/Vue research decks that need semantic slide structure, reusable visual components, generated charts/QR codes, and screenshot-based verification.

Slidev Semantic Deck Workflow

Structure

• Keep slides.md as the deck index, not the implementation surface. Each slide block should contain the slide frontmatter, a local <script setup> import for its full-slide component, and the SlideFrame wrapper when the slide uses the shared frame.
• Store full-slide Vue single-file components under slides/, grouped by deck section. Use the existing section folders: background, solution, demo, conclusion, and appendix; put cover and agenda slides directly in slides/.
• Keep components/ for reusable primitives only: frames, logos, radar charts, diagram pieces, code blocks, figure boxes, cards, tables, and other elements shared by multiple slides.
• Use Vue single-file components for pages with grid/flex layout, generated charts, QR codes, annotated code, screenshot overlays, or any meaningful visual composition. Avoid large page layouts directly in slides.md.
• Prefer named classes over inline style attributes, including CSS custom-property assignments. Put visual variants on semantic classes such as .protocol-card or .renderer-card; reserve Vue :style bindings for genuinely data-driven values such as chart colors or media fit.
• Use grid for page-level composition, repeated card matrices, stable text/media tracks, and any layout that needs row or column alignment. Use flex inside a component for one-dimensional stacks, toolbars, legends, and simple rows. Do not use flex wrapping as a substitute for a slide grid whose tracks need to stay aligned.
• Keep absolute positioning only for intentional annotations, overlays, or fixed media alignment. It must not be the default way to place slide content.
• When moving a slide component out of components/, update the corresponding local import in slides.md and ensure tsconfig.json includes slides/**/*.vue.
• Remember that Slidev auto-imports ./components/ but not arbitrary slides/ subfolders. Use explicit imports in each slide block for full-slide components in slides/.
• Keep layouts/ for Slidev layout overrides and legacy/ for archived source/reference material. Do not import directly from legacy/ in the live deck.

Slide Composition

• Wrap standard content slides in SlideFrame, passing semantic section and title props from slides.md. Keep the full-slide component focused on the body content.
• Let title and contents slides be intentionally different when needed; they can live outside SlideFrame if the deck design calls for it.
• Name full-slide components with a semantic Slide suffix, for example ProtocolSchemaSlide.vue or FireDqnWorkflowSlide.vue. Do not use the suffix for reusable primitives unless the component is genuinely a complete slide.
• Use specific reusable component names that describe their role, for example PlatformCapabilityRadar, DemoCodeBlock, ResearchBrandLogos, and FigureImageBox; avoid generic names inherited from extraction or early prototyping.
• Keep repeated copy, scales, data presets, and code snippets structured in component data or typed constants instead of scattering them through templates.
• Give every standard frame a fixed, shared body geometry at the target canvas size. Full-slide components should use height: 100% rather than copying the body height as a raw pixel value.
• Keep the footer useful and stable: include a short deck identity, a source/repository address, event or venue context, the presentation date, and the page number. Keep event, date, and page in that order. The footer needs an opaque background and stacking order so overflowing slide content cannot hide it.
• Put global frame spacing, body height, card spacing, border colors, radii, and typography in shared design tokens. Local components may choose from those tokens; avoid one-off outer-card padding unless a dense appendix or code surface has a documented reason.

Light And Dark Themes

• Treat light/dark support as a deck-wide capability, not a per-slide cosmetic option. Set colorSchema: auto in Slidev headmatter so the deck follows the operating-system preference while retaining Slidev's player toggle and D shortcut. Use light or dark only when the user explicitly requests a locked scheme.
• Define the light palette as semantic custom properties under :root and override those same properties under html.dark. At minimum separate canvas, raised surface, muted surface, primary text, body text, muted text, border, strong border, code surface, glass/overlay, and text-on-accent roles.
• Never make one token serve both a theme-dependent surface and invariant text on a saturated color. For example, a historical token such as --color-white may become a dark raised surface; page-number or button text must instead use a token such as --color-on-accent that remains white in both themes.
• Components must consume semantic tokens rather than literal light neutrals. Replace fixed white backgrounds, navy body text, pale-gray borders, and pastel fills with canvas/surface/text/border/tone tokens. Fixed data-series or hazard colors may remain literal only when they have verified contrast in both schemes.
• Theme inline SVGs as part of the component: use CSS variables in fill, stroke, label, grid, and halo properties. Radar/chart primitives should default to semantic CSS-variable colors so every caller inherits the active scheme.
• Libraries that parse color strings outside CSS, including many QR, canvas, and chart renderers, may not resolve var(...). Import useDarkMode from @slidev/client in reusable Vue components and pass concrete light/dark color values, or use <LightOrDark> with scheme-specific assets. Do not assume composables are auto-imported outside slide markdown, and do not pass an unresolved CSS variable to a library that expects a hex color.
• Keep screenshots and recorded demos faithful to the captured application even when they contain a light UI. Theme their surrounding frame, caption, and annotation surfaces; do not recolor research evidence merely to make the slide uniformly dark.
• Cover art and raster backgrounds need an explicit dark-mode treatment when a dark overlay is insufficient. Prefer a scheme-specific asset; a documented brightness/saturation filter is acceptable for decorative imagery that does not encode evidence.
• Avoid component-local html.dark overrides for ordinary text and surfaces. Add or refine shared semantic tokens instead, so future slides inherit both schemes without accumulating page-specific patches.

Charts And Media

• Draw charts from explicit data presets. Prefer the existing SvgRadarChart plus radarChartModel.ts path for radar-style comparisons unless a new chart type clearly needs another library.
• If introducing a library such as Chart.js or ECharts, register all required controllers/scales/elements locally and keep the rendered component reusable.
• Generate QR codes with a Vue ecosystem component and keep the target URL in component data.
• Keep chart components reusable when multiple slides compare the same dimensions or presets. Full-slide components should choose presets; reusable chart components should own rendering details.
• Use real media assets when they clarify the research story. Keep generated screenshots, extracted PPTX images, logos, and other deck assets under public/assets/ with descriptive names.
• Keep PPTX-derived files in public/assets/pptx/ only when the live deck references them, and rename them by content instead of keeping export names like image7.png.
• Keep screenshots and serialized demo data in public/assets/examples/, language logos in public/assets/platform_logos/, and shared frame logos in public/assets/brand/.
• In repeated two-by-two card layouts, place optional media on a stable right-hand track and text on the left. Keep the media region approximately square; use object-fit: contain for screenshots, charts, and diagrams unless cropping is intentional.
• Prefer a real screenshot over a video when the claim is about a specific inspectable UI state. Use video when motion, latency, or an interaction sequence is itself the evidence.
• Before deleting an asset, search the live deck paths (slides/, components/, layouts/, styles/, and slides.md) for references. After deletion, verify no stale /assets/... path remains.

Code Slides

• Store code snippets as structured line arrays with semantic tone metadata rather than raw code blocks in slides.md.
• Use consistent tone names and colors across slides, for example declarative, imperative, action, and chart.
• Include a legend on the first code-heavy slide and reuse the same colors later.
• Keep code-heavy slide layouts dense but readable: stable columns, predictable line heights, and no text overflow at the 1280x720 canvas.
• When showing commands from another repository, read that repository's current README, CLI help, or bundled skill first. Do not preserve retired aliases in slides. If the authoritative command prefix is long, show it once and list readable command suffixes beneath it.

Visual Style

Reusable Micro-surfaces

• Mark every compact status, category, metric, or legend badge with .tag; wrap a homogeneous row or grid of them in .tags. Use a semantic local class only for the role or variant, never for a duplicate tag box model.

• Configure tag variants through inherited custom properties: --tags-gap, --tag-min-*, --tag-pad-*, --tag-border-*, --tag-bg, --tag-color, and typography properties. Keep default --tag-* values on an inherited token scope such as :root, so a .tags container can override every child; do not redeclare defaults on .tags > *.

• Use .terminal for every command, prompt, output, and terminal-only workflow. Configure its surface and typography with --terminal-bg, --terminal-color, --terminal-border-*, --terminal-pad-*, --terminal-gap, and font properties; local classes should only add their distinct layout or content treatment.

• Use .edge-box for framed panels and accent-edge callouts. Combine its left, color-frame, tint-frame, tint-bg, or bare variants and configure --eb-* properties rather than recreating borders, accent strips, surface fills, or padding with page-local CSS.

• Design for a research talk: precise, calm, and high-signal. Favor restrained contrast, clear hierarchy, and spatial grouping over decorative effects.

• Avoid nested cards and ornamental backgrounds. Use cards only for repeated items, comparison units, or genuinely framed artifacts.

• Keep text within its container at the configured canvas size. Check long labels, code lines, radar legends, and section titles after edits.

• Keep default ul markers visible. Remove bullets only for explicitly non-list UI such as nav trails, step flows, chips, or tag rows.

• Do not solve thin typography by making most text bold. Define a small shared weight scale (normally regular 400, medium 500, semibold 600, and bold 700) and use tokens rather than arbitrary numeric values. Body copy is regular; metadata and compact labels are medium or semibold; headings and deliberate emphasis are bold. Avoid synthetic values such as 730, 760, 850, 900, or 950.

• Use one spacing scale for frame gutters, grids, cards, and compact controls. Standard cards should inherit the shared padding; dense code, appendix, and micro-UI surfaces may use smaller named spacing tokens.

• Define radius semantics once. A deck may choose square or rounded rectangular surfaces, but all cards, media frames, code panels, badges, and controls must use the shared surface/control radius tokens. Reserve a separate fully-round token for genuinely circular objects such as agents, scale nodes, and numbered steps; do not mix arbitrary 2px, 7px, 10px, and pill radii across components.

• Prefer semantic class names tied to the topic or component purpose, such as route-grid, metric-table, or agent-operations. Avoid page-number names such as p4-grid or p8-block, which become stale when slides are reordered.

• A slide title, section label, body copy, panel heading, metadata label, and code surface should each have one consistent typographic role across the deck. Do not restyle the same role independently on every slide.

Refactors And Renames

• Use git mv when renaming tracked slides, components, and assets so history is easy to review. If changes are later unstaged, Git may show the same work as deleted files plus untracked files until git add -A is run.
• After renaming full-slide components, update both the import path and component tag in slides.md.
• After renaming reusable components, update all auto-imported component tags and local imports, especially nested dependencies such as radar helpers.
• Keep file renames semantic rather than decorative: names should reveal the slide topic, component responsibility, or media content.

Verification

• Run pnpm build after structural changes.
• Prefer the in-app browser for local Slidev visual QA when it is available; otherwise use the repository's Playwright Chromium dependency. Inspect at the configured canvas size, normally 1280x720.
• Verify every slide in both light and dark mode after introducing or changing theme tokens. In Playwright, set localStorage['slidev-color-schema'] to light or dark before navigation/reload; in the player, also smoke-test the navigation toggle or D shortcut.
• Capture the same routes in both modes and compare them as a pair. Check canvas/frame continuity, text and border contrast, SVG/chart labels, QR readability, code surfaces, translucent overlays, logos, and media frames; a successful build alone does not validate a theme.
• Include library-rendered visuals in the theme audit. QR/canvas/chart output can remain stuck in the light palette even when its surrounding Vue component changes correctly.
• After direct navigation to a Slidev route, wait for DOM content and a short stabilization interval before capturing. An immediate screenshot can catch Slidev's black transition frame even when the DOM has rendered correctly.
• For broad refactors, inspect every route for broken images, stale asset paths, and overflow. A DOM overflow scan is useful, but treat pseudo-element connectors, range thumbs, SVG labels, and font glyph metrics as possible false positives; confirm flagged pages visually.
• Check for raw HTML leakage, blank canvases, text overflow, overlapping labels, and asset rendering.
• Check that every standard slide shows the shared footer and that slide content does not cover it.
• Remove temporary screenshot directories before finishing unless the user explicitly wants them preserved.
• If pnpm build reports Rolldown warnings from third-party packages but exits successfully, note them as warnings rather than treating them as deck regressions.
• In headless Slidev checks, Wake Lock permission errors can appear as browser runtime noise. Filter or note them separately if image loading, console errors, and page rendering otherwise pass.