agentic-ds-kit 0.1.0

package/contracts/badge.json

@@ -0,0 +1,92 @@
+{
+  "id": "badge",
+  "status": "stable",
+  "intent": "Compact status or category pill.",
+  "useWhen": [
+    "Status badges on table rows or cards",
+    "Filtering labels and category markers"
+  ],
+  "doNotUseWhen": [
+    "Primary actions — use Button",
+    "Clickable navigation — use AppNav links",
+    "People or faces — use Avatar",
+    "Long sentences — use body text"
+  ],
+  "props": {
+    "children": {
+      "type": "string",
+      "required": true
+    },
+    "tone": {
+      "type": "enum",
+      "values": [
+        "neutral",
+        "brand",
+        "success",
+        "warning",
+        "danger",
+        "info"
+      ],
+      "default": "neutral"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "removable": {
+      "type": "boolean",
+      "default": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "onRemove": {
+      "type": "function",
+      "required": false,
+      "note": "used when removable"
+    }
+  },
+  "tokens": [
+    "surface.muted",
+    "surface.card",
+    "text.secondary",
+    "border.faint",
+    "border.focus",
+    "action.primary",
+    "status.success",
+    "status.successSubtle",
+    "status.successBorder",
+    "status.warning",
+    "status.warningSubtle",
+    "status.warningBorder",
+    "status.danger",
+    "status.dangerSubtle",
+    "status.dangerBorder",
+    "status.info",
+    "status.infoSubtle",
+    "status.infoBorder",
+    "radius.controlSm"
+  ],
+  "a11y": {
+    "element": "span",
+    "requirements": [
+      "Text content must be readable",
+      "disabled sets aria-disabled and prevents interaction",
+      "When removable, the X control is a button with aria-label Remove {children}",
+      "If removable and disabled, the remove control does not fire",
+      "Remove control shows a focus-visible ring using --border-focus"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Badge or Tag",
+    "Do not use raw hex",
+    "Do not use Badge as a button except the remove control"
+  ],
+  "snippet": "<Badge tone=\"info\" size=\"md\">In progress</Badge>"
+}

package/contracts/barchart.json

@@ -0,0 +1,55 @@
+{
+  "id": "barchart",
+  "status": "stable",
+  "intent": "Compare magnitudes across categories with vertical or horizontal bars.",
+  "useWhen": [
+    "Ranking values at a glance",
+    "Grouped comparisons with categories plus series"
+  ],
+  "doNotUseWhen": [
+    "Part-to-whole share — use PieChart",
+    "Change over time — use LineChart"
+  ],
+  "props": {
+    "data": {
+      "type": "array",
+      "required": false,
+      "note": "single-series flat array"
+    },
+    "categories": { "type": "array", "required": false },
+    "series": { "type": "array", "required": false },
+    "title": { "type": "string", "required": false },
+    "description": { "type": "string", "required": false },
+    "orientation": {
+      "type": "enum",
+      "values": ["vertical", "horizontal"],
+      "default": "vertical"
+    },
+    "showGrid": { "type": "boolean", "default": true },
+    "showTable": { "type": "boolean", "default": true },
+    "height": { "type": "number", "default": 240 },
+    "emptyLabel": { "type": "string", "default": "No data for this range" }
+  },
+  "tokens": [
+    "surface.card",
+    "text.primary",
+    "text.muted",
+    "border.faint",
+    "fill.brand"
+  ],
+  "a11y": {
+    "element": "figure",
+    "requirements": [
+      "Title on figure when provided",
+      "Hover reads the category",
+      "Legend highlight emphasises one series",
+      "Bars expose category and value in accessible names",
+      "Table view keeps values readable"
+    ]
+  },
+  "doNot": [
+    "Do not invent chart container cousins",
+    "Do not use raw hex"
+  ],
+  "snippet": "<BarChart title=\"Revenue by region\" data={[{ label: 'North', value: 2610 }]} />"
+}

package/contracts/breadcrumb.json

@@ -0,0 +1,76 @@
+{
+  "id": "breadcrumb",
+  "status": "stable",
+  "intent": "Path to the current page as a hierarchy of links.",
+  "useWhen": [
+    "show where this page sits in the app",
+    "sit above PageHeader or in a list-detail chrome"
+  ],
+  "doNotUseWhen": [
+    "page title block — use PageHeader",
+    "sidebar nav — use AppNav",
+    "in-page sections — use Tabs or Section"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "required": true,
+      "minItems": 2,
+      "itemShape": {
+        "label": {
+          "type": "string",
+          "required": true
+        },
+        "href": {
+          "type": "string",
+          "required": false
+        },
+        "onClick": {
+          "type": "function",
+          "required": false,
+          "note": "In-app select. When set, the crumb is a button. Last item is still the current page and is never a control."
+        }
+      },
+      "note": "Last item is the current page (no href used even if passed). Need at least 2 items."
+    },
+    "separator": {
+      "type": "enum",
+      "values": [
+        "chevron",
+        "slash"
+      ],
+      "default": "chevron",
+      "note": "chevron = Lucide ChevronRight. slash = text /."
+    },
+    "maxItems": {
+      "type": "number",
+      "required": false,
+      "note": "When items.length > maxItems, show the first item, an ellipsis, then the last (maxItems - 1) items. Ellipsis is aria-hidden, not interactive."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "icon.muted",
+    "border.focus",
+    "type.size.body-sm"
+  ],
+  "a11y": {
+    "element": "nav",
+    "requirements": [
+      "nav with aria-label=\"Breadcrumb\"",
+      "ordered list",
+      "current page has aria-current=\"page\" and is not a link",
+      "separators aria-hidden",
+      "collapsed ellipsis is aria-hidden and not interactive"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Breadcrumb, BreadcrumbItem, or BreadcrumbLink",
+    "Do not use raw hex",
+    "Do not turn the current page into a link",
+    "Do not put a dropdown on the ellipsis (no DropdownMenu in the kit)"
+  ],
+  "snippet": "<Breadcrumb items={[{ label: \"Home\", href: \"/\" }, { label: \"Components\", href: \"/components\" }, { label: \"Breadcrumb\" }]} />"
+}

package/contracts/button.json

@@ -0,0 +1,120 @@
+{
+  "id": "button",
+  "status": "stable",
+  "intent": "Clickable action control with a fixed set of sizes and visual variants.",
+  "useWhen": [
+    "Submitting a form or triggering a primary workflow action",
+    "Offering a secondary or tertiary action alongside content",
+    "Destructive actions that need explicit danger styling",
+    "Toolbar or compact actions with a Lucide icon and a visible label",
+    "Icon-only actions when space is tight and ariaLabel names the action"
+  ],
+  "doNotUseWhen": [
+    "Navigation that should be a link \u2014 use an anchor styled elsewhere",
+    "Icon-only without aria-label \u2014 icon-only must set ariaLabel",
+    "More than one primary button in the same view"
+  ],
+  "props": {
+    "size": {
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "default": "md"
+    },
+    "variant": {
+      "type": "enum",
+      "values": [
+        "primary",
+        "secondary",
+        "tertiary",
+        "danger"
+      ],
+      "default": "primary"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "children": {
+      "type": "string",
+      "required": false,
+      "note": "required unless icon-only"
+    },
+    "iconStart": {
+      "type": "string",
+      "required": false,
+      "note": "lucide-react export name from the Foundations catalog (Plus, ArrowRight, \u2026)"
+    },
+    "iconEnd": {
+      "type": "string",
+      "required": false,
+      "note": "lucide-react export name from the Foundations catalog (Plus, ArrowRight, \u2026)"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "required when children is omitted (icon-only)"
+    },
+    "onClick": {
+      "type": "function",
+      "required": false
+    },
+    "type": {
+      "type": "enum",
+      "values": [
+        "button",
+        "submit",
+        "reset"
+      ],
+      "default": "button"
+    },
+    "shape": {
+      "type": "enum",
+      "values": [
+        "default",
+        "pill"
+      ],
+      "default": "default",
+      "note": "pill uses radius-pill. Drawer footers use pill."
+    },
+    "block": {
+      "type": "boolean",
+      "default": false,
+      "note": "Full width of the parent."
+    }
+  },
+  "tokens": [
+    "text.inverse",
+    "text.primary",
+    "text.secondary",
+    "surface.card",
+    "surface.muted",
+    "border.faint",
+    "action.primary",
+    "action.primaryHover",
+    "action.danger",
+    "action.dangerHover",
+    "icon.default",
+    "radius.pill"
+  ],
+  "a11y": {
+    "element": "button",
+    "requirements": [
+      "Visible label via children, OR aria-label for icon-only",
+      "Decorative icons are aria-hidden",
+      "disabled sets aria-disabled and prevents interaction",
+      "Focus ring must be visible on keyboard focus"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Button variants outside the enum",
+    "Do not use raw hex colors in styles",
+    "Do not place more than one variant=primary Button in a single view",
+    "Do not pass custom SVG or React nodes as icons \u2014 use lucide-react export names on iconStart/iconEnd",
+    "Do not ship icon-only without ariaLabel"
+  ],
+  "snippet": "<Button variant=\"primary\" size=\"md\">Save changes</Button>\n<Button variant=\"secondary\" iconStart=\"Plus\">Add</Button>"
+}

package/contracts/buttongroup.json

@@ -0,0 +1,48 @@
+{
+  "id": "buttongroup",
+  "status": "stable",
+  "intent": "Joined row of kit Buttons that share one size and act as one control cluster.",
+  "useWhen": [
+    "Related sibling actions such as a view switch",
+    "Split confirm/cancel pairs that should read as one cluster",
+    "A toolbar of same-size Buttons"
+  ],
+  "doNotUseWhen": [
+    "Unrelated actions that should stay separate Buttons",
+    "Wrapping non-Button controls",
+    "Nesting groups",
+    "paging a list — use Pagination"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "required": true,
+      "note": "only kit Button nodes, same size, 2+"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "names the group"
+    }
+  },
+  "tokens": [
+    "border.faint",
+    "radius.md"
+  ],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "role=group",
+      "optional aria-label names the group",
+      "Buttons keep their own names"
+    ]
+  },
+  "doNot": [
+    "Do not invent a local button group / segmented control",
+    "Do not mix sizes inside one group",
+    "Do not put more than one variant=primary Button in a group (or the view)",
+    "Do not wrap Input, Select, or anything except kit Button",
+    "Do not use raw hex"
+  ],
+  "snippet": "<ButtonGroup ariaLabel=\"Plan period\"><Button variant=\"secondary\" size=\"md\">Day</Button><Button variant=\"secondary\" size=\"md\">Week</Button><Button variant=\"secondary\" size=\"md\">Month</Button></ButtonGroup>"
+}

package/contracts/calendar.json

@@ -0,0 +1,93 @@
+{
+  "id": "calendar",
+  "status": "stable",
+  "intent": "Month grid for picking one date.",
+  "useWhen": [
+    "Booking, scheduling, or choosing a single calendar day",
+    "A date field\u2019s overlay content"
+  ],
+  "doNotUseWhen": [
+    "Time-only \u2014 ask first",
+    "A typed date field without a grid \u2014 use Input type=date or ask",
+    "Range of dates \u2014 not in this contract, ask first",
+    "A form date field \u2014 use DatePicker"
+  ],
+  "props": {
+    "value": {
+      "type": "string",
+      "required": false,
+      "note": "controlled YYYY-MM-DD"
+    },
+    "defaultValue": {
+      "type": "string",
+      "required": false,
+      "note": "uncontrolled YYYY-MM-DD"
+    },
+    "onValueChange": {
+      "type": "function",
+      "required": false,
+      "note": "(date: string) => void // ISO date"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "minDate": {
+      "type": "string",
+      "required": false,
+      "note": "YYYY-MM-DD inclusive lower bound"
+    },
+    "maxDate": {
+      "type": "string",
+      "required": false,
+      "note": "YYYY-MM-DD inclusive upper bound"
+    }
+  },
+  "tokens": [
+    "surface.page",
+    "surface.card",
+    "surface.muted",
+    "text.primary",
+    "text.muted",
+    "text.inverse",
+    "border.faint",
+    "border.strong",
+    "border.focus",
+    "action.primary",
+    "action.onPrimary",
+    "radius.surfaceMd",
+    "radius.controlSm",
+    "shadow.sm",
+    "opacity.disabled",
+    "opacity.muted"
+  ],
+  "a11y": {
+    "element": "div[role=grid]",
+    "requirements": [
+      "role=grid for the month days",
+      "Heading names the visible month and uses aria-live polite",
+      "Previous and next month controls have aria-labels",
+      "Selected day is aria-selected",
+      "Today is announced in the day accessible name",
+      "Disabled days are not selectable",
+      "Keyboard arrows move day focus (roving tabindex)"
+    ]
+  },
+  "doNot": [
+    "Do not invent a local calendar",
+    "Do not use raw hex",
+    "Do not use Calendar as a form field \u2014 use DatePicker",
+    "Do not add range selection in this contract",
+    "Do not replace nav with custom icon buttons \u2014 use kit Buttons"
+  ],
+  "snippet": "<Calendar size=\"md\" defaultValue=\"2026-08-29\" onValueChange={(date) => setDate(date)} />"
+}

package/contracts/card.json

@@ -0,0 +1,123 @@
+{
+  "id": "card",
+  "status": "stable",
+  "intent": "Framed tile with optional header, body, and footer actions.",
+  "useWhen": [
+    "Login or settings tiles",
+    "Feature summaries",
+    "Grouped content that should sit on a card surface"
+  ],
+  "doNotUseWhen": [
+    "Page-level grouping — use Section",
+    "One KPI — use Scorecard",
+    "Dialogs — use Modal or AlertDialog",
+    "Recommended insight — use InsightCard"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": false
+    },
+    "description": {
+      "type": "string",
+      "required": false
+    },
+    "children": {
+      "type": "slot",
+      "required": true,
+      "note": "Body. Compose kit Field/Input/Button/Badge/etc, never a local cousin"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md"
+      ],
+      "default": "md"
+    },
+    "headerAction": {
+      "type": "object",
+      "required": false,
+      "note": "Header kit Button (shadcn CardAction). One max. Tertiary or secondary, not a second primary.",
+      "label": {
+        "type": "string",
+        "required": true
+      },
+      "variant": {
+        "type": "enum",
+        "values": [
+          "primary",
+          "secondary",
+          "tertiary",
+          "danger"
+        ],
+        "required": false
+      },
+      "onClick": {
+        "type": "function",
+        "required": false
+      }
+    },
+    "actions": {
+      "type": "array",
+      "required": false,
+      "note": "Footer kit Buttons, max 2, still one primary per view",
+      "items": {
+        "label": {
+          "type": "string",
+          "required": true
+        },
+        "variant": {
+          "type": "enum",
+          "values": [
+            "primary",
+            "secondary",
+            "tertiary",
+            "danger"
+          ],
+          "required": false
+        },
+        "onClick": {
+          "type": "function",
+          "required": false
+        }
+      }
+    },
+    "imageSrc": {
+      "type": "string",
+      "required": false
+    },
+    "imageAlt": {
+      "type": "string",
+      "required": false,
+      "note": "Required when imageSrc is set"
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "border.faint",
+    "radius.surfaceMd",
+    "shadow.sm",
+    "text.primary",
+    "text.secondary",
+    "space.6",
+    "space.4",
+    "space.2"
+  ],
+  "a11y": {
+    "element": "article",
+    "requirements": [
+      "title is heading when set (use useId)",
+      "aria-labelledby when title exists"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Card, Panel, or Tile",
+    "Do not use raw hex",
+    "Do not use Card as a Scorecard-in-disguise — do not put a lone metric here",
+    "Footer actions must be kit Buttons",
+    "Do not invent CardHeader components",
+    "headerAction is tertiary/secondary, not a second primary"
+  ],
+  "snippet": "<Card title=\"Login to your account\" description=\"Enter your email below to login to your account.\" headerAction={{ label: \"Sign Up\", variant: \"tertiary\" }} actions={[{ label: \"Login\", variant: \"primary\" }, { label: \"Login with Google\", variant: \"secondary\" }]}><Field label=\"Name\" htmlFor=\"name\"><Input id=\"name\" placeholder=\"Boris Jovanovic\" /></Field><Field label=\"Email\" htmlFor=\"email\"><Input id=\"email\" type=\"email\" /></Field><Field label=\"Password\" htmlFor=\"password\" hint=\"Forgot your password?\"><Input id=\"password\" type=\"password\" /></Field><Field label=\"Workspace\" htmlFor=\"workspace\"><Input id=\"workspace\" placeholder=\"Studio\" /></Field></Card>"
+}