slidev-theme-lilac

A standalone Slidev theme with reusable visual presets and optional obsidian-slidev integration.

Ordinary Slidev Markdown can use the theme directly. When a deck is generated by obsidian-slidev, the theme additionally renders its Obsidian-specific semantic markup.

Install

Add the following frontmatter to your slides.md. Start Slidev then it will prompt you to install the theme automatically.

Learn more about how to use a theme.

Obsidian Integration

obsidian-slidev can emit the following frontend-native structures, and this theme styles them directly:

| Source idea | Generated target | | --- | --- | | Obsidian callouts | .obsidian-slidev-callout blocks | | Vault images, videos, and audio | .obsidian-slidev-media figures | | YouTube links | Slidev's built-in <Youtube> component | | Video embeds | Slidev's built-in <SlidevVideo> component | | Obsidian note links | .obsidian-slidev-link anchors | | Missing references | .obsidian-slidev-warning blocks |

The theme does not parse Obsidian Markdown by itself. Keep conversion logic in obsidian-slidev; keep rendering and presentation in this theme.

Semantic Boundary

The theme keeps generic presentation structure separate from integration-specific markup:

| Scope | Names | | --- | --- | | Theme frame and layouts | SlideFrame, .slide-frame, .slide-layout-* | | Theme configuration | themeConfig.presentation, presentationPreset, presentationDensity | | Theme design tokens | --presentation-* | | Markup emitted by obsidian-slidev | .obsidian-slidev-* |

Only the last group is intentionally Obsidian-specific.

Theme Config API

The stable public configuration surface is themeConfig.presentation.

title: My Deck
subtitle: Optional deck subtitle
footer: Custom center footer
authors:
  - name: xunz
    institution: UCAS
    email: [email protected]
  - name: jane
    institution: UCAS
    email: [email protected]
themeConfig:
  presentation:
    preset: default
    accent: "#345f8f"
    density: normal
    chrome: auto
    header: false
    footerAuthors: true
    pageNumber: true

Supported keys:

| Key | Values | Default | Purpose | | --- | --- | --- | --- | | preset | default, ucas, ict | default | Selects the visual system without changing generated markup | | accent | Any CSS color | theme default | Overrides the primary accent color | | density | compact, normal, relaxed | normal | Adjusts slide padding, spacing, and body scale | | chrome | auto, on, off | auto | Controls footer metadata chrome | | header | true, false | false | Shows the optional per-slide title/subtitle header | | footerAuthors | true, false | true | Shows or hides author names in the left footer | | pageNumber | true, false | true | Shows or hides the right footer page number |

Per-slide overrides:

| Frontmatter key | Values | Purpose | | --- | --- | --- | | presentationPreset | default, ucas, ict | Override the preset for one slide | | presentationDensity | compact, normal, relaxed | Override density for one slide | | presentationChrome | auto, on, off | Override slide chrome behavior | | chrome | auto, on, off | Alias for presentationChrome | | presentationHeader | true, false | Force the optional header on or off for one slide | | header | true, false | Alias for presentationHeader | | footerAuthors | true, false | Override left footer author visibility for one slide | | pageNumber | true, false | Override right footer page-number visibility for one slide | | footer | Text | Override the centered footer content for one slide |

themeConfig is Slidev's standard theme/addon configuration object. This theme keeps its own options under themeConfig.presentation so they do not collide with Slidev core fields or other addons. density selects the spacing scale: compact uses tighter padding and lists for information-dense slides, normal is the default, and relaxed gives content more breathing room.

Values resolve independently using first valid precedence. When a layer exists for an option, the order is an explicit layout prop, the canonical per-slide key, its documented alias, the deck-level themeConfig.presentation value, and finally the default. Invalid or empty values are skipped instead of suppressing a valid lower-priority value. accent is intentionally deck-only.

Textual booleans are accepted for YAML and generator compatibility. Boolean options accept native booleans plus the strings true, false, on, and off after trimming; other spellings such as yes, no, 1, or uppercase variants are invalid. chrome also maps native or textual true to on and false to off.

