# Spark Design Prompt Recipes

These prompts are for AI coding agents that need to build with Spark Design
without flattening the system into generic UI. They assume the agent can inspect
files, run commands, and edit code.

Showcase companion: `#/agent-prompt-recipes`.

## How To Use

1. Pick the recipe closest to the task.
2. Paste it into the agent with the product-specific requirements.
3. Keep the hard rules intact.
4. Ask the agent to report which Spark surfaces it verified.

## Universal Spark Contract

Add this block to any prompt when quality matters:

```text
Use Spark Design as a system, not as loose components.

Before implementation:
- Read registry/agent-manifest.json and choose components by intent, states,
  accessibility, composition, and antiPatterns.
- Read registry/tokens/ontology.json before writing styles.
- Prefer npx sparkdesign@latest add <component> for business apps that should
  own copied source.
- Use package imports only if the app already consumes sparkdesign as a runtime.

Hard rules:
- Do not invent duplicate components when Spark already covers the intent.
- Do not hard-code hex colors, raw rgba overlays, arbitrary radii, or one-off
  spacing in published UI.
- Preserve data-theme for color and data-style for layout density/radius/rhythm.
- Keep portal UI consistent with the active theme/style.
- For AI workflows, prefer chat components such as ChatInput, Response,
  ToolInvocationCard, PermissionCard, ReasoningStep, TaskPart, PlanPart,
  FileReviewPart, and RelatedPrompts instead of plain cards and Markdown.

Before handoff:
- Run the narrow checks that prove the changed surfaces.
- Report changed files, validation commands, and any remaining risk.
```

## Recipe 1: Install Spark In A New App

```text
Set up Spark Design in this React app.

Requirements:
- Determine whether this project should use CLI copied source or package imports.
- Prefer CLI copied source unless the project already uses sparkdesign as a
  runtime dependency or I explicitly ask for package mode.
- If using CLI mode, run npx sparkdesign@latest init and add only the components
  needed for the screen.
- Configure Tailwind CSS 4 correctly, including @tailwindcss/vite and @source
  for copied Spark components.
- Set data-theme and data-style on the root or document element.
- Verify dark mode and at least one portal component if the screen uses overlays.

Do not mix CLI copied-source imports with package imports.
Do not leave Vite starter CSS fighting Spark tokens.
```

## Recipe 2: Select Components For A Product Screen

```text
Design and implement this product screen using Spark Design.

Task:
[Describe the screen, users, data density, and primary workflow.]

Process:
1. Read registry/agent-manifest.json.
2. List the Spark components selected by intent and explain why each one fits.
3. Check antiPatterns for every selected component before composing the screen.
4. Read registry/tokens/ontology.json and choose token families before styling.
5. Implement the screen with tokenized classes and existing Spark primitives.
6. Keep workflows efficient: use icons for tools, segmented controls for modes,
   toggles for binary settings, and menus for option sets.

Verification:
- No duplicate local component that Spark already provides.
- No hard-coded hex/rgb, arbitrary radii, or arbitrary spacing unless explained.
- Text fits on desktop and mobile.
- Keyboard/focus behavior remains intact for controls and overlays.
```

## Recipe 3: Build An AI Workflow

```text
Build this AI workflow with Spark Design chat components.

Workflow:
[Describe prompt entry, tool calls, files, approvals, reasoning, generated
content, error handling, and follow-up prompts.]

Use Spark chat components where they match intent:
- ChatInput for prompt composition and attachments.
- Response or Markdown for generated answers.
- ToolInvocationCard for tool execution visibility.
- PermissionCard or AskUserPart for approval/confirmation.
- ReasoningStep, PlanPart, TaskPart, or BrowserActionPart for structured agent
  progress.
- FileCard, FileAttachment, FileReviewPart, and GeneratedImagesGrid for files.
- RelatedPrompts for next actions.

Do not flatten tool calls, approvals, or reasoning into plain Markdown.
Expose state clearly: pending, streaming, success, blocked, skipped, failed.
```

## Recipe 4: Add Or Change A Component

```text
Add or change this Spark component while keeping the system isomorphic.

Component intent:
[Describe what user problem the component solves and what it should not solve.]

Required sequence:
1. Search existing registry/basic, registry/chat, and registry/agent-manifest.json
   to confirm this component is not a duplicate.
2. Implement source of truth in registry/.
3. Keep dependencies public and copy-safe for CLI users.
4. Export component and prop types through src/components/.
5. Regenerate or validate registry/meta.json and sync cli/registry if needed.
6. Add showcase demo blocks with production-like examples and matching snippets.
7. Add props metadata and localized labels.
8. Update registry/agent-manifest.json with intent, slots, states, a11y,
   composition, antiPatterns, and agentHints.
9. Update P3 headers and P2 AGENTS.md maps.
10. Run component, registry, showcase, token, and manifest checks.

Do not call the component complete until registry, CLI, package exports,
showcase, docs, and agent manifest agree.
```

## Recipe 5: Audit A Spark Change

```text
Review this Spark Design change as a maintainer.

Prioritize:
- Behavioral bugs and regressions.
- Drift between registry, CLI, package exports, showcase, docs, and manifest.
- Token misuse: hard-coded colors, raw rgba, arbitrary spacing/radius, theme
  inheritance failures, and one-off visual language.
- Accessibility gaps: labels, roles, focus states, keyboard behavior, status
  text, and color-only meaning.
- Showcase quality: examples should teach real usage and snippets should compile.
- AI friendliness: manifest intent and antiPatterns should prevent bad agent
  choices.

Return findings first with file/line references, then open questions, then a
short verification summary.
```

## Maintainer Checklist

- Prompt picked the correct consumption path: CLI copied source or package import.
- Prompt forced manifest and ontology reads before implementation.
- Prompt preserved theme/style axes and portal inheritance.
- Prompt required showcase and docs updates when public behavior changed.
- Prompt required agent manifest updates for new or changed components.
- Prompt kept AI-facing docs package-visible when guidance changed.
- Prompt included concrete verification commands and evidence.