@deckio/deck-engine 0.2.1 → 0.2.3

package/instructions/AGENTS.md

@@ -24,3 +24,15 @@ Create and maintain slide-based presentations. Each project is a self-contained
 - `@deckio/deck-engine` provides: `Slide`, `BottomBar`, `Navigation`, `SlideProvider`, `useSlides`, `GenericThankYouSlide`
 - See `.github/instructions/` for detailed conventions on slide JSX, CSS modules, and deck.config.js
 - See `.github/skills/` for step-by-step workflows (e.g., adding a slide)
+
+## Design system
+
+Check `designSystem` in `deck.config.js`. When it is `'shadcn'`:
+
+- Real shadcn/ui components are preinstalled: `Button`, `Card`, `Badge`, `Separator`, `Alert`
+- ReactBits motion components are preinstalled: `Aurora`, `BlurText`, `ShinyText`, `DecryptedText`, `SpotlightCard`
+- **Prefer real component imports over CSS imitation** — this is the default authoring pattern
+- **Expand via MCP** — the shadcn MCP server is pre-configured in `.vscode/mcp.json`. To add new components, prompt Copilot (e.g., *"Add Dialog from shadcn"*) or use `npx shadcn@latest add <name>`
+- Both shadcn/ui and ReactBits registries are configured in `components.json` and coexist cleanly
+- Read the shadcn supplement instructions (`shadcn-setup.instructions.md`, `shadcn-components.instructions.md`) for the full reference
+- See `MCP-GUIDE.md` for detailed MCP authoring prompts and workflows

package/instructions/deck-project.instructions.md

@@ -29,6 +29,12 @@ Then read the active theme descriptor:
 
 Use the descriptor as the source of truth for slide structure, CSS patterns, decorative language, component ecosystem, and anti-patterns.
 
+If `designSystem` is `shadcn`, also read the shadcn supplement instructions:
+- `shadcn-setup.instructions.md` — infrastructure contract
+- `shadcn-components.instructions.md` — component reference, preinstalled set, MCP expansion workflow
+
+Real shadcn/ui components (`Button`, `Card`, `Badge`, `Separator`, `Alert`) are preinstalled — prefer them over CSS imitation. To add more components, use MCP (prompt Copilot, e.g., *"Add Dialog from shadcn"*) or CLI (`npx shadcn@latest add dialog`). See `MCP-GUIDE.md` for the full MCP authoring reference.
+
 ## Out of scope — do NOT modify
 
 - `App.jsx`, `main.jsx` — these are generic, engine-driven, identical across projects

package/instructions/shadcn-components.instructions.md