Deck metadata such as title, subtitle, footer, and authors stays at the Slidev frontmatter root because it describes content, not theme behavior. The cover layout renders explicit subtitle metadata under the title; it does not infer a subtitle from the first paragraph. authors can be a list of strings or objects with name, institution, and email; the cover layout renders each author's full details side by side under the title, and the footer uses only author names on the left when themeConfig.presentation.footerAuthors is enabled. The centered footer uses per-slide footer first, then top-level footer, then top-level title.

Title rendering follows a fixed rule:

| Location | Visible title source | Metadata role | | --- | --- | --- | | cover layout | Root or cover-slide title / subtitle metadata | The first Markdown # is hidden when metadata title exists, preventing duplicate cover titles | | Normal content layouts | Markdown content such as # Slide Title | Per-slide title / subtitle is metadata for navigation, TOC extraction, and the optional header | | Optional header | Per-slide title / subtitle metadata only | It never falls back to the deck title, so global deck metadata is not repeated on every slide | | Footer center | Per-slide footer, then root footer, then root title | Footer content is deck chrome, not the slide's visible content title |

Theme chrome means the non-content frame around each slide. By default it is footer-only: author names are used on the left footer, deck metadata is used in the centered footer, and themeConfig.presentation.pageNumber only controls the right footer page number. The header is intentionally opt-in because per-slide title and subtitle usually duplicate the visible Markdown heading.

Compatibility and migration

No migration is required for existing decks. Ordinary Slidev Markdown, all eleven layout names and props, root deck metadata, themeConfig.presentation, documented per-slide overrides, and .obsidian-slidev-* semantic markup remain compatible. The refactor changes internal ownership—one shared frame and one configuration authority—without changing the public authoring surface. Legacy chrome and header per-slide aliases remain accepted; the presentationChrome and presentationHeader names are preferred in new decks.

CSS Variables

Advanced users can override theme tokens from custom CSS or a Slidev style entry.

| Variable | Purpose | | --- | --- | | --slidev-theme-primary | Slidev-compatible primary color | | --presentation-accent | Theme accent used for links, chrome, callouts, and highlights | | --presentation-bg | Slide background base color | | --presentation-bg-elevated | Elevated surface color | | --presentation-bg-muted | Muted code/table background color | | --presentation-frame-bg | Optional frame-level background overlay | | --presentation-text | Main text color | | --presentation-text-muted | Secondary text, captions, and chrome text | | --presentation-border | Borders for tables, chrome, callouts, and inline code | | --presentation-border-strong | Strong table and default divider borders | | --presentation-shadow | Shared elevation shadow | | --presentation-scrollbar-thumb | Scrollbar thumb color for overflowing slide content | | --presentation-scrollbar-track | Scrollbar track color for overflowing slide content | | --presentation-font-sans | Shared sans-serif family stack | | --presentation-font-serif | Shared serif family stack | | --presentation-font-body | Body-copy family selected by the active preset | | --presentation-font-display | Heading and display family selected by the active preset | | --presentation-font-quote | Quote layout italic font stack | | --presentation-font-label | Chrome, metadata, and numeric-label family | | --presentation-font-mono | Code font stack | | --presentation-reading-width | Maximum width for paragraphs, lists, and blockquotes | | --presentation-block-width | Maximum width for tables, code blocks, callouts, and warnings | | --presentation-slide-padding | Frame padding | | --presentation-two-cols-gap | Gap between columns in the two-cols layout | | --presentation-content-gap | Vertical rhythm between common markdown blocks | | --presentation-body-size | Base body font size | | --presentation-body-line-height | Base body line height | | --presentation-heading-scale | Multiplier for heading size | | --presentation-heading-weight | Heading font weight | | --presentation-heading-letter-spacing | Heading tracking | | --presentation-heading-line-height | Heading line height | | --presentation-list-spacing | Vertical space between list items | | --presentation-table-size | Table text size | | --presentation-chrome-size | Header and footer text size | | --presentation-caption-size | Figure caption and secondary label size | | --presentation-footnote-size | Footnote text size | | --presentation-table-header-bg | Table header background | | --presentation-table-row-alt-bg | Alternating table row background | | --presentation-code-bg | Code block background | | --presentation-code-border | Code block border | | --presentation-inline-code-bg | Inline code background | | --presentation-inline-code-border | Inline code glass border | | --presentation-inline-code-shadow | Inline code glass shadow | | --presentation-blockquote-bg | Blockquote background | | --presentation-blockquote-border | Blockquote left border | | --presentation-blockquote-font-style | Blockquote font style | | --presentation-callout-bg | Default generated callout background | | --presentation-callout-border | Default generated callout border color | | --presentation-callout-radius | Generated callout border radius | | --presentation-callout-shadow | Generated callout shadow | | --presentation-warning-bg | Generated warning background | | --presentation-warning-border | Generated warning border color | | --presentation-warning-text | Generated warning text color | | --presentation-caption-font-style | Generated media caption font style | | --presentation-caption-letter-spacing | Generated media caption tracking | | --presentation-media-max-height | Maximum generated image/video height | | --presentation-media-radius | Generated image/video corner radius | | --presentation-media-shadow | Generated image/video shadow | | --presentation-quote-size | Quote layout text size | | --presentation-quote-line-height | Quote layout line height |

