agentic-ds-kit 0.1.0

package/contracts/navigationmenu.json

@@ -0,0 +1,65 @@
+{
+  "id": "navigationmenu",
+  "status": "stable",
+  "intent": "Horizontal site nav. Dropdowns are kit DropdownMenu. Not SideNav. Not AppNav.",
+  "useWhen": [
+    "Top-of-page site navigation with links and dropdowns",
+    "A horizontal bar of destinations, some of which open a menu"
+  ],
+  "doNotUseWhen": [
+    "Vertical product chrome — use SideNav",
+    "Playground catalog list — use AppNav",
+    "Path to the current page — use Breadcrumb",
+    "In-page panels — use Tabs",
+    "Actions from a button — use DropdownMenu",
+    "Product top bar with logo and search — use AppHeader"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "required": true,
+      "itemShape": {
+        "id": "string",
+        "label": "string",
+        "href": "string? link items",
+        "active": "boolean? link items",
+        "groups": "DropdownMenuGroup[]? dropdown items — presence of groups means dropdown",
+        "columns": "1 | 2? dropdown items, default 1"
+      },
+      "note": "A dropdown item is detected by groups. A link item has href and no groups."
+    },
+    "onSelect": {
+      "type": "function",
+      "required": false,
+      "note": "(id: string) => void"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "surface.muted",
+    "radius.control.md",
+    "focus.ring",
+    "type.size.body-sm",
+    "type.weight.label"
+  ],
+  "a11y": {
+    "element": "nav",
+    "requirements": [
+      "nav with aria-label",
+      "Link items are a with aria-current=page when active",
+      "Dropdowns are kit DropdownMenu with triggerStyle=nav",
+      "Only one dropdown open at a time"
+    ]
+  },
+  "doNot": [
+    "Do not invent NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink, NavigationMenuViewport, or NavigationMenuIndicator",
+    "Do not use radix or @base-ui/react navigation-menu",
+    "Do not use native select or details for dropdowns — use kit DropdownMenu",
+    "Do not use SideNav or AppNav for horizontal site nav",
+    "Do not use raw hex"
+  ],
+  "contains": [
+    "dropdownmenu"
+  ],
+  "snippet": "<NavigationMenu items={[{ id: \"home\", label: \"Home\", href: \"/\", active: true }, { id: \"docs\", label: \"Docs\", groups: [{ items: [{ id: \"intro\", label: \"Introduction\", href: \"/docs\" }] }] }]} />"
+}

package/contracts/numbertransition.json

@@ -0,0 +1,33 @@
+{
+  "id": "numbertransition",
+  "status": "stable",
+  "intent": "Rolling number treatment for live metrics and counters.",
+  "useWhen": [
+    "Dashboard metrics that update in place",
+    "Animated count-ups with tabular numerals"
+  ],
+  "doNotUseWhen": [
+    "Static labels without changing values",
+    "Non-numeric copy"
+  ],
+  "props": {
+    "value": { "type": "number|string", "required": true },
+    "format": { "type": "function", "required": false },
+    "size": {
+      "type": "enum",
+      "values": ["sm", "md", "lg"],
+      "default": "md"
+    },
+    "label": { "type": "string", "required": false }
+  },
+  "tokens": ["text.primary"],
+  "a11y": {
+    "element": "span",
+    "requirements": [
+      "aria-live=polite",
+      "aria-label mirrors formatted value when label omitted"
+    ]
+  },
+  "doNot": ["Do not use raw hex"],
+  "snippet": "<NumberTransition value={12840} format={(n) => n.toLocaleString()} />"
+}

package/contracts/pageheader.json

