@deckio/deck-engine 0.1.1 → 0.2.1

package/skills/deck-generate-image/SKILL.md

@@ -31,17 +31,34 @@ OPENAI_API_KEY=sk-proj-...
 
 ## Workflow
 
-### Step 1 — Craft the prompt
+### Step 1 — Read the active theme descriptor
+
+Open `deck.config.js`, read `theme` and `designSystem`, then resolve the active theme descriptor using the same rules as `deck-add-slide`.
+
+Use the descriptor as the source of truth for:
+
+- palette and semantic token intent
+- overall image style
+- what decorative language belongs in the project
+- what to avoid so the image does not fight the slide system
+
+### Step 2 — Craft the prompt
 
 Write a detailed prompt including:
 
-- **Subject** — what the image depicts.
-- **Style** — flat icon, line art, illustration, isometric, etc.
-- **Colors** — match the design system: `#0d1117` (bg-deep), `#58a6ff` (accent), `#3fb950` (green), `#bc8cff` (purple).
-- **Background** — almost always "transparent background".
-- **Aspect ratio** — square (1024x1024) for icons, wide (1536x1024) for banners.
+- **Subject** — what the image depicts
+- **Style** — match the descriptor's slide personality and example direction
+- **Colors** — derive from the descriptor's token table and visual language instead of hardcoded hex values
+- **Background** — usually "transparent background"
+- **Aspect ratio** — square (`1024x1024`) for icons, wide (`1536x1024`) for banners
+
+Examples:
+
+- Dark descriptor → deep, high-contrast accents, presentation-friendly glow restraint
+- Light descriptor → brighter, cleaner palette with subtle contrast and restrained glow
+- shadcn descriptor → clean editorial/system aesthetic with semantic surfaces and no deep-space ornament
 
-### Step 2 — Generate
+### Step 3 — Generate
 
 Run from the project root:
 
@@ -60,7 +77,7 @@ node node_modules/@deckio/deck-engine/scripts/generate-image.mjs --prompt "..."
 
 Images are saved to `src/data/generated/`.
 
-### Step 3 — Use in a slide
+### Step 4 — Use in a slide
 
 ```jsx
 import myIcon from '../data/generated/my-icon.png'
@@ -68,9 +85,9 @@ import myIcon from '../data/generated/my-icon.png'
 <img src={myIcon} alt="Bridge icon" style={{ width: 120, height: 120 }} />
 ```
 
-### Step 4 — Iterate
+### Step 5 — Iterate
 
-If the image doesn't match expectations, refine the prompt and re-run with the same `--name` to overwrite. Use **deck-eyes** to verify how it looks in the slide.
+If the image doesn't match expectations, refine the prompt and re-run with the same `--name` to overwrite. Use **deck-inspect** to verify how it looks in the slide.
 
 ## SVG alternative
 
@@ -78,7 +95,7 @@ For simple icons, write SVG markup directly in JSX:
 
 ```jsx
 <svg width="48" height="48" viewBox="0 0 48 48" fill="none">
-  <circle cx="24" cy="24" r="20" stroke="#58a6ff" strokeWidth="2" />
+  <circle cx="24" cy="24" r="20" stroke="currentColor" strokeWidth="2" />
 </svg>
 ```
 

package/skills/deck-inspect/SKILL.md

@@ -7,6 +7,23 @@ description: Capture a screenshot of the deck app to visually inspect slides. Us
 
 Captures a screenshot of the running deck using VS Code browser tools (Edge "Sharing with Agent").
 
+## Step 0 — Read `deck.config.js` and the active theme descriptor
+
+Before deciding what to capture:
+
+1. Open `deck.config.js`
+2. Read `theme` and `designSystem`
+3. Resolve and read the active theme descriptor using the same rules as `deck-add-slide`
+4. Use that descriptor as the visual source of truth
+
+Judge the screenshot against the descriptor's:
+
+- slide personality
+- decorative elements
+- surface treatment
+- component ecosystem
+- anti-patterns
+
 ## Deciding what to capture
 
 1. **Slide** — resolve in this order:
