@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-stress-prfaq/references/prfaq-workflow.md

@@ -0,0 +1,118 @@
+# PR/FAQ Workflow
+
+Two-phase workflow for the Amazon PR/FAQ stress test method. This document is consumed by the `arn-spark-stress-prfaq` skill to orchestrate the marketing PM agent across draft and critique modes.
+
+## Overview
+
+The PR/FAQ method forces a product concept to pass two tests:
+
+1. **Can you tell a compelling story about this product?** If the press release is unconvincing, the product concept has messaging problems that likely trace to concept clarity problems.
+2. **Does the story hold up under scrutiny?** If adversarial questions expose crack points, the product concept has structural weaknesses that need addressing before architecture commitment.
+
+The two phases use **separate agent invocations** by design. Same-context self-critique tends toward rubber-stamping -- the critic unconsciously defends what the drafter wrote. Separate invocations force genuine adversarial evaluation.
+
+---
+
+## Phase 1: Draft Mode
+
+### Goal
+
+Produce a genuinely compelling press release and FAQ that represents the best possible public story of the product. The draft must be good enough that a real reader would want to try the product -- not a placeholder exercise with bracketed terms.
+
+### Agent Invocation
+
+Invoke the `arn-spark-marketing-pm` agent in **draft mode** 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:
+- Full product concept
+- Product pillars (to anchor messaging)
+- Operating mode: `draft`
+
+### Expected Output
+
+1. **Press Release (400-600 words)** following Amazon PR/FAQ format:
+   - Headline -- news-worthy, not a tagline
+   - Subheading -- who this is for and what it changes
+   - Problem paragraph -- specific, grounded in real scenarios
+   - Solution paragraph -- user experience focused, not technology focused
+   - Customer quote -- realistic, from a target persona, referencing a specific workflow scenario
+   - Product details paragraph -- features organized by value, not architecture
+   - Call to action -- specific next step
+
+2. **Customer FAQ (5-8 entries)** -- questions a potential customer would ask:
+   - Practical usage (how it works in their workflow)
+   - Pricing and access
+   - Migration and onboarding
+   - Data handling and privacy
+   - Integration with existing tools
+   - Scope boundaries framed as focus, not limitation
+
+3. **Internal FAQ (3-5 entries)** -- harder questions the team asks themselves:
+   - Why this will succeed where competitors failed
+   - Biggest technical risk
+   - Go-to-market strategy for first 1000 users
+   - Key assumption risk
+   - Success metrics for first 90 days
+
+### Quality Check
+
+Before proceeding to Phase 2, verify the draft is substantive:
+- Press release should be 400-600 words, not a skeleton
+- Customer FAQ answers should be concrete, not "it depends"
+- Internal FAQ questions should be genuinely hard, not softballs
+- Customer quote should sound like a real person, not a marketing team
+
+If the draft is too thin or generic, retry with more specific context from the product concept -- highlight specific features, personas, and competitive positioning to ground the draft.
+
+---
+
+## Phase 2: Critique Mode
+
+### Goal
+
+Adversarially evaluate the draft to find every place where the messaging makes a claim the product concept cannot fully support. The critique is not about copywriting quality -- it is about concept integrity.
+
+### Agent Invocation
+
+Invoke the `arn-spark-marketing-pm` agent in **critique mode** 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:
+- Full product concept (same as Phase 1)
+- Product pillars (same as Phase 1)
+- Operating mode: `critique`
+- Draft output from Phase 1 (complete press release + both FAQs)
+
+**Critical:** This MUST be a separate invocation from Phase 1. Do not pass Phase 1 context or conversation history. The critic has no memory of being the drafter.
+
+### Expected Output
+
+1. **Adversarial Questions (5-8)** -- questions the PR dodges:
+   - Each with: the question, why the PR dodges it, damage potential (High/Medium/Low)
+   - Focus on questions that expose concept weaknesses, not messaging weaknesses
+
+2. **Crack Points (3-5)** -- gaps between messaging claims and concept substance:
+   - What the concept claims (from the PR/FAQ)
+   - What the question reveals (the gap or contradiction)
+   - What needs strengthening (actionable recommendation for the concept, not the copy)
+
+3. **Recommended Concept Updates** -- standardized table derived from crack points
+
+4. **Unresolved Questions** -- questions the critique raised that need real data to answer
+
+### Quality Check
+
+Verify the critique is genuinely adversarial:
+- Adversarial questions should target concept substance, not word choice
+- Crack points should identify real gaps, not cosmetic issues
+- Damage potential ratings should be justified, not all "Medium"
+- Recommendations should change the product concept, not the press release
+
+If the critique is too soft, retry with explicit instruction: "The critique should make the product team uncomfortable. If no crack point makes someone say 'we need to address that before we build this,' the critique is too gentle."
+
+---
+
+## Rationale for Separate Invocations
+
+The two-mode architecture exists because of a well-documented cognitive bias: **consistency bias in self-evaluation.** When the same agent drafts and critiques in a single context:
+
+1. The critic has access to the drafter's reasoning and intent, making it harder to challenge assumptions that "obviously" made sense during drafting
+2. The critic unconsciously defends claims it just wrote, finding reasons they work rather than reasons they fail
+3. Questions tend to be answerable (because the critic already knows the answers) rather than genuinely probing
+
+Separate invocations break this pattern by forcing the critic to evaluate the draft as an outsider -- the same way a real journalist, competitor, or skeptical customer would encounter the messaging.