@@ -0,0 +1,101 @@
+{
+  "id": "pageheader",
+  "status": "stable",
+  "intent": "Top-of-page title with optional Breadcrumb trail, subtitle, and actions.",
+  "useWhen": [
+    "Product page title with optional Breadcrumb trail and actions",
+    "Placing primary/secondary Buttons aligned to the page title"
+  ],
+  "doNotUseWhen": [
+    "In-card titles — use Section",
+    "Sidebar — use AppNav or SideNav",
+    "Product top chrome with logo and search — use AppHeader",
+    "Modal titles — use ModalCard",
+    "Path-only without a page title — use Breadcrumb"
+  ],
+  "contains": [
+    "breadcrumb",
+    "button"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "subtitle": {
+      "type": "string",
+      "required": false
+    },
+    "eyebrow": {
+      "type": "string",
+      "required": false,
+      "note": "Kept for existing call sites. Breadcrumbs replace eyebrow as the default where-am-I."
+    },
+    "actions": {
+      "type": "slot",
+      "allowedContracts": [
+        "button"
+      ],
+      "required": false,
+      "note": "kit Buttons. At most one primary."
+    },
+    "breadcrumbs": {
+      "type": "array",
+      "required": false,
+      "itemShape": {
+        "label": {
+          "type": "string",
+          "required": true
+        },
+        "href": {
+          "type": "string",
+          "required": false
+        },
+        "onClick": {
+          "type": "function",
+          "required": false,
+          "note": "Passed through to kit Breadcrumb."
+        }
+      },
+      "note": "Same shape as Breadcrumb items. Rendered only when length >= 2. Passed through to kit Breadcrumb."
+    },
+    "breadcrumbSeparator": {
+      "type": "enum",
+      "values": [
+        "chevron",
+        "slash"
+      ],
+      "default": "chevron",
+      "note": "Passed through to kit Breadcrumb separator."
+    },
+    "breadcrumbMaxItems": {
+      "type": "number",
+      "required": false,
+      "note": "Passed through to kit Breadcrumb maxItems."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "type.size.title",
+    "type.size.body",
+    "space.3",
+    "space.4"
+  ],
+  "a11y": {
+    "element": "header",
+    "requirements": [
+      "Page title is h1",
+      "Composed Breadcrumb keeps nav aria-label=Breadcrumb",
+      "Actions remain keyboard accessible"
+    ]
+  },
+  "doNot": [
+    "Do not invent local PageHeader",
+    "Do not invent BreadcrumbItem or BreadcrumbLink cousins — compose kit Breadcrumb",
+    "Do not restyle Breadcrumb internals from PageHeader",
+    "Do not use raw hex",
+    "Do not put more than one primary Button in actions"
+  ],
+  "snippet": "<PageHeader title=\"Aurora\" subtitle=\"Campaign settings and collaborators.\" breadcrumbs={[{ label: \"Home\", href: \"#\" }, { label: \"Projects\", href: \"#\" }, { label: \"Aurora\" }]} actions={<><Button variant=\"secondary\">Edit</Button><Button>Save</Button></>} />"
+}

package/contracts/pagination.json

@@ -0,0 +1,85 @@
+{
+  "id": "pagination",
+  "status": "stable",
+  "intent": "Page navigation with previous, next, page numbers, and ellipsis. Not ButtonGroup. Not Tabs.",
+  "useWhen": [
+    "tables",
+    "long lists",
+    "search results"
+  ],
+  "doNotUseWhen": [
+    "in-page panels — Tabs",
+    "a pair of sibling actions — ButtonGroup"
+  ],
+  "contains": [
+    "button"
+  ],
+  "props": {
+    "page": {
+      "type": "number",
+      "required": false,
+      "note": "controlled 1-based. Controlled when page is a number."
+    },
+    "defaultPage": {
+      "type": "number",
+      "default": 1,
+      "note": "uncontrolled initial page"
+    },
+    "pageCount": {
+      "type": "number",
+      "required": true,
+      "note": ">= 1"
+    },
+    "onPageChange": {
+      "type": "function",
+      "required": false,
+      "note": "(page: number) => void"
+    },
+    "showPages": {
+      "type": "boolean",
+      "default": true,
+      "note": "false shows Previous/Next only (icons-only when showLabels is also false)"
+    },
+    "showLabels": {
+      "type": "boolean",
+      "default": true,
+      "note": "Previous / Next text next to chevrons. Icon-only uses ariaLabel."
+    },
+    "showPreviousNext": {
+      "type": "boolean",
+      "default": true,
+      "note": "false hides Previous/Next (Simple: page numbers only)"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md"
+      ],
+      "default": "md",
+      "note": "passed to kit Button"
+    }
+  },
+  "tokens": [
+    "space.1",
+    "icon.muted"
+  ],
+  "a11y": {
+    "element": "nav",
+    "requirements": [
+      "nav with aria-label=\"Pagination\"",
+      "Previous disabled on page 1",
+      "Next disabled on last page",
+      "current page uses kit Button variant=secondary and aria-current=page",
+      "ellipsis is a span with Lucide Ellipsis, aria-hidden, not a Button",
+      "icon-only Previous/Next set ariaLabel"
+    ]
+  },
+  "doNot": [
+    "no PaginationContent/Item/Link/Previous/Next/Ellipsis cousins",
+    "do not use raw hex",
+    "do not use ButtonGroup for paging",
+    "page numbers are kit Button"
+  ],
+  "snippet": "<Pagination page={2} pageCount={10} onPageChange={() => {}} />"
+}

