@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-visual-sketch/references/sketch-gallery-guide.md

@@ -0,0 +1,282 @@
+# Sketch Gallery Guide
+
+This guide defines how the gallery index page should be structured. The `arn-spark-visual-sketch` skill creates and maintains this page — the `arn-spark-visual-sketcher` agents do not touch it.
+
+## Purpose
+
+The gallery is the user's entry point for comparing visual direction proposals. It must be immediately useful: a user landing on it should see all proposals at a glance, understand each direction, and navigate to any proposal in one click.
+
+## Gallery Layout
+
+### Structure
+
+```
+/arness-sketches/                    ← Gallery index (this page)
+/arness-sketches/round-1/proposal-1/ ← First proposal screens
+/arness-sketches/round-1/proposal-2/ ← Second proposal screens
+/arness-sketches/round-1/proposal-3/ ← Third proposal screens
+/arness-sketches/round-2/expansion-1/ ← Expansion of selected proposal
+/arness-sketches/round-2/expansion-2/ ← Another expansion
+```
+
+### Gallery Index Content
+
+The gallery index page displays:
+
+1. **Title:** "Visual Direction Sketches" or similar
+2. **Round sections:** One section per round, most recent first
+3. **Proposal cards:** Within each round, one card per proposal
+
+### Proposal Cards
+
+Each card shows:
+
+- **Proposal identifier:** e.g., "Proposal A" or "Expansion 1"
+- **Direction brief summary:** The first sentence or a shortened version of the direction brief
+- **Key visual indicators:** 3-4 color swatches from the proposal's CSS variables (rendered as small colored circles or rectangles)
+- **Link:** Clicking the card navigates to the proposal's first screen
+
+### Multi-Round Display
+
+- All rounds are shown, newest at the top
+- The selected proposal from each completed round is visually highlighted (e.g., a border, a "Selected" badge, or a subtle background)
+- Rounds that led to expansions show a visual connection: "Round 2 — Expansions of Proposal B from Round 1"
+
+### Navigation
+
+- Each proposal card links to the proposal's first screen
+- Within each proposal, the `arn-spark-visual-sketcher` agent creates intra-proposal navigation between screens
+- A "Back to Gallery" link should appear on each proposal's pages (the agent's intra-proposal nav handles this within its layout)
+
+## Framework-Specific Patterns
+
+### SvelteKit
+
+```
+src/routes/arness-sketches/
+  +page.svelte              ← Gallery index
+  +layout.svelte            ← Minimal shared layout (no global styling that affects proposals)
+  round-1/
+    proposal-1/
+      +layout.svelte        ← CSS variable isolation for this proposal
+      +page.svelte          ← First screen
+      list/+page.svelte     ← Second screen
+    proposal-2/
+      +layout.svelte
+      +page.svelte
+      ...
+```
+
+The top-level `+layout.svelte` at `arness-sketches/` should be minimal — just a wrapper that does NOT define CSS variables. Only proposal-level layouts define `--sketch-*` variables.
+
+### Next.js (App Router)
+
+```
+app/arness-sketches/
+  page.tsx                  ← Gallery index
+  layout.tsx                ← Minimal shared layout
+  round-1/
+    proposal-1/
+      layout.tsx            ← CSS variable isolation
+      page.tsx              ← First screen
+      list/page.tsx         ← Second screen
+    ...
+```
+
+### Nuxt
+
+```
+pages/arness-sketches/
+  index.vue                 ← Gallery index
+  round-1/
+    proposal-1/
+      index.vue             ← First screen (layout via definePageMeta or wrapper)
+      list.vue              ← Second screen
+    ...
+```
+
+### Generic (no file-based routing)
+
+Create a standalone HTML page or a route in the project's router configuration. Use a simple hash-based or conditional rendering approach for the gallery.
+
+## Implementation Notes
+
+- The gallery itself is **sketch-quality** — it does not need to be polished. Simple layout, readable text, clickable links. It is a tool for comparison, not a deliverable.
+- Use the project's CSS framework for basic styling (Tailwind utilities, etc.) but do NOT use proposal-specific CSS variables. The gallery should look neutral.
+- Read each proposal's `proposal-manifest.json` to get the screen list, routes, direction summary, and CSS variable values for rendering color swatches.
+- When updating the gallery for a new round (Step 8 of the skill), preserve existing round sections. Prepend the new round at the top.
+- If a proposal failed to generate (agent error), show a placeholder card: "Proposal X — Generation failed. [Error summary]"
+
+## Gallery Visual Standards
+
+The gallery is a comparison tool, not a product deliverable — but it must look consistent across runs so the user can focus on comparing proposals, not deciphering a different layout each time. These standards define the gallery's visual scaffold using a dedicated `--gallery-*` CSS variable namespace that never collides with `--sketch-*` proposal variables.
+
+### CSS Variables
+
+Define these on the gallery wrapper element (never on `:root`):
+
+```css
+--gallery-bg: #fafafa;
+--gallery-surface: #ffffff;
+--gallery-text: #1a1a1a;
+--gallery-text-muted: #6b7280;
+--gallery-border: #e5e7eb;
+--gallery-accent: #2563eb;
+--gallery-radius: 8px;
+--gallery-font: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+--gallery-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+```
+
+### Page Structure
+
+- Max-width: `960px`, centered with `margin: 0 auto`
+- Horizontal padding: `2rem`
+- Background: `var(--gallery-bg)`
+- All text uses `var(--gallery-font)` — the gallery never inherits proposal fonts
+
+### Round Section Headers
+
+- Round title (e.g., "Round 1" or "Round 2 — Expansions of Proposal B"): `1.25rem`, font-weight `600`, color `var(--gallery-text-muted)`
+- Margin: `2.5rem` top (between rounds), `1rem` bottom (before card grid)
+- First round has no top margin
+
+### Proposal Card Grid
+
+- Layout: `display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 1.25rem`
+- No media queries — `auto-fill` with `minmax` handles responsive behavior intrinsically (1 column on narrow, 2-3 on wider)
+
+### Card Anatomy
+
+Every proposal card follows this exact internal structure:
+
+```
+┌─────────────────────────────┐
+│  Proposal A                 │  ← identifier: 1rem, bold
+│                             │
+│  Dark and focused with      │  ← brief: 0.875rem, muted,
+│  deep charcoal backgrounds  │     max 3 lines, overflow
+│  and electric blue...       │     hidden with ellipsis
+│                             │
+│  Confident & calm · Sharp   │  ← direction note: 0.75rem,
+│  edges, no shadows          │     italic, muted, 1 line
+│                             │
+│  ● ● ● ●                   │  ← swatches: 4 circles
+│                             │
+│  View proposal →            │  ← link: 0.875rem, accent
+└─────────────────────────────┘
+```
+
+Card styling:
+- Background: `var(--gallery-surface)`
+- Border: `1px solid var(--gallery-border)`
+- Border-radius: `var(--gallery-radius)`
+- Box-shadow: `var(--gallery-shadow)`
+- Padding: `1.25rem`
+
+**Proposal identifier:** `font-size: 1rem; font-weight: 700; color: var(--gallery-text); margin-bottom: 0.5rem`
+
+**Direction brief:** `font-size: 0.875rem; color: var(--gallery-text-muted); line-height: 1.5; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; margin-bottom: 0.75rem`
+
+**Direction note:** `font-size: 0.75rem; font-style: italic; color: var(--gallery-text-muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; margin-bottom: 0.75rem`
+- Shows the tone commitment + differentiation anchor from the direction brief, separated by " · "
+- Sourced from `proposal-manifest.json` field `directionNote`
+- If `directionNote` is not present in the manifest (backward compatibility with older proposals), omit this line entirely
+
+**Color swatches:** A row of exactly **4 circles** showing the proposal's key colors:
+- Values sourced from `proposal-manifest.json`: `--sketch-bg`, `--sketch-primary`, `--sketch-accent`, `--sketch-surface`
+- Each circle: `width: 24px; height: 24px; border-radius: 50%; border: 1px solid var(--gallery-border)`
+- Row: `display: flex; gap: 8px; margin-bottom: 0.75rem`
+
+**View link:** `font-size: 0.875rem; color: var(--gallery-accent); text-decoration: none; font-weight: 500`
+
+### Selected Proposal Highlight
+
+When a proposal has been selected in a completed round:
+- `border-left: 3px solid var(--gallery-accent)` (replaces the standard `1px` left border)
+- A "Selected" badge in the header row: `display: inline-block; font-size: 0.6875rem; font-weight: 600; background: var(--gallery-accent); color: #ffffff; padding: 2px 8px; border-radius: 999px; margin-left: 0.5rem; vertical-align: middle`
+
+### Failed Proposal Treatment
+
+When a proposal failed to generate:
+- Border style: `1px dashed var(--gallery-border)`
+- Background: `var(--gallery-bg)` (matches page, visually recessed)
+- Brief text: italic, shows error summary
+- No swatch row or view link
+
+### Required HTML Skeleton
+
+All framework implementations must produce this semantic structure:
+
+```html
+<div class="gallery-wrapper" style="/* --gallery-* variables defined here */">
+  <h1>Visual Direction Sketches</h1>
+
+  <!-- One section per round, newest first -->
+  <section class="gallery-round">
+    <h2>Round 1</h2>
+    <div class="gallery-grid">
+
+      <a href="/arness-sketches/round-1/proposal-1" class="gallery-card">
+        <div class="card-header">
+          <span class="card-id">Proposal A</span>
+          <!-- if selected: <span class="card-badge">Selected</span> -->
+        </div>
+        <p class="card-brief">Direction brief summary...</p>
+        <p class="card-note">Confident & calm · Sharp edges, no shadows</p>
+        <div class="card-swatches">
+          <span class="swatch" style="background: #1a1a2e"></span>
+          <span class="swatch" style="background: #2563eb"></span>
+          <span class="swatch" style="background: #7c3aed"></span>
+          <span class="swatch" style="background: #1e1e30"></span>
+        </div>
+        <span class="card-link">View proposal →</span>
+      </a>
+
+      <!-- repeat for each proposal -->
+    </div>
+  </section>
+</div>
+```
+
+Class names are semantic references — use the project's CSS framework to implement the styles. The structure (nesting, element types, order of children) must be followed.
+
+### Tailwind Utility Example
+
+For projects using Tailwind, the card grid and card anatomy translate to:
+
+```html
+<!-- Gallery wrapper -->
+<div class="max-w-[960px] mx-auto px-8 bg-[#fafafa] font-[system-ui]">
+
+  <!-- Round section -->
+  <section class="mt-10 first:mt-0">
+    <h2 class="text-xl font-semibold text-gray-500 mb-4">Round 1</h2>
+    <div class="grid grid-cols-[repeat(auto-fill,minmax(280px,1fr))] gap-5">
+
+      <!-- Card -->
+      <a href="..." class="block bg-white border border-gray-200 rounded-lg shadow-sm p-5
+                           hover:shadow-md transition-shadow no-underline">
+        <div class="mb-2">
+          <span class="text-base font-bold text-gray-900">Proposal A</span>
+        </div>
+        <p class="text-sm text-gray-500 leading-relaxed line-clamp-3 mb-3">
+          Dark and focused with deep charcoal backgrounds...
+        </p>
+        <p class="text-xs italic text-gray-400 truncate mb-3">
+          Confident & calm · Sharp edges, no shadows
+        </p>
+        <div class="flex gap-2 mb-3">
+          <span class="w-6 h-6 rounded-full border border-gray-200" style="background:#1a1a2e"></span>
+          <span class="w-6 h-6 rounded-full border border-gray-200" style="background:#2563eb"></span>
+          <span class="w-6 h-6 rounded-full border border-gray-200" style="background:#7c3aed"></span>
+          <span class="w-6 h-6 rounded-full border border-gray-200" style="background:#1e1e30"></span>
+        </div>
+        <span class="text-sm font-medium text-blue-600">View proposal →</span>
+      </a>
+
+    </div>
+  </section>
+</div>
+```
+
+Adapt class names for the project's Tailwind version and configuration, but maintain the same visual proportions and structure.

