Improve dashboard skill, examples, and documentation checks

.github/workflows/pages.yml

@@ -43,13 +43,36 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Build packages
-        run: pnpm build
+        run: pnpm exec turbo build --filter='!@datav-kit/docs'
 
       - name: Build docs
         run: pnpm docs:build
         env:
           VITEPRESS_BASE: /${{ github.event.repository.name }}/
 
+      - name: Check documentation and example sources
+        run: pnpm docs:check
+        env:
+          VITEPRESS_BASE: /${{ github.event.repository.name }}/
+
+      - name: Install browser
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Verify example previews
+        run: pnpm examples:test
+        env:
+          VITEPRESS_BASE: /${{ github.event.repository.name }}/
+
+      - name: Upload browser verification
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: example-browser-verification
+          path: |
+            .cache/playwright-report
+            .cache/playwright-results
+            .cache/example-screenshots
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5
         with:

.github/workflows/skill-examples.yml

@@ -0,0 +1,37 @@
+name: Skill examples
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    env:
+      VITEPRESS_BASE: /datav-kit/
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 11.6.0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm exec turbo build --filter='!@datav-kit/docs'
+      - run: pnpm docs:build
+      - run: pnpm docs:check
+      - run: pnpm examples:test
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: example-browser-verification
+          path: |
+            .cache/playwright-report
+            .cache/playwright-results
+            .cache/example-screenshots

.gitignore

@@ -11,6 +11,7 @@ node_modules
 temp
 cache
 .eslintcache
+/docs/public/examples/
 
 # AI
 .agents

docs/.vitepress/config.ts

@@ -1,21 +1,26 @@
 import process from 'node:process'
 import { defineConfig } from 'vitepress'
 import llmstxt, { copyOrDownloadAsMarkdownButtons } from 'vitepress-plugin-llms'
