agentic-ds-kit 0.1.0

package/contracts/sidenav.json

@@ -0,0 +1,133 @@
+{
+  "id": "sidenav",
+  "status": "stable",
+  "intent": "Product side nav: brand header, icon items, optional badges, closeable. Not AppNav. Not Drawer.",
+  "useWhen": [
+    "Product app chrome",
+    "Persistent nav with icons"
+  ],
+  "doNotUseWhen": [
+    "Docs catalog \u2014 use AppNav",
+    "Overlay task panel \u2014 use Drawer",
+    "Centered short task \u2014 use Modal",
+    "Horizontal site nav \u2014 use NavigationMenu",
+    "Product top bar with logo and search \u2014 use AppHeader"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": true,
+      "note": "Brand title in the header. Accessible name on the aside when showHeader is false"
+    },
+    "mark": {
+      "type": "string",
+      "required": false,
+      "note": "Brand letter. Defaults to the first character of title"
+    },
+    "showHeader": {
+      "type": "boolean",
+      "default": true,
+      "note": "Brand mark, title, and close. Set false when AppHeader already provides brand. Rail stays expanded."
+    },
+    "radius": {
+      "type": "enum",
+      "values": [
+        "md",
+        "none"
+      ],
+      "default": "md",
+      "note": "Rail corners. md is radius-surface-md. none is a flush square column next to AppHeader."
+    },
+    "open": {
+      "type": "boolean",
+      "required": false,
+      "note": "controlled"
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "default": true
+    },
+    "onOpenChange": {
+      "type": "function",
+      "required": false,
+      "note": "(open: boolean) => void"
+    },
+    "side": {
+      "type": "enum",
+      "values": [
+        "left",
+        "right"
+      ],
+      "default": "left",
+      "note": "Does not position SideNav. The consumer shell uses row-reverse for right"
+    },
+    "groups": {
+      "type": "array",
+      "required": false,
+      "note": "Labeled sections of SideNavItem. Takes precedence over items"
+    },
+    "items": {
+      "type": "array",
+      "required": false,
+      "note": "Flat list when groups is omitted. Leaf onClick is in-app select; href is a link when onClick is omitted."
+    },
+    "footer": {
+      "type": "object",
+      "required": false,
+      "note": "Single footer row (e.g. Settings)"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "text.brand",
+    "text.disabled",
+    "surface.card",
+    "surface.muted",
+    "surface.brandSubtle",
+    "surface.disabled",
+    "border.subtle",
+    "border.faint",
+    "border.surface",
+    "border.divider",
+    "fill.brand",
+    "brand.onBrand",
+    "icon.secondary",
+    "icon.brand",
+    "icon.muted",
+    "focus.ring",
+    "layout.sidebar",
+    "layout.sidebarCompact",
+    "radius.surfaceMd",
+    "radius.controlMd",
+    "radius.0",
+    "motion.expand.duration",
+    "motion.expand.easing",
+    "motion.overlay.duration",
+    "motion.overlay.easing"
+  ],
+  "a11y": {
+    "element": "aside",
+    "requirements": [
+      "In-flow aside, not a dialog and not position:fixed",
+      "No overlay, no focus trap, no Escape-to-close",
+      "Close is a kit Button with PanelLeftClose or PanelRightClose and ariaLabel Close",
+      "Closed rail reopens via the brand mark button with ariaLabel Open",
+      "Title is visible in the header when open; clipped when closed",
+      "When showHeader is false, omit the header and close; title remains the accessible name via aria-label",
+      "Active leaf uses aria-current=page",
+      "Parent with nested items is a disclosure with aria-expanded",
+      "Closed rail keeps labels available as sr-only text"
+    ]
+  },
+  "doNot": [
+    "Do not invent Sidebar, SidebarHeader, SidebarNav, SidebarSection, SidebarItem, SidebarSubmenu, SidebarFooter, SidebarProvider, SidebarTrigger, SidebarContent, SidebarGroup, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarInset, or SidebarRail",
+    "Do not compose AppNav inside SideNav",
+    "Do not use Drawer for persistent app chrome",
+    "Do not use AppNav as closeable product chrome",
+    "Do not use position:fixed, an overlay, a focus trap, or Escape-to-close",
+    "Do not use the shadcn sidebar package",
+    "Do not use raw hex"
+  ],
+  "snippet": "<SideNav title=\"Agentix\" mark=\"A\" open={open} onOpenChange={setOpen} groups={groups} footer={[{ id: \"invite\", label: \"Invite members\", icon: \"CirclePlus\" }, { id: \"settings\", label: \"Settings\", icon: \"Settings\" }]} />"
+}

