opencodekit 0.21.10 → 0.23.0

package/dist/template/.opencode/skill/hi-fi-prototype-html/SKILL.md

@@ -1,253 +0,0 @@
----
-name: hi-fi-prototype-html
-description: Use when building high-fidelity HTML prototypes, interactive product mockups, app/iOS/Android screen demos, or design-variation explorations (NOT production web apps — use frontend-design for that). Enforces Junior Designer mode (show assumptions early, iterate), single-file inline React for double-clickable mockups, real images instead of generic placeholders, and Playwright click-test before delivery.
----
-
-# Hi-Fi Prototype (HTML as Medium)
-
-> Adapted from `huashu-design`. HTML is your **medium**, not your destination. You are a designer who happens to use HTML, not a developer who happens to be designing.
-
-## When to Use
-
-- **Interactive prototypes** — clickable product mockups for user testing or design review
-- **Design variation exploration** — 3+ side-by-side directions before committing
-- **App / iOS / Android mockups** — single-page or full-flow demos
-- **Concept demos** — convey an interaction or feel before any production code
-- **Information graphics** with hand-tuned typography
-
-**Don't use for**:
-
-- Production web apps with real backends → `frontend-design` + `react-best-practices`
-- SEO/marketing sites → `frontend-design`
-- Component library work → `mockup-to-code` (mockup → production component)
-
-## Core Discipline
-
-### 1. Start From Existing Context — Don't Design From Air
-
-Good hi-fi designs grow from existing context. Before opening a blank file:
-
-- Ask: do you have a design system / UI kit / Figma / brand site / reference screenshots?
-- If yes → run `brand-asset-protocol` to extract real assets
-- If no AND brief is vague → run `design-direction-advisor` first
-- Only as last resort: design from generic intuition (will produce AI slop — see `anti-ai-slop`)
-
-### 2. Junior Designer Mode — Show Assumptions Early, Then Iterate
-
-You are the user's junior designer. The user is the manager.
-
-❌ **Don't** disappear for an hour and reveal a finished file.
-
-✅ **Do** open the HTML with your assumptions written as comments + reasoning + grayblock placeholders. Show this **first**. Get nod. Then write components. Show again at 50% done. Iterate.
-
-```html
-<!-- Assumptions:
-     - Audience: enterprise admins
-     - Style direction: Pentagram-style (per design-direction-advisor)
-     - 3 variations differ in: density, hierarchy, accent color
-     - Real product photos pending from user (Step 1 of brand-asset-protocol)
--->
-<div class="placeholder">[Hero image — DJI Pocket 4 product render, TBD]</div>
-<div class="placeholder">[Headline copy — TBD from user]</div>
-```
-
-**Why**: misunderstanding the brief is 100× cheaper to fix at this stage than after a finished build.
-
-### 3. Give Variations, Not "The Answer"
-
-When the user says "design X", don't deliver one polished answer. Deliver **3+ variations** spanning:
-
-- by-the-book → novel (a continuum, not all in one corner)
-- different axes: visual, interaction, color, layout, animation
-- let the user mix and match
-
-Implementation:
-
-- Pure visual comparison → side-by-side static layout (`design_canvas`-style grid)
-- Interactive flow with branching options → full prototype with toggles ("Tweaks") for live parameter swap
-
-### 4. Honest Placeholders Beat Bad Implementations
-
-- Missing icon? → gray block + label "[icon]". Don't draw a wonky SVG.
-- Missing data? → `<!-- TBD: real data from user -->`. Don't fabricate plausible-looking numbers.
-- Missing image? → labeled placeholder. Don't AI-draw a face.
-
-**In hi-fi work, an honest placeholder is 10× better than a clumsy attempt at the real thing.**
-
-### 5. System First, Don't Pad Filler
-
-Every element earns its place. Whitespace is a design problem solved by **composition**, not by inventing content.
-
-Especially watch for these "slop" categories (see `anti-ai-slop`):
-
-- **Data slop** — meaningless stats, decorative numbers
-- **Iconography slop** — every heading needs an icon
-- **Gradient slop** — every background gets a gradient
-
-> "One thousand no's for every yes."
-
-## App / iOS Prototype Rules (override generic placeholder rules)
-
-App mockups are **demos at presentation time** — generic gray rectangles and lorem ipsum kill credibility. Different rules apply:
-
-### A. Architecture: Default to Single-File Inline React
-
-**Default**: all JSX/data/styles inside a `<script type="text/babel">…</script>` tag in one HTML file. Reasons:
-
-- `file://` blocks external JS as cross-origin → forces user to spin up an HTTP server → violates "double-click to open" principle
-- Local images must be base64 data URLs (don't assume a server)
-
-**Split files only when**:
-
-- Single file >1000 lines and unmaintainable → split into `components.jsx` + `data.js`, document the `python3 -m http.server` command in delivery notes
-- Multiple subagents need to write different screens in parallel → `index.html` + per-screen HTML, iframe-aggregated, each screen self-contained
-
-| Scenario                          | Architecture             | Delivery                                  |
-| --------------------------------- | ------------------------ | ----------------------------------------- |
-| Single dev, 4-6 screens (default) | Single-file inline React | One `.html`, double-click                 |
-| Single dev, large app (>10 scr)   | Multi-jsx + HTTP server  | Include startup command                   |
-| Multi-agent parallel              | Multi-HTML + iframe      | `index.html` aggregator, each opens alone |
-
-### B. Real Images First, Not "Just Placeholders"
-
-By default, **actively fetch real images**. Don't draw SVG. Don't leave gray blocks. Don't wait for user to ask.
-
-| Use case                          | Source                                                              |
-| --------------------------------- | ------------------------------------------------------------------- |
-| Art / museum / historical content | Wikimedia Commons (public domain), Met Museum Open Access, AIC API  |
-| General lifestyle photography     | Unsplash, Pexels (royalty-free)                                     |
-| User's existing assets            | `~/Downloads`, project `_archive/`, user's configured asset library |
-
-Wikimedia caveat: `curl` via TLS proxy often fails. Use Python `urllib` and a compliant User-Agent (`MyProject/0.1 (https://github.com/you; you@example.com)`). Use the MediaWiki API (`action=query&list=categorymembers`) for batch / `prop=imageinfo&iiurlwidth=` for sized thumbs.
-
-**Honest-image test**: before fetching, ask — _"if I remove this image, is information lost?"_
-
-| Scenario                                                     | Verdict                        | Action                                      |
-| ------------------------------------------------------------ | ------------------------------ | ------------------------------------------- |
-| Essay list cover / profile background / settings page banner | Decoration, no link to content | **Don't add** — equivalent to gradient slop |
-| Museum content portrait / product detail / map card location | Image IS the content           | **Must add** — real image required          |
-| Graph / visualization background texture (very subtle)       | Atmosphere, not focus          | Add at `opacity ≤ 0.08`                     |
-
-❌ Don't pad text essays with Unsplash "inspiration shots." Permission to use real images ≠ license to over-use them.
-
-### C. Two Standard Delivery Forms — Ask First
-
-Multi-screen app prototypes split into two standard forms. **Ask which one** before defaulting:
-
-| Form                                      | When                                                                    | How                                                                                 |
-| ----------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| **Overview tile (design review default)** | User wants to see all screens, compare layout, walk through consistency | All screens in parallel, each in its own iPhone frame, no clicks needed             |
-| **Flow demo (single device)**             | User wants to demonstrate a specific user flow (onboarding, purchase)   | One iPhone with `AppPhone` state machine — tabs, buttons, annotations all clickable |
-
-Routing keywords:
-
-- "tile / show all pages / overview / compare / all screens" → overview
-- "demonstrate flow / user path / walk through / clickable / interactive demo" → flow demo
-- Ambiguous → ask. Don't default to flow demo (it's much more work).
-
-**Overview skeleton:**
-
-```jsx
-<div style={{ display: "flex", gap: 32, flexWrap: "wrap", padding: 48, alignItems: "flex-start" }}>
-  {screens.map((s) => (
-    <div key={s.id}>
-      <div style={{ fontSize: 13, color: "#666", marginBottom: 8, fontStyle: "italic" }}>
-        {s.label}
-      </div>
-      <IosFrame>
-        <ScreenComponent data={s} />
-      </IosFrame>
-    </div>
-  ))}
-</div>
-```
-
-**Flow demo skeleton:**
-
-```jsx
-function AppPhone({ initial = "today" }) {
-  const [screen, setScreen] = React.useState(initial);
-  const [modal, setModal] = React.useState(null);
-  // dispatch to the right ScreenComponent, pass onEnter/onClose/onTabChange callbacks
-}
-```
-
-Each Screen takes callback props (`onEnter`, `onClose`, `onTabChange`, `onOpen`, `onAnnotation`) — don't hard-code state. TabBar, buttons, cards get `cursor: pointer` + hover feedback.
-
-### D. Click-Test Before Delivery
-
-Static screenshots only show layout. Interaction bugs only surface when you click. Run a **3-action minimum Playwright test** before saying done:
-
-1. Enter detail view
-2. Trigger a key annotation
-3. Switch tabs
-
-Check `pageerror` count is 0. If not, fix and re-run.
-
-```bash
-npx playwright test prototype.spec.ts
-```
-
-### E. iOS Frame: Use a Pinned-Spec Component, Don't Hand-Code
-
-The iPhone Dynamic Island has fixed pixel dimensions (124×36, top:12, centered). Hand-coding the bezel + status bar + island + home indicator → 99% chance of placement bugs (status bar items get squeezed by the island, content top-padding miscalculated).
-
-**Rule**: bind to a known-good iOS frame component (e.g. an `IosFrame` you keep in a personal asset library). Don't write `.dynamic-island`, `.status-bar`, `.home-indicator`, or the bezel chrome inline.
-
-```jsx
-<IosFrame time="9:41" battery={85}>
-  <YourScreen />
-</IosFrame>
-```
-
-Same rule for Android (`AndroidFrame`), macOS windows (`MacosWindow`), browser windows (`BrowserWindow`).
-
-## Position Questions — Answer Before Designing the System
-
-For every page / screen / shot, answer these **4 position questions** before opening CSS:
-
-- **Narrative role** — hero / transition / data / quote / closer? (every page in a deck differs)
-- **Viewing distance** — 10cm phone / 1m laptop / 10m projector? (drives font size + density)
-- **Visual temperature** — quiet / excited / cool / authoritative / tender / mournful? (drives palette + rhythm)
-- **Capacity check** — sketch 3 five-second thumbnails on paper. Does the content fit?
-
-Then verbalize the design system (palette / type / layout rhythm / component patterns). System serves the answers — don't pick the system first and stuff content in.
-
-🛑 **Checkpoint**: state the 4 answers + the system out loud. Wait for user nod **before** opening CSS.
-
-## Standard Workflow (with Checkpoints)
-
-1. **Understand the need.**
-   - 🔍 If task names a specific real product (DJI Pocket 4, Gemini 3 Pro, etc.): WebSearch first, write facts to `product-facts.md`. Don't guess from memory.
-   - Ask focused clarifying questions — batch them, don't drip-feed.
-   - 🛑 **Checkpoint 1**: send all questions, wait for user to answer in batch.
-   - 🛑 If brief is vague → run `design-direction-advisor` and complete Phase 1-4 first.
-
-2. **Explore resources + extract assets.** Read design system, linked files, screenshots. For specific brands: run `brand-asset-protocol` (5 steps).
-   - 🛑 **Checkpoint 2 (asset self-check)**: physical product → product photo present (not CSS silhouette); digital product → logo + UI screenshot present; colors extracted from real HTML/SVG. Missing → stop and fix.
-
-3. **Answer the 4 position questions, then verbalize the system.**
-   - 🛑 **Checkpoint 3**: state position answers + system. Wait for nod.
-
-4. **Build folder structure.** `<project-name>/` holds main HTML + needed asset copies (don't bulk-copy >20 files).
-
-5. **Junior pass.** HTML opens with assumptions + placeholders + reasoning comments.
-   - 🛑 **Checkpoint 4**: show early (gray blocks + labels are fine). Wait for feedback before writing components.
-
-6. **Full pass.** Fill placeholders, build variations, add Tweaks if needed. **Show again mid-way**, not only at the end.
-
-7. **Verify.** Playwright screenshot + console error check. Send to user.
-   - 🛑 **Checkpoint 5**: open the file in your own browser. Walk through. AI-written prototype code commonly has subtle interaction bugs.
-
-8. **Summary.** Minimal — caveats and next steps only.
-
-**Checkpoint principle**: when you hit a 🛑, stop and explicitly say _"I did X, next I plan Y, confirm?"_ — then **actually wait**. Don't say it and immediately continue.
-
-## Pairs Well With
-
-- `brand-asset-protocol` — extract real brand assets before designing
-- `anti-ai-slop` — actively avoid the AI default aesthetic
-- `design-direction-advisor` — when brief is too vague to start
-- `design-taste-frontend` / `high-end-visual-design` — base aesthetic discipline
-- `frontend-design` — when prototype graduates to production code
-- `playwright` — for the click-test step

package/dist/template/.opencode/skill/html-deck-export/SKILL.md

@@ -1,189 +0,0 @@
----
-name: html-deck-export
-description: Use when building HTML-based slide decks that need to ship as PDF or editable PPTX. MUST load BEFORE writing the first line of HTML if PPTX (with editable text) is a delivery target — choosing the wrong architecture costs 2-3 hours of rework. Covers multi-file vs single-file deck architecture, browser presentation, PDF export, and the 4 hard constraints for editable PPTX.
----
-
-# HTML Deck Export
-
-> Adapted from `huashu-design`. The hardest checkpoint isn't "single-file or multi-file" — it's **"what's the final delivery format?"** Get this wrong and you're rewriting 17 pages of HTML.
-
-## The Critical Decision (Before First Line of HTML)
-
-```
-Q: What's the final delivery format?
-├── Browser fullscreen presentation only / local HTML  → maximum visual freedom
-├── PDF (print / share / archive)                      → maximum visual freedom, any architecture exports
-└── Editable PPTX (teammates will edit text)           → 🛑 MUST follow 4 hard constraints from the first line
-```
-
-**Why "editable PPTX" forces decisions early**: PPTX with editable text requires `html2pptx`-style element-by-element DOM translation. That tool needs a structurally constrained HTML (see "4 Hard Constraints" below). Writing visually-rich HTML and converting after is a 2-3 hour rewrite. **From-scratch with constraints adds ~5 minutes per slide.**
-
-### Real-Cost Comparison
-
-| Path                                  | Approach                                               | Result                                                                       | Cost                                                              |
-| ------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| ❌ **Free-form HTML, fix PPTX later** | Single-file deck-stage + lots of SVG / span / gradient | To get editable PPTX: hand-write hundreds of pptxgenjs lines OR rewrite HTML | **2-3 hour rework + ongoing maintenance debt** (HTML edit ≠ PPTX) |
-| ✅ **Path-A constraints from line 1** | Per-page HTML + 4 constraints + 720×405pt              | One command exports 100% editable PPTX, also presents in browser             | **+5 min per slide thinking "how do I wrap text in `<p>`?"**      |
-
-## Opening Questionnaire (paste-ready)
-
-> Before I touch HTML, confirm delivery:
->
-> - **Browser presentation / PDF** → I can use animations, web components, complex SVG, CSS gradients
-> - **Editable PPTX** (someone will edit text in PowerPoint) → I must follow 4 hard HTML constraints from the start. Visual capabilities reduce (no gradients, no web components, no complex SVG), but export becomes a single command
->
-> Which?
-
-**Mixed delivery clarifications:**
-
-- "I want HTML presentation **and** editable PPTX" → not actually mixed. Path-A HTML _is_ presentable HTML; just add a deck index. Zero extra cost.
-- "I want PPTX **and** animation/web component" → real conflict. Make the user choose. Don't silently hand-write pptxgenjs (becomes permanent maintenance debt).
-
-## Architecture: Single-File vs Multi-File
-
-After delivery format is locked, pick architecture:
-
-| Architecture             | When                                                 | Pattern                                                                  |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------ |
-| **Multi-file** (default) | ≥10 pages, academic/courseware, multi-agent parallel | Each page is its own HTML; an `index.html`/iframe stitcher combines them |
-| **Single-file**          | ≤10 pages, pitch decks, cross-page state needed      | One HTML with a slide container component (web component or React)       |
-
-**Multi-file advantages**: independent CSS scopes (no specificity wars), trivial parallel work, individual page reload during dev.
-**Single-file advantages**: one file to share, easy state sharing across slides.
-
-### Multi-File Stitcher (skeleton)
-
-```html
-<!-- index.html -->
-<!doctype html>
-<style>
-  body {
-    margin: 0;
-    background: #000;
-  }
-  iframe {
-    display: block;
-    width: 100vw;
-    height: 100vh;
-    border: 0;
-  }
-</style>
-<iframe id="stage" src="01.html"></iframe>
-<script>
-  const slides = ["01.html", "02.html", "03.html", "04.html"];
-  let i = 0;
-  const stage = document.getElementById("stage");
-  document.addEventListener("keydown", (e) => {
-    if (e.key === "ArrowRight" && i < slides.length - 1) i++;
-    if (e.key === "ArrowLeft" && i > 0) i--;
-    stage.src = slides[i];
-  });
-</script>
-```
-
-Each `NN.html` is a fully standalone, double-clickable slide.
-
-### Single-File Pattern (web component or React)
-
-```html
-<deck-stage>
-  <section class="active">Slide 1</section>
-  <section>Slide 2</section>
-</deck-stage>
-<script src="deck_stage.js"></script>
-```
-
-Two **hard constraints** for the web-component pattern:
-
-- The `<script>` tag for the component **must come after** the `</deck-stage>` close tag (else slot rendering breaks)
-- Section's `display: flex` must be on the `.active` class (not the section itself, else inactive slides fight for space)
-
-## The 4 Hard Constraints for Editable PPTX
-
-If you need editable PPTX export (via `html2pptx`-style tooling):
-
-1. **Body fixed at 720pt × 405pt** — _not_ 1920×1080px. Use `pt` units for the deck container (PowerPoint's native unit).
-2. **All text wrapped in `<p>` or `<h1>`–`<h6>`** — never plain `<div>` with text. Never `<span>` as the primary text carrier.
-3. **`<p>` and `<h*>` themselves cannot have background / border / shadow** — put those on an outer `<div>`.
-4. **No `background-image` on `<div>`** — use real `<img>` tags. No CSS gradients. No web components. No complex decorative SVG.
-
-**If your HTML violates any of these**, the editable export will produce broken slides or fail outright. The _image-mode_ PPTX export (slide rendered as an image, embedded in PowerPoint) doesn't have these constraints — but the result is **not editable**.
-
-## Two PPTX Export Modes
-
-| Mode              | Visual fidelity       | Editability                        | When                                                                  |
-| ----------------- | --------------------- | ---------------------------------- | --------------------------------------------------------------------- |
-| **Image mode**    | 100% — pixel-perfect  | None — text is image               | Visual-rich slides, no edits expected, PDF-equivalent in PPTX wrapper |
-| **Editable mode** | Reduced — constraints | Full — text editable in PowerPoint | Teammates will edit text, brand-spec font fallbacks expected          |
-
-Tools (per huashu-design pattern):
-
-- `playwright` for browser rendering (already in this kit)
-- `pptxgenjs` for PPTX object construction
-- `pdf-lib` for multi-page PDF merge
-- `sharp` (only for editable mode image fallbacks)
-
-## PDF Export (Easy Path)
-
-PDF tolerates any HTML architecture. Per-page browser screenshot → merge.
-
-```js
-// scripts/export-deck-pdf.mjs (skeleton)
-import { chromium } from "playwright";
-import { PDFDocument } from "pdf-lib";
-import fs from "fs";
-
-const slides = fs.readdirSync("slides").filter((f) => f.endsWith(".html"));
-const browser = await chromium.launch();
-const ctx = await browser.newContext({ viewport: { width: 1920, height: 1080 } });
-const merged = await PDFDocument.create();
-
-for (const file of slides) {
-  const page = await ctx.newPage();
-  await page.goto(`file://${process.cwd()}/slides/${file}`);
-  const pdfBytes = await page.pdf({ width: "1920px", height: "1080px", printBackground: true });
-  const tmp = await PDFDocument.load(pdfBytes);
-  const pages = await merged.copyPages(tmp, tmp.getPageIndices());
-  pages.forEach((p) => merged.addPage(p));
-  await page.close();
-}
-
-fs.writeFileSync("deck.pdf", await merged.save());
-await browser.close();
-```
-
-**Single-file deck-stage caveat**: shadow-DOM slot rendering can cause "only first slide exports." Use a per-slide URL fragment (`?slide=N`) and force the active slide before `page.pdf()`, or convert to multi-file before exporting.
-
-## Recovery: Rewriting for Editable PPTX After the Fact
-
-You're already mid-build and the user pivots to "we need editable PPTX." Two imperfect options:
-
-| Option                                    | Cost                                             | When                                                         |
-| ----------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
-| **Rewrite HTML to satisfy 4 constraints** | 2-3 hours for a typical 15-20 page deck          | Long-term — it's the only path to ongoing one-command export |
-| **Hand-write pptxgenjs version**          | 1-2 hours initially + permanent dual-maintenance | One-shot delivery — never edited again                       |
-
-**Always tell the user explicitly** which option you're picking and why. Don't silently choose the maintenance-debt path.
-
-## Position Questions for Each Slide
-
-Same as `hi-fi-prototype-html` — answer these before writing any slide:
-
-- **Narrative role** — hero, transition, data, quote, closer?
-- **Viewing distance** — laptop screen at 1m or projector at 10m? Drives font size and density.
-- **Visual temperature** — quiet/excited/cool/authoritative/tender? Drives palette and rhythm.
-- **Capacity check** — sketch 3 five-second thumbnails. Does it fit? (Most overcrowding is caught here.)
-
-## Anti-Patterns
-
-- ❌ Drawing slide chrome (page numbers, progress bars, titles) inside each slide AND in the deck stitcher → both render, double chrome
-- ❌ Using `1920×1080px` units for editable-PPTX target (must be `720pt × 405pt`)
-- ❌ One CSS file shared across multi-file slides — defeats the architecture's main benefit (scope isolation)
-- ❌ Building visual-rich slides "we can convert to PPTX later" — the 2-3 hour rework is real
-
-## Pairs Well With
-
-- `hi-fi-prototype-html` — same checkpoint discipline (4 position questions, junior pass)
-- `brand-asset-protocol` — required for branded decks
-- `anti-ai-slop` — slide decks are slop-prone (gradient backgrounds, emoji bullets)
-- `playwright` — drives PDF / image-mode PPTX export