agentic-ds-kit 0.1.0

package/contracts/carousel.json

@@ -0,0 +1,98 @@
+{
+  "id": "carousel",
+  "status": "stable",
+  "intent": "Paged track of slides with prev/next kit Buttons. One piece.",
+  "useWhen": [
+    "galleries",
+    "featured cards",
+    "paged media"
+  ],
+  "doNotUseWhen": [
+    "Tabs for views",
+    "Pagination for lists",
+    "don't use for primary nav"
+  ],
+  "contains": [
+    "button"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "required": true,
+      "minItems": 1,
+      "note": "ReactNode slides. No CarouselCard or Slide cousins."
+    },
+    "orientation": {
+      "type": "enum",
+      "values": [
+        "horizontal",
+        "vertical"
+      ],
+      "default": "horizontal"
+    },
+    "loop": {
+      "type": "boolean",
+      "default": false
+    },
+    "align": {
+      "type": "enum",
+      "values": [
+        "start",
+        "center"
+      ],
+      "default": "start"
+    },
+    "slidesPerView": {
+      "type": "enum",
+      "values": [
+        1,
+        2,
+        3,
+        4
+      ],
+      "default": 1,
+      "note": "1 = full slide; 3 = one-third; 4 = quarter. Scoreboard uses 4 when items > 4."
+    },
+    "showControls": {
+      "type": "boolean",
+      "default": true
+    },
+    "showIndex": {
+      "type": "boolean",
+      "default": false,
+      "note": "Caption under the track: Slide N of M, aria-live polite"
+    },
+    "onIndexChange": {
+      "type": "function",
+      "required": false,
+      "note": "(index: number) => void // 0-based"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "default": "Carousel"
+    }
+  },
+  "tokens": [
+    "text.muted",
+    "focus.ring",
+    "space.4",
+    "space.12"
+  ],
+  "a11y": {
+    "element": "div[role=region]",
+    "requirements": [
+      "region with aria-roledescription=carousel",
+      "slides are role=group with aria-roledescription=slide",
+      "button names Previous slide / Next slide",
+      "index live region if shown"
+    ]
+  },
+  "doNot": [
+    "no CarouselContent/Item/Previous/Next",
+    "do not use raw hex",
+    "compose kit Button for controls",
+    "no autoplay in v1"
+  ],
+  "snippet": "<Carousel items={[<span>1</span>, <span>2</span>, <span>3</span>]} />"
+}

package/contracts/cell.json