@@ -32,29 +49,35 @@ Read `project` and `port` from `.github/memory/state.md` if not known.
 
 ### Step 2 — Navigate to the target slide
 
-The deck opens on slide 1. To reach slide N, press `ArrowRight` (N − 1) times:
-
-```js
-// run_playwright_code on the page
-for (let i = 0; i < N - 1; i++) {
-  await page.keyboard.press('ArrowRight');
-  await page.waitForTimeout(300);
-}
-```
+The deck opens on slide 1. To reach slide N, press `ArrowRight` (N − 1) times.
 
 If the page is already on a different slide, navigate to slide 1 first by pressing `Home`, then advance forward.
 
 ### Step 3 — Take a screenshot
 
-Use `screenshot_page` with the page ID to capture the current view. The screenshot is returned inline — no file path needed.
+Use `screenshot_page` with the page ID to capture the current view.
 
 ### Step 4 — Inspect and report
 
 Study the screenshot and check for:
+
 - Layout alignment and spacing
-- Typography (size, weight, color)
+- Typography hierarchy
 - Missing or broken elements
 - Color and contrast issues
 - Overflow or clipping
+- Theme or design-system mismatches
+
+### Step 5 — Use the descriptor to judge fit
+
+Examples of descriptor mismatches to flag:
+
+- A default descriptor slide missing the left accent bar or orb treatment
+- A shadcn descriptor slide showing DECKIO orb backgrounds or gradient card-top bars
+- A shadcn descriptor slide that ignores semantic surfaces and looks like a dark DECKIO default slide
+- A light descriptor slide using heavy dark-theme glows that muddy the canvas
+- A slide importing or visually implying the wrong component ecosystem
+
+If `designSystem` and the descriptor disagree, explicitly report that as a configuration mismatch.
 
-Report any issues found to the user.
+When a mismatch exists, say the slide was built with the wrong theme/design-system pattern set and should be corrected using `deck-add-slide`.

package/skills/deck-sketch/SKILL.md

@@ -61,31 +61,38 @@ Write-Host "Sketch saved: $file"
 
 Reference the saved screenshot image. Study it carefully and identify:
 
-- **Layout structure** — columns/rows, content zones, header/footer areas.
-- **Text elements** — headings, labels, bullet points, callouts.
-- **Visual elements** — boxes, icons, images, dividers, backgrounds.
-- **Data patterns** — tables, grids, lists, charts, metrics.
+- **Layout structure** — columns/rows, content zones, header/footer areas
+- **Text elements** — headings, labels, bullet points, callouts
+- **Visual elements** — boxes, icons, images, dividers, backgrounds
+- **Data patterns** — tables, grids, lists, charts, metrics
 
 Describe what you see back to the user and confirm your interpretation.
 
-### Step 4 — Create the slide
+### Step 4 — Build the slide with the active descriptor
 
-Use the **deck-add-slide** skill to build the slide, guided by the sketch:
+Before creating code:
 
-1. Map sketch regions to CSS Grid or Flexbox layout.
-2. Translate hand-drawn text into real content with proper typography.
-3. Replace rough shapes with styled `<div>` containers using CSS Modules.
-4. Follow all deck-add-slide conventions (accent-bar, content-frame, BottomBar, imports from `@deckio/deck-engine`).
-5. Register the slide in `deck.config.js`.
+1. Read `deck.config.js`
+2. Read `theme` and `designSystem`
+3. Resolve the active theme descriptor using the same rules as `deck-add-slide`
+4. Use **deck-add-slide** plus that descriptor to build the real slide
+
+While translating the sketch:
+
+1. Map sketch regions to CSS Grid or Flexbox layout
+2. Translate hand-drawn text into real content with proper typography
+3. Replace rough shapes with styled containers using CSS Modules
+4. Follow the active descriptor for JSX skeleton, CSS skeleton, decoration, tokens, and allowed components
+5. Register the slide in `deck.config.js`
 
 ### Step 5 — Visual verification
 