@@ -0,0 +1,283 @@
+---
+description: "Component reference and migration patterns for shadcn DECKIO decks. Read alongside shadcn-setup.instructions.md when designSystem is shadcn."
+applyTo: "**/*"
+---
+
+# shadcn Component Reference
+
+Read this file when `deck.config.js` has `designSystem: 'shadcn'`. It complements the setup contract (`shadcn-setup.instructions.md`) with component-specific authoring guidance.
+
+## Component availability matrix
+
+| Component | Status | How to get it | Import path |
+|-----------|--------|---------------|-------------|
+| `Button` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/button'` |
+| `Card` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/card'` |
+| `CardHeader` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/card'` |
+| `CardTitle` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/card'` |
+| `CardDescription` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/card'` |
+| `CardAction` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/card'` |
+| `CardContent` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/card'` |
+| `CardFooter` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/card'` |
+| `Badge` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/badge'` |
+| `Separator` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/separator'` |
+| `Alert` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/alert'` |
+| `Aurora` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/aurora'` |
+| `BlurText` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/blur-text'` |
+| `ShinyText` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/shiny-text'` |
+| `DecryptedText` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/decrypted-text'` |
+| `SpotlightCard` | ✅ Preinstalled | Scaffolded automatically | `'@/components/ui/spotlight-card'` |
+| `Dialog` | ➕ Add first | `npx shadcn@latest add dialog` | `'@/components/ui/dialog'` |
+| `Sheet` | ➕ Add first | `npx shadcn@latest add sheet` | `'@/components/ui/sheet'` |
+| `Tooltip` | ➕ Add first | `npx shadcn@latest add tooltip` | `'@/components/ui/tooltip'` |
+| `Accordion` | ➕ Add first | `npx shadcn@latest add accordion` | `'@/components/ui/accordion'` |
+| `Tabs` | ➕ Add first | `npx shadcn@latest add tabs` | `'@/components/ui/tabs'` |
+| `Input` | ➕ Add first | `npx shadcn@latest add input` | `'@/components/ui/input'` |
+| `Table` | ➕ Add first | `npx shadcn@latest add table` | `'@/components/ui/table'` |
+| `Progress` | ➕ Add first | `npx shadcn@latest add progress` | `'@/components/ui/progress'` |
+| Any other shadcn | ➕ Add first | `npx shadcn@latest add <name>` | `'@/components/ui/<name>'` |
+| Any ReactBits | ➕ Add first | `npx shadcn@latest add @react-bits/<name>` | `'@/components/ui/<name>'` |
+
+### Preinstalled rule
+
+- ✅ components: import directly, no setup needed
+- ➕ components: run the CLI command first, **then** import — never import a file that doesn't exist
+
+## Migration patterns: raw markup → real components
+
+When updating slides from CSS-imitation patterns to real components, follow these transformations.
+
+### Card surface
+
+**Before (CSS imitation):**
+```jsx
+<div className={styles.card}>
+  <h3 className={styles.cardTitle}>Title</h3>
+  <p className={styles.cardText}>Description</p>
+</div>
+```
+```css
+.card {
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 24px;
+}
+.cardTitle { color: var(--card-foreground); font-weight: 600; }
+.cardText { color: var(--muted-foreground); }
+```
+
+**After (real component):**
+```jsx
+import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
+
+<Card className={styles.metricCard}>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <p>Description</p>
+  </CardContent>
+</Card>
+```
+```css
+.metricCard {
+  /* Only layout-specific overrides — component handles surface, border, radius */
+}
+```
+
+### Badge / label
+
+**Before (CSS imitation):**
+```jsx
+<span className={styles.badge}>Phase 1</span>
+```
+```css
+.badge {
+  background: var(--secondary);
+  color: var(--secondary-foreground);
+  padding: 2px 10px;
+  border-radius: 9999px;
+  font-size: 12px;
+  font-weight: 500;
+}
+```
+
+**After (real component):**
+```jsx
+import { Badge } from '@/components/ui/badge'
+
+<Badge variant="secondary">Phase 1</Badge>
+```
+
+### Action button
+
+**Before (CSS imitation):**
+```jsx
+<button className={styles.actionBtn}>Get started</button>
+```
+```css
+.actionBtn {
+  background: var(--primary);
+  color: var(--primary-foreground);
+  padding: 10px 20px;
+  border-radius: var(--radius);
+  border: none;
+  font-weight: 500;
+  cursor: pointer;
+}
+```
+
+**After (real component):**
+```jsx
+import { Button } from '@/components/ui/button'
+
+<Button>Get started</Button>
+```
+
+### Alert / callout
+
+**Before (CSS imitation):**
+```jsx
+<div className={styles.callout}>
+  <strong>Important</strong>
+  <p>This is a key message for the audience.</p>
+</div>
+```
+```css
+.callout {
+  background: var(--muted);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 16px;
+}
+```
+
+**After (real component):**
+```jsx
+import { Alert, AlertTitle, AlertDescription } from '@/components/ui/alert'
+
+<Alert>
+  <AlertTitle>Important</AlertTitle>
+  <AlertDescription>This is a key message for the audience.</AlertDescription>
+</Alert>
+```
+
+### Divider
+
+**Before (CSS imitation):**
+```jsx
+<hr className={styles.divider} />
+```
+```css
+.divider {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 16px 0;
+}
+```
+
+**After (real component):**
+```jsx
+import { Separator } from '@/components/ui/separator'
+
+<Separator />
+```
+
+## Component-first authoring decision tree
+
+When building a new slide element in a shadcn deck:
+
+1. **Is there a preinstalled component for this?** → Use it. (`Card`, `Badge`, `Button`, `Alert`, `Separator`)
+2. **Is there a preinstalled ReactBits component?** → Use it for motion/effects. (`BlurText`, `SpotlightCard`, etc.)
+3. **Would a non-preinstalled shadcn component fit?** → Add it via MCP or CLI, then import.
+4. **None of the above?** → Write custom JSX + CSS Module using semantic tokens from the descriptor.
+
+## Expanding with MCP — the primary workflow
+
+**MCP is the recommended way to add components** beyond the preinstalled set. The shadcn MCP server is pre-configured in `.vscode/mcp.json` and gives AI assistants direct access to both the shadcn/ui and ReactBits registries.
+
+### How it works
+
+When an author (or an AI agent acting on behalf of the author) needs a component that isn't preinstalled:
+
+1. **Prompt Copilot** with what you need — e.g., *"Add the Dialog component from shadcn"*
+2. The MCP server resolves the component from the registry
+3. The component source is written to `src/components/ui/`
+4. Import it in your slide: `import { Dialog } from '@/components/ui/dialog'`
+
+### Example prompts for agents and authors
+
+**shadcn/ui components:**
+- *"Add the Dialog component from shadcn"*
+- *"Add Sheet, Tooltip, and Tabs from shadcn"*
+- *"I need a data table — add Table from shadcn"*
+- *"Add Accordion from shadcn for collapsible sections"*
+- *"What shadcn components would work for a pricing comparison slide?"*
+
+**ReactBits components:**
+- *"Add Hyperspeed from React Bits for an animated background"*
+- *"Show me available text animations from React Bits"*
+- *"Add AnimatedContent from React Bits for scroll reveals"*
+
+### Registry coexistence
+
+Both registries are declared in `components.json` and share the same output directory:
+
+| Registry | CLI syntax | MCP prompt pattern |
+|----------|-----------|-------------------|
+| **shadcn/ui** | `npx shadcn@latest add dialog` | *"Add Dialog from shadcn"* |
+| **ReactBits** | `npx shadcn@latest add @react-bits/code-block` | *"Add code-block from React Bits"* |
+
+They never conflict — shadcn/ui components use Radix primitives and Tailwind, ReactBits components use their own animation systems. Both consume the same `cn()` utility and `@/` path alias.
+
+### CLI fallback
+
+If MCP is unavailable, the CLI produces identical results:
+
+```bash
+npx shadcn@latest add dialog sheet tooltip
+npx shadcn@latest add @react-bits/animated-content
+```
+
+### For agents: when to suggest MCP expansion
+
+When generating slide code that would benefit from a non-preinstalled component:
+
+1. **Don't silently import a component that doesn't exist** — check the preinstalled list above
+2. **Suggest the MCP prompt** — e.g., "This slide would benefit from a Dialog. Run: *Add Dialog from shadcn* or `npx shadcn@latest add dialog`"
+3. **Then generate the slide code** using the component, noting the dependency
+
+## Design-system supplement discovery
+
+The shadcn design system adds a supplementary authoring layer on top of the theme:
+
+- **Theme descriptor** (`shadcn.md`) → visual language, token contract, slide personality, anti-patterns
+- **Setup contract** (`shadcn-setup.instructions.md`) → infrastructure, what's wired, how to verify
+- **Component reference** (this file) → what components exist, how to use them, migration patterns
+
+Skills and agents should load all three when `designSystem: 'shadcn'` is detected in `deck.config.js`. The presence of this field is the trigger — there is no separate plugin or runtime discovery mechanism.
+
+### How skills detect the design system
+
+```js
+// In deck.config.js
+export default {
+  // ...
+  designSystem: 'shadcn',  // ← triggers component-first authoring
+  theme: 'shadcn',          // ← drives visual token set
+}
+```
+
+When a skill reads `designSystem: 'shadcn'`:
+1. Load the theme descriptor for visual rules
+2. Load `shadcn-setup.instructions.md` for infrastructure rules
+3. Load `shadcn-components.instructions.md` for component authoring rules
+4. Prefer real component imports over CSS imitation in all generated code
+
+### Extending the supplement pattern
+
+If a future design system is added (e.g., `designSystem: 'radix'`), the same pattern applies:
+- Create `<name>-setup.instructions.md` and `<name>-components.instructions.md`
+- Skills check `designSystem` and load the matching supplement files
+- Theme descriptors remain independent of the design system choice

