agentic-ds-kit 0.1.0

package/contracts/input.json

@@ -0,0 +1,119 @@
+{
+  "id": "input",
+  "status": "stable",
+  "intent": "Single-line text entry for forms and filters. Optional start and end slots sit inside the field.",
+  "useWhen": [
+    "Collecting short text such as name, email, or search queries",
+    "Inside a Field wrapper when label, hint, or error messaging is needed"
+  ],
+  "doNotUseWhen": [
+    "One-time code or PIN \u2014 use InputOTP",
+    "Multi-line content \u2014 use Textarea",
+    "Choosing from fixed options \u2014 use Select or RadioGroup",
+    "Standalone labeled forms without Field \u2014 you must wire label association yourself"
+  ],
+  "props": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "type": {
+      "type": "enum",
+      "values": [
+        "text",
+        "email",
+        "password",
+        "search"
+      ],
+      "default": "text"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "default": "md"
+    },
+    "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
+    },
+    "start": {
+      "type": "string",
+      "required": false,
+      "note": "Prefix text inside the field on the left. Not a label."
+    },
+    "end": {
+      "type": "string",
+      "required": false,
+      "note": "Suffix text inside the field on the right. Not a label."
+    },
+    "iconStart": {
+      "type": "string",
+      "required": false,
+      "note": "Lucide catalog name on the left."
+    },
+    "iconEnd": {
+      "type": "string",
+      "required": false,
+      "note": "Lucide catalog name on the right."
+    },
+    "value": {
+      "type": "string",
+      "required": false,
+      "note": "controlled. When set, do not also rely on defaultValue."
+    },
+    "onChange": {
+      "type": "function",
+      "required": false,
+      "note": "(value: string) => void"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "When there is no Field label, such as search inside DropdownMenu."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "icon.muted",
+    "surface.card",
+    "surface.muted",
+    "border.faint",
+    "border.focus",
+    "status.danger"
+  ],
+  "a11y": {
+    "element": "input",
+    "requirements": [
+      "Must have associated label via Field or aria-label",
+      "error state should be described by Field error text"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Input variants or InputGroup",
+    "Do not use raw hex in styles",
+    "Do not use start or end as the accessible name \u2014 wrap with Field label",
+    "Do not use Lucide except via LucideByName from @/ui/Button/lucideName"
+  ],
+  "snippet": "<Field label=\"Website\" htmlFor=\"website\"><Input id=\"website\" start=\"https://\" placeholder=\"example.com\" /></Field>"
+}

package/contracts/inputotp.json

