@cueplusplus/ui 0.13.0

package/manifest/components/elements-data-table.json

@@ -0,0 +1,75 @@
+{
+  "name": "ElementsDataTable",
+  "slug": "elements-data-table",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A small comparison table the model can answer with directly.",
+  "props": [
+    {
+      "name": "rows",
+      "type": "readonly ModelUsage[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Table rows with model name, context window, and cost.",
+      "control": {
+        "kind": "array",
+        "fixture": "table.model-usage-6"
+      }
+    },
+    {
+      "name": "cycle",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "Identity key that remounts the body so row entrance can replay.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-micro"
+  ],
+  "summary": "A small comparison table the model can answer with directly.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { DataTable } from \"@cueplusplus/ui/elements\";\n\n<DataTable\n  rows={[{ name: \"Sonnet\", context: \"200k\", cost: \"$3\" }]}\n  cycle={0}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elements-data-table",
+  "mdUrl": "/docs/components/elements-data-table.md",
+  "jsonUrl": "/r/components/elements-data-table.json",
+  "specimens": [
+    {
+      "title": "ElementsDataTable",
+      "group": "elements-knowledge",
+      "components": [
+        "ElementsDataTable"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"what the research cost\" wide>\n    <ElementsDataTable rows={USAGE} cycle={0} />\n  </Specimen>\n  <Specimen label=\"one row\" wide>\n    <ElementsDataTable rows={USAGE.slice(0, 1)} cycle={1} />\n  </Specimen>\n</Specimens>",
+      "note": "A small table the model can answer with directly — three columns, no sorting, no virtualisation, no header menu. It is `ElementsDataTable` because the package already sells a real one at `@cueplusplus/ui/instruments`: that one is a data grid, this one is a paragraph shaped like a grid, and the rename keeps a consumer from reaching for the wrong one.",
+      "interaction": "none. `cycle` remounts the body, so a new answer's rows stagger in rather than mutating in place."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/elements-timeline.json

@@ -0,0 +1,77 @@
+{
+  "name": "ElementsTimeline",
+  "slug": "elements-timeline",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Events on a time axis, with what already happened and what is still coming.",
+  "props": [
+    {
+      "name": "events",
+      "type": "readonly TimelineEvent[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Events in chronological order, past and scheduled together.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.events"
+      }
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many events have been resolved.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"events\" | \"visibleCount\"> & {\n  /** Events in chronological order, past and scheduled together. */\n  events: readonly TimelineEvent[];\n  /** How many events have been resolved. */\n  visibleCount: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-radius-overlay",
+    "--cue-stream",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "Events on a time axis, with what already happened and what is still coming.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { Timeline } from \"@cueplusplus/ui/elements\";\n\n<Timeline events={events} visibleCount={events.length} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elements-timeline",
+  "mdUrl": "/docs/components/elements-timeline.md",
+  "jsonUrl": "/r/components/elements-timeline.json",
+  "specimens": [
+    {
+      "title": "ElementsTimeline",
+      "group": "elements-agents",
+      "components": [
+        "ElementsTimeline"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"past, now and scheduled\" wide>\n    <ElementsTimeline events={EVENTS} visibleCount={EVENTS.length} />\n  </Specimen>\n  <Specimen label=\"two events in\" wide>\n    <ElementsTimeline events={EVENTS} visibleCount={2} />\n  </Specimen>\n</Specimens>",
+      "note": "Events on one axis, with what already happened and what is still coming in the same list — `past`, `now` and `future` are one union, so a schedule and a history are the same component. It publishes as `ElementsTimeline` because cue already sells a `Timeline`; the spec asked for `ToolTimeline`, which turned out to be the next bench's name.",
+      "interaction": "none. The now marker is the only one that pulses, and it holds still for a reader who asked for less motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/elicitation-form.json

@@ -0,0 +1,130 @@
+{
+  "name": "ElicitationForm",
+  "slug": "elicitation-form",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A server pausing mid-tool-call to ask you for the fields it still needs.",
+  "props": [
+    {
+      "name": "server",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which server paused to ask.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "message",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Why the input is needed, in the server's words.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "fields",
+      "type": "readonly ElicitationField[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The schema the server sent, already resolved to display values.",
+      "control": {
+        "kind": "array",
+        "fixture": "composer.fields"
+      }
+    },
+    {
+      "name": "state",
+      "type": "\"request\" | \"accepted\" | \"declined\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Swaps the action row for the outcome once the user answers.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "request",
+          "accepted",
+          "declined"
+        ]
+      }
+    },
+    {
+      "name": "onAccept",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the filled form is sent back.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "onDecline",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the request is refused.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"server\"\n  | \"message\"\n  | \"fields\"\n  | \"state\"\n  | \"onAccept\"\n  | \"onDecline\"\n> & {\n  /** Which server paused to ask. */\n  server: string;\n  /** Why the input is needed, in the server's words. */\n  message: string;\n  /** The schema the server sent, already resolved to display values. */\n  fields: readonly ElicitationField[];\n  /** Swaps the action row for the outcome once the user answers. */\n  state: ElicitationState;\n  /** Called when the filled form is sent back. */\n  onAccept?: () => void;\n  /** Called when the request is refused. */\n  onDecline?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-bg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A server pausing mid-tool-call to ask you for the fields it still needs.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ElicitationForm } from \"@cueplusplus/ui/elements\";\n\n<ElicitationForm\n  server=\"github-mcp\"\n  message=\"Confirm where the release notes should be published.\"\n  fields={fields}\n  state=\"request\"\n  onAccept={send}\n  onDecline={decline}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/elicitation-form",
+  "mdUrl": "/docs/components/elicitation-form.md",
+  "jsonUrl": "/r/components/elicitation-form.json",
+  "specimens": [
+    {
+      "title": "ElicitationForm",
+      "group": "elements-composer",
+      "components": [
+        "ElicitationForm"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"asking\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state={elicitation}\n      onAccept={() => setElicitation(\"accepted\")}\n      onDecline={() => setElicitation(\"declined\")}\n    />\n  </Specimen>\n  <Specimen label=\"answered\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state=\"accepted\"\n    />\n  </Specimen>\n  <Specimen label=\"refused\" wide>\n    <ElicitationForm\n      server=\"eos-desk\"\n      message=\"Confirm which universe to patch into before I write anything to the show file.\"\n      fields={FIELDS}\n      state=\"declined\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "A server pausing mid-tool-call to ask for the fields it still needs — MCP's elicitation, drawn. The fields arrive already resolved to display values, so the element renders a schema without ever having parsed one, and `state` swaps the two buttons for the outcome the moment the user answers. Declining is a first-class answer here, not a dismissal.",
+      "interaction": "each field's control is chosen by its `kind` — a value chip, a row of options, or a switch — and the required ones are marked on the label rather than announced only on failure."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-composer.json

@@ -0,0 +1,71 @@
+{
+  "name": "EmptyStateComposer",
+  "slug": "empty-state-composer",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A composer-shaped invitation under the suggestions. It is a display rather than a\nworking input — the placeholder is a string and send takes a handler — for the\nscreen whose real composer is somewhere else.",
+  "props": [
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Resting text in the input bar.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onSend",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called from the send control. Omit it and the control renders disabled.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"placeholder\"> & {\n  /** Resting text in the input bar. */\n  placeholder: string;\n  /** Called from the send control. Omit it and the control renders disabled. */\n  onSend?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "A composer-shaped invitation under the suggestions.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-composer",
+  "mdUrl": "/docs/components/empty-state-composer.md",
+  "jsonUrl": "/r/components/empty-state-composer.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-greeting.json

@@ -0,0 +1,49 @@
+{
+  "name": "EmptyStateGreeting",
+  "slug": "empty-state-greeting",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The one line at the top of a blank thread. A heading, so a screen reader lands on it.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"h2\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "The one line at the top of a blank thread.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-greeting",
+  "mdUrl": "/docs/components/empty-state-greeting.md",
+  "jsonUrl": "/r/components/empty-state-greeting.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-suggestion.json

@@ -0,0 +1,60 @@
+{
+  "name": "EmptyStateSuggestion",
+  "slug": "empty-state-suggestion",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "One thing worth asking, as a pill. `index` staggers its entrance so the row arrives\nleft to right rather than all at once.",
+  "props": [
+    {
+      "name": "index",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Position in the row. Staggers the entrance so the pills arrive in order.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "ComponentProps<\"button\"> & {\n  /** Position in the row. Staggers the entrance so the pills arrive in order. */\n  index?: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "One thing worth asking, as a pill.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-suggestion",
+  "mdUrl": "/docs/components/empty-state-suggestion.md",
+  "jsonUrl": "/r/components/empty-state-suggestion.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state-suggestions.json

@@ -0,0 +1,49 @@
+{
+  "name": "EmptyStateSuggestions",
+  "slug": "empty-state-suggestions",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "The row the suggestion pills wrap in.",
+  "props": [],
+  "typeReferences": [
+    "ComponentProps<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-subtle",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-title"
+  ],
+  "summary": "The row the suggestion pills wrap in.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state-suggestions",
+  "mdUrl": "/docs/components/empty-state-suggestions.md",
+  "jsonUrl": "/r/components/empty-state-suggestions.json",
+  "specimens": [
+    {
+      "title": "ChatEmptyState",
+      "group": "elements-composer",
+      "components": [
+        "ChatEmptyState",
+        "EmptyStateGreeting",
+        "EmptyStateSuggestions",
+        "EmptyStateSuggestion",
+        "EmptyStateComposer"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"greeting, ways in, composer\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>What is the rig doing tonight?</EmptyStateGreeting>\n      <EmptyStateSuggestions>\n        {OPENERS.map((opener, index) => (\n          <EmptyStateSuggestion key={opener} index={index}>\n            {opener}\n          </EmptyStateSuggestion>\n        ))}\n      </EmptyStateSuggestions>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" onSend={() => undefined} />\n    </ChatEmptyState>\n  </Specimen>\n  <Specimen label=\"greeting only\" wide>\n    <ChatEmptyState>\n      <EmptyStateGreeting>Ready when you are.</EmptyStateGreeting>\n      <EmptyStateComposer placeholder=\"Ask about the rig\" />\n    </ChatEmptyState>\n  </Specimen>\n</Specimens>",
+      "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
+      "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/empty-state.json

@@ -0,0 +1,111 @@
+{
+  "name": "EmptyState",
+  "slug": "empty-state",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The \"there is nothing here\" panel body.\n\nCentred and quiet: an empty state is a report, not an alarm, so it uses the\nmuted ramp throughout and gets its emphasis from position rather than colour.\nThe icon is decorative — the title carries the meaning, so a screen reader\nhears one sentence instead of a shrug emoji.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is missing. One short line: \"No cues yet\".",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "hint",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "How to fix it. One sentence, muted.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "action",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The way out — normally a single `Button`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional glyph above the title (e.g. a lucide icon), drawn `aria-hidden`.",
+      "control": {
+        "kind": "opaque",
+        "fixture": "icon.play"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra content between the hint and the action — rarely needed.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-leading-ui",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "The \"there is nothing here\" panel body.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Panel>\n  <EmptyState\n    icon={ListX}\n    title=\"No cues yet\"\n    hint=\"Record one from the live look, or import a show file.\"\n    action={<Button variant=\"primary\">Record cue</Button>}\n  />\n</Panel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/empty-state",
+  "mdUrl": "/docs/components/empty-state.md",
+  "jsonUrl": "/r/components/empty-state.json",
+  "specimens": [
+    {
+      "title": "EmptyState",
+      "group": "chrome",
+      "components": [
+        "EmptyState"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel>\n    <EmptyState\n      icon={List}\n      title={COPY.empty.title}\n      hint={COPY.empty.hint}\n      action={<Button variant=\"primary\">{COPY.empty.action}</Button>}\n    />\n  </Panel>\n  <Panel>\n    <EmptyState\n      icon={Eye}\n      title={COPY.error.title}\n      hint={COPY.error.hint}\n      action={<Button>{COPY.error.action}</Button>}\n    >\n      <StatusDot tone=\"danger\" label=\"No reply\" />\n    </EmptyState>\n  </Panel>\n</div>",
+      "note": "The standard empty copy, from lib/samples.tsx. Same words everywhere in the app.",
+      "interaction": "the action is an ordinary Button and behaves like one."
+    }
+  ],
+  "todo": true
+}