@deckspec/cli 0.1.1 → 0.1.3

package/templates/noir-display/patterns/three-pillars/index.tsx

@@ -0,0 +1,112 @@
+import { z } from "zod";
+
+const pillarSchema = z.object({
+  title: z.string().min(1).describe("Pillar title"),
+  description: z.string().min(1).describe("Pillar description"),
+  value: z.string().optional().describe("Optional large display value"),
+});
+
+export const schema = z.object({
+  label: z.string().min(1).max(30).optional().describe("Accent eyebrow"),
+  heading: z.string().min(1).max(60).describe("Section heading"),
+  pillars: z.array(pillarSchema).min(2).max(3).describe("Pillars (2-3)"),
+});
+
+type Props = z.infer<typeof schema>;
+
+export default function ThreePillars({ label, heading, pillars }: Props) {
+  return (
+    <div className="slide-stack" style={{ justifyContent: "center", gap: 48 }}>
+      {/* Header */}
+      <div style={{ textAlign: "center" }}>
+        {label && (
+          <span
+            style={{
+              fontSize: 17,
+              fontWeight: 600,
+              letterSpacing: "-0.022em",
+              color: "var(--color-primary)",
+              display: "block",
+              marginBottom: 8,
+            }}
+          >
+            {label}
+          </span>
+        )}
+        <h2
+          style={{
+            fontSize: 48,
+            fontWeight: 600,
+            lineHeight: 1.08,
+            letterSpacing: "-0.003em",
+          }}
+        >
+          {heading}
+        </h2>
+      </div>
+
+      {/* Pillars as white cards on gray canvas */}
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: `repeat(${pillars.length}, 1fr)`,
+          gap: 20,
+        }}
+      >
+        {pillars.map((p, i) => (
+          <div
+            key={i}
+            style={{
+              backgroundColor: "#ffffff",
+              borderRadius: 18,
+              padding: "36px 32px",
+              display: "flex",
+              flexDirection: "column",
+              gap: 12,
+              boxShadow: "4px 4px 12px rgba(0,0,0,0.06)",
+            }}
+          >
+            {p.value && (
+              <span
+                style={{
+                  fontSize: 40,
+                  fontWeight: 600,
+                  fontFamily: "var(--font-heading)",
+                  lineHeight: 1,
+                  letterSpacing: "-0.009em",
+                  color: "var(--color-primary)",
+                }}
+              >
+                {p.value}
+              </span>
+            )}
+            <span
+              style={{
+                fontSize: 21,
+                fontWeight: 600,
+                fontFamily: "var(--font-heading)",
+                letterSpacing: "0.011em",
+                color: "var(--color-foreground)",
+                lineHeight: 1.24,
+              }}
+            >
+              {p.title}
+            </span>
+            <span
+              style={{
+                fontSize: 17,
+                fontWeight: 400,
+                fontFamily: "var(--font-body)",
+                letterSpacing: "-0.022em",
+                color: "var(--color-muted-foreground)",
+                lineHeight: 1.47,
+              }}
+            >
+              {p.description}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/templates/noir-display/patterns/title-center/index.tsx

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+export const schema = z.object({
+  title: z.string().min(1).max(40).describe("Display headline — large, dramatic"),
+  subtitle: z.string().min(1).max(80).describe("Muted subtitle beneath headline"),
+});
+
+type Props = z.infer<typeof schema>;
+
+export default function TitleCenter({ title, subtitle }: Props) {
+  return (
+    <div
+      className="slide"
+      style={{
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        background: "#ffffff",
+      }}
+    >
+      <div className="stack-center" style={{ gap: 16, maxWidth: 900, marginBottom: 32 }}>
+        <h1
+          style={{
+            fontSize: 72,
+            fontWeight: 600,
+            lineHeight: 1.05,
+            letterSpacing: "-0.015em",
+          }}
+        >
+          {title}
+        </h1>
+        <p
+          style={{
+            fontSize: 24,
+            fontWeight: 400,
+            lineHeight: 1.17,
+            letterSpacing: "0.009em",
+            color: "var(--color-muted-foreground)",
+          }}
+        >
+          {subtitle}
+        </p>
+      </div>
+    </div>
+  );
+}

package/templates/noir-display/tokens.json

@@ -0,0 +1,30 @@
+{
+  "name": "noir-display",
+  "displayName": "Pristine Display",
+  "description": "Apple.com inspired light theme — canvas gray background, display typography, dramatic whitespace, and cinematic clarity.",
+  "colors": {
+    "background": "#f5f5f7",
+    "foreground": "#1d1d1f",
+    "primary": "#0071e3",
+    "muted": "#e8e8ed",
+    "muted-foreground": "#6e6e73",
+    "border": "rgba(0,0,0,0.08)",
+    "accent": "#0066cc",
+    "card-background": "#ffffff"
+  },
+  "fonts": {
+    "heading": "'SF Pro JP', 'SF Pro Display', 'Hiragino Sans', 'Helvetica Neue', 'Noto Sans JP', sans-serif",
+    "body": "'SF Pro JP', 'SF Pro Text', 'Hiragino Sans', 'Helvetica Neue', 'Noto Sans JP', sans-serif"
+  },
+  "spacing": {
+    "slide-padding": "60px",
+    "slide-padding-x": "80px",
+    "slide-gap": "32px"
+  },
+  "borderRadius": "12px",
+  "slide": {
+    "width": 1200,
+    "height": 675,
+    "aspectRatio": "16/9"
+  }
+}

package/templates/noir-display/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": ".",
+    "composite": true,
+    "jsx": "react-jsx"
+  },
+  "include": [
+    "patterns/",
+    "components/"
+  ]
+}

package/templates/skills/deckspec-add-pattern/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: deckspec-add-pattern
+description: "Use this skill when the user asks to create a new pattern, add a layout, or make a reusable slide template. Triggers on: 'add pattern', 'create pattern', 'new layout', 'パターン作って', 'レイアウト追加'."
+---
+
+# Add Pattern Skill
+
+Create a new reusable pattern in the theme.
+
+## Arguments
+
+The user should specify:
+- Pattern name (kebab-case)
+- What the pattern displays (layout description)
+- Which theme to add it to
+
+## Workflow
+
+### 1. Read the theme's design system
+- Read `themes/<theme>/design.md` for design philosophy and rules
+- Read `themes/<theme>/tokens.json` for colors, fonts, spacing
+- Read `themes/<theme>/globals.css` for available semantic classes
+- Look at existing patterns for conventions
+
+### 2. Create the pattern
+
+Create `themes/<theme>/patterns/<name>/index.tsx`:
+
+```tsx
+import { z } from "zod";
+import React from "react";
+
+export const schema = z.object({
+  // Define vars with .describe() for clarity
+  heading: z.string().describe("Main heading text"),
+  items: z.array(z.object({
+    label: z.string(),
+    value: z.string(),
+  })).describe("List of items to display"),
+});
+
+type Props = z.infer<typeof schema>;
+
+export default function PatternName(props: Props) {
+  return (
+    <div className="slide-pad slide-stack">
+      <h1>{props.heading}</h1>
+      {/* Layout using semantic classes */}
+    </div>
+  );
+}
+```
+
+### 3. Create examples.yaml
+
+Create `themes/<theme>/patterns/<name>/examples.yaml`:
+
+```yaml
+- name: "Basic example"
+  vars:
+    heading: "Example Heading"
+    items:
+      - label: "Item 1"
+        value: "Value 1"
+```
+
+### 4. Validate and preview
+
+Create a test deck referencing the new pattern, validate it, and preview with `npx deckspec dev`.
+
+## Design Rules
+- Use semantic CSS classes (`.slide-pad`, `.card`, `.list`, etc.)
+- Colors via CSS custom properties (`var(--color-primary)`) — never hardcode hex
+- Minimum font size: 16px
+- No serif fonts
+- No Tailwind CSS
+- Export both `schema` (Zod) and `default` (React component)
+- Use `.describe()` on Zod fields for AI-friendly documentation

package/templates/skills/deckspec-make-slides/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: deckspec-make-slides
+description: "Use this skill when the user asks to create a presentation, make slides, build a deck, or write deck.yaml. Triggers on: 'make slides', 'create presentation', 'build a deck', 'プレゼン作って', 'スライド作って', 'デッキ作って'."
+---
+
+# Make Slides Skill
+
+Create a DeckSpec presentation from a user request.
+
+## Workflow
+
+### 1. Understand the request
+- What is the presentation about?
+- How many slides?
+- What tone? (business, technical, casual)
+
+### 2. Check available patterns
+Run: `npx deckspec patterns --examples`
+Read: `themes/*/design.md` for design philosophy and pattern catalog.
+
+### 3. Create deck.yaml
+
+Create `decks/<deck-name>/deck.yaml`:
+
+```yaml
+meta:
+  title: "Presentation Title"
+  theme: noir-display
+slides:
+  - file: <pattern-name>
+    vars:
+      # ... content
+```
+
+**Pattern selection guide:**
+- Opening: `title-center` or `hero-statement`
+- Data/metrics: `feature-metrics`, `big-number`, `chart-bar`
+- Comparison: `comparison-columns`, `pricing-tiers`
+- Process/flow: `flow-diagram`, `three-pillars`
+- Content: `bullet-list`, `icon-grid`
+- Closing: `thank-you`
+
+### 4. Validate
+```bash
+npx deckspec validate decks/<deck-name>/deck.yaml
+```
+Fix any schema errors.
+
+### 5. Preview
+```bash
+npx deckspec dev
+```
+Open http://localhost:3002 and navigate to the deck.
+
+### 6. Iterate
+Ask the user for feedback and adjust slides accordingly.
+
+## If no existing pattern fits
+
+Create a deck-local pattern at `decks/<deck-name>/patterns/<name>/index.tsx`:
+- Export `schema` (Zod) and `default` (React component)
+- Use semantic CSS classes from the theme's `globals.css`
+- Do NOT hardcode colors — use CSS custom properties
+- The pattern is compiled on-the-fly with esbuild, no build step needed
+
+## Rules
+- Always validate before presenting to the user
+- Use pattern `examples.yaml` as reference for vars structure
+- Minimum font size: 16px, no serif fonts
+- Colors via CSS custom properties only

package/templates/skills/deckspec-promote-pattern/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: deckspec-promote-pattern
+description: "Use this skill when the user asks to promote, elevate, or graduate a deck-local pattern to a theme pattern. Triggers on: 'promote pattern', 'elevate to theme', 'make it reusable', 'add to theme', 'graduate pattern', 'パターン昇格', 'テーマに昇格', or any request to move a deck-local pattern into the theme."
+---
+
+# Promote Pattern Skill
+
+Promote a deck-local pattern to a theme pattern. Abstract hardcoded values into vars, making it a reusable, generic pattern.
+
+## Arguments
+
+```
+/promote-pattern <deck-pattern-path> [--theme <theme-name>]
+```
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `deck-pattern-path` | (required) | Path to the deck-local pattern (e.g., `decks/my-project/patterns/product-comparison`) |
+| `--theme` | `noir-display` | Target theme name |
+
+## Workflow
+
+This skill proceeds **interactively**. Each step asks for user confirmation before moving on.
+
+### Phase 1: Analysis
+
+1. Read the specified deck-local pattern's `index.tsx`
+2. Analyze the source code to identify:
+   - **Hardcoded values**: text strings, numbers, currency symbols, proper nouns, industry terms
+   - **Domain-specific variable names**: names tied to a particular domain (e.g., `products` → `items`, `competitors` → `columns`)
+   - **Domain-specific logic**: fixed format functions (e.g., hardcoded currency locale)
+   - **Values already in vars**: can be kept as-is
+3. Present the analysis to the user
+
+### Phase 2: Interactive design decisions
+
+**All design decisions use `AskUserQuestion` with `options`.** Let the user click choices rather than type free text.
+
+#### 2a. Pattern name
+
+`AskUserQuestion` with candidates:
+- header: "Pattern name"
+- options: suggested names (mark recommended with `(Recommended)`) + 2-3 alternatives
+- e.g., `["product-comparison (Recommended)", "feature-grid", "data-table"]`
+
+#### 2b. Hardcoded value → vars decisions
+
+For each detected hardcoded value, use `AskUserQuestion`:
+- header: "Hardcoded value"
+- question: `"Total" (table footer label) — what should we do?`
+- options:
+  - `Add to vars: footerLabel (string, optional)` — recommended
+  - `Keep hardcoded`
+  - `Remove`
+
+For many values, use `multiSelect: true` for batch selection:
+- question: `Which hardcoded values should become vars?`
+- options: list each value
+
+#### 2c. Variable renaming
+
+`AskUserQuestion`:
+- header: "Rename vars"
+- options:
+  - `Apply suggested renames (Recommended)` — description lists the rename map
+  - `Keep current names`
+
+#### 2d. Extra options
+
+`AskUserQuestion` with `multiSelect: true`:
+- header: "Extra options"
+- question: `Select additional options to add`
+- options: each candidate option with description
+
+### Phase 3: Implementation
+
+Based on user answers:
+
+1. **Create pattern file**: `themes/{theme}/patterns/{new-name}/index.tsx`
+   - Replace hardcoded values with vars
+   - Rename variables as agreed
+   - Implement extra options
+   - Add `.describe()` to all Zod schema fields
+
+2. **Create examples.yaml**: `themes/{theme}/patterns/{new-name}/examples.yaml`
+   - First example: the original deck's vars (proof it works as-is)
+   - Second example: usage in a different domain (proof of generality)
+   - Third example (optional): demonstrate optional features
+
+3. **Update index.ts**: Add re-export to `themes/{theme}/patterns/index.ts`
+
+4. **Update design.md**: Add the pattern to the catalog section with vars spec
+
+### Phase 4: Verification
+
+1. Run `pnpm build` to confirm the theme builds
+2. Create a test deck with examples.yaml vars, run `npx deckspec validate` + `npx deckspec render`
+3. Take screenshots and present to user
+4. Fix issues based on user feedback
+
+### Phase 5: Old pattern disposition
+
+`AskUserQuestion`:
+- header: "Old pattern"
+- question: `What should we do with the original deck-local pattern?`
+- options:
+  - `Keep it (Recommended)` — description: maintains backward compatibility
+  - `Delete and update deck.yaml` — description: replace with new theme pattern name
+
+## Analysis hints
+
+### Detecting hardcoded values
+- String literals in the target language (any natural language text)
+- Currency/unit symbols (`"$"`, `"%"`, `"EUR"`, etc.)
+- Fixed locale strings (e.g., `"en-US"` in `.toLocaleString()`)
+- Hardcoded CSS colors (`"#xxx"` — anything not using `var()`)
+- Fixed number formatting
+
+### Naming conventions
+- Pattern names: kebab-case, replace domain terms with generic ones (e.g., `product-comparison` → `comparison-table`)
+- Var names: camelCase, use `.describe()` in Zod schema
+- Array names: plural (`rows`, `columns`, `items`)
+
+### examples.yaml best practices
+- Example 1: original deck's real data (proof of migration)
+- Example 2: different domain usage (proof of generality)
+- Example 3: optional feature showcase (e.g., `showTotal: false`)
+
+## Important notes
+
+- Read the target theme's `design.md` first to understand design rules
+- Keep var naming consistent with existing patterns (`label`, `heading`, etc.)
+- If the pattern uses theme utilities like `_lib/icon.tsx`, verify they exist in the target theme

package/templates/skills/deckspec-screenshot/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: deckspec-screenshot
+description: "Use this skill when the user asks to screenshot, capture, or photograph slides from a DeckSpec deck. Triggers on: 'screenshot', 'capture slides', 'save slide images', 'スクリーンショット', 'スライド撮影'."
+---
+
+# Screenshot Deck Skill
+
+Capture all slides of a DeckSpec deck as individual PNG images (1200x675, 16:9).
+
+## Prerequisites
+
+- Playwright installed: `npm install -D playwright && npx playwright install chromium`
+
+## Workflow
+
+### 1. Render the deck to HTML
+
+```bash
+npx deckspec render decks/<deck-name>/deck.yaml -o output/<deck-name>
+```
+
+### 2. Run the screenshot script
+
+```bash
+node scripts/screenshot-deck.mjs output/<deck-name>/index.html output/<deck-name>-slides
+```
+
+This will:
+- Open the HTML in headless Chromium at 1200x675 viewport
+- Hide navigation controls
+- Screenshot each slide as `slide-01.png`, `slide-02.png`, etc.
+
+### 3. Verify
+
+Read the generated PNG files to visually confirm the output.
+
+## Output
+
+- `output/<deck-name>-slides/slide-01.png`
+- `output/<deck-name>-slides/slide-02.png`
+- Each image is 1200x675px PNG (16:9)

package/templates/skills/deckspec-to-pptx/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: deckspec-to-pptx
+description: "Use this skill when the user asks to convert a DeckSpec deck to PowerPoint (.pptx). Triggers on: 'PowerPoint', 'pptx', 'convert to pptx', 'export to PowerPoint', 'パワポ', 'パワーポイント'."
+---
+
+# Deck to PowerPoint Skill
+
+Convert a DeckSpec deck.yaml to a PowerPoint (.pptx) file.
+
+## Prerequisites
+
+- pptxgenjs installed: `npm install -D pptxgenjs`
+
+## Workflow
+
+### 1. Run the conversion
+
+```bash
+node scripts/deck-to-pptx.mjs decks/<deck-name>/deck.yaml -o output/<deck-name>.pptx
+```
+
+### 2. Check for warnings
+
+The script warns for unregistered patterns: `⚠ No pptx renderer for pattern "<name>" — blank slide`
+
+To fix, add a renderer function in `scripts/deck-to-pptx.mjs`.
+
+### 3. Open and verify
+
+Open the .pptx in PowerPoint or Google Slides to verify.
+
+## Notes
+
+- Colors and fonts are loaded from `themes/<theme>/tokens.json`
+- Local images are embedded as base64
+- Not all patterns have pptx renderers yet — unregistered patterns produce blank slides