@@ -0,0 +1,119 @@
+{
+  "id": "inputotp",
+  "status": "stable",
+  "intent": "One-time code / PIN as separate slots. Paste and autocomplete work. Not a row of Inputs.",
+  "useWhen": [
+    "email/SMS verification, PIN, 2FA code"
+  ],
+  "doNotUseWhen": [
+    "normal text — Input",
+    "multi-line — Textarea",
+    "choosing options — Select/RadioGroup"
+  ],
+  "props": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "length": {
+      "type": "number",
+      "default": 6
+    },
+    "groups": {
+      "type": "number[]",
+      "required": false,
+      "note": "Slot counts per group; must sum to length. Default [3, 3] when length is 6, else [length]. Separator sits between groups only."
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "error": {
+      "type": "boolean",
+      "default": false
+    },
+    "value": {
+      "type": "string",
+      "required": false,
+      "note": "controlled"
+    },
+    "defaultValue": {
+      "type": "string",
+      "required": false,
+      "note": "uncontrolled"
+    },
+    "onChange": {
+      "type": "function",
+      "required": false,
+      "note": "(value: string) => void"
+    },
+    "onComplete": {
+      "type": "function",
+      "required": false,
+      "note": "fires when value.length === length"
+    },
+    "pattern": {
+      "type": "enum",
+      "values": [
+        "digits",
+        "alphanumeric"
+      ],
+      "default": "digits"
+    },
+    "name": {
+      "type": "string",
+      "required": false
+    },
+    "autoComplete": {
+      "type": "string",
+      "default": "one-time-code"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "required when not wrapped in Field"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "icon.muted",
+    "surface.card",
+    "border.faint",
+    "border.focus",
+    "border.strong",
+    "focus.ring",
+    "status.danger",
+    "opacity.disabled",
+    "radius.control.md",
+    "motion.duration.600",
+    "motion.ease.linear"
+  ],
+  "a11y": {
+    "element": "input",
+    "requirements": [
+      "Single native input so paste, autocomplete, and form submit work",
+      "id associates with Field htmlFor",
+      "Unlabeled needs Field or ariaLabel (default One-time code)",
+      "aria-invalid when error",
+      "Disabled is exposed on the input"
+    ]
+  },
+  "doNot": [
+    "Do not invent InputOTPGroup, InputOTPSlot, or InputOTPSeparator",
+    "Do not wrap kit Input N times",
+    "Do not add the input-otp package",
+    "Do not use raw hex",
+    "Do not use Lucide except via LucideByName from @/ui/Button/lucideName",
+    "Unlabeled needs Field or ariaLabel"
+  ],
+  "snippet": "<Field label=\"Verification code\" htmlFor=\"otp\"><InputOTP id=\"otp\" /></Field>"
+}

package/contracts/insightcard.json

@@ -0,0 +1,130 @@
+{
+  "id": "insightcard",
+  "status": "stable",
+  "intent": "A recommended insight or opportunity as a compact card, with tone and optional actions.",
+  "useWhen": [
+    "surface a recommendation, warning, or finding on a dashboard",
+    "next to Scorecards when the metric needs a suggested action"
+  ],
+  "doNotUseWhen": [
+    "one KPI number — Scorecard",
+    "login/settings tile — Card",
+    "inline page status — Alert",
+    "toast — not in kit, ask"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "description": {
+      "type": "string",
+      "required": false
+    },
+    "eyebrow": {
+      "type": "string",
+      "default": "Insight"
+    },
+    "tone": {
+      "type": "enum",
+      "values": [
+        "opportunity",
+        "warning",
+        "danger",
+        "info",
+        "neutral"
+      ],
+      "default": "opportunity"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "confidence": {
+      "type": "string",
+      "required": false,
+      "note": "e.g. High confidence"
+    },
+    "source": {
+      "type": "string",
+      "required": false,
+      "note": "e.g. From last 7 days"
+    },
+    "primaryAction": {
+      "type": "object",
+      "required": false,
+      "note": "kit Button primary. One primary per view.",
+      "label": {
+        "type": "string",
+        "required": true
+      },
+      "onClick": {
+        "type": "function",
+        "required": false
+      }
+    },
+    "secondaryAction": {
+      "type": "object",
+      "required": false,
+      "note": "kit Button secondary",
+      "label": {
+        "type": "string",
+        "required": true
+      },
+      "onClick": {
+        "type": "function",
+        "required": false
+      }
+    },
+    "onDismiss": {
+      "type": "function",
+      "required": false,
+      "note": "text Dismiss control, not a Button cousin"
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "border.highlight",
+    "border.faint",
+    "radius.surfaceMd",
+    "shadow.sm",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "icon.brand",
+    "icon.secondary",
+    "icon.warning",
+    "icon.danger",
+    "icon.info",
+    "space.4",
+    "space.6",
+    "space.8",
+    "type.size.heading",
+    "type.size.bodySm",
+    "type.size.caption",
+    "border.focus"
+  ],
+  "a11y": {
+    "element": "article",
+    "requirements": [
+      "title is h3 with useId",
+      "aria-labelledby",
+      "aria-describedby when description",
+      "tone icon aria-hidden",
+      "Dismiss is a button"
+    ]
+  },
+  "doNot": [
+    "Do not invent local InsightCard, Insight, or RecommendationCard",
+    "Do not use raw hex",
+    "Do not put a metric as the title (that is Scorecard)",
+    "Actions must be kit Buttons",
+    "One primary per view (the primaryAction is the one)"
+  ],
+  "snippet": "<InsightCard title=\"Rebook no-shows automatically\" description=\"Fill empty slots from the waitlist when clients cancel.\" tone=\"opportunity\" primaryAction={{ label: \"Review\" }} />"
+}

package/contracts/linechart.json

@@ -0,0 +1,51 @@
+{
+  "id": "linechart",
+  "status": "stable",
+  "intent": "Change and progress over ordered samples as a line or area chart.",
+  "useWhen": [
+    "Following a trajectory across time or sequence",
+    "Multi-series trends with shared labels"
+  ],
+  "doNotUseWhen": [
+    "Comparing unrelated magnitudes at one moment — use BarChart",
+    "Part-to-whole share — use PieChart"
+  ],
+  "props": {
+    "data": { "type": "array", "required": false },
+    "labels": { "type": "array", "required": false },
+    "series": { "type": "array", "required": false },
+    "title": { "type": "string", "required": false },
+    "description": { "type": "string", "required": false },
+    "variant": {
+      "type": "enum",
+      "values": ["line", "area"],
+      "default": "area"
+    },
+    "showGrid": { "type": "boolean", "default": true },
+    "showTable": { "type": "boolean", "default": true },
+    "includeZero": { "type": "boolean", "default": false },
+    "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 sample",
+      "Legend highlight emphasises one series",
+      "Table view keeps values readable"
+    ]
+  },
+  "doNot": [
+    "Do not invent chart container cousins",
+    "Do not use raw hex"
+  ],
+  "snippet": "<LineChart title=\"Weekly active users\" variant=\"area\" data={[{ label: 'Mon', value: 1240 }]} />"
+}

package/contracts/loadinganimation.json

@@ -0,0 +1,33 @@
+{
+  "id": "loadinganimation",
+  "status": "stable",
+  "intent": "Square dot-grid loading indicator for compact waits.",
+  "useWhen": [
+    "Panel or card content is loading",
+    "Short blocking fetches inside a region"
+  ],
+  "doNotUseWhen": [
+    "Assistant thinking state — use ThinkingAnimation",
+    "Determinate progress — use Progress"
+  ],
+  "props": {
+    "label": { "type": "string", "default": "Loading" },
+    "size": {
+      "type": "enum",
+      "values": ["sm", "md", "lg"],
+      "default": "md"
+    },
+    "variant": {
+      "type": "enum",
+      "values": ["grid"],
+      "default": "grid"
+    }
+  },
+  "tokens": ["surface.muted", "text.primary", "border.faint"],
+  "a11y": {
+    "element": "span[role=status]",
+    "requirements": ["role=status", "aria-label describes loading"]
+  },
+  "doNot": ["Do not use raw hex"],
+  "snippet": "<LoadingAnimation label=\"Loading\" size=\"md\" />"
+}

package/contracts/modal.json

@@ -0,0 +1,100 @@
+{
+  "id": "modal",
+  "status": "stable",
+  "intent": "Dismissible overlay for short tasks, forms, or extra detail. Composes ModalCard. Not a must-choose confirm.",
+  "useWhen": [
+    "Short forms",
+    "Extra detail",
+    "Command palettes",
+    "Anything that can be dismissed"
+  ],
+  "doNotUseWhen": [
+    "Must-choose confirm — use AlertDialog",
+    "Inline status — use Alert",
+    "Side panel — use Drawer",
+    "Full-page — use a route",
+    "Panel without overlay — use ModalCard",
+    "Passive help — use Tooltip"
+  ],
+  "props": {
+    "open": {
+      "type": "boolean",
+      "required": true
+    },
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "description": {
+      "type": "string",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "showClose": {
+      "type": "boolean",
+      "default": true
+    },
+    "onClose": {
+      "type": "function",
+      "required": true
+    },
+    "children": {
+      "type": "slot",
+      "required": true,
+      "note": "Body"
+    },
+    "footer": {
+      "type": "slot",
+      "required": false,
+      "note": "kit Buttons / ButtonGroup"
+    },
+    "contained": {
+      "type": "boolean",
+      "default": false,
+      "note": "In-canvas docs only. Product screens omit it (portal to document.body)."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "surface.overlay",
+    "surface.page",
+    "surface.muted",
+    "shadow.modal",
+    "radius.controlLg",
+    "border.focus",
+    "motion.overlay",
+    "motion.modal",
+    "icon.muted",
+    "icon.primary",
+    "z.overlay",
+    "z.modal"
+  ],
+  "a11y": {
+    "element": "dialog",
+    "requirements": [
+      "Composes ModalCard with role=dialog and aria-modal",
+      "Title is the accessible name, description is aria-describedby when present",
+      "Focus is trapped while open",
+      "Escape closes",
+      "Scrim click closes",
+      "Focus restores to the previously focused element on close",
+      "Unique ids via useId — do not hardcode modal-title"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Dialog, Modal, DialogTrigger, or CommandDialog",
+    "Do not use raw hex",
+    "Do not use AlertDialog for dismissible work",
+    "Do not skip the close control unless showClose is false AND footer/body still provide a way out. Scrim click and Escape still close."
+  ],
+  "snippet": "<Modal open={open} title=\"Edit profile\" description=\"Make changes to your profile.\" onClose={close} footer={<ButtonGroup ariaLabel=\"Modal actions\"><Button variant=\"secondary\" onClick={close}>Cancel</Button><Button variant=\"primary\" onClick={save}>Save</Button></ButtonGroup>}>...</Modal>"
+}

package/contracts/modalcard.json

@@ -0,0 +1,88 @@
+{
+  "id": "modalcard",
+  "status": "stable",
+  "intent": "The panel chrome for a modal (title, body, footer). Use inside Modal, or standalone in docs. Not a page Card.",
+  "useWhen": [
+    "The surface inside a Modal",
+    "Showing modal sizes in the catalog without an overlay"
+  ],
+  "doNotUseWhen": [
+    "Page tile — use Card",
+    "One KPI — use Scorecard",
+    "Recommended insight — use InsightCard",
+    "Overlay behavior — use Modal",
+    "Must-choose confirm — use AlertDialog"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "description": {
+      "type": "string",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "onClose": {
+      "type": "function",
+      "required": false,
+      "note": "X only when provided"
+    },
+    "children": {
+      "type": "slot",
+      "required": false,
+      "note": "Body"
+    },
+    "footer": {
+      "type": "slot",
+      "required": false,
+      "note": "kit Buttons / ButtonGroup"
+    }
+  },
+  "tokens": [
+    "surface.page",
+    "surface.muted",
+    "shadow.modal",
+    "radius.controlLg",
+    "text.primary",
+    "text.muted",
+    "icon.muted",
+    "icon.primary",
+    "border.focus",
+    "space.inset.md",
+    "space.inset.lg",
+    "space.inset.xl",
+    "space.stack.xs",
+    "space.inline.sm",
+    "type.size.body",
+    "type.size.bodySm",
+    "type.size.heading"
+  ],
+  "a11y": {
+    "element": "group",
+    "requirements": [
+      "role=group when standalone",
+      "When used inside Modal: role=dialog, aria-modal=true, tabIndex=-1",
+      "Title is the accessible name via aria-labelledby",
+      "description is aria-describedby when present",
+      "Close is a button with aria-label Close, only when onClose is set",
+      "Unique ids via useId"
+    ]
+  },
+  "doNot": [
+    "Do not invent local ModalCard, Dialog, or DialogContent",
+    "Do not use raw hex",
+    "Do not use Card, Scorecard, or InsightCard as modal chrome",
+    "Do not add a footer divider",
+    "Footer actions must be kit Buttons / ButtonGroup"
+  ],
+  "snippet": "<ModalCard title=\"Edit profile\" description=\"Make changes to your profile.\" footer={<ButtonGroup ariaLabel=\"Modal actions\"><Button variant=\"secondary\">Cancel</Button><Button variant=\"primary\">Save</Button></ButtonGroup>}>Make changes to your profile here.</ModalCard>"
+}