@iamdangavin/claude-skill-vitepress-docs 3.1.4 → 3.1.7

package/README.md

@@ -1,2 +1,130 @@
 # claude-skill-vitepress-docs
 
+A [Claude Code](https://claude.ai/claude-code) skill suite for creating and maintaining VitePress documentation for any project. Covers the full docs lifecycle — from initial setup through writing, capturing screenshots and videos, keeping docs in sync with code changes, and configuring visual branding.
+
+## Installation
+
+```bash
+npx @iamdangavin/claude-skill-vitepress-docs
+```
+
+This installs the `vitedocs:` command suite into `~/.claude/commands/vitedocs/`. Commands are then available in any Claude Code session.
+
+## Commands
+
+### `/vitedocs:init`
+
+Entry point. Asks which mode you need and tells you which command to run next. Use this if you're not sure where to start.
+
+---
+
+### `/vitedocs:setup`
+
+Wire up VitePress and GitHub Actions for GitHub Pages deployment.
+
+- Scaffolds the VitePress config, package.json, and directory structure inside your chosen docs folder
+- Writes a GitHub Actions workflow (`.github/workflows/deploy-docs.yml`) that builds and deploys to GitHub Pages on push
+- Adds `node_modules` and `.vitepress/cache` to `.gitignore`
+- Outputs the expected deploy URL and a next-steps checklist
+
+**Next:** `/vitedocs:generate`
+
+---
+
+### `/vitedocs:generate`
+
+Analyze the codebase and write documentation pages.
+
+- Auto-detects the tech stack (Next.js, WordPress, Node, static, etc.) before asking any questions
+- Supports user-facing guides, developer reference docs, or both
+- Proposes a doc structure outline and confirms before writing anything
+- Identifies 3–6 home page feature highlights drawn from the actual codebase
+- Writes all pages with real content — gaps are marked with `<!-- GAP: ... -->` comments rather than stopping to ask
+- Inserts image placeholders and records them in `.vitepress/docs-manifest.json` for capture later
+- Suggests video captures (via `VideoDemo`) for interactive flows and screenshots for static UI states
+- Installs and registers custom VitePress components: `ApiEndpoint`, `VideoDemo`, medium-zoom
+- Generates API endpoint docs using the `ApiEndpoint` component when REST routes are found
+- Includes color chips (inline swatches) in any table that references color values
+
+**Next:** `/vitedocs:capture` (if placeholder images were created)
+
+---
+
+### `/vitedocs:capture`
+
+Capture screenshots and record interaction videos for docs pages.
+
+- Reads `.vitepress/docs-manifest.json` to find all pending captures
+- Batches all screenshots into a single script (one approval covers the full set)
+- Records `.webm` interaction videos using Playwright with step-by-step captions
+- Generates `.vtt` caption files (committed to git) synced to video timestamps
+- Shows a custom cursor overlay during video recordings for visibility
+- Hides the Next.js Turbopack dev tools badge (`#devtools-indicator`) in all captures
+- Supports local dev servers (Node or non-Node) and deployed URLs
+- Handles auth-gated screens — credentials are used only in-session and never written to any file
+- Videos are uploaded to GitHub Releases (tagged `docs-media`) to keep binary files out of git
+- Rewrites surrounding prose to match what was actually captured
+
+**Next:** `/vitedocs:sync`
+
+---
+
+### `/vitedocs:sync`
+
+Detect code drift and update docs that are out of date.
+
+- Hashes source files referenced in the manifest and compares against `syncHash` values from last sync
+- Reports which pages have drifted and which are current
+- Rewrites only the sections that changed — does not regenerate entire pages
+- Flags screenshots that may need recapture after content changes
+- Confirms each proposed update before writing
+
+**Next:** `/vitedocs:capture` (if screenshots were flagged for recapture)
+
+---
+
+### `/vitedocs:brand`
+
+Configure colors, fonts, logo, and favicon for VitePress docs.
+
+- Derives a full VitePress brand palette (4 tokens, light + dark) from a single hex color
+- Previews the derived palette as a table with inline color chips before writing anything
+- Supports Google Fonts, custom CSS imports, or the VitePress default (Inter)
+- Writes brand variables to `.vitepress/theme/index.css` and logo/favicon to `config.mjs`
+- Can apply shared branding across all docs paths or different branding per path
+
+**Next:** `/vitedocs:capture` or `/vitedocs:sync`
+
+---
+
+### `/vitedocs:update`
+
+Retrofit an existing VitePress docs setup with the latest components and dependencies.
+
+- Writes or overwrites `ApiEndpoint.vue` and `VideoDemo.vue` to the latest versions
+- Merges medium-zoom setup and component registrations into `.vitepress/theme/index.js`
+- Adds required z-index CSS rules to `index.css`
+- Installs `medium-zoom` and `highlight.js` if not already present
+- Reads existing files before editing — never rewrites unrelated config sections
+
+**Next:** `/vitedocs:capture` or `/vitedocs:sync`
+
+---
+
+## How the commands fit together
+
+```
+setup → generate → capture → sync (repeat as code changes)
+                 ↘ brand (anytime)
+                 ↘ update (when upgrading the skill)
+```
+
+## Manifest
+
+All modes read and write `.vitepress/docs-manifest.json`. This file tracks page-to-source mappings, image placeholder status, sync hashes, and video metadata. It is local-only and should be added to `.gitignore`.
+
+## Requirements
+
+- [Claude Code](https://claude.ai/claude-code)
+- [Playwright](https://playwright.dev/) (for `/vitedocs:capture` — install with `npx playwright install`)
+- A GitHub repo with GitHub Pages enabled (for deployment and video hosting)

package/commands/vitedocs/brand.md

@@ -87,21 +87,16 @@ If custom: ask as plain text — "What hex color for dark mode accent?"
 
 ### Step 4 — Preview palette
 
-Before writing any files, present the full derived palette as a table:
+Before writing any files, present the full derived palette as a markdown table with inline color chips. Use this format exactly — the `<span>` renders in Claude's markdown output and in VitePress:
 
-```
-Light mode
-  --vp-c-brand-1:    #E63946
-  --vp-c-brand-2:    #EB5E6A
-  --vp-c-brand-3:    #F28B93
-  --vp-c-brand-soft: #E6394620
-
-Dark mode
-  --vp-c-brand-1:    #F05A64
-  --vp-c-brand-2:    #F47980
-  --vp-c-brand-3:    #F7A0A5
-  --vp-c-brand-soft: #F05A6420
-```
+| Token | &nbsp; | Light | &nbsp; | Dark |
+|---|---|---|---|---|
+| `--vp-c-brand-1` | <span style="display:inline-block;width:14px;height:14px;background:#E63946;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#E63946` | <span style="display:inline-block;width:14px;height:14px;background:#F05A64;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F05A64` |
+| `--vp-c-brand-2` | <span style="display:inline-block;width:14px;height:14px;background:#EB5E6A;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#EB5E6A` | <span style="display:inline-block;width:14px;height:14px;background:#F47980;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F47980` |
+| `--vp-c-brand-3` | <span style="display:inline-block;width:14px;height:14px;background:#F28B93;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F28B93` | <span style="display:inline-block;width:14px;height:14px;background:#F7A0A5;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F7A0A5` |
+| `--vp-c-brand-soft` | <span style="display:inline-block;width:14px;height:14px;background:#E6394620;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#E6394620` | <span style="display:inline-block;width:14px;height:14px;background:#F05A6420;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F05A6420` |
+
+Substitute real derived hex values in place of the examples above.
 
 Then ask:
 
@@ -155,4 +150,6 @@ Files updated:
   PATH/.vitepress/config.mjs       — logo, favicon
 
 Run the local dev server to preview: npm run dev
+
+Next: run /vitedocs:capture if you have pending screenshots or videos, or /vitedocs:sync to check for code drift.
 ```

package/commands/vitedocs/generate.md

@@ -406,6 +406,16 @@ Populate `name`, `text`, `tagline`, and the `link` in `actions` from what you kn
    Use a screenshot (not video) for: static UI states, settings screens, empty states, error messages.
    Use a video for: multi-step flows, button interactions, animations, form submissions, drag-and-drop.
 
+**Color chips in tables:** Whenever a doc page contains a table with color values (hex codes, `rgb()`, `hsl()`, or CSS custom properties that resolve to a color), include an inline color chip in the same table cell. Use a `<span>` with an inline style — VitePress renders HTML inside markdown tables:
+
+```md
+| Token | | Value |
+|---|---|---|
+| `--brand-primary` | <span style="display:inline-block;width:14px;height:14px;background:#E63946;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#E63946` |
+```
+
+Apply this to any color reference you encounter in the source — CSS variables, Tailwind config values, design token files, theme files, etc. If the value is a CSS variable (e.g. `var(--some-color)`) and you can resolve its hex from the source, use the resolved hex for the chip. If you can't resolve it, omit the chip for that row.
+
 Do not stop to ask gap questions mid-page. Keep writing and accumulate all gaps.
 
 ### Step 5 — Gap review

package/commands/vitedocs/setup.md

@@ -274,4 +274,8 @@ docs.yourdomain.com
 
 ### Step 4 — Summary
 
-List files written and give the user a next-steps checklist with the expected deploy URL.
+List files written and give the user a next-steps checklist with the expected deploy URL. End with:
+
+```
+Next: run /vitedocs:generate to analyze the codebase and write documentation pages.
+```

package/commands/vitedocs/sync.md

@@ -93,5 +93,5 @@ Update `lastSynced` and `syncHash` for all updated pages. Update the top-level `
 ```
 Updated X of N drifted pages.
   X gap comments added for manual review.
-  Y screenshots flagged for recapture — run /vitedocs:screenshot when ready.
+  Y screenshots flagged for recapture — run /vitedocs:capture when ready.
 ```

package/commands/vitedocs/update.md

@@ -134,6 +134,8 @@ Changes applied:
   PATH/.vitepress/theme/index.js              — merged medium-zoom + ApiEndpoint
   PATH/.vitepress/theme/index.css             — added z-index rules
   PATH/package.json                           — installed medium-zoom, highlight.js
+
+Next: run /vitedocs:capture to refresh screenshots, or /vitedocs:sync to check for code drift.
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamdangavin/claude-skill-vitepress-docs",
-  "version": "3.1.4",
+  "version": "3.1.7",
   "description": "Installs the vitedocs: Claude Code skill suite — VitePress docs setup, generate, screenshot, sync, brand, and update.",
   "type": "module",
   "bin": {