+import { copySkillExamples, skillExamples } from './skill-examples'
+
+const base = process.env.VITEPRESS_BASE || '/'
 
 export default defineConfig({
   title: 'DataV Kit',
   description: 'Framework-agnostic Web Components for data dashboard decoration.',
-  base: process.env.VITEPRESS_BASE || '/',
+  base,
+  buildEnd: copySkillExamples,
   cleanUrls: true,
   vite: {
-    plugins: [llmstxt()],
+    plugins: [llmstxt(), skillExamples(base)],
     server: {
       host: '0.0.0.0',
     },
   },
   themeConfig: {
     nav: [
       { text: 'Guide', link: '/guide/introduction' },
+      { text: 'Examples', link: '/guide/dashboard-examples' },
       { text: 'Components', link: '/components/decorations/decoration-1' },
       { text: 'Reference', link: '/reference/architecture-contracts' },
     ],
@@ -31,6 +36,7 @@ export default defineConfig({
             { text: 'Installation', link: '/guide/installation' },
             { text: 'Framework Integration', link: '/guide/framework-integration' },
             { text: 'Theming', link: '/guide/theming' },
+            { text: 'Dashboard Examples', link: '/guide/dashboard-examples' },
             { text: 'Component Authoring', link: '/guide/component-authoring' },
           ],
         },
@@ -101,15 +107,6 @@ export default defineConfig({
           ],
         },
       ],
-      '/technical-architecture': [
-        {
-          text: 'Reference',
-          items: [
-            { text: 'Architecture Contracts', link: '/reference/architecture-contracts' },
-            { text: 'Technical Architecture', link: '/technical-architecture' },
-          ],
-        },
-      ],
     },
     search: {
       provider: 'local',

docs/.vitepress/skill-examples.ts

@@ -0,0 +1,62 @@
+import type { Plugin } from 'vite'
+import type { SiteConfig } from 'vitepress'
+import { copyFile, mkdir, readdir, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const assets = fileURLToPath(new URL('../../skills/datav-kit/assets/', import.meta.url))
+const examples = path.join(assets, 'examples')
+
+function sourceFile(name: string): string | undefined {
+  if (!/^[a-z-]+\.(?:html|png)$/.test(name))
+    return undefined
+  if (name === 'minimal.html')
+    return path.join(assets, 'minimal-example.html')
+  return path.join(examples, name.endsWith('.png') ? 'previews' : '', name)
+}
+
+export function skillExamples(base: string): Plugin {
+  return {
+    name: 'datav-skill-examples',
+    async configResolved() {
+      // Public files must exist before VitePress resolves image and HTML links.
+      await copyExamples(fileURLToPath(new URL('../public/examples/', import.meta.url)))
+    },
+    configureServer(server) {
+      server.middlewares.use(async (request, response, next) => {
+        const pathname = new URL(request.url || '/', 'http://localhost').pathname
+        const prefix = `${base}examples/`
+        if (!pathname.startsWith(prefix))
+          return next()
+        const name = pathname.slice(prefix.length)
+        const file = sourceFile(name)
+        if (!file)
+          return next()
+        try {
+          const content = await readFile(file)
+          response.setHeader('Content-Type', name.endsWith('.png') ? 'image/png' : 'text/html; charset=utf-8')
+          response.end(content)
+        }
+        catch {
+          response.statusCode = 404
+          response.end('Example not found')
+        }
+      })
+    },
+  }
+}
+
+export async function copySkillExamples(site: SiteConfig): Promise<void> {
+  await copyExamples(path.join(site.outDir, 'examples'))
+}
+
+async function copyExamples(destination: string): Promise<void> {
+  await mkdir(destination, { recursive: true })
+  const html = (await readdir(examples)).filter(name => name.endsWith('.html'))
+  const previews = (await readdir(path.join(examples, 'previews'))).filter(name => name.endsWith('.png'))
+  await Promise.all([...html, ...previews, 'minimal.html'].map(async (name) => {
+    const file = sourceFile(name)
+    if (file)
+      await copyFile(file, path.join(destination, name))
+  }))
+}

docs/components/borders/border-box-1.md

@@ -20,6 +20,12 @@ description: Animated rectangular SVG border component with moving highlight for
 </dvk-border-box-1>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-10.md

@@ -20,6 +20,12 @@ description: Rounded outline panel with animated corner glows and responsive con
 </dvk-border-box-10>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-11.md

@@ -20,6 +20,12 @@ description: Enterprise data-platform frame with status rails, live nodes, and r
 </dvk-border-box-11>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-12.md

@@ -20,6 +20,12 @@ description: Minimal electric-blue HUD frame with chamfered corners, title rail,
 </dvk-border-box-12>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-13.md

@@ -20,6 +20,12 @@ description: Sparse electric-blue split rail frame with corner modules, carrier
 </dvk-border-box-13>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-14.md

@@ -20,6 +20,12 @@ description: Orthogonal signal-port corner frame with circuit traces, pin contac
 </dvk-border-box-14>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-15.md

@@ -20,6 +20,12 @@ description: Lightweight responsive panel with corner dots, corner ticks, straig
 </dvk-border-box-15>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-16.md

@@ -20,6 +20,12 @@ description: Floating CPU-like thin border with broken outer rails, open inner h
 </dvk-border-box-16>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-2.md

@@ -20,6 +20,12 @@ description: Layered neon cyber frame with corners, energy bars, tick marks, and
 </dvk-border-box-2>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-3.md

@@ -20,6 +20,12 @@ description: Restrained futuristic blue frame with fixed corners, center modules
 </dvk-border-box-3>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-4.md

@@ -20,6 +20,12 @@ description: Dense neon HUD frame with ornate corners, detail modules, and sourc
 </dvk-border-box-4>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-5.md

@@ -33,6 +33,12 @@ description: Layered electric-blue HUD frame with five fixed frame layers and re
 </dvk-border-box-5>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-6.md

@@ -33,6 +33,12 @@ description: High-precision cyan HUD frame with traced source layers, marker sta
 </dvk-border-box-6>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-7.md

@@ -20,6 +20,12 @@ description: Chamfered glowing panel with fixed mirrored corner ornaments and op
 </dvk-border-box-7>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |

docs/components/borders/border-box-8.md

@@ -20,6 +20,12 @@ description: Dynamic polygon panel with four fixed mirrored animated corner orna
 </dvk-border-box-8>
 ```
 
+## Content
+
+Place headings and charts in the default slot. CSS parts are styling hooks, not named
+slots. Keep the automatic content inset; see the shared [content-area contract](/reference/architecture-contracts#authoring-slotted-content)
+for wrapper padding and explicit overrides.
+
 ## Props
 
 | Name | Type | Default | Notes |