Tables, code blocks, callouts, and warnings use the quieter block measure by default. Add class="presentation-full-width" to one of those top-level blocks when a wide table or code sample genuinely needs the full content area.

Presets

Use themeConfig.presentation.preset to switch visual systems without changing the generated markup.

| Preset | Use case | | --- | --- | | default | Paper talks, methods reports, reading groups, and thesis defenses | | ucas | UCAS-branded courses, seminars, project reviews, and research talks | | ict | ICT-branded systems, architecture, AI, and computing research talks |

When no preset is specified, default is selected. It is a paper-inspired but projection-aware system: serif display type, a centered academic title page, booktabs-like tables, flat code and callout surfaces, italic captions, and an ink-blue section field create academic formality without reproducing the density of a printed article.

ucas is an independent research-oriented direction based on the official UCAS blue and the bundled bilingual identity assets. Its cover uses a deep-blue-to-white gradient brand rail with the vertical UCAS lockup; ordinary slides return to a cold-white, rail-free canvas with restrained serif display titles, booktabs-like tables, and a compact horizontal wordmark. Emblem watermarks are reserved for cover, section, statement, and center layouts so research content remains primary. The preset supports the same layouts and generated Obsidian markup as the other presets, and it also works with ordinary Slidev Markdown.

ict is a separate computing-research visual system based on the official two-blue ICT orbital emblem and bilingual institute lockup. It combines a cool-white editorial canvas with muted navy brand fields, precise cyan accents, sans-serif display typography, restrained technical chrome, and mode-aware code surfaces. Strong branding is concentrated on cover, section, and statement layouts; ordinary content slides remain quiet and projection-friendly.

For ucas and ict, themeConfig.presentation.accent changes content accents such as links, callouts, and chrome while the official identity colors used by logos and signature layouts remain locked.

Typography

All presets share the same three bilingual families, but map them to different roles so their personalities stay distinct without causing large text reflow:

| Preset | Display | Body | Quote | Labels / code | | --- | --- | --- | --- | --- | | default | Source Serif 4 / Noto Serif SC | Source Sans 3 / Noto Sans SC | Source Serif 4 / Noto Serif SC | Source Sans 3 / JetBrains Mono | | ucas | Source Serif 4 / Noto Serif SC | Source Sans 3 / Noto Sans SC | Source Serif 4 / Noto Serif SC | Source Sans 3 / JetBrains Mono | | ict | Source Sans 3 / Noto Sans SC | Source Sans 3 / Noto Sans SC | Source Serif 4 / Noto Serif SC | JetBrains Mono |