-After creating the slide, use **deck-eyes** to capture a screenshot of the rendered result.
+After creating the slide, use **deck-inspect** to capture a screenshot of the rendered result.
 
 Compare the rendered slide against the original sketch. If the user is present, show both and ask if adjustments are needed.
 
 ## Notes
 
-- Whiteboard sketches are rough — interpret intent, not exact pixels.
-- If text is hard to read, ask the user to clarify.
-- Screenshots are saved under `.github/eyes/` (gitignored) with a `sketch-` prefix.
+- Whiteboard sketches are rough — interpret intent, not exact pixels
+- If text is hard to read, ask the user to clarify
+- Screenshots are saved under `.github/eyes/` (gitignored) with a `sketch-` prefix

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

@@ -5,77 +5,117 @@ description: Validate and audit a deck project for correctness. Use this when as
 
 # Validate & Audit a Deck Project
 
-## Step 1: Audit deck.config.js
+## Step 0 — Read `deck.config.js`
 
-Open `deck.config.js` and verify:
+Open `deck.config.js` and read:
 
-### 1a. All imports resolve
+- `theme`
+- `designSystem`
+- `slides`
 
-For each slide import at the top of the file, verify the target file exists in `src/slides/`.
+Then resolve the active theme descriptor using the same rules as `deck-add-slide`:
 
-### 1b. slides array matches imports
+- Built-ins: read `dark.md`, `light.md`, or `shadcn.md` from the engine package descriptors folder
+- Custom themes: read the project's custom `descriptor.md` or `*.descriptor.md`
+- If no custom descriptor exists, fall back to the built-in descriptor implied by `designSystem`
 
-- Every imported slide should appear in the `slides` array.
-- No unused imports (imported but not in the array).
-- No undefined entries in the array (in array but not imported).
+Use the descriptor as the source of truth for required structure, required tokens, allowed components, decorative elements, and anti-patterns.
 
----
+## Step 1: Audit `deck.config.js`
 
-## Step 2: Verify slide structure
+Verify:
 
-For each slide `.jsx` file in `src/slides/`, verify:
+1. Every imported slide resolves to an existing file in `src/slides/`
+2. Every imported slide appears in the `slides` array
+3. There are no unused imports or undefined slide entries
+4. `slides` is non-empty
+5. `theme` and `designSystem` were not changed accidentally during unrelated work
 
-- [ ] Imports `{ Slide }` and `{ BottomBar }` from `'@deckio/deck-engine'`
-- [ ] Wrapped in `<Slide index={index} className={styles.xxx}>` (accepts `index` as prop)
-- [ ] Contains `<div className="accent-bar" />` as first child
-- [ ] Contains at least one decorative orb
-- [ ] Content is inside `<div className="content-frame content-gutter">`
-- [ ] `<BottomBar />` is the **last child** inside `<Slide>`
-- [ ] `BottomBar text` is consistent across all slides in the project
+## Step 2: Validate slide structure against the descriptor
 
-For each `.module.css` file, verify the root class has:
-- [ ] `background: var(--bg-deep)`
-- [ ] `padding: 0 0 44px 0`
-- [ ] Does NOT use `flex: 1` on the body wrapper (defeats vertical centering)
-- [ ] Does NOT redundantly set `flex-direction: column` (inherited from engine `.slide` class)
+For each slide `.jsx` file in `src/slides/`, check:
 
----
+### Common checks (all themes)
 
-## Step 3: Check companion files
+- [ ] Imports `{ Slide, BottomBar }` from `'@deckio/deck-engine'`
+- [ ] Uses `<Slide index={index} className={styles.xxx}>`
+- [ ] Uses a wrapper that includes `content-frame content-gutter`
+- [ ] Places `<BottomBar />` as the last child inside `<Slide>`
+- [ ] Uses consistent `BottomBar text` across slides
 
-- Every `.jsx` slide in `src/slides/` should have a matching `.module.css` file
-- No orphaned `.module.css` files without a matching `.jsx`
+### Descriptor-driven checks
 
----
+Read the descriptor and verify the slide matches:
 