package/instructions/shadcn-setup.instructions.md

@@ -0,0 +1,117 @@
+---
+description: "Canonical Tailwind v4 + shadcn setup contract for DECKIO decks. Read when designSystem is shadcn."
+applyTo: "**/*"
+---
+
+# shadcn Setup Contract
+
+Use this file when `deck.config.js` has `designSystem: 'shadcn'`.
+
+## What is canonical today
+
+1. `src/main.jsx` should import `./index.css`
+2. `src/index.css` is the single CSS entrypoint for the deck
+3. `src/index.css` should import:
+   - `@deckio/deck-engine/styles/global.css`
+   - `@deckio/deck-engine/themes/<theme>.css`
+4. `global.css` establishes the canonical Tailwind layer order: `@layer theme, base, components, utilities;`
+5. The active theme CSS provides `@import "tailwindcss"` plus the `@theme inline` bridge used by shadcn-style utilities
+
+## Preinstalled components
+
+Scaffolded shadcn decks ship with **real, working components** out of the box. These are source files copied into the project — not npm dependencies.
+
+### shadcn/ui starter set (preinstalled)
+
+| Component | Import path | Source |
+|-----------|-------------|--------|
+| `Button` | `'@/components/ui/button'` | Pre-scaffolded from engine templates |
+| `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | `'@/components/ui/card'` | Pre-scaffolded from engine templates |
+| `Badge` | `'@/components/ui/badge'` | Pre-scaffolded from engine templates |
+| `Separator` | `'@/components/ui/separator'` | Pre-scaffolded from engine templates |
+| `Alert`, `AlertTitle`, `AlertDescription` | `'@/components/ui/alert'` | Pre-scaffolded from engine templates |
+
+### ReactBits starter set (preinstalled)
+
+| Component | Import path | Purpose |
+|-----------|-------------|---------|
+| `Aurora` | `'@/components/ui/aurora'` | Gradient background effect |
+| `BlurText` | `'@/components/ui/blur-text'` | Blur-in text animation |
+| `ShinyText` | `'@/components/ui/shiny-text'` | Shimmer text effect |
+| `DecryptedText` | `'@/components/ui/decrypted-text'` | Glitch text animation |
+| `SpotlightCard` | `'@/components/ui/spotlight-card'` | Spotlight glow card wrapper |
+
+### Infrastructure (preinstalled)
+
+| Resource | Path | Purpose |
+|----------|------|---------|
+| `cn()` utility | `src/lib/utils.js` | Class name merging (clsx + tailwind-merge) |
+| `ThemeProvider` | `src/components/theme-provider.jsx` | Light/dark mode shell |
+| `components.json` | project root | shadcn CLI + registry config |
+| `jsconfig.json` | project root | `@/*` path alias |
+| `.vscode/mcp.json` | `.vscode/` | shadcn MCP server config |
+
+### Add via MCP or CLI (not preinstalled)
+
+Everything else in the shadcn/ui and ReactBits registries must be added before importing.
+
+**MCP (recommended):** The shadcn MCP server is pre-configured in `.vscode/mcp.json`. Prompt Copilot directly:
+- *"Add the Dialog component from shadcn"*
+- *"Add Sheet and Tooltip from shadcn"*
+- *"Add AnimatedContent from React Bits"*
+
+**CLI (fallback):**
+```bash
+# Official shadcn/ui components
+npx shadcn@latest add dialog
+npx shadcn@latest add sheet tooltip input textarea select
+
+# ReactBits components via registry
+npx shadcn@latest add @react-bits/code-block
+npx shadcn@latest add @react-bits/animated-content
+```
+
+Both methods produce the same result — component source files in `src/components/ui/`.
+
+### Registry coexistence
+
+`components.json` declares two registries that share the same output directory and infrastructure:
+
+- **shadcn/ui** (default): UI primitives — no prefix needed
+- **ReactBits** (`@react-bits/`): Animation and effect components
+
+They never conflict. shadcn/ui components use Radix + Tailwind, ReactBits components use their own animation systems. Both use the `cn()` utility and `@/` alias.
+
+## Default authoring pattern
+
+**Real components are the default.** When `designSystem: 'shadcn'`, every new slide should:
+
+1. **Import preinstalled components first** — `Button`, `Card`, `Badge`, `Separator`, `Alert` are already there. Use them.
+2. **Use ReactBits for motion** — `BlurText`, `SpotlightCard`, etc. for animation inside content blocks.
+3. **Use CSS Modules only for layout** — grid, spacing, density, positioning. Not for recreating what components already do.
+4. **Never imitate a component with raw markup** — if `<Card>` exists, use it. Don't hand-build a card-like div with border-radius and background.
+5. **Expand via MCP when needed** — if the slide needs a dialog, accordion, or tabs, prompt Copilot (e.g., *"Add Dialog from shadcn"*) or run `npx shadcn@latest add <name>`, then import.
+
+## Design-system supplement layer
+
+When `designSystem: 'shadcn'` is set in `deck.config.js`, agents should load additional authoring context beyond the theme descriptor:
+
+1. Read this file (`shadcn-setup.instructions.md`) for the setup contract
+2. Read `shadcn-components.instructions.md` for the component reference and migration patterns
+3. Check which components exist in `src/components/ui/` before importing — the preinstalled set is guaranteed, but additional ones may have been added by the author
+
+This two-layer approach (theme descriptor + design-system supplement) lets the theme control visual language while the design system controls component authoring patterns.
+
+## Verification checklist
+
+Before claiming a deck is "using shadcn":
+
+- `src/index.css` exists and is imported by `src/main.jsx`
+- `components.json` exists with correct aliases (`@/components`, `@/lib/utils`, `@/components/ui`) and registries (`@react-bits`)
+- `@/` resolves to `src`
+- `src/lib/utils.js` exists
+- Preinstalled shadcn/ui components exist: `button.jsx`, `card.jsx`, `badge.jsx`, `separator.jsx`, `alert.jsx` in `src/components/ui/`
+- Preinstalled ReactBits components exist in `src/components/ui/`
+- `.vscode/mcp.json` exists with the shadcn MCP server configured
+- `MCP-GUIDE.md` exists at project root
+- Any additional imported component actually exists under `src/components/ui/`

package/instructions/slide-css.instructions.md

@@ -19,6 +19,14 @@ Before writing any slide CSS:
 - Custom themes: read `src/themes/<theme>/descriptor.md` or `src/themes/<theme>.descriptor.md`
 - If the custom descriptor is missing, fall back to the built-in descriptor implied by `designSystem`
 
+If `designSystem` is `shadcn`, also read the shadcn supplement instructions:
+- `shadcn-setup.instructions.md` — infrastructure contract
+- `shadcn-components.instructions.md` — component reference, preinstalled set, migration patterns
+
+### CSS role in shadcn decks
+
+When real components are available, **CSS Modules handle layout only** — grid, spacing, density, positioning. The components own their own surface styling (background, border, border-radius, typography). Do not rewrite component styles in CSS Modules. Override only when the descriptor explicitly calls for deck-specific layout adjustments (e.g., a card width constraint or grid gap).
+
 ## What to read in the descriptor
 
 Before generating CSS, read:

package/instructions/slide-jsx.instructions.md

@@ -19,6 +19,10 @@ Before writing any slide JSX:
 - Custom themes: read `src/themes/<theme>/descriptor.md` or `src/themes/<theme>.descriptor.md`
 - If the custom descriptor is missing, fall back to the built-in descriptor implied by `designSystem`
 
+If `designSystem` is `shadcn`, also read the shadcn supplement instructions:
+- `shadcn-setup.instructions.md` — infrastructure contract
+- `shadcn-components.instructions.md` — component reference, preinstalled set, migration patterns
+
 ## Common imports
 
 ```jsx
@@ -26,6 +30,22 @@ import { BottomBar, Slide } from '@deckio/deck-engine'
 import styles from './MySlide.module.css'
 ```
 
+### shadcn deck imports (when `designSystem === 'shadcn'`)
+
+Preinstalled components are ready to import — no CLI setup needed:
+
+```jsx
+import { Button } from '@/components/ui/button'
+import { Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter } from '@/components/ui/card'
+import { Badge } from '@/components/ui/badge'
+import { Separator } from '@/components/ui/separator'
+import { Alert, AlertTitle, AlertDescription } from '@/components/ui/alert'
+import SpotlightCard from '@/components/ui/spotlight-card'
+import BlurText from '@/components/ui/blur-text'
+```
+
+**Real components are the default authoring pattern.** Never recreate a Card, Badge, Button, Alert, or Separator with raw `<div>` + CSS when the real component is available.
+
 ## What to read in the descriptor
 
 Before generating JSX, read:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deckio/deck-engine",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -40,6 +40,7 @@
     "**/*.css"
   ],
   "scripts": {
+    "version:sync": "node scripts/sync-version-from-npm.mjs",
     "prepublishOnly": "npm test --if-present"
   },
   "dependencies": {

package/scripts/sync-version-from-npm.mjs

@@ -0,0 +1,68 @@
+import { execSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageJsonPath = join(__dirname, '..', 'package.json')
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+
+function parseVersion(value) {
+  const match = String(value || '').trim().match(/^(\d+)\.(\d+)\.(\d+)$/)
+  if (!match) {
+    throw new Error(`Unsupported semver value: ${value}`)
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  }
+}
+
+function compareVersion(left, right) {
+  if (left.major !== right.major) return left.major - right.major
+  if (left.minor !== right.minor) return left.minor - right.minor
+  return left.patch - right.patch
+}
+
+function formatVersion(value) {
+  return `${value.major}.${value.minor}.${value.patch}`
+}
+
+function getPublishedVersion(packageName) {
+  const npmCommand = process.platform === 'win32'
+    ? `npm view ${packageName} version`
+    : `npm view ${packageName} version`
+  const raw = execSync(npmCommand, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: true,
+  }).trim()
+
+  if (!raw) {
+    throw new Error(`npm view returned an empty version for ${packageName}`)
+  }
+
+  return raw
+}
+
+const localVersion = parseVersion(packageJson.version)
+const publishedVersionRaw = getPublishedVersion(packageJson.name)
+const publishedVersion = parseVersion(publishedVersionRaw)
+
+if (compareVersion(localVersion, publishedVersion) > 0) {
+  console.log(`Local version ${packageJson.version} is already ahead of npm ${publishedVersionRaw}`)
+  process.exit(0)
+}
+
+const nextVersion = {
+  major: publishedVersion.major,
+  minor: publishedVersion.minor,
+  patch: publishedVersion.patch + 1,
+}
+
+packageJson.version = formatVersion(nextVersion)
+writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`)
+
+console.log(`Updated ${packageJson.name} version from ${formatVersion(localVersion)} to ${packageJson.version} using npm latest ${publishedVersionRaw}`)

package/skills/deck-add-slide/SKILL.md

@@ -51,6 +51,32 @@ If no custom descriptor exists, fall back to the built-in descriptor that matche
 
 If the descriptor and `designSystem` disagree, follow `designSystem` for structure and call out the mismatch in your response so the project owner can fix the configuration.
 
+### When `designSystem === 'shadcn'`: load the component supplement
+
+Also read the shadcn supplement instructions before generating code:
+
+1. `shadcn-setup.instructions.md` — infrastructure contract
+2. `shadcn-components.instructions.md` — component reference, migration patterns, MCP expansion workflow
+
+These tell you which real components are preinstalled and ready to import:
+
+| Preinstalled | Import |
+|---|---|
+| `Button` | `'@/components/ui/button'` |
+| `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter` | `'@/components/ui/card'` |
+| `Badge` | `'@/components/ui/badge'` |
+| `Separator` | `'@/components/ui/separator'` |
+| `Alert`, `AlertTitle`, `AlertDescription` | `'@/components/ui/alert'` |
+| `Aurora`, `BlurText`, `ShinyText`, `DecryptedText`, `SpotlightCard` | `'@/components/ui/<name>'` |
+
+**Always prefer real component imports over CSS imitation.** If a preinstalled component can replace a hand-built div, use the component.
+
+**Need a component that isn't preinstalled?** Use MCP (recommended) or CLI to add it first:
+- MCP: Prompt Copilot — *"Add Dialog from shadcn"* or *"Add AnimatedContent from React Bits"*
+- CLI: `npx shadcn@latest add dialog` or `npx shadcn@latest add @react-bits/animated-content`
+
+Never import a component file that doesn't exist. Add it first, then import.
+
 ## Step 3 — Create the slide from the descriptor
 
 The descriptor is the source of truth. Read these sections before generating code:
@@ -109,6 +135,9 @@ After writing the slide:
 
 - [ ] Read `theme` and `designSystem` from `deck.config.js`
 - [ ] Read the active theme descriptor before writing code
+- [ ] If `designSystem === 'shadcn'`: read the shadcn supplement instructions
+- [ ] If `designSystem === 'shadcn'`: used real component imports (Card, Badge, Button, Alert, Separator) instead of CSS imitation
+- [ ] If `designSystem === 'shadcn'` and a non-preinstalled component is needed: added it via MCP or CLI before importing
 - [ ] Used the descriptor's exact JSX skeleton or direct variant of it
 - [ ] Used the descriptor's exact CSS skeleton or direct variant of it
 - [ ] Stayed inside the descriptor's token set and component ecosystem

package/skills/deck-validate-project/SKILL.md

@@ -96,6 +96,40 @@ Check whether the project configuration and descriptor agree:
 - If `designSystem` is not `'shadcn'`, the project should follow a default DECKIO descriptor such as dark or light
 - If the descriptor and `designSystem` disagree, report an **architecture mismatch** even if individual slides render
 
+### When `designSystem === 'shadcn'`: validate preinstalled components
+
+Verify the preinstalled component set is intact:
+
+- [ ] `src/components/ui/button.jsx` exists
+- [ ] `src/components/ui/card.jsx` exists
+- [ ] `src/components/ui/badge.jsx` exists
+- [ ] `src/components/ui/separator.jsx` exists
+- [ ] `src/components/ui/alert.jsx` exists
+- [ ] `src/lib/utils.js` exists (provides `cn()`)
+- [ ] `components.json` exists at project root with correct aliases and registries
+- [ ] `.vscode/mcp.json` exists with shadcn MCP server configured
+- [ ] `MCP-GUIDE.md` exists at project root
+- [ ] ReactBits files exist: `aurora.jsx`, `blur-text.jsx`, `shiny-text.jsx`, `decrypted-text.jsx`, `spotlight-card.jsx` in `src/components/ui/`
+
+If any preinstalled file is missing, report it as a **scaffold integrity issue** — the file may have been accidentally deleted.
+
+### Validate MCP integration
+
+- [ ] `.vscode/mcp.json` exists and contains a `shadcn` server entry
+- [ ] `components.json` has `registries` with `@react-bits` configured
+- [ ] `components.json` has correct `aliases` (`@/components`, `@/lib/utils`, `@/components/ui`)
+
+If MCP config is missing, the author loses the primary component expansion workflow.
+
+### Validate component usage patterns
+
+For each slide in a shadcn deck, check:
+
+- [ ] Slides use real `<Card>`, `<Badge>`, `<Button>`, `<Alert>`, `<Separator>` imports instead of CSS-imitation divs where applicable
+- [ ] No hand-built card-like patterns when the Card component is available
+- [ ] No raw `<button>` or `<span className={styles.badge}>` when real components exist
+- [ ] CSS Modules focus on layout (grid, spacing, positioning) not component surface styling
+
 ## Step 6: Report results
 
 Summarize:
@@ -112,6 +146,10 @@ Summarize:
 
 - [ ] Read `theme` and `designSystem`
 - [ ] Read the active descriptor
+- [ ] If `designSystem === 'shadcn'`: read shadcn supplement instructions
+- [ ] If `designSystem === 'shadcn'`: verified preinstalled component files exist
+- [ ] If `designSystem === 'shadcn'`: verified MCP config (`.vscode/mcp.json`, `components.json` registries)
+- [ ] If `designSystem === 'shadcn'`: verified slides use real components over CSS imitation
 - [ ] All `deck.config.js` imports resolve
 - [ ] `slides` array matches imports
 - [ ] Every `.jsx` slide has a companion `.module.css`