package/plugins/arn-spark/skills/arn-spark-visual-sketch/references/visual-direction-template.md

@@ -0,0 +1,174 @@
+# Visual Direction Template
+
+This template defines the structure for visual direction documents written by the `arn-spark-visual-sketch` skill. The document is saved to the project's Vision directory as `visual-direction.md`.
+
+A visual direction captures the selected visual approach from iterative sketch exploration. It provides enough detail for downstream skills (especially `arn-spark-style-explore`) to translate the direction into precise design tokens, CSS variables, and toolkit configuration. It is intentionally lighter than a style brief — approximate values and directional characteristics rather than exact token tables.
+
+## Instructions for arn-spark-visual-sketch
+
+When populating this template:
+
+- Replace all bracketed placeholders with concrete values from the exploration
+- Color values should be approximate hex values — exact tokens come from `arn-spark-style-explore`
+- Include the full iteration history so downstream skills understand how the direction evolved
+- Screenshot paths must reference files in the visual grounding `designs/` directory
+- The CSS variables section should list what the selected sketch's layout component actually defined
+- The direction brief should be the full text of the winning brief, not a summary
+- The Tone & Creative Anchors section should extract the tone commitment and differentiation anchor from the winning direction brief, and the Design Thinking answers from the selected sketch's layout component HTML comment block
+- The Animation & Motion section should describe motion intent from the selected sketch in platform-agnostic terms. If the sketch had working animations, read the proposal source and manifest to identify patterns, approach, and role. If the sketch was static, note it explicitly — do not leave animation unaddressed
+- If screenshots were not captured (Playwright unavailable), note it in the Screenshots section
+
+---
+
+## Template
+
+```markdown
+# [Product Name] - Visual Direction
+
+## Selected Direction
+
+[2-3 sentences describing the chosen visual approach. Reference the product personality and target users. E.g., "A warm, inviting interface with generous whitespace that reflects a tool used between family members. Cream backgrounds and terracotta accents create a friendly atmosphere, while serif headings add a touch of personality without sacrificing readability."]
+
+## Tone & Creative Anchors
+
+| Anchor | Value |
+|--------|-------|
+| Tone Commitment | [The aesthetic posture from the direction brief, e.g., "archival/typographic", "luxury/refined", "industrial/utilitarian"] |
+| Differentiation Anchor | [The one memorable design choice, e.g., "ruled-line ledger system structures all content", "oversized italic serif pull quotes as section dividers"] |
+| Anti-Pattern Constraint | [The direction-specific thing to avoid, e.g., "No drop shadows — depth comes only from layered backgrounds"] |
+
+### Design Thinking (from selected sketch proposal)
+
+| Question | Answer |
+|----------|--------|
+| Purpose | [What problem does this interface solve? Who uses it? What do they need to feel?] |
+| Tone | [Aesthetic posture committed to] |
+| Differentiation | [The one thing someone will remember] |
+| Execution | [How the commitment was applied — bold, restrained, layered, etc.] |
+
+[These anchors were established during visual sketch exploration and should be preserved through style refinement. The tone commitment and differentiation anchor are the creative DNA of this direction — downstream skills should translate them into precise tokens, not dilute them into generic defaults.]
+
+## Direction Characteristics
+
+| Aspect | Value |
+|--------|-------|
+| Color Mood | [e.g., warm earthy tones, cool minimalist, dark with neon accents] |
+| Typography Feel | [e.g., modern sans-serif, mixed serif headings / sans-serif body, playful rounded] |
+| Layout Approach | [e.g., top navigation with card grid, sidebar with list content, split-panel] |
+| Layout Density | [e.g., spacious, comfortable, compact] |
+| Component Style | [e.g., rounded with subtle shadows, sharp with strong borders, pill-shaped minimal] |
+| Overall Feel | [2-3 adjectives, e.g., warm, inviting, approachable] |
+
+## Color Palette (Approximate)
+
+| Role | Color | Hex |
+|------|-------|-----|
+| Background | [description] | [#hex] |
+| Surface | [description] | [#hex] |
+| Primary | [description] | [#hex] |
+| Primary Foreground | [description] | [#hex] |
+| Accent | [description] | [#hex] |
+| Text Primary | [description] | [#hex] |
+| Text Secondary | [description] | [#hex] |
+| Border | [description] | [#hex] |
+
+[These are the approximate values used in the sketch. Style-explore will refine them into a complete palette with semantic colors, hover states, and dark mode variants.]
+
+## CSS Variables Used
+
+The selected sketch's layout component defined these CSS custom properties:
+
+```css
+--sketch-bg: [value];
+--sketch-surface: [value];
+--sketch-primary: [value];
+--sketch-primary-fg: [value];
+--sketch-accent: [value];
+--sketch-text: [value];
+--sketch-text-muted: [value];
+--sketch-border: [value];
+--sketch-font-heading: [value];
+--sketch-font-body: [value];
+--sketch-font-size-base: [value];
+--sketch-radius: [value];
+--sketch-spacing: [value];
+--sketch-shadow: [value];
+```
+
+## Animation and Motion
+
+| Aspect | Value |
+|--------|-------|
+| Motion Philosophy | [minimal / moderate / expressive / scroll-driven narrative — overall approach] |
+| Key Animation Patterns | [e.g., "scroll-triggered cascading reveals", "hero entrance sequence", "hover micro-interactions only"] |
+| Animation Approach | [e.g., "GSAP with ScrollTrigger", "CSS transitions only", "Svelte transitions", "platform-native", "none"] |
+| Animation Role | [integral to direction identity / decorative enhancement / none] |
+
+[If the selected sketch had no animations: "Direction is static — no temporal effects. Motion philosophy to be determined during style exploration."]
+
+[If animations were present: brief description of the motion experience in platform-agnostic terms. Describe intent and characteristics (timing, easing, stagger), not implementation details. E.g., "Content reveals as if being declassified — each section cascades in with a 0.15s stagger triggered by scroll position. The overall effect is archival — slow, deliberate, authoritative."]
+
+## Screens Sketched
+
+| Screen | What It Shows |
+|--------|--------------|
+| [name] | [description of what this screen displays and its primary purpose] |
+
+## Screenshots
+
+| Screen | Path | Description |
+|--------|------|-------------|
+| [Screen Name] | [visual-grounding/designs/visual-sketch-screen-name.png] | [Brief description of what the screenshot shows] |
+
+[If no screenshots captured: "Screenshots not captured (Playwright unavailable). Style-explore will work from the direction description, characteristics, and CSS variables above."]
+
+## Iteration History
+
+| Round | Proposals | Selected | User Feedback |
+|-------|-----------|----------|---------------|
+| 1 | [N] proposals: [brief name for each] | Proposal [X] — [name] | [summary of user's choice rationale and feedback] |
+| 2 | [N] expansions of Proposal [X] | Expansion [Y] — [name] | [summary] |
+
+## Direction Brief (Selected)
+
+[Full text of the selected direction brief — the paragraph that the winning arn-spark-visual-sketcher agent received as its creative constraint. Preserved verbatim for downstream reference.]
+
+## Sketch Routes
+
+| Screen | Route |
+|--------|-------|
+| [name] | [/arness-sketches/round-N/proposal-N/path] |
+
+[If routes were removed during cleanup: "Sketch routes were removed from the project after direction capture. Screenshots above are the visual record."]
+
+## Relationship to Style Brief
+
+This document provides visual direction grounding for `/arn-spark-style-explore`. The style brief will translate these approximate values into:
+
+- Precise design tokens with exact hex/HSL values for all color roles
+- Complete typography table with font families, weights, sizes, and line heights
+- Spacing and sizing token scale
+- Component style specifications per component type
+- Toolkit-specific configuration (CSS framework config, component library theme)
+- Animation and motion philosophy
+
+The visual direction establishes *what the product should feel like*. The style brief specifies *exactly how to implement that feel*.
+```
+
+---
+
+## Section Guidance
+
+| Section | Source | Depth |
+|---------|--------|-------|
+| Selected Direction | User's final selection + skill's iteration summary | 2-3 sentences capturing the feel |
+| Tone & Creative Anchors | Tone commitment and differentiation anchor from the winning direction brief; Design Thinking from the selected sketch's layout component HTML comment block | Structured table with anchors + Design Thinking Q&A |
+| Direction Characteristics | Extracted from the selected sketch's direction brief | One-line descriptions per aspect |
+| Color Palette | From the selected sketch's CSS variables | Approximate hex values, major roles only |
+| CSS Variables | From the selected sketch's layout component | All `--sketch-*` variables verbatim |
+| Animation and Motion | From the selected sketch's animation code + proposal-manifest.json animation field | Motion philosophy, key patterns, library/approach, role (integral/decorative/none) |
+| Screens Sketched | From the confirmed screen list (Step 2) | Name and description per screen |
+| Screenshots | From `arn-spark-style-capture` output (Step 9) | Paths to files in visual grounding designs/ |
+| Iteration History | Accumulated during the selection loop | One row per round with selection rationale |
+| Direction Brief | The winning direction brief from Step 4 / Step 8 | Full paragraph, verbatim |
+| Sketch Routes | From the proposal-manifest.json of the selected sketch | Route paths, or cleanup note |