-## Step 4: Verify metadata
+- its **Exact JSX skeleton**
+- its **Decorative elements available** section
+- its **Available components** section
+- its **Anti-patterns** section
 
-Check `deck.config.js` exports these fields:
-- [ ] `id` — string, matches the project folder name convention
-- [ ] `title` — display name
-- [ ] `subtitle` — tagline
-- [ ] `icon` — emoji
-- [ ] `accent` — CSS color value
-- [ ] `slides` — non-empty array
+Examples:
 
----
+- If the descriptor requires `accent-bar` and orbs, those must be present
+- If the descriptor forbids `accent-bar`, `orb`, or deep-space ornament, they must be absent
+- If the descriptor allows shadcn / ReactBits imports, imports must stay inside that ecosystem
+
+## Step 3: Validate CSS against the descriptor
+
+For each `.module.css` file, check:
+
+### Common checks (all themes)
+
+- [ ] Root class includes `padding: 0 0 44px 0`
+- [ ] No `flex: 1` on the body wrapper
+- [ ] No redundant `flex-direction: column` on the slide root
+- [ ] No obvious overflow-causing patterns
+
+### Descriptor-driven checks
+
+Read the descriptor and verify the CSS matches:
 
-## Step 5: Report results
+- its **Exact CSS skeleton**
+- its **Token table**
+- its **Anti-patterns**
 
-Summarize findings:
+Examples:
 
+- If the descriptor requires `var(--background)`, `var(--card)`, `var(--border)`, or other semantic tokens, use those exact names
+- If the descriptor forbids `var(--bg-deep)`, `var(--surface)`, `var(--text)`, or `var(--text-muted)`, flag them
+- If the descriptor forbids orb positioning classes or card `::before` bars, flag them
+
+## Step 4: Check companion files
+
+- Every `.jsx` slide in `src/slides/` should have a matching `.module.css`
+- No orphaned `.module.css` files without a matching `.jsx`
+
+## Step 5: Validate theme/design-system alignment
+
+Check whether the project configuration and descriptor agree:
+
+- If `designSystem === 'shadcn'`, the project should visually and structurally follow the shadcn descriptor rules
+- 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
+
+## Step 6: Report results
+
+Summarize:
+
+- Active theme detected
+- Design system detected
+- Descriptor used
 - Number of slides validated
-- Any issues found and fixed (missing files, broken imports, structural issues)
+- Descriptor mismatches found
+- Any issues found and fixed
 - Overall project health: **pass** or **issues found**
 
----
-
 ## Quick checklist
 
-- [ ] All imports in `deck.config.js` resolve to existing files
-- [ ] `slides` array matches imports (no unused, no missing)
+- [ ] Read `theme` and `designSystem`
+- [ ] Read the active descriptor
+- [ ] All `deck.config.js` imports resolve
+- [ ] `slides` array matches imports
 - [ ] Every `.jsx` slide has a companion `.module.css`
-- [ ] All slides have accent-bar, content-frame, BottomBar
-- [ ] BottomBar text is consistent across the project
-- [ ] CSS root classes have required properties (`background`, `padding`) and no `flex: 1` on body wrapper
-- [ ] Project metadata (id, title, subtitle, icon, accent) is present
+- [ ] All slides match the descriptor and the design system
+- [ ] `BottomBar` is present and consistent
+- [ ] CSS root classes have required properties
+- [ ] No descriptor anti-patterns slipped in

package/themes/descriptors/dark.md