package/contracts/slider.json

@@ -0,0 +1,81 @@
+{
+  "id": "slider",
+  "status": "stable",
+  "intent": "Pick a value or range along a track. One piece. Range is a two-value array, not a RangeSlider cousin.",
+  "useWhen": [
+    "Adjust a numeric setting on a continuous scale",
+    "Pick a min and max range for filters",
+    "Volume, brightness, or percent controls in a form"
+  ],
+  "doNotUseWhen": [
+    "Discrete choices from a short list — use RadioGroup or Select",
+    "On/off settings — use Switch",
+    "Determinate task completion — use Progress"
+  ],
+  "props": {
+    "value": {
+      "type": "number | number[]",
+      "required": true,
+      "note": "Current value. Single number for one thumb. Two numbers for a range."
+    },
+    "min": {
+      "type": "number",
+      "default": 0
+    },
+    "max": {
+      "type": "number",
+      "default": 100
+    },
+    "step": {
+      "type": "number",
+      "default": 1
+    },
+    "orientation": {
+      "type": "enum",
+      "values": ["horizontal", "vertical"],
+      "default": "horizontal",
+      "note": "Vertical is orientation, not a VerticalSlider cousin."
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "required": false,
+      "note": "Called with the next value or value array."
+    }
+  },
+  "tokens": [
+    "fill.brand",
+    "fill.subtle",
+    "surface.card",
+    "border.faint",
+    "border.strong",
+    "action.primary",
+    "action.onPrimary",
+    "focus.ring",
+    "radius.pill",
+    "radius.full",
+    "space.1",
+    "space.2",
+    "motion.interactionDuration",
+    "motion.interactionEasing"
+  ],
+  "a11y": {
+    "element": "span[role=slider]",
+    "requirements": [
+      "Each thumb has role=slider",
+      "aria-valuemin, aria-valuemax, aria-valuenow on each thumb",
+      "Arrow keys adjust by step. Home and End jump to min and max",
+      "Focus ring on thumb focus-visible"
+    ]
+  },
+  "doNot": [
+    "Do not invent SliderTrack, SliderThumb, SliderRange, RangeSlider, or VerticalSlider",
+    "Do not use raw hex",
+    "Do not use radix or @base-ui/react",
+    "Do not use a native range input"
+  ],
+  "snippet": "<Slider value={33} onValueChange={setValue} />\n<Slider value={[25, 75]} onValueChange={setRange} />\n<Slider value={50} orientation=\"vertical\" disabled />"
+}

package/contracts/spinner.json

@@ -0,0 +1,52 @@
+{
+  "id": "spinner",
+  "status": "stable",
+  "intent": "Spinning circular loader for indeterminate waits. One piece. Distinct from LoadingAnimation dot-grid.",
+  "useWhen": [
+    "Button or inline action is processing",
+    "Short indeterminate page or panel load",
+    "Waiting state with no known percent"
+  ],
+  "doNotUseWhen": [
+    "Square dot-grid compact wait — use LoadingAnimation",
+    "Assistant thinking — use ThinkingAnimation",
+    "Known percent completion — use Progress"
+  ],
+  "props": {
+    "size": {
+      "type": "enum",
+      "values": ["sm", "md", "lg"],
+      "default": "md"
+    },
+    "label": {
+      "type": "string",
+      "required": false,
+      "note": "Visible label beside the spinner. When omitted, aria-label is Loading."
+    }
+  },
+  "tokens": [
+    "icon.secondary",
+    "text.secondary",
+    "type.size.caption",
+    "type.size.label",
+    "type.size.bodySm",
+    "space.2",
+    "motion.duration600",
+    "motion.easeLinear"
+  ],
+  "a11y": {
+    "element": "span[role=status]",
+    "requirements": [
+      "role=status with aria-live=polite",
+      "aria-label Loading when label is omitted",
+      "Visible label is not duplicated in aria-label"
+    ]
+  },
+  "doNot": [
+    "Do not invent SpinnerIcon or merge Spinner into LoadingAnimation",
+    "Do not add Spinner as a LoadingAnimation variant",
+    "Do not change Button to accept spinner children",
+    "Do not use raw hex"
+  ],
+  "snippet": "<Spinner />\n<Spinner size=\"lg\" label=\"Processing payment…\" />\n<div style={{ display: \"flex\", gap: \"var(--space-2)\", alignItems: \"center\" }}><Spinner size=\"sm\" /><Button disabled>Loading…</Button></div>"
+}