@@ -0,0 +1,203 @@
+{
+  "id": "cell",
+  "status": "stable",
+  "intent": "Inline cell content for datasets: text, avatar, file, payment, badge, trend, avatar group, select, progress, rating, or row actions, with optional checkbox.",
+  "useWhen": [
+    "DataTable body cells",
+    "Mixed visual and label content in a row"
+  ],
+  "doNotUseWhen": [
+    "A full searchable dataset \u2014 use DataTable, which composes Cell",
+    "A short static text table \u2014 use Table"
+  ],
+  "contains": [
+    "avatar",
+    "avatargroup",
+    "badge",
+    "buttongroup",
+    "button",
+    "checkbox",
+    "select",
+    "progress"
+  ],
+  "props": {
+    "type": {
+      "type": "enum",
+      "values": [
+        "text",
+        "avatar",
+        "file",
+        "payment",
+        "badge",
+        "badges",
+        "trendPositive",
+        "trendNegative",
+        "avatarGroup",
+        "select",
+        "progress",
+        "rating",
+        "actions",
+        "actionIcons",
+        "actionMenu"
+      ],
+      "default": "text"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md"
+      ],
+      "default": "md",
+      "note": "Avatar, AvatarGroup, and Badge map sm/md. Checkbox is always sm."
+    },
+    "text": {
+      "type": "boolean",
+      "default": true,
+      "note": "When false, hide the label (visual-only). type=text with text=false and no checkbox is an empty slot."
+    },
+    "checkbox": {
+      "type": "boolean",
+      "default": false,
+      "note": "Leading unlabeled kit Checkbox. ariaLabel is Select ${label || name || \"row\"}."
+    },
+    "label": {
+      "type": "string",
+      "required": false,
+      "note": "Text shown when text is true. For type=text this is the content."
+    },
+    "name": {
+      "type": "string",
+      "required": false,
+      "note": "Avatar / AvatarGroup person name; required for those types; falls back to label."
+    },
+    "src": {
+      "type": "string",
+      "required": false
+    },
+    "initials": {
+      "type": "string",
+      "required": false
+    },
+    "people": {
+      "type": "array",
+      "required": false,
+      "itemShape": {
+        "name": "string",
+        "src": "string?",
+        "initials": "string?"
+      },
+      "note": "Required for avatarGroup. Passed to kit AvatarGroup, max default 3."
+    },
+    "icon": {
+      "type": "string",
+      "required": false,
+      "note": "Lucide catalog name. file default File, payment default CreditCard."
+    },
+    "tone": {
+      "type": "enum",
+      "values": [
+        "neutral",
+        "brand",
+        "success",
+        "warning",
+        "danger",
+        "info"
+      ],
+      "default": "neutral",
+      "note": "Single Badge. Demos use success for Active-like, else neutral."
+    },
+    "badges": {
+      "type": "array",
+      "required": false,
+      "itemShape": {
+        "label": "string",
+        "tone": "BadgeTone?"
+      },
+      "note": "type=badges. Cap at 3 kit Badges."
+    },
+    "value": {
+      "type": "string | number",
+      "required": false,
+      "note": "Trend number, progress 0-100, rating 0-5, or select value."
+    },
+    "checked": {
+      "type": "boolean",
+      "required": false,
+      "note": "only when checkbox"
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "required": false,
+      "note": "only when checkbox"
+    },
+    "onCheckedChange": {
+      "type": "function",
+      "required": false,
+      "note": "(checked: boolean) => void \u2014 only when checkbox"
+    },
+    "id": {
+      "type": "string",
+      "required": false,
+      "note": "checkbox id; useId if omitted"
+    },
+    "options": {
+      "type": "array",
+      "required": false,
+      "itemShape": {
+        "value": "string",
+        "label": "string"
+      },
+      "note": "Required for type=select. Passed to kit Select."
+    },
+    "actions": {
+      "type": "array",
+      "required": false,
+      "itemShape": {
+        "label": "string?",
+        "icon": "string?",
+        "ariaLabel": "string?",
+        "variant": "ButtonVariant?"
+      },
+      "note": "type=actions (labeled Buttons in ButtonGroup, cap 3), actionIcons (icon-only Buttons, each ariaLabel), actionMenu composes kit DropdownMenu from actions."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "icon.muted",
+    "icon.warning",
+    "status.success",
+    "status.danger",
+    "fill.brand",
+    "surface.muted",
+    "space.2",
+    "radius.full"
+  ],
+  "a11y": {
+    "element": "span",
+    "requirements": [
+      "type=text is text (or text plus checkbox)",
+      "Avatar and AvatarGroup keep their own a11y",
+      "File and payment icons are aria-hidden; if text=false set aria-label on the cell from label or name",
+      "Trend aria-label is Up {value} or Down {value} when text is false",
+      "When checkbox, unlabeled kit Checkbox with ariaLabel Select ${label || name || \"row\"}",
+      "type=select uses kit Select with ariaLabel from label",
+      "type=progress composes kit Progress",
+      "type=rating is role=img, '{n} of 5'",
+      "type=actionIcons each icon-only Button needs ariaLabel",
+      "type=actionMenu ariaLabel is Row actions unless label is set"
+    ]
+  },
+  "doNot": [
+    "Do not invent DataTableCell, Tag, Trend, FileIcon, PaymentMethod, or a second Badge",
+    "Do not use raw hex",
+    "Do not use Badge for trends",
+    "Do not invent local Avatar, AvatarGroup, Badge, or Checkbox \u2014 compose the kit pieces",
+    "Do not use Lucide except via LucideByName from @/ui/Button/lucideName",
+    "Do not invent a local progress bar \u2014 type=progress composes kit Progress. Do not invent Rating, StarRating, ActionCell",
+    "Do not invent a local DropdownMenu \u2014 type=actionMenu composes kit DropdownMenu",
+    "Do not invent local Select, Button, or ButtonGroup \u2014 compose the kit pieces"
+  ],
+  "snippet": "<Cell type=\"progress\" size=\"md\" value={64} />"
+}

package/contracts/chat.json