package/plugins/arn-spark/skills/arn-spark-style-explore/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: arn-spark-style-explore
+description: >-
+  This skill should be used when the user says "style explore", "arn style",
+  "visual style", "explore styles", "UI style", "look and feel",
+  "design direction", "pick a style", "choose colors", "theme the app",
+  "visual direction", "style guide", or wants to explore and define the visual
+  design direction for their project through guided conversation, producing a
+  style brief document with implementable toolkit configuration.
+version: 1.0.0
+---
+
+# Arness Style Explore
+
+Explore visual style direction for the project through iterative conversation, aided by the `arn-spark-ux-specialist` agent (a greenfield agent in this plugin) for design guidance, optionally the `arn-spark-style-capture` agent for capturing reference website screenshots, and optionally the `arn-spark-prototype-builder` agent for sample screens. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifact is a **style brief document** with implementable toolkit configuration.
+
+This skill covers the visual identity of the product: colors, typography, spacing, component customization, and animation approach. It translates these into concrete configuration for the project's CSS framework and component library. It does not create full application screens -- that is `/arn-spark-static-prototype` and `/arn-spark-clickable-prototype`'s job.
+
+## Prerequisites
+
+A product concept document should exist for context on target users and product personality. Check in order:
+
+1. Read the project's `arness.md` for a `## Arness` section. If found, 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
+
+**If a product concept is found:** Read it to inform style recommendations.
+
+**If no product concept is found:** Proceed with the user's description of the product. Style exploration does not hard-require a product concept.
+
+**Visual direction (recommended):**
+1. Check the configured Vision directory for `visual-direction.md`
+2. If no `## Arness` section found, check `.arness/vision/visual-direction.md` at the project root
+
+**If a visual direction is found:** Read it. The visual direction provides primary visual grounding from `/arn-spark-visual-sketch`: selected direction characteristics (color mood, typography feel, component style, layout density), approximate color palette with hex values, CSS variables used in the sketch, screenshot paths in the visual grounding `designs/` directory, **creative anchors** — tone commitment, differentiation anchor, and Design Thinking answers that capture the creative intent behind the direction, and **animation and motion context** — motion philosophy, key patterns, animation approach used, and whether animation is integral to the direction's identity. Use this as the starting point for style exploration rather than asking the user to describe a direction from scratch. The creative anchors are the direction's DNA — preserve them through token refinement rather than diluting them into generic defaults.
+
+**If no visual direction is found:** Proceed normally with the user's verbal description. Visual direction is optional -- style exploration works without it.
+
+The project should be scaffolded with a UI toolkit already configured (CSS framework and component library installed via `/arn-spark-scaffold`). Check:
+
+1. Read the project's `package.json` to identify installed CSS framework and component library
+2. Read the architecture vision for UI framework and toolkit choices
+
+**If the project is scaffolded:** Use the installed toolkit for style configuration.
+
+**If the project is NOT scaffolded:** Inform the user: "The project does not appear to be scaffolded yet. I can explore style direction conceptually, but the toolkit configuration section will be more useful after running `/arn-spark-scaffold`." Proceed with the exploration -- the style brief can be written without toolkit config and updated later.
+
+Determine the output directory:
+1. Read the project's `arness.md` and check for a `## Arness` section
+2. If found, extract the configured Vision 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 output directory does not exist, create it
+
+Determine the visual grounding directory:
+1. Read the project's `arness.md` `## Arness` section
+2. If found, extract the Visual grounding directory path
+3. If not found, fall back to `.arness/visual-grounding`
+4. Create the directory and subfolders (`references/`, `designs/`, `brand/`) if they do not exist
+
+Check for design tool integration:
+1. Read the `## Arness` section for `Figma` and `Canva` fields
+2. Only offer Figma/Canva integration in Step 1 if the corresponding field is `yes`
+3. If the field is `no` or missing, do not mention or attempt to use that design tool
+
+## Workflow
+
+### Step 1: Gather Context
+
+Load available context:
+
+- **Product concept:** Target users, core experience, product personality
+- **Architecture vision:** UI framework, platform (desktop, web, mobile)
+- **Scaffold results:** Installed CSS framework, component library, icon library
+- **Visual direction (if found):** Selected direction characteristics, approximate color palette, CSS variables used in the sketch, screenshot paths, creative anchors (tone commitment, differentiation anchor, Design Thinking), animation context (motion philosophy, key patterns, animation approach, role)
+
+Present the context to the user:
+
+**If a visual direction exists:**
+
+"Your project uses **[UI framework]** with **[CSS framework]** and **[component library]**. The product is [brief description from product concept, targeting audience].
+
+A visual direction was established via `/arn-spark-visual-sketch`. The selected direction is: [summary from visual-direction.md — overall feel, color mood, typography, layout approach]. The creative anchors are: **Tone:** [tone commitment], **Differentiation:** [differentiation anchor].
+
+[If screenshots exist:] Screenshots of the sketched screens are available at [paths].
+
+I will use this as the starting point for the style brief."
+
+Ask the user:
+
+> **How would you like to proceed with this visual direction?**
+> 1. **Proceed** — Build a style proposal based on this direction
+> 2. **Adjust** — Refine specific aspects before proceeding
+> 3. **Different direction** — Take it in a completely different direction
+
+**If no visual direction exists:**
+
+"Your project uses **[UI framework]** with **[CSS framework]** and **[component library]**. The product is [brief description from product concept, targeting audience].
+
+Adapt the context summary based on what was found. If the project is not scaffolded, omit toolkit details and present only what is known (e.g., product description and platform context).
+
+Describe the visual feel you want. You can:
+- **Use words:** minimal, dark, playful, professional, etc.
+- **Reference other apps:** 'I like how Linear looks' or 'something like Discord'
+- **Share URLs:** Paste a URL and I can capture a screenshot to analyze the design
+- **Share screenshots:** Paste or reference image files
+
+Some starting points if you are not sure:
+- **Minimal and clean** -- lots of whitespace, muted colors, thin borders
+- **Dark with neon accents** -- dark backgrounds, vibrant accent colors, tech feel
+- **Warm and approachable** -- rounded corners, warm colors, friendly tone
+- **Professional and dense** -- compact layout, neutral palette, data-focused
+
+Or describe your own direction."
+
+After the user describes their initial direction, ask about visual assets:
+
+Ask the user:
+
+**"Do you have any visual assets to guide the style direction?"**
+
+Options:
+1. **Reference images** — Screenshots or URLs of apps/sites you admire (inspirational)
+2. **Design mockups** — Figma, Canva, or exported screen designs (specification)
+3. **Brand assets** — Logos, brand guidelines, color specs (constraints)
+4. **None** — We will work from verbal descriptions
+
+**Handle each asset type:**
+
+| User has | Action |
+|----------|--------|
+| Reference URLs | Invoke `arn-spark-style-capture` → save to `[visual-grounding]/references/` |
+| Reference image files | User provides paths → copy to `[visual-grounding]/references/` |
+| Figma designs (Figma enabled in config) | Use Figma MCP to read selected designs, export screenshots → save to `[visual-grounding]/designs/` |
+| Figma designs (Figma not enabled) | Do not offer Figma integration. If user mentions Figma, suggest re-running `/arn-spark-init` to enable it. User can export as PNG/PDF manually → save to `[visual-grounding]/designs/` |
+| Canva designs (Canva enabled in config) | Use Canva MCP to export designs → save to `[visual-grounding]/designs/` |
+| Canva designs (Canva not enabled) | Same as Figma — suggest re-running init or manual export → save to `[visual-grounding]/designs/` |
+| Hand-drawn wireframes | User provides photos → save to `[visual-grounding]/designs/` |
+| Brand assets (logos, guidelines) | User provides files → save to `[visual-grounding]/brand/` |
+
+**If the user provides one or more URLs:** 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), with the URLs and save screenshots to the visual grounding directory (under `references/`). If the agent reports Playwright is not available, inform the user:
+
+"Playwright is not installed in this environment, so I cannot automatically capture that URL. You can either:
+1. Install Playwright (`npm install -D playwright && npx playwright install chromium`) and try again
+2. Take a screenshot yourself and share it
+3. Describe what you like about the referenced site and I will work from that"
+
+If capture succeeds, use the agent's extracted design characteristics (colors, typography, layout, spacing) as input to the `arn-spark-ux-specialist` alongside the user's verbal description.
+
+### Step 2: Initial Style Proposal
+
+Invoke the `arn-spark-ux-specialist` agent (greenfield 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:
+
+- The user's style description or preferences
+- Product concept context (target users, product personality)
+- UI toolkit context (CSS framework, component library)
+- Platform context (desktop app, web app, mobile)
+- **Visual direction context (if found):** Include the visual direction's characteristics, approximate color palette, CSS variables, screenshot paths, and creative anchors (tone commitment, differentiation anchor, Design Thinking answers). Instruct the specialist: "A visual direction has been established via /arn-spark-visual-sketch. Use it as the primary input for the style proposal. The screenshots show the selected visual approach applied to real product screens. The tone commitment is '[tone]' and the differentiation anchor is '[differentiation]' — these are the creative DNA of the direction. Translate the direction into precise design tokens while preserving its character. Every token decision should support the tone commitment and keep the differentiation anchor intact. Do not flatten distinctive choices into generic defaults during refinement."
+- **Visual direction animation context (if found):** If the visual direction includes an Animation & Motion section, pass it to the specialist: "The visual direction includes animation context: [motion philosophy], with key patterns [patterns], using [animation approach]. Animation is [integral/decorative/none] to the direction. Build the style brief's Animation and Motion section grounded in these choices — do not reinvent the motion approach from scratch. Describe animation in platform-agnostic intent language."
+- **All available visual grounding assets.** Provide images from all three subfolders with category context so the specialist knows the intent:
+  - **References** (`[visual-grounding]/references/`): "These reference images are inspirational direction — they inform the overall feel but are not pixel-level targets."
+  - **Designs** (`[visual-grounding]/designs/`): "These design mockups are specification targets — match them for layout, spacing, and proportions where applicable."
+  - **Brand** (`[visual-grounding]/brand/`): "These brand assets are fixed constraints — logos, colors, and typefaces must be incorporated as-is."
+
+Visual references provide nuances that text descriptions alone cannot convey — the UX specialist should see the actual images alongside the extracted design characteristics.
+
+Request that the agent provide recommendations covering: color palette (with hex values for all roles), typography (specific font families and sizes), spacing and sizing tokens, border radius values, component style characteristics, and animation approach. These map directly to the style brief template sections.
+
+The agent returns design recommendations:
+
+- Color palette with specific values
+- Typography recommendations
+- Spacing and sizing tokens
+- Component customization approach for the chosen library
+- Animation and motion philosophy
+
+Present the proposal to the user. Frame it as a starting point:
+
+"Here is an initial style direction based on your description:
+
+**Colors:** [Brief summary with primary, background, and accent colors]
+**Typography:** [Font families and general sizing]
+**Components:** [Overall feel -- rounded, sharp, shadows, borders]
+**Animation:** [Approach -- minimal, moderate, expressive]
+
+What do you think? We can adjust colors, change the overall feel, or try a completely different direction."
+
+### Step 3: Iterative Refinement
+
+Enter a conversation loop. The user may want to:
+
+| User Request | Action |
+|-------------|--------|
+| "Make it darker" / "warmer" / "more playful" | Re-invoke `arn-spark-ux-specialist` with adjusted direction |
+| "I like the colors but change the typography" | Re-invoke `arn-spark-ux-specialist` with partial update request |
+| "Show me what it looks like" | Invoke `arn-spark-prototype-builder` to create 1-2 sample screens |
+| "Compare two directions" | Invoke `arn-spark-ux-specialist` for both, present side-by-side |
+| "Use [specific color/font]" | Record directly, adjust the proposal |
+| "What would [reference app] style look like?" | Invoke `arn-spark-ux-specialist` with the reference for interpretation |
+| User provides a URL to reference | Invoke `arn-spark-style-capture` with the URL, save to `[visual-grounding]/references/`. Feed results to `arn-spark-ux-specialist`. |
+| User provides multiple URLs to compare | Invoke `arn-spark-style-capture` with all URLs, save to `[visual-grounding]/references/`. Present the comparison and feed results to `arn-spark-ux-specialist`. |
+| User provides design mockups (Figma/Canva/manual) | Save to `[visual-grounding]/designs/`. Feed to `arn-spark-ux-specialist` as specification targets. |
+| User provides brand assets | Save to `[visual-grounding]/brand/`. Feed to `arn-spark-ux-specialist` as fixed constraints. |
+| User is happy with the direction | Proceed to Step 4 |
+
+**Sample screens (optional):** If the user wants to see the style applied, invoke the `arn-spark-prototype-builder` agent to create 1-2 representative screens (e.g., the main screen and a settings screen). These use the actual component library with the proposed style configuration. If visual grounding assets are available, include them so the builder can visually match the intended direction — especially design mockups (specification targets) and brand assets (fixed constraints).
+
+**Readiness check:** When the style direction seems settled:
+
+"I think we have a solid visual direction. Here is a summary:
+
+**Primary:** [color] | **Background:** [color] | **Accent:** [color]
+**Font:** [family] | **Corners:** [radius] | **Animation:** [approach]
+
+Ask the user:
+
+> **Ready to write the style brief?**
+> 1. **Yes, write it** — Generate the style brief document
+> 2. **Keep adjusting** — I want to refine more before writing"
+
+### Step 4: Write the Style Brief
+
+When the user is ready:
+
+1. Read the template:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-style-explore/references/style-brief-template.md`
+
+2. Populate the template with all decisions from the conversation:
+   - Specific color values (hex/HSL) for all palette roles
+   - Typography with actual font families and sizes
+   - Spacing and sizing tokens
+   - Component style characteristics
+   - Animation approach and specific animations if discussed
+   - **Toolkit Configuration section:** Translate all design tokens into the project's CSS framework config (e.g., Tailwind theme extensions) and component library theme (e.g., shadcn CSS custom properties)
+
+3. Write the document to the output directory as `style-brief.md`
+
+4. Present a summary:
+   - Document path
+   - Color palette overview
+   - Font choices
+   - Note whether toolkit configuration was included or deferred
+
+### Step 5: Recommend Next Steps
+
+"Style brief saved to `[path]/style-brief.md`.
+
+Recommended next steps:
+1. **Build static prototype:** Run `/arn-spark-static-prototype` to validate visual fidelity with component showcases
+2. **Apply toolkit config:** The style brief includes [CSS framework] and [component library] configuration that will be applied during prototyping
+
+The prototype will use the style brief to ensure all screens share a consistent visual language."
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| User provides reference URL(s) (Step 1 or Step 3) | Invoke `arn-spark-style-capture` with URLs, save to `[visual-grounding]/references/`. If Playwright unavailable, fall back to user-provided screenshots or verbal description. |
+| User provides design mockups or brand assets | Save to `[visual-grounding]/designs/` or `[visual-grounding]/brand/` respectively. For Figma/Canva exports, use the MCP only if the corresponding flag is `yes` in `## Arness` config. |
+| Initial style proposal (Step 2) | Invoke `arn-spark-ux-specialist` with user's direction + product context + toolkit context + ALL visual grounding assets (with category context: references=inspirational, designs=specification, brand=constraints) |
+| User wants style adjustments | Invoke `arn-spark-ux-specialist` with updated direction + all visual grounding assets. Always provide images alongside text when they exist — visual nuances matter. |
+| User wants to see sample screens | Invoke `arn-spark-prototype-builder` with: screen list (1-2 screens), navigation flow (minimal), style brief (current direction), UI framework + component library, project root path, and visual grounding assets (especially design mockups and brand assets) |
+| User asks which CSS framework to use | Defer: "CSS framework is chosen during `/arn-spark-scaffold`. If you want to change it, re-run scaffold." |
+| User asks about specific component APIs | Defer: "Component implementation details come during feature development. The style brief defines how components should look." |
+| User asks about features or architecture | Defer to the appropriate skill |
+
+## Error Handling
+
+- **No product concept found:** Proceed with the user's verbal description. The style can be explored without a formal product concept.
+- **Project not scaffolded:** Explore style conceptually. Write the style brief without the Toolkit Configuration section, note it for later.
+- **UX specialist returns unhelpful response:** Summarize the issue and continue the conversation directly. Try a more specific request on the next invocation.
+- **User cannot describe a style direction:** Offer the curated archetypes from Step 1. If still stuck, ask: "What apps do you use and enjoy the look of?" and use those as reference points.
+- **Writing the document fails:** Print the full content in the conversation so the user can copy it.
+- **Style brief already exists:**
+
+  Ask the user:
+
+  > **A style brief already exists at `[path]`. How would you like to proceed?**
+  > 1. **Replace** — Start fresh with a new style brief
+  > 2. **Update** — Update specific sections of the existing brief
+- **Sample screen build fails:** Note the issue, continue with the style exploration. The prototype build is optional during style exploration.
+- **Playwright not available for URL capture:** Inform the user and offer alternatives: install Playwright, provide manual screenshots, or describe the reference verbally. Do not block the style exploration -- URL capture is optional.
+- **URL capture fails (timeout, auth wall):** Report which URL failed. Ask the user to provide a manual screenshot or describe what they like about the site. Continue with the exploration.

package/plugins/arn-spark/skills/arn-spark-style-explore/references/style-brief-template.md

@@ -0,0 +1,198 @@
+# Style Brief Template
+
+This template defines the structure for visual style documents written by the `arn-spark-style-explore` skill. The document is saved to the project's vision directory as `style-brief.md`.
+
+A style brief captures the visual design direction for the project: colors, typography, spacing, component customization, and toolkit-specific configuration. It serves as the visual contract between design decisions and implementation, ensuring the prototype and production code share the same visual language.
+
+## Instructions for arn-spark-style-explore
+
+When populating this template:
+
+- Replace all bracketed placeholders with concrete values from the style exploration conversation
+- Color values must be specific (hex, HSL, or RGB) -- not vague descriptions like "blue"
+- Typography must specify actual font families, not categories like "sans-serif"
+- The Toolkit Configuration section is critical -- it translates the design into implementable code
+- If using a component library (shadcn, Skeleton UI, etc.), include the library-specific theme configuration
+- Dark/light mode: specify both palettes if the project supports both, or note that only one mode is in scope for v1
+- Visual grounding assets (references, designs, brand) are optional but helpful for communicating intent and enabling downstream fidelity comparison
+
+---
+
+## Template
+
+```markdown
+# [Product Name] - Style Brief
+
+## Design Direction
+
+[2-3 sentences describing the overall visual feel. Reference the target audience and product personality from the product concept. E.g., "Warm and approachable, reflecting a tool used between family members and close friends. Clean but not clinical -- soft edges, gentle shadows, and a color palette that feels inviting rather than corporate."]
+
+## Color Palette
+
+### Primary Colors
+
+| Role | Color | Hex | Usage |
+|------|-------|-----|-------|
+| Primary | [Name] | [#hex] | [Primary actions, key UI elements] |
+| Primary Hover | [Name] | [#hex] | [Hover/active state for primary] |
+| Primary Foreground | [Name] | [#hex] | [Text on primary background] |
+
+### Neutral Colors
+
+| Role | Color | Hex | Usage |
+|------|-------|-----|-------|
+| Background | [Name] | [#hex] | [Page background] |
+| Surface | [Name] | [#hex] | [Card/panel backgrounds] |
+| Border | [Name] | [#hex] | [Borders, dividers] |
+| Text Primary | [Name] | [#hex] | [Main body text] |
+| Text Secondary | [Name] | [#hex] | [Secondary/muted text] |
+| Text Disabled | [Name] | [#hex] | [Disabled state text] |
+
+### Semantic Colors
+
+| Role | Color | Hex | Usage |
+|------|-------|-----|-------|
+| Success | [Name] | [#hex] | [Connected, active, confirmed] |
+| Warning | [Name] | [#hex] | [Attention needed, degraded state] |
+| Error | [Name] | [#hex] | [Disconnected, failed, destructive] |
+| Info | [Name] | [#hex] | [Informational, neutral status] |
+
+### Dark Mode (if applicable)
+
+[If dark mode is in scope: provide the equivalent palette for dark mode. If not: note "Dark mode deferred to post-v1."]
+
+## Typography
+
+| Role | Font Family | Weight | Size | Line Height |
+|------|-------------|--------|------|-------------|
+| Heading 1 | [Family] | [Weight] | [Size] | [Line height] |
+| Heading 2 | [Family] | [Weight] | [Size] | [Line height] |
+| Heading 3 | [Family] | [Weight] | [Size] | [Line height] |
+| Body | [Family] | [Weight] | [Size] | [Line height] |
+| Body Small | [Family] | [Weight] | [Size] | [Line height] |
+| Caption | [Family] | [Weight] | [Size] | [Line height] |
+| Monospace | [Family] | [Weight] | [Size] | [Line height] |
+
+**Font loading:** [How fonts are loaded -- Google Fonts, local files, system fonts, etc.]
+
+## Spacing and Sizing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| spacing-xs | [value] | [Tight gaps, icon padding] |
+| spacing-sm | [value] | [Inner padding, form gaps] |
+| spacing-md | [value] | [Section padding, card padding] |
+| spacing-lg | [value] | [Section margins, major gaps] |
+| spacing-xl | [value] | [Page margins, hero spacing] |
+
+### Border Radius
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| radius-sm | [value] | [Badges, small elements] |
+| radius-md | [value] | [Buttons, inputs, cards] |
+| radius-lg | [value] | [Modals, large containers] |
+| radius-full | 9999px | [Avatars, circular elements] |
+
+## Component Style
+
+### General Characteristics
+
+- **Edges:** [Rounded / Sharp / Mixed -- describe the approach]
+- **Shadows:** [None / Subtle / Prominent -- describe the approach and when shadows are used]
+- **Borders:** [Visible / Minimal / None -- describe when borders appear]
+- **Density:** [Compact / Comfortable / Spacious -- describe the information density]
+
+### Buttons
+
+- **Primary:** [Description: fill color, text color, hover behavior, border radius]
+- **Secondary:** [Description: outline/ghost style, hover behavior]
+- **Destructive:** [Description: color treatment for destructive actions]
+- **Disabled:** [Description: opacity, cursor, color changes]
+
+### Inputs
+
+- **Default:** [Description: border style, background, focus ring, placeholder color]
+- **Focus:** [Description: ring color, border change, animation]
+- **Error:** [Description: border color, helper text color]
+
+### Cards / Panels
+
+- **Background:** [Surface color, border, shadow, radius]
+- **Hover:** [If interactive: hover effect description]
+
+## Animation and Motion
+
+- **Approach:** [Minimal / Moderate / Expressive -- describe the philosophy]
+- **Transitions:** [Duration and easing for standard transitions, e.g., "150ms ease-out for hover, 200ms ease-in-out for layout changes"]
+- **Specific animations:** [List any product-specific animations, e.g., "Pulse animation on incoming knock", "Fade-in for new device discovery"]
+
+## Toolkit Configuration
+
+This section translates the design decisions above into implementable configuration for the project's specific CSS framework and component library.
+
+### [CSS Framework] Configuration
+
+[E.g., "Tailwind CSS Configuration" -- provide the actual config values]
+
+```[language]
+// [config file name, e.g., tailwind.config.js theme extend section]
+[Actual configuration code that implements the color palette, typography, spacing, and border radius defined above]
+```
+
+### [Component Library] Theme
+
+[E.g., "shadcn-svelte Theme Variables" -- provide the actual CSS custom properties or theme config]
+
+```css
+/* [Description of where these variables live, e.g., app.css :root block] */
+[Actual CSS custom properties or theme configuration that customizes the component library]
+```
+
+### Global CSS
+
+```css
+/* Base styles applied globally */
+[Any global CSS needed: font imports, base resets, custom utility classes]
+```
+
+## Visual Grounding
+
+### References
+[Inspirational images that informed the style direction. These guide the overall feel but are not pixel-level targets.]
+
+| Source | Path | What it informs |
+|--------|------|-----------------|
+| [URL or description] | [visual-grounding/references/filename.png] | [colors / layout / feel] |
+
+### Designs
+[Design mockups that serve as specification targets. These are the ground truth for visual fidelity.]
+
+| Source | Path | Screens covered |
+|--------|------|----------------|
+| [Figma / Canva / hand-drawn] | [visual-grounding/designs/filename.png] | [which screens or components] |
+
+### Brand
+[Fixed brand assets that must be incorporated.]
+
+| Asset | Path | Constraint |
+|-------|------|-----------|
+| [Logo / color spec / typeface] | [visual-grounding/brand/filename.png] | [how it constrains the design] |
+
+[If no visual grounding assets were provided, note: "No visual grounding assets. Style derived from verbal description only."]
+```
+
+---
+
+## Section Guidance
+
+| Section | Source | Depth |
+|---------|--------|-------|
+| Design Direction | User's description + UX specialist analysis | 2-3 sentences capturing the feel |
+| Color Palette | UX specialist recommendation + user refinement | Exact values, all roles covered |
+| Typography | UX specialist recommendation + user refinement | Exact values for all text roles |
+| Spacing and Sizing | UX specialist recommendation | Token table with concrete values |
+| Component Style | UX specialist recommendation + user preferences | Descriptive characteristics per component type |
+| Animation and Motion | User preferences + UX specialist guidance | Philosophy + specific animations |
+| Toolkit Configuration | Translated from design tokens by skill | Actual code that can be copy-pasted into config files |
+| Visual Grounding | User-provided + MCP exports + URL captures | Three categories: references (inspirational), designs (specification), brand (constraints). Paths to files in visual grounding directory. |