package/contracts/patterns/activity.json

@@ -0,0 +1,30 @@
+{
+  "id": "activity",
+  "status": "stable",
+  "intent": "Activity blueprint: PageHeader, Scoreboard, task cards or list, and a tabbed DataTable feed.",
+  "contains": [
+    "pageheader",
+    "scoreboard",
+    "section",
+    "carousel",
+    "insightcard",
+    "table",
+    "badge",
+    "buttongroup",
+    "button",
+    "empty",
+    "tabs",
+    "datatable",
+    "drawer",
+    "avatar",
+    "progress"
+  ],
+  "doNot": [
+    "Do not invent a local activity feed, task carousel, or schedule grid",
+    "Do not skip Scoreboard for the metrics strip",
+    "Do not put a month calendar on this page",
+    "Do not add more than one primary Button",
+    "Do not restyle kit components inside the pattern"
+  ],
+  "snippet": "<ActivityPattern />"
+}

package/contracts/patterns/assistant-workspace.json

@@ -0,0 +1,16 @@
+{
+  "id": "assistant-workspace",
+  "status": "stable",
+  "intent": "Workspace with two-column InsightCards and an inline Chat rail.",
+  "contains": ["pageheader", "section", "insightcard", "chat", "button"],
+  "doNot": [
+    "Do not put Chat in a Modal",
+    "Do not invent a local assistant rail or insight stack",
+    "Do not skip layout-workspace for the rail",
+    "Do not skip layout-split for the InsightCards",
+    "Do not skip Chat radius none for the rail",
+    "Do not give InsightCards primaryAction while Chat is open — Chat Send is the one primary",
+    "Do not restyle Chat or InsightCard"
+  ],
+  "snippet": "<AssistantWorkspacePattern />"
+}

package/contracts/patterns/dashboard.json

@@ -0,0 +1,12 @@
+{
+  "id": "dashboard",
+  "status": "stable",
+  "intent": "Overview dashboard: page title, KPI strip, and chart plus task table in Sections.",
+  "contains": ["pageheader", "scoreboard", "linechart", "section", "datatable"],
+  "doNot": [
+    "Do not restyle kit components inside the pattern",
+    "Do not define a local dashboard layout component",
+    "Do not invent a local table, filter bar, or chart wrapper"
+  ],
+  "snippet": "<DashboardPattern />"
+}

package/contracts/patterns/empty-first-run.json

@@ -0,0 +1,15 @@
+{
+  "id": "empty-first-run",
+  "status": "stable",
+  "intent": "First-run page: PageHeader, outlined Empty, and one primary that opens a create Modal.",
+  "contains": ["pageheader", "empty", "modal", "field", "input", "button", "buttongroup", "toast"],
+  "doNot": [
+    "Do not invent a local empty stack, illustration, or create dialog",
+    "Do not use AlertDialog for a dismissible first create",
+    "Do not skip Field wrappers on labeled inputs",
+    "Do not wrap a single Field in FieldSet",
+    "Do not add more than one primary Button",
+    "Do not put a primary on PageHeader while Empty already has one"
+  ],
+  "snippet": "<EmptyFirstRunPattern />"
+}

package/contracts/patterns/inbox.json

@@ -0,0 +1,32 @@
+{
+  "id": "inbox",
+  "status": "stable",
+  "intent": "Inbox blueprint: PageHeader, Scoreboard, tabbed Table, detail Section, and a reply Drawer.",
+  "contains": [
+    "pageheader",
+    "scoreboard",
+    "section",
+    "tabs",
+    "table",
+    "cell",
+    "badge",
+    "button",
+    "empty",
+    "drawer",
+    "fieldset",
+    "field",
+    "input",
+    "textarea",
+    "toast",
+    "avatar"
+  ],
+  "doNot": [
+    "Do not invent a local inbox row, from stack, or reply dialog",
+    "Do not skip Cell type=avatar for the From column",
+    "Do not use AlertDialog for a dismissible reply",
+    "Do not skip Field wrappers on labeled inputs",
+    "Do not add more than one primary Button",
+    "Do not restyle kit components inside the pattern"
+  ],
+  "snippet": "<InboxPattern />"
+}

