@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-static-prototype/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: arn-spark-static-prototype
+description: >-
+  This skill should be used when the user says "static prototype", "arn static
+  prototype", "visual validation", "pixel perfect", "component showcase",
+  "static screens", "build a static prototype", "create a component showcase",
+  "visual review", "validate the visuals", "check the design",
+  "validate components", "review the design visuals", or wants to create a static component showcase and
+  validate it through iterative expert review cycles with per-criterion scoring,
+  an independent judge verdict, and versioned output.
+version: 1.0.0
+---
+
+# Arness Static Prototype
+
+Create a static component showcase and validate it through iterative build-review cycles, aided by the `arn-spark-prototype-builder` agent (in showcase mode) for rendering, the `arn-spark-style-capture` agent for screenshots, `arn-spark-product-strategist` and `arn-spark-ux-specialist` (greenfield agents in this plugin) for expert review, and the `arn-spark-ux-judge` agent for an independent final verdict. This is a conversational skill that runs in normal conversation (NOT plan mode).
+
+The primary artifacts are **versioned showcase pages** with component renders, **review reports** with per-criterion scores, and a **final report** documenting the complete validation history. All output is versioned so the user can compare evolution across cycles.
+
+This skill covers visual fidelity validation: do the components look correct according to the style brief? It does not cover interactive behavior -- that is `/arn-spark-clickable-prototype`'s job.
+
+## Prerequisites
+
+The following artifacts inform the validation. Check in order:
+
+Determine the prototypes output directory:
+1. Read the project's `arness.md` and check for a `## Arness` section
+2. If found, extract the configured Prototypes directory path — this is the source of truth
+3. If no `## Arness` section exists or Arness Spark fields are missing, inform the user: "Arness Spark is not configured for this project yet. Run `/arn-brainstorming` to get started — it will set everything up automatically." Do not proceed without it.
+4. If the directory does not exist, create it
+
+> All references to `prototypes/` in this skill refer to the configured prototypes directory determined above.
+
+**Style brief (strongly recommended):**
+1. Read the project's `arness.md` for a `## Arness` section. If found, check the configured Vision directory for `style-brief.md`
+2. If no `## Arness` section found, check `.arness/vision/style-brief.md` at the project root
+
+**Product concept (recommended):**
+1. Check the configured Vision directory for `product-concept.md`
+2. If no `## Arness` section found, check `.arness/vision/product-concept.md` at the project root
+
+**Architecture vision (for framework context):**
+1. Check the configured Vision directory for `architecture-vision.md`
+2. If no `## Arness` section found, check `.arness/vision/architecture-vision.md` at the project root
+
+**Visual grounding assets (recommended):**
+1. Read the `## Arness` section for the Visual grounding directory path
+2. Check for assets in `[visual-grounding]/references/`, `[visual-grounding]/designs/`, `[visual-grounding]/brand/`
+3. Also check the style brief's Visual Grounding section for asset paths and categories
+
+If found: visual grounding assets will be provided to expert reviewers and the judge alongside showcase screenshots for comparison.
+
+**Fresh design assets (optional):**
+1. Read the `## Arness` section for `Figma` and `Canva` fields
+2. If either is `yes` AND the visual grounding directory already has assets in `designs/` or `brand/`:
+   Ask the user:
+
+   > **Design assets exist from style exploration. Would you like to pull fresh versions from [Figma/Canva] before starting validation?**
+   > 1. **Yes** — Pull fresh design assets
+   > 2. **No** — Use existing assets on disk
+
+   - If **Yes**: ask the user to specify which assets to fetch (Figma file URL, page, or frame names / Canva design URL). Use the corresponding MCP to fetch and save to `[visual-grounding]/designs/` or `[visual-grounding]/brand/`. Show a summary of what was downloaded or replaced.
+   - If no: proceed with existing assets on disk.
+3. If either is `yes` but NO existing design assets found in `designs/` or `brand/`:
+   Ask the user:
+
+   > **No design mockups found yet. Would you like to pull design assets from [Figma/Canva]?**
+   > 1. **Yes** — Pull design assets now
+   > 2. **No** — Proceed without design mockups
+
+   - If **Yes**: same flow as above.
+   - If **No**: proceed without design mockups.
+4. If neither flag is `yes` or flags are missing: skip silently.
+
+**If a style brief is found:** Use it for visual validation criteria.
+
+**If no style brief is found:** Inform the user: "No style brief found. I can create a component showcase with default styling, but visual validation is more meaningful with a style brief. Consider running `/arn-spark-style-explore` first." Proceed if the user wants to continue -- criteria will focus on component quality and layout rather than style fidelity.
+
+**Project scaffold:** The project must be scaffolded with the UI framework and component library installed. Check the project's dependency configuration. If not scaffolded, inform the user: "The project needs to be scaffolded before building a component showcase. Run `/arn-spark-scaffold` first."
+
+## Workflow
+
+### Step 1: Detect Resume or Fresh Start
+
+Check for existing versioned output:
+
+1. Look for `prototypes/static/v*/` directories at the project root
+2. If versions exist, find the highest version number
+
+**If existing versions found:**
+
+Ask the user:
+
+**"I found existing static prototype versions up to v[N]. Which would you prefer?"**
+
+Options:
+1. **Continue from v[N]** — I will read the latest review report and continue with new cycles
+2. **Fresh start** — I will begin from v1 (existing versions are preserved)
+
+If continuing: read `prototypes/static/v[N]/review-report.md` to understand the current state and what was flagged. Ask the user for the new cycle budget and any focus refinements.
+
+**If no existing versions:** Proceed to Step 2.
+
+### Step 2: Configure Validation Parameters
+
+Present defaults and ask the user to confirm or adjust:
+
+"Let me set up the validation parameters:
+
+**Scoring:**
+- **Scale:** 1-5 (1 = unmet, 5 = exemplary)
+- **Minimum threshold:** 4 (every criterion must score at least 4)
+- **Max cycles:** 3 (build-review iterations before judge review)
+
+**Criteria:** Based on your style brief and product concept, here are the proposed criteria:
+
+| # | Criterion | Description |
+|---|-----------|-------------|
+| 1 | [criterion] | [description] |
+| ... | ... | ... |
+
+Adjust any parameter or criterion, or confirm to proceed."
+
+To propose criteria:
+1. Read the default criteria template:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-static-prototype/references/static-prototype-criteria.md`
+2. Adapt based on available artifacts (remove dark mode criterion if not applicable, add reference image criterion if images exist, etc.)
+3. Present the adapted list
+
+When the user confirms, write the agreed criteria to `prototypes/criteria.md` (create `prototypes/` directory if needed).
+
+### Step 3: Create Task List
+
+Create the task structure for the validation run. For max_cycles=N:
+
+- Task pairs: Build v[X] + Validate v[X] for each cycle (2 tasks per cycle)
+- Judge review task
+- User review task
+
+Example for max_cycles=3 (starting from v1):
+```
+Task 1:  Build v1
+Task 2:  Validate v1
+Task 3:  Build v2
+Task 4:  Validate v2
+Task 5:  Build v3
+Task 6:  Validate v3
+Task 7:  Judge review
+Task 8:  User review
+```
+
+If resuming from v[N], number versions sequentially from v[N+1].
+
+Present the task list to the user and proceed.
+
+### Step 4: Build-Review Cycle (Iterative)
+
+For each cycle:
+
+#### 4a: Build
+
+Invoke the `arn-spark-prototype-builder` agent via the Task tool, passing the model from `.arness/agent-models/spark.md` as the `model` parameter (see `plugins/arn-spark/skills/arn-spark-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:
+- **Showcase mode:** true
+- **Style brief:** toolkit configuration section
+- **Component list:** components from the criteria + style brief
+- **UI framework and component library:** from architecture vision or the project's dependency configuration
+- **Project root path**
+- **Output path:** `prototypes/static/v[N]/`
+- **Reference images (if available):** captured screenshots or user-provided images
+- **Previous review feedback (if not first cycle):** failing criteria details and improvement suggestions from the previous cycle's review report
+- **Showcase expectations:** The builder should produce numbered sections showing each component with all variants, all states, contextual usage (components in realistic surroundings, not just isolation), working interactive elements (toggles that toggle, inputs that accept text), and a simulated environment background appropriate to the application type. If the style brief includes dark mode, the showcase should have an inline dark/light toggle.
+
+Mark the Build task as in_progress before invoking, completed after.
+
+#### 4b: Capture Screenshots
+
+Invoke the `arn-spark-style-capture` agent via the Task tool, passing the model from `.arness/agent-models/spark.md` as the `model` parameter (see `plugins/arn-spark/skills/arn-spark-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:
+- **URL:** the URL serving the showcase (from the running prototype)
+- **Output path:** `prototypes/static/v[N]/screenshots/`
+
+If Playwright is unavailable, ask the user to provide screenshots of the showcase manually, or attempt to serve the showcase and capture screenshots through an alternative method. Note the limitation in the review report.
+
+#### 4c: Expert Review
+
+Invoke `arn-spark-product-strategist` and `arn-spark-ux-specialist` in parallel. Both agents receive the same inputs:
+
+- Screenshots, criteria list, scoring scale, threshold, style brief, product concept
+- If visual grounding assets are available, include them with category context:
+  - **References:** "These are inspirational references. Assess whether the overall direction aligns."
+  - **Designs:** "These are design mockups (specification). Assess fidelity — how closely does the showcase match these designs?"
+  - **Brand:** "These are brand constraints. Verify brand elements (logos, colors, typefaces) are correctly applied."
+- Request per-criterion scores and feedback from each agent.
+
+After both agents complete:
+
+For each criterion, use the LOWER of the two expert scores as the combined score. If only one expert is available (e.g., `arn-spark-ux-specialist` is not accessible), use that single expert's scores as the combined scores and note the limitation in the review report.
+
+#### 4d: Evaluate and Record
+
+1. Check all combined scores against the minimum threshold
+2. Read the review report template:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-static-prototype/references/review-report-template.md`
+3. Write the review report to `prototypes/static/v[N]/review-report.md`
+4. Write version notes to `prototypes/static/v[N]/version-notes.md` (what changed from previous version, or "Initial version" for v1)
+
+**If ALL criteria pass:** Mark the Validate task as completed. Skip remaining cycles and proceed to Step 5 (Judge Review).
+
+**If ANY criterion fails:**
+- Mark the Validate task as completed
+- Present the failing criteria to the user with a brief summary
+- Feed the failing criteria details and improvement suggestions to the next cycle's Build step
+- Proceed to the next cycle (or Step 5 if this was the last cycle)
+
+### Step 5: Judge Review
+
+Invoke the `arn-spark-ux-judge` agent via the Task tool, passing the model from `.arness/agent-models/spark.md` as the `model` parameter (see `plugins/arn-spark/skills/arn-spark-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:
+- **Review mode:** `static` -- the judge reviews screenshots and files (there is nothing interactive to navigate in a static showcase)
+- **Prototype artifacts:** paths to the latest version's showcase files and screenshots
+- **Criteria list:** from `prototypes/criteria.md`
+- **Scoring scale and minimum threshold**
+- **Style brief and product concept**
+- **Visual grounding assets (if available):** provide all three categories with context so the judge can compare the showcase against reference images, design mockups, and brand assets directly
+- **Version number**
+- **Previous review reports:** the latest version's review-report.md
+
+Write the judge's report to `prototypes/static/v[N]/judge-report.md`.
+
+**If Judge returns PASS:** Proceed to Step 6.
+
+**If Judge returns FAIL and cycle budget remains:**
+- Present the judge's failing criteria to the user
+- Calculate remaining budget (original max_cycles minus cycles used)
+Ask the user:
+
+> **The judge flagged [N] criteria below threshold. You have [M] cycles remaining. Run more fix cycles?**
+> 1. **Yes** — Run [M] more fix cycles
+> 2. **No** — Proceed with current results
+
+- If **Yes**: create new Build+Validate task pairs for the remaining cycles, return to Step 4
+- If **No**: proceed to Step 6 with the judge's report
+
+**If Judge returns FAIL and no budget remains:** Proceed to Step 5b with the judge's report.
+
+### Step 5b: Generate Visual Showcase
+
+After the judge review completes (whether PASS or FAIL with no budget), generate structured screenshot images so the user can review the final visual state without running a dev server. This is the user's primary visual deliverable.
+
+1. Read the showcase capture guide:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-static-prototype/references/showcase-capture-guide.md`
+
+2. Read the section manifest from `prototypes/static/v[N]/showcase-manifest.json` (written by the prototype builder). If the manifest does not exist, note the limitation and capture a single full-page screenshot only.
+
+3. Start the prototype dev server (same procedure as Step 4b).
+
+4. Generate a Playwright capture script appropriate to the project's stack. The script captures:
+   - A full-page scrolling screenshot (`showcase-full.png`)
+   - A per-section screenshot for each entry in the manifest (e.g., `01-typography.png`, `04-buttons.png`)
+   - Dark mode variants of all captures if the showcase has a dark/light toggle
+
+   Write the script to `prototypes/static/v[N]/showcase/capture-script.js` so the user can re-run it.
+
+5. Run the capture script. If individual section captures fail, skip them and note the gaps.
+
+6. Stop the prototype dev server.
+
+7. Write `prototypes/static/v[N]/showcase/showcase-index.md` — a self-contained markdown document embedding all captured images with:
+   - Version number, judge verdict, and generation date
+   - Final criterion scores summary
+   - Each section's screenshot with its title as a heading
+   - Full-page overview
+   - Dark mode section (if applicable)
+
+If Playwright is unavailable, skip this step entirely and inform the user: "Playwright is not available. The showcase can be viewed by running the dev server. Automated visual export was skipped."
+
+### Step 6: User Review
+
+Present the complete validation history:
+
+"**Static prototype validation complete.**
+
+**Latest version:** v[N]
+**Judge verdict:** [PASS / FAIL]
+
+**Version history:**
+| Version | Criteria Passing | Criteria Failing | Notable Changes |
+|---------|-----------------|------------------|----------------|
+| v1 | [X]/[M] | [Y] | Initial build |
+| v2 | [X]/[M] | [Y] | [summary of fixes] |
+| ... | ... | ... | ... |
+
+**Final scores (v[N]):**
+| # | Criterion | Expert Score | Judge Score | Status |
+|---|-----------|-------------|-------------|--------|
+| 1 | [name] | [score] | [score] | PASS/FAIL |
+| ... | ... | ... | ... | ... |
+
+The showcase is at `prototypes/static/v[N]/`.
+[If showcase images were generated:] Visual showcase images are at `prototypes/static/v[N]/showcase/showcase-index.md` — open this file to see all components at a glance without running the dev server.
+
+Ask the user:
+
+> **Are you satisfied with this result?**
+> 1. **Yes, finalize** — Write the final report
+> 2. **Run additional cycles** — Return to Step 2 with new parameters"
+
+If the user chooses **Run additional cycles**, return to Step 2 with new parameters (the user can adjust criteria, threshold, or cycle count).
+
+### Step 7: Write Final Report
+
+Write `prototypes/static/final-report.md` with:
+- Complete version history and all scores
+- Judge verdict and report (from `prototypes/static/v[N]/judge-report.md`)
+- User decision
+- Criteria used
+- Links to all version directories
+- Link to the visual showcase (`prototypes/static/v[N]/showcase/showcase-index.md`) if generated
+
+### Step 8: Recommend Next Steps
+
+"Static prototype validation complete. Results saved to `prototypes/static/`.
+
+Recommended next steps:
+1. **Build clickable prototype:** Run `/arn-spark-clickable-prototype` to add interaction and validate user journeys
+2. **Lock the prototype:** After clickable validation, run `/arn-spark-prototype-lock` to freeze a snapshot before development modifies shared source files
+3. **Extract features:** Run `/arn-spark-feature-extract` to create a prioritized feature backlog
+
+The clickable prototype will build on the validated visual direction from this static prototype."
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| Build showcase (Step 4a) | Invoke `arn-spark-prototype-builder` in showcase mode with style brief, components, output path, and previous review feedback |
+| Capture screenshots (Step 4b) | Invoke `arn-spark-style-capture` with the showcase URL and output path. If unavailable, ask the user for manual screenshots. |
+| Expert review (Step 4c) | Invoke `arn-spark-product-strategist` and `arn-spark-ux-specialist` in parallel with screenshots, criteria, scoring parameters, and visual grounding assets (with category context). After both complete, take the LOWER score per criterion. |
+| Judge review (Step 5) | Invoke `arn-spark-ux-judge` in `static` mode with latest screenshots, criteria, scoring parameters, review reports, and visual grounding assets for direct comparison |
+| Generate visual showcase (Step 5b) | Read the showcase capture guide, start the prototype, generate and run a Playwright capture script per the section manifest, write `showcase-index.md`. Skip if Playwright unavailable. |
+| User asks about interactive behavior | Defer: "Interactive behavior is validated in `/arn-spark-clickable-prototype`. This skill focuses on visual fidelity." |
+| User asks to change the style | Defer to `/arn-spark-style-explore` for style brief updates, then re-run static prototype validation |
+| User asks about features | Defer: "Feature work starts after `/arn-spark-feature-extract`. If Arness Code is installed, continue with `/arn-code-feature-spec` for detailed specifications." |
+| Builder fails | Retry up to 3 times. If still failing, present the error for manual investigation. |
+| Expert returns unhelpful scores | Re-invoke with more specific prompt referencing the exact criteria and screenshots. |
+
+## Error Handling
+
+- **No style brief found:** Proceed with component quality and layout criteria only. Note that visual fidelity criteria are deferred until a style brief exists.
+- **Project not scaffolded:** Cannot build showcase. Suggest `/arn-spark-scaffold` first.
+- **Builder fails (3 times):** Present the error. The user can investigate manually or adjust the approach.
+- **Capture fails (Playwright unavailable):** Fall back to asking the user for manual screenshots. Note the limitation. The visual showcase (Step 5b) is also skipped.
+- **Showcase manifest missing:** The builder did not write `showcase-manifest.json`. Capture a full-page screenshot only. Note: "Section manifest not found. Re-build the showcase to generate per-section captures."
+- **Expert returns unhelpful scores (vague, all maximum, etc.):** Re-invoke with a more specific prompt asking for scores on each criterion individually with evidence.
+- **arn-spark-ux-specialist unavailable:** Proceed with `arn-spark-product-strategist` as the sole expert reviewer. Use its scores directly as the combined scores. Note the limitation in the review report.
+- **Judge unavailable:** The user becomes the judge. Present all expert review reports and ask the user to make the pass/fail decision.
+- **Resume from interrupted cycle:** Detect the latest version directory. If it has a review-report.md, the cycle completed -- continue from the next cycle. If it has showcase files but no review-report.md, the build completed but review did not -- run review on the existing build.
+- **Criteria file already exists:**
+
+  Ask the user:
+
+  > **Existing criteria found at `prototypes/criteria.md`. What would you like to do?**
+  > 1. **Use existing** — Keep the current criteria
+  > 2. **Define new** — Create fresh criteria for this validation
+- **Writing the document fails:** Print the full content in the conversation so the user can copy it.

package/plugins/arn-spark/skills/arn-spark-static-prototype/references/review-report-template.md

@@ -0,0 +1,65 @@
+# Review Report Template -- Static Prototype
+
+Use this template for each version's expert review report during the static prototype validation cycle.
+
+```markdown
+# Review Report: Version [N]
+
+## Reviewers
+- **Product strategist:** arn-spark-product-strategist
+- **UX specialist:** arn-spark-ux-specialist
+
+## Scoring
+- **Scale:** [1-N]
+- **Minimum threshold:** [T]
+
+## Criterion Scores
+
+| # | Criterion | Product Strategist | UX Specialist | Combined | Status |
+|---|-----------|-------------------|---------------|----------|--------|
+| 1 | [name] | [score] | [score] | [lower] | PASS/FAIL |
+| 2 | [name] | [score] | [score] | [lower] | PASS/FAIL |
+| ... | ... | ... | ... | ... | ... |
+
+## Visual Grounding Comparison
+
+**Assets provided to reviewers:**
+| Category | Count | Source |
+|----------|-------|--------|
+| References | [N] | [URL captures, user screenshots] |
+| Designs | [N] | [Figma exports, Canva exports, manual mockups] |
+| Brand | [N] | [logos, guidelines] |
+
+**Comparison notes:**
+- **Reference alignment:** [How well the showcase matches the inspirational direction]
+- **Design fidelity:** [How closely components match the design mockups — only if designs exist]
+- **Brand compliance:** [Whether brand elements are correctly applied — only if brand assets exist]
+
+[If no visual grounding assets were available: "No visual grounding assets provided. Review based on style brief text only."]
+
+## Failing Criteria
+
+### [Criterion Name] -- Combined [X]/[scale]
+- **Product strategist feedback:** [specific observation and suggestion]
+- **UX specialist feedback:** [specific observation and suggestion]
+- **Priority:** [Critical / Important]
+
+[Repeat for each failing criterion]
+
+## Passing Criteria Highlights
+[Brief notes on particularly strong aspects, if any]
+
+## Summary
+- **Passing:** [N] of [M] criteria meet threshold
+- **Failing:** [N] criteria below threshold
+- **Verdict:** PROCEED TO NEXT CYCLE / ALL CRITERIA PASS -- PROCEED TO JUDGE
+
+## Recommended Focus for Next Cycle
+[If failing: ordered list of what to fix, most critical first]
+```
+
+## Usage Notes
+
+- The combined score uses the LOWER of the two expert scores for each criterion. This ensures both perspectives are satisfied.
+- If only one expert is available (e.g., arn-spark-product-strategist only), use that single score as the combined score.
+- The skill writes this report to `prototypes/static/vN/review-report.md` after each validation cycle.

package/plugins/arn-spark/skills/arn-spark-static-prototype/references/showcase-capture-guide.md

@@ -0,0 +1,153 @@
+# Showcase Capture Guide
+
+This document defines how the `arn-spark-static-prototype` skill generates structured visual showcase images after the judge review passes. The output is a set of per-section screenshots and an index document that the user can glance at without running a dev server.
+
+## When This Runs
+
+After the judge returns PASS (or after the final cycle if the judge fails but the user proceeds). This is the last automated step before presenting results to the user. The showcase images are the user's primary visual deliverable from the static prototype process.
+
+## Prerequisites
+
+- The showcase is built and can be served (dev server starts successfully)
+- The `showcase-manifest.json` exists in the version directory (written by `arn-spark-prototype-builder`)
+- Playwright is available for screenshot capture
+
+If Playwright is not available, skip automated capture and inform the user: "Playwright is not available. The showcase can be viewed by running the dev server. Automated visual export was skipped." The skill continues to the user review step without showcase images.
+
+## Capture Process
+
+### 1. Read the section manifest
+
+Read `prototypes/static/v[N]/showcase-manifest.json` to get the list of sections with their IDs and titles. If the manifest does not exist (e.g., an older prototype build), fall back to capturing a single full-page screenshot only.
+
+### 2. Start the prototype
+
+Start the dev server using the same procedure as Step 4b of the main skill. Record the URL and process ID.
+
+### 3. Generate a capture script
+
+Generate a Playwright script tailored to the project's stack. The script must:
+
+1. **Navigate** to the showcase URL
+2. **Wait** for the page to be fully loaded (network idle, no pending animations)
+3. **Set dark mode to OFF** (if a dark/light toggle exists) for the primary captures
+4. **Capture full page:** Take a full-page scrolling screenshot → `showcase-full.png`
+5. **Capture each section:** For each entry in the manifest:
+   - Scroll the element with `id="showcase-section-NN"` into view
+   - Wait for any lazy-loaded content or animations to settle
+   - Capture the element's bounding box → `NN-title.png` (e.g., `01-typography.png`, `04-buttons.png`)
+6. **Dark mode captures (if applicable):** If the showcase has dark mode:
+   - Toggle dark mode ON
+   - Capture full page → `showcase-full-dark.png`
+   - Capture each section → `NN-title-dark.png`
+
+**Script generation approach by stack:**
+
+| Stack | Capture method |
+|-------|---------------|
+| Web app (any framework) | Playwright script targeting `localhost` URL |
+| Desktop app with web view (Tauri, Electron) | Playwright script targeting the web view URL (Tauri: `localhost` dev server; Electron: dev server or `chrome-devtools://` if needed) |
+| Native mobile app | Start simulator/emulator, use platform screenshot tools (`xcrun simctl io` for iOS, `adb exec-out screencap` for Android). Per-section capture requires scrolling automation via the platform's UI testing framework. If not feasible, capture full-page only and note the limitation. |
+| Terminal/CLI app | Not applicable for visual showcase. Skip this step and note: "Terminal applications do not produce visual showcases." |
+
+For the vast majority of greenfield projects (web, Tauri, Electron), the Playwright approach works directly because the prototype builder creates web-based showcases served via a dev server.
+
+**Script location:** Write the generated script to `prototypes/static/v[N]/showcase/capture-script.js` (or `.ts`, `.py` — match the project's ecosystem). This allows the user to re-run the capture manually if needed.
+
+### 4. Run the capture script
+
+Execute the script via Bash. If a section capture fails (element not found, timeout), skip that section and note it in the showcase index. Do not fail the entire capture for one missing section.
+
+### 5. Stop the prototype
+
+Kill the dev server process.
+
+## Output Structure
+
+```
+prototypes/static/v[N]/showcase/
+├── capture-script.js          ← Generated Playwright script (re-runnable)
+├── showcase-full.png          ← Full-page scrolling capture (light mode)
+├── showcase-full-dark.png     ← Full-page scrolling capture (dark mode, if applicable)
+├── 01-typography.png          ← Per-section captures (light mode)
+├── 02-colors.png
+├── 03-containers.png
+├── 04-buttons.png
+├── 05-forms.png
+├── ...
+├── 01-typography-dark.png     ← Per-section captures (dark mode, if applicable)
+├── 02-colors-dark.png
+├── ...
+└── showcase-index.md          ← Visual summary document
+```
+
+### File naming convention
+
+- Section files: `NN-title.png` where `NN` is the zero-padded section number and `title` is the section title in kebab-case (e.g., `04-buttons-and-controls.png`)
+- Dark mode variants: append `-dark` before the extension (e.g., `04-buttons-and-controls-dark.png`)
+- Full page: `showcase-full.png` / `showcase-full-dark.png`
+
+## Showcase Index Template
+
+The `showcase-index.md` is a self-contained markdown document that the user can open to see all showcase images with context. It embeds the images using relative markdown image links.
+
+```markdown
+# Component Showcase — v[N]
+
+**Version:** [N]
+**Judge verdict:** [PASS / FAIL]
+**Date:** [YYYY-MM-DD]
+**Style brief:** [product-name] style brief
+
+## Scores Summary
+
+| # | Criterion | Score | Status |
+|---|-----------|-------|--------|
+| 1 | [name] | [combined] | PASS/FAIL |
+| ... | ... | ... | ... |
+
+---
+
+## Component Sections
+
+### 1. Typography
+![Typography](./01-typography.png)
+
+### 2. Colors
+![Colors](./02-colors.png)
+
+### 3. Containers
+![Containers](./03-containers.png)
+
+[... one section per captured image ...]
+
+## Full Page View
+![Full showcase](./showcase-full.png)
+
+[If dark mode exists:]
+
+---
+
+## Dark Mode
+
+### 1. Typography (Dark)
+![Typography Dark](./01-typography-dark.png)
+
+[... repeat for all sections ...]
+
+### Full Page View (Dark)
+![Full showcase dark](./showcase-full-dark.png)
+
+---
+
+*Generated by Arness Static Prototype v[N] — [date]*
+```
+
+## Error Handling
+
+- **Playwright unavailable:** Skip the entire capture. Inform the user the showcase can be viewed by running the dev server.
+- **Manifest missing:** Capture full-page only. Note: "Section manifest not found. Only full-page capture produced. Re-build the showcase to generate per-section captures."
+- **Section element not found:** Skip that section's capture. List skipped sections in the showcase index.
+- **Dev server fails to start:** Skip the capture. Print the showcase index template (without images) so the user knows what sections exist.
+- **Dark mode toggle not found:** Capture light mode only. Note in the index: "Dark mode toggle not detected. Only light mode captured."
+- **Native mobile (no Playwright):** Attempt platform-specific capture. If not feasible, note the limitation and suggest the user capture screenshots manually from the simulator.

package/plugins/arn-spark/skills/arn-spark-static-prototype/references/static-prototype-criteria.md

@@ -0,0 +1,54 @@
+# Static Prototype Default Criteria
+
+This template provides the default criteria for visual validation of static component showcases. The `arn-spark-static-prototype` skill proposes these criteria based on available project artifacts (style brief, product concept). The user confirms or adjusts before validation begins.
+
+## Default Criteria
+
+### Visual Fidelity
+
+| # | Criterion | Description |
+|---|-----------|-------------|
+| 1 | Color palette accuracy | All color roles (primary, secondary, accent, background, text, border) match the style brief hex values |
+| 2 | Typography conformance | Font families, weights, and sizes match the style brief specifications |
+| 3 | Spacing consistency | Spacing tokens (padding, margins, gaps) are applied consistently and match the style brief |
+| 4 | Border radius conformance | Component corner radii match the style brief specifications |
+| 5 | Shadow and elevation | Box shadows and elevation effects match the style brief (or absent if not specified) |
+
+### Component Quality
+
+| # | Criterion | Description |
+|---|-----------|-------------|
+| 6 | Component variant coverage | All specified component variants (sizes, states) are rendered |
+| 7 | State representation | Interactive states (default, hover, active, disabled, error) are visually distinct |
+| 8 | Component library usage | Components use the project's actual component library, not custom implementations |
+| 9 | Theme integration | Component library theme configuration is applied globally, not per-component overrides |
+
+### Layout and Composition
+
+| # | Criterion | Description |
+|---|-----------|-------------|
+| 10 | Visual hierarchy | Heading, body, and caption text establish clear hierarchy |
+| 11 | Alignment and grid | Components align to a consistent grid or layout system |
+| 12 | Content density | Spacing between elements matches the intended density (compact, moderate, spacious) |
+
+### Overall Impression
+
+| # | Criterion | Description |
+|---|-----------|-------------|
+| 13 | Style brief adherence | Overall visual impression matches the style brief's described feel and direction |
+| 14 | Dark mode consistency | If dark mode is specified: all components render correctly in dark mode with appropriate contrast |
+
+## Adapting Criteria
+
+- **If no style brief exists:** Remove criteria 1-5 and 13-14. Focus on component quality and layout.
+- **If no dark mode:** Remove criterion 14.
+- **If reference images exist** (in visual grounding `references/`): Add criterion:
+  "Reference alignment — overall visual direction aligns with provided reference images"
+- **If design mockups exist** (in visual grounding `designs/`): Add criterion:
+  "Design fidelity — component rendering matches the provided design mockups in layout, spacing, and proportions"
+- **If brand assets exist** (in visual grounding `brand/`): Add criterion:
+  "Brand compliance — brand elements (logos, colors, typefaces) are correctly incorporated"
+- **If specific components were discussed:** Add per-component criteria as needed.
+- **If style brief specifies animations:** Add criterion: "Animation readiness — Elements that will be animated have correct initial states (e.g., opacity: 0 for fade-in elements), data attributes for animation targeting, and appropriate class names or identifiers. The animation approach's imports are present. Animations may not be fully wired to triggers in the static prototype."
+
+The user may add, remove, or modify any criterion before validation begins.