sparkdesign 0.4.6 → 0.4.7

package/cli/registry/agent-manifest.json

@@ -0,0 +1,794 @@
+{
+  "schemaVersion": "0.1.0",
+  "library": {
+    "name": "sparkdesign",
+    "versionSource": "package.json",
+    "agentContract": "Use this manifest to choose components by intent, constraints, and composition rules before reading source code.",
+    "defaultConsumption": "cli",
+    "consumptionModes": {
+      "cli": {
+        "when": "Business applications that should own and customize copied component source.",
+        "init": "npx sparkdesign@latest init",
+        "add": "npx sparkdesign@latest add <component>"
+      },
+      "package": {
+        "when": "Fast prototypes, showcase usage, or projects that explicitly install the package runtime.",
+        "install": "npm install sparkdesign",
+        "styleImport": "import 'sparkdesign/style'"
+      }
+    }
+  },
+  "globalRules": [
+    "Prefer existing Spark components over creating visually similar one-off UI.",
+    "Use design tokens and semantic utility classes; do not hard-code hex colors, ad-hoc radii, or arbitrary shadows in product UI.",
+    "For portaled UI, preserve data-theme and data-style inheritance through ThemeStyleProvider or component wrappers.",
+    "Choose chat components only for conversational, agentic, tool, file, or reasoning flows; use basic components for product UI primitives.",
+    "Read antiPatterns before composing a component into a generated screen."
+  ],
+  "tokenRules": {
+    "color": {
+      "preferred": [
+        "text-text",
+        "text-text-secondary",
+        "text-text-tertiary",
+        "bg-bg-base",
+        "bg-bg-elevated",
+        "bg-fill-secondary",
+        "border-border",
+        "bg-primary",
+        "text-primary-foreground"
+      ],
+      "forbidden": [
+        "hard-coded hex colors",
+        "raw rgb/rgba values unless binding to a tokenized CSS variable",
+        "semantic misuse such as destructive colors for neutral emphasis"
+      ]
+    },
+    "spacing": {
+      "preferred": [
+        "gap-*",
+        "p-*",
+        "px-*",
+        "py-*",
+        "var(--spacing-*)"
+      ],
+      "forbidden": [
+        "pixel-perfect arbitrary spacing without a component-specific reason",
+        "layout rhythm that changes across sibling components"
+      ]
+    },
+    "motion": {
+      "preferred": [
+        "short functional transitions for feedback",
+        "Framer Motion only when state transition clarity improves"
+      ],
+      "forbidden": [
+        "decorative motion that delays task completion",
+        "motion without reduced-motion consideration for complex scenes"
+      ]
+    }
+  },
+  "components": {
+    "alert": {
+      "id": "alert",
+      "name": "Alert",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Inline callout for contextual status, warnings, or explanatory feedback inside page flow.",
+      "packageImport": "import { Alert, AlertTitle, AlertDescription } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add alert",
+      "slots": [
+        "Alert",
+        "AlertTitle",
+        "AlertDescription",
+        "leading icon"
+      ],
+      "states": [
+        "default",
+        "info",
+        "success",
+        "warning",
+        "destructive"
+      ],
+      "a11y": [
+        "Use semantic text content, not icon-only alerts.",
+        "Use destructive only for high-impact errors or irreversible risk.",
+        "Keep title and description concise so screen reader output stays useful."
+      ],
+      "composition": [
+        "Card",
+        "Form",
+        "PermissionCard",
+        "ChatInput"
+      ],
+      "antiPatterns": [
+        "Do not use Alert as a toast replacement for transient feedback.",
+        "Do not stack multiple alerts when one grouped message is clearer."
+      ],
+      "agentHints": [
+        "Choose Alert when the message belongs in the layout and should remain visible.",
+        "Prefer Toast for ephemeral success notifications."
+      ]
+    },
+    "button": {
+      "id": "button",
+      "name": "Button",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Primary, secondary, ghost, or destructive action trigger with tokenized sizing and interaction states.",
+      "packageImport": "import { Button } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add button",
+      "slots": [
+        "label",
+        "leading icon",
+        "trailing icon"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible",
+        "disabled",
+        "loading by composition"
+      ],
+      "a11y": [
+        "Use a visible label or aria-label for icon-only actions.",
+        "Keep destructive actions visually and semantically explicit.",
+        "Do not disable without preserving an explanation nearby when the reason is unclear."
+      ],
+      "composition": [
+        "DialogTrigger",
+        "DropdownMenuTrigger",
+        "Tooltip",
+        "ChatInputActions",
+        "PermissionCard"
+      ],
+      "antiPatterns": [
+        "Do not use links styled as buttons for navigation unless the semantic element remains an anchor.",
+        "Do not place multiple primary buttons in the same decision group."
+      ],
+      "agentHints": [
+        "Use one primary action per surface.",
+        "Pair dangerous actions with AlertDialog or PermissionCard."
+      ]
+    },
+    "card": {
+      "id": "card",
+      "name": "Card",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Bounded surface for grouped content, settings, forms, summaries, or preview blocks.",
+      "packageImport": "import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add card",
+      "slots": [
+        "Card",
+        "CardHeader",
+        "CardTitle",
+        "CardDescription",
+        "CardAction",
+        "CardContent",
+        "CardFooter"
+      ],
+      "states": [
+        "static",
+        "interactive by composition",
+        "empty",
+        "loading by composition"
+      ],
+      "a11y": [
+        "Use heading hierarchy intentionally inside CardTitle.",
+        "Avoid making the full card clickable when nested controls exist.",
+        "Keep focus order aligned with visual order."
+      ],
+      "composition": [
+        "Button",
+        "Alert",
+        "Input",
+        "Textarea",
+        "Skeleton",
+        "Badge"
+      ],
+      "antiPatterns": [
+        "Do not use Card only to add decoration around unrelated content.",
+        "Do not nest cards more than one level deep unless the information architecture requires it."
+      ],
+      "agentHints": [
+        "Use Card to create scan-friendly groups, not as the default wrapper for every element."
+      ]
+    },
+    "chat-input": {
+      "id": "chat-input",
+      "name": "ChatInput",
+      "category": "chat",
+      "status": "stable",
+      "intent": "Agent prompt composer with attachments, actions, model/status affordances, and send behavior.",
+      "packageImport": "import { ChatInput } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add chat-input",
+      "slots": [
+        "ChatInputRoot",
+        "ChatInputAbove",
+        "ChatInputBox",
+        "ChatInputAttachments",
+        "ChatInputInput",
+        "ChatInputActions",
+        "ChatInputActionsLeft",
+        "ChatInputActionsRight",
+        "ChatInputSendButton",
+        "ChatInputFooterLeft"
+      ],
+      "states": [
+        "idle",
+        "focused",
+        "composing",
+        "disabled",
+        "streaming",
+        "attachments-present",
+        "permission-required"
+      ],
+      "a11y": [
+        "Preserve textarea semantics and keyboard submission behavior.",
+        "Keep send action reachable by keyboard.",
+        "Expose attachment removal with accessible labels.",
+        "Do not hide status text from assistive technology when it communicates task state."
+      ],
+      "composition": [
+        "SendButton",
+        "FileAttachment",
+        "ImageAttachment",
+        "GenerationStatusBar",
+        "PermissionCard",
+        "Tooltip"
+      ],
+      "antiPatterns": [
+        "Do not use ChatInput as a generic form textarea.",
+        "Do not hard-code model labels or footer actions into the component when they are product state.",
+        "Do not place unrelated navigation controls inside ChatInputActions."
+      ],
+      "agentHints": [
+        "Choose ChatInput for conversational or agent command entry.",
+        "Use the compound API when the generated layout needs custom action placement."
+      ]
+    },
+    "dialog": {
+      "id": "dialog",
+      "name": "Dialog",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Focused modal surface for short tasks, confirmations, or contextual forms that block background interaction.",
+      "packageImport": "import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add dialog",
+      "slots": [
+        "Dialog",
+        "DialogTrigger",
+        "DialogPortal",
+        "DialogOverlay",
+        "DialogContent",
+        "DialogHeader",
+        "DialogFooter",
+        "DialogTitle",
+        "DialogDescription",
+        "DialogClose"
+      ],
+      "states": [
+        "open",
+        "closed",
+        "focus-trapped",
+        "dismissible",
+        "non-dismissible by composition"
+      ],
+      "a11y": [
+        "Provide DialogTitle for every DialogContent.",
+        "Use DialogDescription when title alone does not explain the task.",
+        "Keep keyboard focus trapped while open.",
+        "Return focus to the trigger after close."
+      ],
+      "composition": [
+        "Button",
+        "Input",
+        "Textarea",
+        "Alert",
+        "Card"
+      ],
+      "antiPatterns": [
+        "Do not use Dialog for long multi-step workflows that need persistent navigation.",
+        "Do not nest Dialog inside Dialog unless no simpler flow exists.",
+        "Do not use Dialog for passive information that can live inline."
+      ],
+      "agentHints": [
+        "Choose Dialog when the user must complete or dismiss a focused task before continuing.",
+        "Use AlertDialog for destructive confirmation flows."
+      ]
+    },
+    "drawer": {
+      "id": "drawer",
+      "name": "Drawer",
+      "category": "basic",
+      "status": "stable",
+      "intent": "Side sheet for contextual settings, details, filters, or secondary tasks that should preserve the underlying page context.",
+      "packageImport": "import { Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add drawer",
+      "slots": [
+        "Drawer",
+        "DrawerTrigger",
+        "DrawerPortal",
+        "DrawerOverlay",
+        "DrawerContent",
+        "DrawerHeader",
+        "DrawerFooter",
+        "DrawerTitle",
+        "DrawerDescription",
+        "DrawerClose"
+      ],
+      "states": [
+        "open",
+        "closed",
+        "focus-trapped",
+        "dismissible",
+        "side-top",
+        "side-right",
+        "side-bottom",
+        "side-left"
+      ],
+      "a11y": [
+        "Provide DrawerTitle for every DrawerContent.",
+        "Use DrawerDescription when the title does not fully explain the task.",
+        "Keep keyboard focus inside the drawer while open.",
+        "Return focus to the trigger after close."
+      ],
+      "composition": [
+        "Button",
+        "Card",
+        "Alert",
+        "ChatInput",
+        "PermissionCard"
+      ],
+      "antiPatterns": [
+        "Do not use Drawer for destructive confirmations that require explicit acknowledgement; use AlertDialog.",
+        "Do not use Drawer for primary app navigation unless the product pattern explicitly calls for a side panel.",
+        "Do not place long multi-page workflows in a drawer."
+      ],
+      "agentHints": [
+        "Choose Drawer when the user should keep page context while editing settings or inspecting details.",
+        "Prefer side=right for settings and details; use bottom mainly for compact/mobile task surfaces."
+      ]
+    },
+    "file-review-part": {
+      "id": "file-review-part",
+      "name": "FileReviewPart",
+      "category": "chat",
+      "status": "stable",
+      "intent": "Structured review surface for files changed, inspected, or proposed by an agent.",
+      "packageImport": "import { FileReviewPart } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add file-review-part",
+      "slots": [
+        "summary",
+        "file list",
+        "file icon",
+        "status",
+        "approve action",
+        "request changes action"
+      ],
+      "states": [
+        "pending",
+        "approved",
+        "changes-requested",
+        "expanded",
+        "collapsed",
+        "empty"
+      ],
+      "a11y": [
+        "Expose file names as readable text, not only icons.",
+        "Keep approval and request-changes actions keyboard reachable.",
+        "Do not rely on file icon color as the only file type signal."
+      ],
+      "composition": [
+        "Response",
+        "ToolInvocationCard",
+        "PermissionCard",
+        "Button",
+        "Alert"
+      ],
+      "antiPatterns": [
+        "Do not use FileReviewPart for static file attachments; use FileAttachment or FileCard.",
+        "Do not hide risky file changes behind a collapsed-only summary.",
+        "Do not use for generic table data."
+      ],
+      "agentHints": [
+        "Use when an agent proposes or reviews file changes.",
+        "Pair with PermissionCard when applying changes needs explicit approval."
+      ]
+    },
+    "markdown": {
+      "id": "markdown",
+      "name": "MarkdownBody",
+      "category": "chat",
+      "status": "stable",
+      "intent": "Tokenized Markdown renderer for assistant responses, documentation snippets, math, and structured generated text.",
+      "packageImport": "import { MarkdownBody } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add markdown",
+      "slots": [
+        "MarkdownBody",
+        "paragraph",
+        "heading",
+        "list",
+        "table",
+        "code",
+        "math"
+      ],
+      "states": [
+        "static",
+        "rich-content",
+        "code-heavy",
+        "math-heavy",
+        "empty"
+      ],
+      "a11y": [
+        "Preserve semantic Markdown structure.",
+        "Avoid rendering untrusted HTML.",
+        "Ensure tables remain readable on narrow screens."
+      ],
+      "composition": [
+        "Response",
+        "StreamingMarkdownBlock",
+        "CodeBlockPart",
+        "Typography"
+      ],
+      "antiPatterns": [
+        "Do not use MarkdownBody for arbitrary user-authored HTML.",
+        "Do not wrap every short label or UI copy in MarkdownBody."
+      ],
+      "agentHints": [
+        "Use MarkdownBody for assistant-generated rich text.",
+        "Use plain Typography components for static product copy."
+      ]
+    },
+    "permission-card": {
+      "id": "permission-card",
+      "name": "PermissionCard",
+      "category": "chat",
+      "status": "stable",
+      "intent": "Inline permission request surface for agent actions that need explicit user approval.",
+      "packageImport": "import { PermissionCard } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add permission-card",
+      "slots": [
+        "title",
+        "description",
+        "metadata",
+        "primary action",
+        "secondary action"
+      ],
+      "states": [
+        "pending",
+        "approved",
+        "denied",
+        "loading",
+        "expired"
+      ],
+      "a11y": [
+        "Make the requested permission explicit in text, not only button labels.",
+        "Keep approve and deny actions both keyboard reachable.",
+        "Use clear status text after the decision changes."
+      ],
+      "composition": [
+        "Button",
+        "Alert",
+        "ToolInvocationCard",
+        "ChatInput"
+      ],
+      "antiPatterns": [
+        "Do not auto-approve risky tool actions.",
+        "Do not hide denial or cancel actions.",
+        "Do not use PermissionCard for ordinary form confirmation."
+      ],
+      "agentHints": [
+        "Use for file, shell, network, credential, or external side-effect approvals.",
+        "Pair with ToolInvocationCard when the approval unlocks a visible tool run."
+      ]
+    },
+    "response": {
+      "id": "response",
+      "name": "Response",
+      "category": "chat",
+      "status": "stable",
+      "intent": "Structured assistant response renderer for answer text, reasoning, tool calls, files, tasks, and generated artifacts.",
+      "packageImport": "import { Response } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add response",
+      "slots": [
+        "message",
+        "round",
+        "step",
+        "markdown",
+        "reasoning",
+        "tool invocation",
+        "file review",
+        "task",
+        "plan"
+      ],
+      "states": [
+        "streaming",
+        "complete",
+        "error",
+        "empty",
+        "tool-running",
+        "tool-complete"
+      ],
+      "a11y": [
+        "Expose streaming updates without causing excessive announcements.",
+        "Keep generated code and tool output keyboard selectable.",
+        "Preserve logical order for reasoning, tool, and answer sections."
+      ],
+      "composition": [
+        "MarkdownBody",
+        "StreamingMarkdownBlock",
+        "ReasoningStep",
+        "ToolInvocationCard",
+        "FileReviewPart",
+        "TaskPart",
+        "PlanPart",
+        "CodeBlockPart"
+      ],
+      "antiPatterns": [
+        "Do not use Response for user-authored messages.",
+        "Do not flatten tool calls into plain Markdown when structured components exist.",
+        "Do not hide error or partial states during long-running agent work."
+      ],
+      "agentHints": [
+        "Choose Response as the default output surface for assistant messages.",
+        "Use UserMessage for human-authored chat bubbles."
+      ]
+    },
+    "tool-invocation-card": {
+      "id": "tool-invocation-card",
+      "name": "ToolInvocationCard",
+      "category": "chat",
+      "status": "stable",
+      "intent": "Compact disclosure card for agent tool calls, their status, inputs, and outputs.",
+      "packageImport": "import { ToolInvocationCard } from 'sparkdesign'",
+      "cliAdd": "npx sparkdesign@latest add tool-invocation-card",
+      "slots": [
+        "tool icon",
+        "tool name",
+        "status",
+        "summary",
+        "details",
+        "output"
+      ],
+      "states": [
+        "queued",
+        "running",
+        "success",
+        "error",
+        "cancelled",
+        "expanded",
+        "collapsed"
+      ],
+      "a11y": [
+        "Expose status changes as readable text.",
+        "Keep disclosure controls keyboard reachable.",
+        "Do not rely on color alone for success or error status."
+      ],
+      "composition": [
+        "Response",
+        "PermissionCard",
+        "CodeBlockPart",
+        "TerminalCodeBlockPart",
+        "Alert"
+      ],
+      "antiPatterns": [
+        "Do not dump large logs directly into the collapsed summary.",
+        "Do not mark a tool as successful before its output is available.",
+        "Do not use for static documentation sections."
+      ],
+      "agentHints": [
+        "Use for shell, browser, file, search, MCP, or external tool activity.",
+        "Pair with PermissionCard for actions that need explicit approval."
+      ]
+    }
+  },
+  "recipes": {
+    "assistant-composer": {
+      "id": "assistant-composer",
+      "intent": "Build the bottom or inline prompt entry area for an AI assistant.",
+      "useWhen": [
+        "The user needs to send prompts, files, or instructions to an agent.",
+        "The UI needs model/status/action controls around a prompt textarea."
+      ],
+      "components": [
+        "chat-input",
+        "button",
+        "permission-card",
+        "alert"
+      ],
+      "layout": [
+        "Place ChatInput at the primary interaction point.",
+        "Keep secondary actions in ChatInputActionsLeft and submit in ChatInputActionsRight.",
+        "Render blocking permission needs above the input, not hidden in a menu."
+      ],
+      "accessibility": [
+        "Keyboard users must be able to compose, attach, and submit without pointer input.",
+        "Status or permission text must remain readable by assistive technology."
+      ],
+      "antiPatterns": [
+        "Do not turn ChatInput into a general settings form.",
+        "Do not hide send behind a dropdown."
+      ]
+    },
+    "assistant-response-stream": {
+      "id": "assistant-response-stream",
+      "intent": "Render assistant output with structured reasoning, tools, and generated text.",
+      "useWhen": [
+        "The UI displays AI-generated answers.",
+        "The response may include tool calls, code, files, tasks, plans, or Markdown."
+      ],
+      "components": [
+        "response",
+        "markdown",
+        "tool-invocation-card",
+        "permission-card",
+        "alert"
+      ],
+      "layout": [
+        "Use Response as the parent renderer for assistant output.",
+        "Use ToolInvocationCard for each tool step rather than plain text logs.",
+        "Use Alert for inline errors that belong to the response."
+      ],
+      "accessibility": [
+        "Keep response sections in chronological order.",
+        "Avoid excessive live-region announcements during token streaming."
+      ],
+      "antiPatterns": [
+        "Do not collapse all structured output into Markdown.",
+        "Do not hide failed tool states."
+      ]
+    },
+    "focused-task-modal": {
+      "id": "focused-task-modal",
+      "intent": "Collect or confirm a short, focused task without navigating away.",
+      "useWhen": [
+        "The user must complete or dismiss a blocking task.",
+        "The content fits in a compact modal with a clear title and action row."
+      ],
+      "components": [
+        "dialog",
+        "button",
+        "card",
+        "alert"
+      ],
+      "layout": [
+        "Use DialogContent with DialogHeader, DialogTitle, optional DialogDescription, and DialogFooter.",
+        "Use one primary action and one secondary dismissal action.",
+        "Place validation or risk messages inline with Alert."
+      ],
+      "accessibility": [
+        "Always provide DialogTitle.",
+        "Return focus to the trigger after close.",
+        "Do not remove Escape behavior unless there is a clear safety reason."
+      ],
+      "antiPatterns": [
+        "Do not use Dialog for long workflows that need persistent navigation.",
+        "Do not nest modals."
+      ]
+    },
+    "settings-drawer": {
+      "id": "settings-drawer",
+      "intent": "Expose contextual settings or detail editing while preserving the underlying page.",
+      "useWhen": [
+        "The user needs to adjust settings without leaving the current workflow.",
+        "The task is secondary to the page but benefits from a persistent side surface.",
+        "The content fits in a single panel with a clear title and action footer."
+      ],
+      "components": [
+        "drawer",
+        "button",
+        "card",
+        "alert"
+      ],
+      "layout": [
+        "Use DrawerContent with DrawerHeader, DrawerTitle, optional DrawerDescription, content sections, and DrawerFooter.",
+        "Group dense settings inside Card or clear section blocks.",
+        "Place save/cancel actions in DrawerFooter and keep the primary action singular."
+      ],
+      "accessibility": [
+        "Always provide DrawerTitle.",
+        "Keep focus trapped while the drawer is open.",
+        "Return focus to DrawerTrigger after close."
+      ],
+      "antiPatterns": [
+        "Do not use Drawer for destructive confirmations.",
+        "Do not put full application navigation in a contextual settings drawer.",
+        "Do not create nested drawers."
+      ]
+    },
+    "tool-approval-flow": {
+      "id": "tool-approval-flow",
+      "intent": "Request explicit user approval before an agent performs a risky or external side-effecting tool action.",
+      "useWhen": [
+        "The agent wants to run shell, browser, file, network, credential, or external integration actions.",
+        "The user must understand and approve the consequence before execution.",
+        "The approval unlocks a visible tool run."
+      ],
+      "components": [
+        "permission-card",
+        "tool-invocation-card",
+        "response",
+        "button",
+        "alert"
+      ],
+      "layout": [
+        "Render PermissionCard before the tool starts.",
+        "Render ToolInvocationCard after approval to show queued, running, success, or error state.",
+        "Use Alert for risks, denials, or failed preconditions."
+      ],
+      "accessibility": [
+        "Make approve and deny choices both keyboard reachable.",
+        "Expose the requested permission and consequence as readable text.",
+        "Do not rely on color alone for risk or status."
+      ],
+      "antiPatterns": [
+        "Do not auto-approve risky actions.",
+        "Do not hide the deny path.",
+        "Do not show a successful tool state before output exists."
+      ]
+    },
+    "file-review-flow": {
+      "id": "file-review-flow",
+      "intent": "Present agent-proposed file changes for review, approval, or requested revisions.",
+      "useWhen": [
+        "The assistant has inspected, generated, or modified files.",
+        "The user needs a concise review surface before accepting changes.",
+        "The flow includes file-specific status or approval decisions."
+      ],
+      "components": [
+        "file-review-part",
+        "permission-card",
+        "tool-invocation-card",
+        "response",
+        "alert"
+      ],
+      "layout": [
+        "Use FileReviewPart for the file list and review actions.",
+        "Use ToolInvocationCard for the underlying file operation when visible provenance matters.",
+        "Use PermissionCard when applying or committing file changes requires approval."
+      ],
+      "accessibility": [
+        "Keep file names and review status available as text.",
+        "Make approve and request-changes actions keyboard reachable.",
+        "Preserve chronological order between tool execution and review result."
+      ],
+      "antiPatterns": [
+        "Do not replace file review with a plain Markdown bullet list when actions are needed.",
+        "Do not hide changed files in a collapsed-only summary.",
+        "Do not use FileReviewPart for unrelated data tables."
+      ]
+    },
+    "empty-state-with-prompts": {
+      "id": "empty-state-with-prompts",
+      "intent": "Help users start an AI or product workflow from an empty state with clear prompts and one primary action.",
+      "useWhen": [
+        "A page, panel, or chat has no user content yet.",
+        "The product should suggest next actions instead of showing a blank surface.",
+        "The recommended action can be expressed as a prompt or compact action set."
+      ],
+      "components": [
+        "card",
+        "button",
+        "chat-input",
+        "alert"
+      ],
+      "layout": [
+        "Use Card for the empty-state container when the state belongs inside a page section.",
+        "Use one primary Button for the most important setup action.",
+        "Use ChatInput when the best next step is a natural-language prompt."
+      ],
+      "accessibility": [
+        "Use a real heading or clear title text.",
+        "Ensure prompt suggestions are reachable by keyboard.",
+        "Avoid placeholder-only instructions."
+      ],
+      "antiPatterns": [
+        "Do not show more than a small set of competing starting actions.",
+        "Do not use decorative illustration as the only explanation.",
+        "Do not use ChatInput if the flow is a deterministic form task."
+      ]
+    }
+  }
+}