Shared VitePress theme

vitepress-theme-yunlefun gives design, the public developer docs and the internal Wiki one documentation style. Each site owns its content and navigation.

Theme responsibilities

Layer	Responsibility	Source
Foundations	Sky/night colors, text, surfaces, radii, shadows and spacing	@yunlefun/ui
Documentation theme	Cyan anchors and cyan/yellow title rule, navigation, Markdown, scrolling tables, code, callouts and appearance transitions	vitepress-theme-yunlefun
Site	Homepage, navigation, sidebar, languages and business components	design / docs / wiki

Cyan and yellow mark titles; primary actions and links retain brand blue. Documents use system fonts. Sites may opt into brand display fonts.

Install and integrate

The first version is distributed as an npm-format tarball on GitHub Releases:

pnpm add -D https://github.com/YunLeFun/design/releases/download/theme-v0.3.0/vitepress-theme-yunlefun-0.3.0.tgz

In .vitepress/theme/index.ts:

import Theme from 'vitepress-theme-yunlefun'
import 'vitepress-theme-yunlefun/style.css'

export default Theme

In .vitepress/config.ts:

import { defineConfig } from 'vitepress'
import { withYunlefun, yunlefunMarkdown } from 'vitepress-theme-yunlefun/config'

export default defineConfig(withYunlefun({
  lang: 'en',
  title: 'YunLeFun Docs',
  markdown: { config: md => md.use(yunlefunMarkdown) },
}))

withYunlefun preserves existing Vite plugins and bundles the installed Vue theme for server rendering. CSS uses compiled design tokens, requires no Sass and downloads no fonts.

Native features

Navigation, search, sidebars, outlines, languages, code groups and copying use the default VitePress theme. Use native locales for Chinese and English. The theme does not translate content. Optional zhThemeConfig supplies Chinese interface labels.

The native 768px breakpoint keeps primary navigation visible on tablets and desktops, with an expandable menu on phones. At intermediate widths, compact search, spacing and secondary controls preserve full navigation labels. Navigation links use 44px targets, neutral hover and inset focus outlines. A 16×2px sky-blue underline moves between current page links using the shared motion duration. Dropdown groups use text color for the current section and a chevron for expansion, without an underline. The theme observes VitePress selection state and bundles the same positioning source as YlfNavigation; initial rendering retains a static marker and reduced motion disables the transition. When switching between light and dark, browsers with View Transitions play two different scenes: switching to dark, a soft-edged curtain of night falls from the top while the daytime page dims; switching to light, daylight spreads softly from the click point, starting slightly bright before settling. Keyboard toggles start near the top-right switch. Without CSS masks the reveal falls back to a circle, and without View Transitions it keeps the cross-fade. Backdrop blur pauses during the transition to keep it smooth. Page content eases in on navigation, the sky-blue outline marker follows your reading position with the soft spring, and the nav underline uses the same spring. Reduced motion turns all of this off. This is a source update: other documentation sites receive it after upgrading to a theme release that includes it.

Supported: VitePress 1.6.4 and 2.0.0-alpha.16/17/19, with Vue 3.5. Both client and server builds are verified across the three sites.

Extend your site

<script setup lang="ts">
import { Layout } from 'vitepress-theme-yunlefun'
</script>

<template>
  <Layout>
    <template #doc-before>
      <p>A site-specific notice</p>
    </template>
  </Layout>
</template>

Default theme slots and scoped data are forwarded. The cloud scene and component demos stay in design; site directories stay in docs and wiki.

Custom appearance controls can call toggleAppearance() or setAppearance(dark) from useAppearanceTransition() in vitepress-theme-yunlefun/appearance. They share the header's state, respect reduced motion and remain still on initial load.

Upgrade and maintain

Edit shared document styling in packages/vitepress-theme-yunlefun and foundation tokens in packages/ui. Upgrade all sites to the same version and commit lockfiles. The first release uses a fixed GitHub Release URL; npm versions can replace it after initial npm publication is authorized.

Canonical brand assets

Configure themeConfig.brand: { icon: "brand-mark", hero: true } to render the shared logo in navigation and the native home hero. Design uses design-mark. Omit the native logo and hero.image options when using this API. Custom native slots still override the defaults.

Geometry comes from @yunlefun/icons; colors follow --ylf-c-brand from @yunlefun/ui. The icon catalog and design system remain independent repositories connected by dependencies and links.

import { generateBrandAssets } from 'vitepress-theme-yunlefun/brand-assets'

await generateBrandAssets({ outDir: 'docs/public', icon: 'brand-mark', title: 'YunLeFun' })

Run this Node-only helper when updating icons; commit the generated files. PNG generation requires rsvg-convert (librsvg). SVG-only tooling can pass png: false.

Optional workbench surfaces

Icons keeps its asset catalog, platform masks, size controls and technical guides. The theme shares its panel, grid and transparency checker surfaces with the AG-UI demo. Import these styles only on pages that need them:

import 'vitepress-theme-yunlefun/workbench.css'

<section class="ylf-workbench">
  <div class="ylf-workbench-panel ylf-workbench-grid">…</div>
  <div class="ylf-workbench-checker">…</div>
</section>

Colors follow the shared light/dark tokens. Customize --ylf-workbench-grid-size and --ylf-workbench-checker-size within the workbench; product artwork keeps its own palette.