package/contracts/switch.json

@@ -0,0 +1,94 @@
+{
+  "id": "switch",
+  "status": "stable",
+  "intent": "Immediate on/off setting. Pill track, role=switch. Not a Checkbox.",
+  "useWhen": [
+    "Settings rows (notifications, dark mode)",
+    "Binary preference that takes effect now"
+  ],
+  "doNotUseWhen": [
+    "Multi-select or agree-to-terms — use Checkbox",
+    "Choosing one of several options — use RadioGroup",
+    "Primary form submit actions — use Button"
+  ],
+  "props": {
+    "id": {
+      "type": "string",
+      "required": false,
+      "note": "useId fallback"
+    },
+    "label": {
+      "type": "string",
+      "required": false,
+      "note": "visible text; required unless ariaLabel is set"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "required when label is omitted"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "checked": {
+      "type": "boolean",
+      "required": false,
+      "note": "controlled"
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "default": false,
+      "note": "uncontrolled"
+    },
+    "onChange": {
+      "type": "function",
+      "required": false,
+      "note": "(checked: boolean) => void"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.disabled",
+    "action.primary",
+    "action.primaryHover",
+    "action.secondary",
+    "action.onPrimary",
+    "border.faint",
+    "border.strong",
+    "border.control",
+    "radius.pill",
+    "focus.ring",
+    "opacity.disabled",
+    "motion.modalDuration",
+    "motion.easeSpring"
+  ],
+  "a11y": {
+    "element": "button[role=switch]",
+    "requirements": [
+      "role=switch",
+      "aria-checked reflects on/off",
+      "Keyboard uses button defaults (Space/Enter)",
+      "focus-visible kit ring",
+      "Disabled state is exposed",
+      "Visible label via label/htmlFor OR ariaLabel when unlabeled"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Switch, Toggle, or ToggleGroup",
+    "Do not use Checkbox for instant settings",
+    "Do not use raw hex",
+    "Do not ship unlabeled without ariaLabel",
+    "Do not export Thumb or SwitchGroup"
+  ],
+  "snippet": "<Switch label=\"Notifications\" />\n<Switch ariaLabel=\"Dark mode\" />"
+}

package/contracts/table.json

@@ -0,0 +1,92 @@
+{
+  "id": "table",
+  "status": "stable",
+  "intent": "Simple semantic table for invoices, lists, and text rows. Search and filters belong on DataTable. One piece.",
+  "useWhen": [
+    "Listing invoices, products, or other short text rows",
+    "Inside Section on dashboard or list-detail patterns"
+  ],
+  "doNotUseWhen": [
+    "Search, filters, selection, or column settings — use DataTable",
+    "Layout for metrics — use Scoreboard",
+    "Forms — use Field and inputs"
+  ],
+  "props": {
+    "columns": {
+      "type": "array",
+      "itemShape": {
+        "key": "string",
+        "header": "string",
+        "align": "start | end?",
+        "numeric": "boolean?",
+        "emphasis": "boolean?"
+      },
+      "required": true,
+      "note": "numeric or align end right-aligns the column. emphasis or the first column is medium + text-primary."
+    },
+    "rows": {
+      "type": "array",
+      "itemShape": "Record<string, string | number | React.ReactNode>",
+      "required": true,
+      "note": "Values render in native td. ReactNode allowed so Actions can put kit DropdownMenu in a cell."
+    },
+    "caption": {
+      "type": "string",
+      "required": false,
+      "note": "Renders below the grid (caption-side bottom). Not a heading above the table."
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md",
+      "note": "md is compact: th 2.5rem, td padding space-2. sm a hair tighter, lg a hair roomier. Do not recreate DataTable 3–4rem rows."
+    },
+    "emptyLabel": {
+      "type": "string",
+      "default": "No results.",
+      "note": "Shown in one td with colSpan when rows is empty."
+    },
+    "footer": {
+      "type": "object",
+      "required": false,
+      "itemShape": {
+        "label": "string",
+        "value": "string | number"
+      },
+      "note": "Renders tfoot one row: label in a td colSpan={columns.length-1}, value in last td end-aligned."
+    }
+  },
+  "tokens": [
+    "surface.muted",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "border.faint",
+    "type.size.bodySm",
+    "type.weight.label",
+    "space.2",
+    "space.4",
+    "motion.interaction"
+  ],
+  "a11y": {
+    "element": "table",
+    "requirements": [
+      "Column headers in thead with th scope=col",
+      "Optional caption describes the table and sits below",
+      "Empty state is one td with colSpan=columns.length and emptyLabel",
+      "Optional footer is tfoot with label spanning leading columns and value end-aligned"
+    ]
+  },
+  "doNot": [
+    "Do not invent TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, or TableCaption cousins",
+    "Do not compose HeaderCell or Cell — those stay on DataTable",
+    "Search, filters, selection — use DataTable",
+    "Do not add @tanstack/react-table",
+    "Do not use raw hex"
+  ],
+  "snippet": "<Table caption=\"A list of your recent invoices.\" columns={[{ key: 'invoice', header: 'Invoice', emphasis: true }, { key: 'status', header: 'Status' }, { key: 'method', header: 'Method' }, { key: 'amount', header: 'Amount', numeric: true, align: 'end' }]} rows={[{ invoice: 'INV001', status: 'Paid', method: 'Credit Card', amount: '$250.00' }]} footer={{ label: 'Total', value: '$2,500.00' }} emptyLabel=\"No results.\" />"
+}

package/contracts/tabs.json

@@ -0,0 +1,90 @@
+{
+  "id": "tabs",
+  "status": "stable",
+  "intent": "Switch between related views in place. Segmented or line, in lg, md, and sm.",
+  "useWhen": [
+    "Grouped settings or detail sections on one page",
+    "Two to five peer views sharing one context",
+    "Compact local switching such as preview and code"
+  ],
+  "doNotUseWhen": [
+    "Top-level app routes \u2014 use AppNav",
+    "Mutually exclusive form values \u2014 use RadioGroup",
+    "Single panel content \u2014 use Section"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "itemShape": {
+        "id": "string",
+        "label": "string",
+        "content": "node",
+        "disabled": "boolean"
+      },
+      "required": true,
+      "minItems": 2
+    },
+    "value": {
+      "type": "string",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "variant": {
+      "type": "enum",
+      "values": [
+        "segmented",
+        "line"
+      ],
+      "default": "segmented"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "default": "Tabs"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "text.disabled",
+    "surface.muted",
+    "surface.card",
+    "border.faint",
+    "radius.control",
+    "shadow.raisedSm",
+    "focus.ring"
+  ],
+  "a11y": {
+    "element": "tablist",
+    "requirements": [
+      "Tab buttons control tabpanels",
+      "Active tab indicated visually and with aria-selected",
+      "Roving tabindex with arrow keys",
+      "Disabled tabs stay visible and are not selectable"
+    ]
+  },
+  "doNot": [
+    "Do not invent TabsList, TabsTrigger, or TabsContent cousins",
+    "Do not use raw hex",
+    "Do not use Tabs for main app navigation \u2014 use AppNav",
+    "Do not nest tabs inside tabs"
+  ],
+  "snippet": "<Tabs defaultValue=\"overview\" variant=\"segmented\" items={[{ id: 'overview', label: 'Overview', content: '\u2026' }, { id: 'docs', label: 'Docs', content: '\u2026' }]} />"
+}

package/contracts/textarea.json

@@ -0,0 +1,54 @@
+{
+  "id": "textarea",
+  "status": "stable",
+  "intent": "Multi-line text entry for notes and descriptions. Wrap with Field.",
+  "useWhen": [
+    "Paragraphs, notes, or descriptions",
+    "Inside Field when label, hint, or error are required"
+  ],
+  "doNotUseWhen": [
+    "Single-line values — use Input",
+    "One-time code — use InputOTP",
+    "Rich text or markdown editing — out of scope"
+  ],
+  "props": {
+    "id": { "type": "string", "required": true },
+    "size": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
+    "rows": { "type": "number", "required": false, "note": "optional native rows; height also comes from size" },
+    "placeholder": { "type": "string", "required": false },
+    "disabled": { "type": "boolean", "default": false },
+    "error": { "type": "boolean", "default": false },
+    "defaultValue": { "type": "string", "required": false },
+    "name": { "type": "string", "required": false },
+    "demo": { "type": "enum", "values": ["hover", "focus"], "required": false, "note": "playground only" }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "text.disabled",
+    "surface.card",
+    "surface.disabled",
+    "border.faint",
+    "border.strong",
+    "border.focus",
+    "border.disabled",
+    "status.danger",
+    "radius.control.md",
+    "radius.control.lg"
+  ],
+  "a11y": {
+    "element": "textarea",
+    "requirements": [
+      "Must have associated label via Field",
+      "aria-invalid when error",
+      "Disabled uses native disabled and does not resize"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Textarea",
+    "Do not bake Field label or hint into Textarea — wrap with Field",
+    "Do not add start/icon slots — those are Input",
+    "Do not use raw hex"
+  ],
+  "snippet": "<Field label=\"Notes\" htmlFor=\"notes\"><Textarea id=\"notes\" size=\"md\" placeholder=\"Add a note...\" /></Field>"
+}

package/contracts/thinkinganimation.json

@@ -0,0 +1,32 @@
+{
+  "id": "thinkinganimation",
+  "status": "stable",
+  "intent": "Calm processing indicator for assistants and short system waits.",
+  "useWhen": [
+    "Agent or assistant is actively working",
+    "Replace with real content when processing completes"
+  ],
+  "doNotUseWhen": [
+    "Determinate progress — use Progress",
+    "Blocking page load for entire view — use LoadingAnimation"
+  ],
+  "props": {
+    "label": { "type": "string", "default": "Thinking" },
+    "size": {
+      "type": "enum",
+      "values": ["sm", "md", "lg"],
+      "default": "md"
+    },
+    "showLabel": { "type": "boolean", "default": true }
+  },
+  "tokens": ["text.secondary", "text.muted"],
+  "a11y": {
+    "element": "span[role=status]",
+    "requirements": [
+      "role=status with aria-live=polite",
+      "aria-label describes the wait state"
+    ]
+  },
+  "doNot": ["Do not use raw hex", "Do not leave visible after work completes"],
+  "snippet": "<ThinkingAnimation label=\"Thinking\" size=\"md\" />"
+}

package/contracts/timeline.json

@@ -0,0 +1,49 @@
+{
+  "id": "timeline",
+  "status": "stable",
+  "intent": "Vertical sequence of now, next, and later for ordered multi-stage work.",
+  "useWhen": [
+    "Roadmaps and phased delivery",
+    "Status order matters more than dates or magnitudes"
+  ],
+  "doNotUseWhen": [
+    "Comparing values — use charts",
+    "Switching peer views — use Tabs",
+    "Numbered wizard or checkout steps — use ProgressSteps"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "required": false,
+      "note": "{ id?, title?, body?, phase?, status?: now|next|later }[]"
+    },
+    "label": { "type": "string", "required": false },
+    "headingLevel": {
+      "type": "enum",
+      "values": [2, 3, 4],
+      "default": 3
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "border.faint",
+    "border.strong",
+    "border.subtle"
+  ],
+  "a11y": {
+    "element": "ol",
+    "requirements": [
+      "Ordered list semantics",
+      "Optional aria-label on the list",
+      "One now step at a time in content"
+    ]
+  },
+  "doNot": [
+    "Do not invent TimelineItem cousins",
+    "Do not use Timeline for numbered wizard steps — use ProgressSteps",
+    "Do not use raw hex"
+  ],
+  "snippet": "<Timeline items={[{ status: 'now', title: 'Ship beta', body: 'Final QA this week' }]} />"
+}