package/contracts/patterns/invite-members.json

@@ -0,0 +1,14 @@
+{
+  "id": "invite-members",
+  "status": "stable",
+  "intent": "Invite overlay: empty team state, AvatarGroup, and a dismissible Modal with FieldSet.",
+  "contains": ["pageheader", "empty", "avatargroup", "modal", "fieldset", "field", "input", "radiogroup", "button", "buttongroup", "toast"],
+  "doNot": [
+    "Do not invent a local dialog, invite form, or member stack",
+    "Do not use AlertDialog for a dismissible invite",
+    "Do not skip Field wrappers on labeled inputs",
+    "Do not wrap RadioGroup in Field — it has its own legend",
+    "Do not add more than one primary Button"
+  ],
+  "snippet": "<InviteMembersPattern />"
+}

package/contracts/patterns/list-detail.json

@@ -0,0 +1,13 @@
+{
+  "id": "list-detail",
+  "status": "stable",
+  "intent": "List-detail shell: sidebar nav, table list, and detail section.",
+  "contains": ["pageheader", "appnav", "table", "section", "badge"],
+  "doNot": [
+    "Do not restyle AppNav or Table",
+    "Do not replace Table with custom list markup",
+    "Do not add a local sidebar component",
+    "Do not use Tabs instead of AppNav for route-level sections"
+  ],
+  "snippet": "<ListDetailPattern />"
+}

package/contracts/patterns/settings-form.json

@@ -0,0 +1,13 @@
+{
+  "id": "settings-form",
+  "status": "stable",
+  "intent": "Settings page blueprint: header, grouped fields, and save/cancel actions.",
+  "contains": ["pageheader", "section", "field", "input", "select", "checkbox", "button", "toast"],
+  "doNot": [
+    "Do not restyle Field or Input inside the pattern",
+    "Do not invent local form layouts",
+    "Do not skip Field wrappers on labeled inputs",
+    "Do not add more than one primary Button"
+  ],
+  "snippet": "<SettingsFormPattern />"
+}

package/contracts/piechart.json

@@ -0,0 +1,68 @@
+{
+  "id": "piechart",
+  "status": "stable",
+  "intent": "Part-to-whole share for a handful of segments, as a donut or solid pie.",
+  "useWhen": [
+    "Rough share at a glance for up to six segments",
+    "Dashboard tiles where proportion matters more than precise ranking"
+  ],
+  "doNotUseWhen": [
+    "Comparing close values — use BarChart",
+    "Change over time — use LineChart",
+    "More than six segments without folding into Other"
+  ],
+  "props": {
+    "data": {
+      "type": "array",
+      "required": false,
+      "note": "{ label: string, value: number, color?: string }[]"
+    },
+    "title": { "type": "string", "required": false },
+    "description": { "type": "string", "required": false },
+    "variant": {
+      "type": "enum",
+      "values": ["donut", "pie"],
+      "default": "donut"
+    },
+    "layout": {
+      "type": "enum",
+      "values": ["split", "stack"],
+      "default": "split"
+    },
+    "showCenterTotal": { "type": "boolean", "default": true },
+    "showTable": { "type": "boolean", "default": true },
+    "sort": { "type": "boolean", "default": true },
+    "maxSegments": { "type": "number", "default": 6 },
+    "emptyLabel": { "type": "string", "default": "No data for this range" }
+  },
+  "tokens": [
+    "surface.card",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "fill.brand",
+    "fill.success",
+    "fill.warning",
+    "fill.danger",
+    "fill.info",
+    "border.faint",
+    "radius.surface",
+    "shadow.md",
+    "focus-ring"
+  ],
+  "a11y": {
+    "element": "figure",
+    "requirements": [
+      "Title exposed on the figure when provided",
+      "Slices expose name, value, and percent on the hit target",
+      "Legend highlight matches slice hover; tooltip is supplementary",
+      "Table toggle keeps values readable in table view"
+    ]
+  },
+  "doNot": [
+    "Do not invent local chart wrappers",
+    "Do not use raw hex",
+    "Do not add chart-library compound APIs"
+  ],
+  "snippet": "<PieChart title=\"Properties by status\" variant=\"donut\" data={[{ label: 'Listed', value: 256 }]} />"
+}

package/contracts/progress.json