@@ -0,0 +1,131 @@
+{
+  "id": "chat",
+  "status": "stable",
+  "intent": "Assistant panel with a header, a thread, and a composer. One piece.",
+  "useWhen": [
+    "An inline assistant beside a workspace",
+    "A help thread with send and a thinking state",
+    "Suggested prompts above a composer"
+  ],
+  "doNotUseWhen": [
+    "A blocking overlay — use Modal",
+    "A must-choose confirm — use AlertDialog",
+    "A short notice after an action — use Toast"
+  ],
+  "contains": ["button", "input", "thinkinganimation", "dropdownmenu"],
+  "props": {
+    "title": {
+      "type": "string",
+      "default": "Assistant"
+    },
+    "status": {
+      "type": "string",
+      "required": false
+    },
+    "messages": {
+      "type": "array",
+      "required": false,
+      "note": "ChatMessage[] with role user | assistant, content, optional id and timestamp. Type only — not a ChatMessage component."
+    },
+    "suggestions": {
+      "type": "array",
+      "required": false,
+      "note": "Prompt chips above the composer. kit Button sm tertiary."
+    },
+    "placeholder": {
+      "type": "string",
+      "default": "How can we help you?"
+    },
+    "emptyState": {
+      "type": "string",
+      "required": false,
+      "default": "Start a conversation."
+    },
+    "isThinking": {
+      "type": "boolean",
+      "default": false,
+      "note": "Shows kit ThinkingAnimation in the thread."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "value": {
+      "type": "string",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "required": false
+    },
+    "onSend": {
+      "type": "function",
+      "required": false,
+      "note": "(message: string) => void"
+    },
+    "onClose": {
+      "type": "function",
+      "required": false
+    },
+    "closeLabel": {
+      "type": "string",
+      "default": "Close"
+    },
+    "menuItems": {
+      "type": "array",
+      "required": false,
+      "note": "Optional overflow actions. kit DropdownMenu."
+    },
+    "menuLabel": {
+      "type": "string",
+      "default": "More"
+    },
+    "radius": {
+      "type": "enum",
+      "values": ["lg", "none"],
+      "default": "lg",
+      "note": "lg is the standalone card. none squares the panel and drops the outer block/end borders so Chat can sit flush in a workspace rail."
+    },
+    "className": {
+      "type": "string",
+      "required": false
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "fill.brandSubtle",
+    "fill.brand",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "radius.surfaceLg",
+    "radius.0",
+    "radius.full",
+    "space.5",
+    "type.size.label",
+    "type.weight.heading",
+    "type.size.bodySm"
+  ],
+  "a11y": {
+    "element": "section",
+    "requirements": [
+      "section named by title",
+      "thread is role=log with aria-live=polite",
+      "aria-busy while thinking",
+      "composer input has an accessible name",
+      "Send and Close are named icon-only kit Buttons"
+    ]
+  },
+  "doNot": [
+    "Do not invent ChatMessage, ChatInput, ChatHeader, ChatBubble, or ChatAvatar cousins",
+    "Do not use Modal for an inline assistant panel",
+    "Do not override Chat radius from the host — use radius none for a full-height workspace rail",
+    "Do not use raw hex",
+    "Do not use Florence, BillingPlatform, or copilot wording in copy"
+  ],
+  "snippet": "<Chat title=\"Assistant\" messages={messages} onSend={handleSend} isThinking={busy} onClose={close} />"
+}

package/contracts/checkbox.json

@@ -0,0 +1,101 @@
+{
+  "id": "checkbox",
+  "status": "stable",
+  "intent": "Multi-select or confirmation control. Optional visible label.",
+  "useWhen": [
+    "Independent booleans such as agree to terms or enable notifications",
+    "Confirmations that are not a submit action",
+    "Table row or icon-only select without visible text — set ariaLabel"
+  ],
+  "doNotUseWhen": [
+    "Choosing one of several options — use RadioGroup",
+    "Primary form submit actions — use Button",
+    "Immediate on/off setting — use Switch"
+  ],
+  "props": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "label": {
+      "type": "string",
+      "required": false,
+      "note": "visible text; required unless ariaLabel is set"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "required when label is omitted (table row, icon-only slot)"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "default": "md"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "error": {
+      "type": "boolean",
+      "default": false
+    },
+    "checked": {
+      "type": "boolean",
+      "required": false,
+      "note": "controlled"
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "default": false,
+      "note": "uncontrolled"
+    },
+    "indeterminate": {
+      "type": "boolean",
+      "default": false,
+      "note": "visual + aria-checked mixed; set via input.indeterminate"
+    },
+    "onChange": {
+      "type": "function",
+      "required": false,
+      "note": "(checked: boolean) => void"
+    },
+    "name": {
+      "type": "string",
+      "required": false
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "action.primary",
+    "action.onPrimary",
+    "surface.card",
+    "border.strong",
+    "border.faint",
+    "border.focus",
+    "status.danger",
+    "radius.controlSm"
+  ],
+  "a11y": {
+    "element": "input[type=checkbox]",
+    "requirements": [
+      "Visible label via label/htmlFor OR aria-label when no text",
+      "Disabled state is exposed",
+      "Error described if used with Field",
+      "Indeterminate is aria-checked=mixed",
+      "Do not ship unlabeled without ariaLabel"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Checkbox",
+    "Do not use raw hex",
+    "Do not use RadioGroup for booleans",
+    "Do not ship unlabeled without ariaLabel",
+    "Do not use Switch as a checkbox"
+  ],
+  "snippet": "<Checkbox id=\"updates\" label=\"Send me product updates\" />\n<Checkbox id=\"row-1\" ariaLabel=\"Select row\" />"
+}

package/contracts/collapsible.json

@@ -0,0 +1,66 @@
+{
+  "id": "collapsible",
+  "status": "stable",
+  "intent": "Single show/hide panel with a title and a toggle.",
+  "useWhen": [
+    "One disclosure whose body composes kit pieces",
+    "Order, product, or extra spec the user can hide"
+  ],
+  "doNotUseWhen": [
+    "Two or more related sections, one open at a time — use Accordion",
+    "In-page peer views — use Tabs"
+  ],
+  "props": {
+    "trigger": {
+      "type": "string",
+      "required": true,
+      "note": "Title on the left. Toggle is a ChevronsUpDown button, not the whole row"
+    },
+    "children": {
+      "type": "slot",
+      "required": true,
+      "note": "Revealed body. Compose kit pieces, never a local cousin"
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "default": false
+    },
+    "open": {
+      "type": "boolean",
+      "required": false,
+      "note": "controlled"
+    },
+    "onOpenChange": {
+      "type": "function",
+      "required": false,
+      "note": "(open: boolean) => void"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "icon.muted",
+    "surface.muted",
+    "surface.card",
+    "border.faint",
+    "border.focus",
+    "radius.surface.md",
+    "radius.control.sm"
+  ],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "Title is not the toggle",
+      "Toggle is a button with aria-expanded and aria-label Toggle {trigger}",
+      "Button aria-controls the panel",
+      "Panel is role=region, aria-labelledby the title",
+      "Closed panel is hidden from AT"
+    ]
+  },
+  "doNot": [
+    "Do not invent CollapsibleTrigger or CollapsibleContent cousins",
+    "Do not use Accordion for a single block",
+    "Do not make the whole header row the button",
+    "Do not use raw hex"
+  ],
+  "snippet": "<Collapsible trigger=\"Order #4189\" defaultOpen>\n  {children}\n</Collapsible>"
+}

package/contracts/command.json

@@ -0,0 +1,84 @@
+{
+  "id": "command",
+  "status": "stable",
+  "intent": "Searchable command menu for quick actions.",
+  "useWhen": [
+    "Searchable actions and quick jumps",
+    "Command palette — kit Button opens kit Modal with Command inside"
+  ],
+  "doNotUseWhen": [
+    "Short Field dropdown — use Select",
+    "Actions from a button — use DropdownMenu",
+    "Sidebar navigation — use AppNav",
+    "Overlay chrome — compose Modal; do not add CommandDialog"
+  ],
+  "props": {
+    "placeholder": {
+      "type": "string",
+      "default": "Type a command or search..."
+    },
+    "empty": {
+      "type": "string",
+      "default": "No results found."
+    },
+    "groups": {
+      "type": "array",
+      "required": true,
+      "itemShape": {
+        "heading": "string?",
+        "items": [
+          {
+            "id": "string",
+            "label": "string",
+            "icon": "string?",
+            "shortcut": "string?",
+            "disabled": "boolean?"
+          }
+        ]
+      },
+      "note": "Each group has optional heading and a required items array. Item icon is a Lucide PascalCase name from the catalog."
+    },
+    "onSelect": {
+      "type": "function",
+      "required": false,
+      "note": "(id: string) => void"
+    },
+    "label": {
+      "type": "string",
+      "default": "Command menu",
+      "note": "Accessible name on the combobox input"
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "surface.muted",
+    "border.faint",
+    "border.focus",
+    "radius.surfaceMd",
+    "shadow.sm",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "icon.muted",
+    "space.1"
+  ],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "Input is role=combobox with aria-expanded=true, aria-controls the listbox, aria-autocomplete=list, aria-activedescendant, and aria-label from label",
+      "List is role=listbox",
+      "Items are role=option with aria-selected when highlighted and aria-disabled when disabled",
+      "useId for ids",
+      "Search icon is aria-hidden"
+    ]
+  },
+  "doNot": [
+    "Do not invent CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut, or CommandDialog",
+    "Do not wrap the search field in Field — Command owns its input",
+    "Do not use kit Input (uncontrolled) for the query",
+    "Do not use cmdk or extra dependencies",
+    "Do not use raw hex",
+    "Do not close itself — compose Modal for an overlay"
+  ],
+  "snippet": "<Button variant=\"secondary\" iconStart=\"Search\" onClick={open} />\n<Modal open={open} title=\"Command menu\" onClose={close}>\n  <Command groups={groups} onSelect={close} />\n</Modal>"
+}