Slidev loads Source Sans 3, Source Serif 4, and JetBrains Mono as web fonts and exposes the same families through UnoCSS utilities such as font-sans, font-serif, and font-mono. The theme requests real roman and italic faces at weights 400, 500, 600, and 700; its CSS uses only those weights. Noto Sans SC and Noto Serif SC are loaded separately at upright weights so mixed Chinese/Latin headings keep a coherent sans or serif voice; Google Fonts serves them in unicode-range subsets, so a deck fetches only the ranges it uses. Decks marked with a Chinese lang keep CJK headings, captions, and quotations upright with neutral tracking.

For offline venues, preload or self-host the five web families, or override the --presentation-font-* variables with fonts installed on the presentation machine.

Layouts

This theme provides the following layouts:

| Layout | Purpose | | --- | --- | | default | Main content slides with optional footer chrome | | cover | Opening slide, chrome hidden by default | | intro | Introductory slide with normal chrome behavior | | section | Section divider, chrome hidden by default | | toc | Table of contents generated from section slides | | center | Centered single-message slide | | two-cols | Two-column content layout using ::right:: | | statement | Large centered claim or takeaway | | quote | Pull quote with optional author, source, or cite frontmatter | | figure | Centered media-first slide | | references | Smaller reference/bibliography slide |

Protocol Fixture

The repository includes fixtures/obsidian-protocol.md, a dedicated deck for validating the generated markup contract with obsidian-slidev.

It covers:

• Obsidian callout classes
• Generated image, video, audio, and YouTube media figures
• Obsidian links and warning blocks
• Long lists, tables, inline code, code blocks, and footnotes
• Default preset behavior plus UCAS and ICT overrides on the same generated protocol
• Preset contrast slides with identical content structure
• Section-driven deck structure with TOC
• Preset-specific statement, quote, figure, references, and center layouts

Run it with:

pnpm run dev:fixture
pnpm run build:fixture

Quality gates

Install dependencies from the frozen lockfile before running release checks:

pnpm install --frozen-lockfile

Focused diagnostics:

node tests/quality/configuration.spec.mjs
node scripts/check-presentation-css.mjs
node --test tests/quality/preset-isolation.spec.mjs
node --test tests/quality/accessibility.spec.mjs
node --test tests/quality/visual.spec.mjs
pnpm run assets:check

pnpm run assets:optimize is the deterministic source-maintenance command for the six UCAS SVGs. It removes only the reviewed non-rendering metadata and refuses unknown source hashes. Run pnpm run assets:check afterward to verify exact size budgets, structure, alpha, browser RGBA output, explicit image dimensions, and idempotence. Normal asset checks do not rewrite assets or approved baselines.

The aggregate release command is:

pnpm run quality

It builds the five maintained decks and three generated preset-matrix decks with at most two builds at once, then runs configuration, architecture, preset isolation, accessibility, interaction, visual, asset, and output-size gates. Runtime evidence and a phase summary are retained under .artifacts/quality/. The gate exits 0 on success, 1 for product or contract failures, and 2 for harness errors, unapproved skips, or the hard limit of 300 seconds.

Approved visual and output baselines are immutable during normal checks. Update them only for an intentional reviewed change:

pnpm run quality:update-baselines -- --reviewer "Reviewer name" --rationale "Approved visual or output change"
git diff -- tests/quality/baselines
pnpm run quality

Review the resulting PNG, manifest, byte-budget, and provenance diff. Never update a baseline merely to hide an unexplained failure.

Development

The latest cross-preset visual review is recorded in qa/refactor-theme-architecture/visual-review.md.

• pnpm install
• pnpm run dev to start theme preview of example.md
• pnpm run dev:fixture to start the protocol fixture preview
• pnpm run build:default / pnpm run screenshot:default for the Default research showcase
• pnpm run build:ucas to build the UCAS preset showcase
• pnpm run screenshot:ucas to render the UCAS showcase as PNG slides
• pnpm run build:ict to build the ICT preset showcase
• pnpm run screenshot:ict to render the ICT showcase as PNG slides
• pnpm run build to verify the example can be built
• pnpm run build:fixture to verify the plugin/theme protocol fixture can be built