@@ -0,0 +1,124 @@
+{
+  "id": "progress",
+  "status": "stable",
+  "intent": "Task completion as a bar or circle from 0 to 100. One piece. Optional name label. Percent overlay, end, or in the ring hole. Tones brand, danger, muted. Sizes sm, md, lg. Fill grows once on load.",
+  "useWhen": [
+    "Upload, import, or task completion",
+    "A determinate percent in a form, card, or page",
+    "A determinate percent as a ring or semicircle",
+    "DataTable Cell type=progress (Cell composes this)"
+  ],
+  "doNotUseWhen": [
+    "A spinner with no known percent \u2014 not this component",
+    "A rating out of 5 \u2014 that stays a Cell type",
+    "A KPI number \u2014 use Scorecard",
+    "Part-to-whole share across segments \u2014 use PieChart",
+    "Numbered wizard or checkout steps \u2014 use ProgressSteps"
+  ],
+  "props": {
+    "value": {
+      "type": "number",
+      "default": 0,
+      "note": "0 to 100. Clamped."
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md",
+      "note": "Bar track height: sm is space-1, md is space-2, lg is space-3. Overlay uses space-5. Circle and semicircle: sm 56, md 96, lg 196."
+    },
+    "shape": {
+      "type": "enum",
+      "values": [
+        "bar",
+        "circle",
+        "semicircle"
+      ],
+      "default": "bar",
+      "note": "bar is the track. circle is a donut ring. semicircle is a bottom U gauge: 0 to 100 maps onto 180 degrees, not a cropped 360 degree ring. Same piece. Size sets the ring, not bar height."
+    },
+    "label": {
+      "type": "string",
+      "required": false,
+      "note": "Visible name above the track. Prefer this over ProgressLabel."
+    },
+    "showValue": {
+      "type": "boolean",
+      "default": false,
+      "note": "Shows the rounded percent. Overlay sits on the bar. End sits after the bar, or in meta when a name label is set. Circle puts it in the hole. Semicircle puts it in the bowl."
+    },
+    "valuePosition": {
+      "type": "enum",
+      "values": [
+        "overlay",
+        "end"
+      ],
+      "default": "end",
+      "note": "Bar only. overlay centers the percent on the track. end puts it after the bar, or opposite a name label in the meta row. Circle uses the hole. Semicircle uses the bowl."
+    },
+    "tone": {
+      "type": "enum",
+      "values": [
+        "brand",
+        "danger",
+        "muted"
+      ],
+      "default": "brand"
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "Required when label is omitted. Cell passes the percent or its label."
+    }
+  },
+  "tokens": [
+    "fill.brand",
+    "fill.brandSubtle",
+    "fill.danger",
+    "fill.dangerSubtle",
+    "fill.subtle",
+    "fill.strong",
+    "text.primary",
+    "surface.card",
+    "radius.full",
+    "radius.controlSm",
+    "space.1",
+    "space.2",
+    "space.3",
+    "space.5",
+    "type.size.bodySm",
+    "type.size.caption",
+    "type.weight.label",
+    "motion.interactionDuration",
+    "motion.duration400",
+    "motion.easeOut"
+  ],
+  "a11y": {
+    "element": "div[role=progressbar]",
+    "requirements": [
+      "role=progressbar on the track or ring",
+      "aria-valuemin 0, aria-valuemax 100, aria-valuenow rounded percent",
+      "aria-valuetext is '{n}%'",
+      "Visible label uses aria-labelledby; unlabeled needs ariaLabel"
+    ]
+  },
+  "doNot": [
+    "Do not invent ProgressLabel, ProgressValue, ProgressTrack, ProgressIndicator, or ProgressRoot",
+    "Do not invent MeterCircle or ProgressCircle",
+    "Do not use PieChart for a determinate percent ring",
+    "Do not use img assets for the ring",
+    "Do not add threshold-zone rings, datatip, or reference lines",
+    "Do not use radix or @base-ui/react",
+    "Do not use a native progress element",
+    "Do not use raw hex",
+    "Do not add indeterminate",
+    "Do not add a multi-segment status bar",
+    "Do not use Progress for ordered wizard steps — use ProgressSteps",
+    "Do not skip prefers-reduced-motion on the load animation"
+  ],
+  "snippet": "<Progress value={33} />\n<Progress value={56} label=\"Upload progress\" showValue />\n<Progress value={50} showValue valuePosition=\"overlay\" />\n<Progress value={50} showValue tone=\"danger\" />\n<Progress value={50} shape=\"circle\" showValue />"
+}