@@ -0,0 +1,169 @@
+# Theme Descriptor — Dark
+
+## Metadata
+
+- **Theme id:** `dark`
+- **Primary slide authoring pattern:** `default`
+- **Compatible design systems:** `default`
+- **Mood:** deep-space, cinematic, high-contrast, presentation-first
+- **Read this file when:** `deck.config.js` uses `theme: 'dark'` or no explicit theme and you need to create, inspect, validate, or generate assets for slides
+
+## Slide personality
+
+Dark slides should feel unmistakably DECKIO: a deep background, a left accent bar, ambient orb decoration, and high-contrast content surfaces that glow subtly without looking noisy.
+
+## Exact JSX skeleton
+
+Use this exact starting structure for new slides:
+
+```jsx
+import { BottomBar, Slide } from '@deckio/deck-engine'
+import styles from './MyNewSlide.module.css'
+
+export default function MyNewSlide({ index, project }) {
+  return (
+    <Slide index={index} className={styles.myNewSlide}>
+      <div className="accent-bar" />
+      <div className={`orb ${styles.orb1}`} />
+      <div className={`orb ${styles.orb2}`} />
+
+      <div className={`${styles.body} content-frame content-gutter`}>
+        {/* Slide content */}
+      </div>
+
+      <BottomBar text="Project Footer Text" />
+    </Slide>
+  )
+}
+```
+
+### Required child order inside `<Slide>`
+
+1. `<div className="accent-bar" />`
+2. `2–4` decorative orb elements using the global `orb` class plus local positioning classes
+3. One content wrapper using `content-frame content-gutter`
+4. `<BottomBar text="..." />` as the last child
+
+## Exact CSS skeleton
+
+```css
+.myNewSlide {
+  background: var(--background);
+  padding: 0 0 44px 0;
+}
+
+.orb1 {
+  width: 420px;
+  height: 420px;
+  top: -100px;
+  right: -60px;
+  background: radial-gradient(
+    circle at 40% 40%,
+    var(--accent),
+    color-mix(in srgb, var(--green) 30%, transparent) 50%,
+    transparent 70%
+  );
+}
+
+.orb2 {
+  width: 320px;
+  height: 320px;
+  bottom: -40px;
+  right: 100px;
+  background: radial-gradient(
+    circle at 50% 50%,
+    var(--purple-deep),
+    color-mix(in srgb, var(--purple-deep) 30%, transparent) 60%,
+    transparent 75%
+  );
+}
+
+.body {
+  position: relative;
+  z-index: 10;
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+
+.cards {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 24px;
+}
+
+.card {
+  position: relative;
+  overflow: hidden;
+  background: var(--secondary);
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  padding: 24px;
+}
+
+.card::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 3px;
+  background: linear-gradient(90deg, var(--purple), var(--accent));
+  opacity: 0.6;
+}
+```
+
+## Token table
+
+### Use these tokens
+
+- `var(--background)`
+- `var(--foreground)`
+- `var(--muted-foreground)`
+- `var(--secondary)`
+- `var(--border)`
+- `var(--accent)`
+- `var(--blue-glow)`
+- `var(--purple)`
+- `var(--purple-deep)`
+- `var(--pink)`
+- `var(--cyan)`
+- `var(--green)`
+- `var(--surface-overlay)`
+
+### Never regress to
+
+- `var(--bg-deep)` in new slide code
+- `var(--surface)` in new slide code
+- `var(--text)` or `var(--text-muted)` in new slide code
+
+## Decorative elements available
+
+| Element | How to use it |
+|---|---|
+| `accent-bar` | Required first child for default DECKIO slides |
+| `orb` | Required ambient decoration; add 2–4 per slide |
+| `grid-dots` | Optional subtle pattern layer inside the content area |
+| Card top gradient | Acceptable via `.card::before` in the default system |
+
+## Available components
+
+| Resource | Import path |
+|---|---|
+| `Slide`, `BottomBar`, `Navigation`, `SlideProvider`, `useSlides`, `GenericThankYouSlide` | `'@deckio/deck-engine'` |
+| Data / logos | `'../data/<file>'` |
+
+## Anti-patterns
+
+1. Missing `accent-bar`
+2. Missing orb decoration
+3. Missing `content-frame content-gutter`
+4. Missing `BottomBar`
+5. Using `flex: 1` on the body wrapper
+6. Adding `flex-direction: column` on the slide root
+7. Overloading the slide until it overflows the viewport
+8. Importing shadcn-only UI components into a default DECKIO slide
+
+## Example slide direction
+
+A strong dark slide should combine a bold heading, restrained supporting copy, and 3-card content blocks over a deep background. The cards can use the default gradient top rule; the overall frame should still feel calm and readable from a distance.