agentic-ds-kit 0.1.0

package/AGENTS.md

@@ -0,0 +1,10 @@
+# Kit rules
+
+Before writing UI, read this package's `contracts/index.json`, then only the matching contract file(s).
+If a contract exists, import the kit component from `agentic-ds-kit`. Never invent a local cousin.
+If a pattern in `contracts/patterns/` matches the screen, import it from `agentic-ds-kit`.
+If something is missing from the index, stop and ask — do not add a one-off.
+Never put hex in components; use semantic tokens from `agentic-ds-kit/tokens.css` (not primitive `--color-*` ramps).
+One `variant="primary"` Button per view.
+
+Copy this file to your app root as `AGENTS.md` (and `CLAUDE.md` with `@AGENTS.md`) so Cursor and Claude Code load it.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boris Jovanovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# agentic-ds-kit
+
+React components, JSON contracts, and tokens for agent-built UI. This is the **installable kit**, not the docs playground.
+
+## Install
+
+```bash
+npm install agentic-ds-kit
+```
+
+Peer: React 19. Your bundler must compile this package (it ships TypeScript and CSS modules). Next.js:
+
+```ts
+const nextConfig = {
+  transpilePackages: ["agentic-ds-kit"],
+};
+```
+
+## Use
+
+```tsx
+import "agentic-ds-kit/tokens.css";
+import { Button, Scoreboard } from "agentic-ds-kit";
+```
+
+```tsx
+import { ActivityPattern } from "agentic-ds-kit";
+```
+
+Contracts live in the package: `agentic-ds-kit/contracts/index.json`. Copy `AGENTS.md` (and `CLAUDE.md`) from this package into your app so Cursor and Claude Code follow the kit.
+
+## Tokens
+
+`lib/tokens.css` is generated from `tokens/tokens.json`:
+
+```bash
+npm run generate:tokens -w agentic-ds-kit
+```

package/contracts/accordion.json

@@ -0,0 +1,38 @@
+{
+  "id": "accordion",
+  "status": "stable",
+  "intent": "One-open disclosure list for short related sections.",
+  "useWhen": [
+    "FAQ or help copy grouped under short titles",
+    "Settings or detail blocks the user opens one at a time"
+  ],
+  "doNotUseWhen": [
+    "In-page peer views — use Tabs",
+    "Sidebar catalog groups — use AppNav",
+    "A single show/hide block — use Collapsible"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "itemShape": { "id": "string", "title": "string", "content": "string" },
+      "required": true,
+      "minItems": 2
+    },
+    "defaultOpen": { "type": "string", "required": false, "note": "Item id that starts open. Omit to start all closed." }
+  },
+  "tokens": ["text.primary", "text.secondary", "surface.card", "border.faint", "icon.muted", "icon.default"],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "Each header is a button with aria-expanded",
+      "Button aria-controls the matching panel",
+      "Closed panels are hidden from AT"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Accordion or Collapse — use Collapsible for one block",
+    "Do not use raw hex",
+    "Do not open more than one item at a time"
+  ],
+  "snippet": "<Accordion items={[{ id: 'hours', title: 'Hours', content: 'Weekdays 9–5.' }, { id: 'address', title: 'Address', content: 'Knez Mihailova 1.' }]} defaultOpen=\"hours\" />"
+}

package/contracts/alert.json

@@ -0,0 +1,57 @@
+{
+  "id": "alert",
+  "status": "stable",
+  "intent": "Inline status banner that stays on the page.",
+  "useWhen": [
+    "Page or form feedback the user should still see after it appears",
+    "Success, warning, or danger copy tied to the current view"
+  ],
+  "doNotUseWhen": [
+    "Transient confirmations that disappear — not a toast; ask before adding one",
+    "Compact status chips — use Badge",
+    "Dismissible overlay — use Modal",
+    "Must-choose overlay confirm — use AlertDialog",
+    "A dismissible insight tile — use InsightCard"
+  ],
+  "props": {
+    "variant": {
+      "type": "enum",
+      "values": [
+        "info",
+        "success",
+        "warning",
+        "danger"
+      ],
+      "default": "info"
+    },
+    "title": {
+      "type": "string",
+      "required": false
+    },
+    "children": {
+      "type": "string",
+      "required": true
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "status.info",
+    "status.success",
+    "status.warning",
+    "status.danger"
+  ],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "info and success use role=status",
+      "warning and danger use role=alert",
+      "Title and body are readable text"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Alert, Banner, or Callout",
+    "Do not use raw hex",
+    "Do not use Alert for toast-style popups"
+  ],
+  "snippet": "<Alert variant=\"success\" title=\"Saved\">Your changes are live.</Alert>"
+}

package/contracts/alertdialog.json

@@ -0,0 +1,89 @@
+{
+  "id": "alertdialog",
+  "status": "stable",
+  "intent": "Must-choose overlay that interrupts until the user cancels or confirms.",
+  "useWhen": [
+    "Confirming a destructive or irreversible action",
+    "A decision that must be answered before the page continues"
+  ],
+  "doNotUseWhen": [
+    "Inline status on the page \u2014 use Alert",
+    "Dismissible short tasks or forms \u2014 use Modal",
+    "Passive help \u2014 use Tooltip"
+  ],
+  "props": {
+    "open": {
+      "type": "boolean",
+      "required": true
+    },
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "description": {
+      "type": "string",
+      "required": true
+    },
+    "cancelLabel": {
+      "type": "string",
+      "required": false,
+      "default": "Cancel"
+    },
+    "actionLabel": {
+      "type": "string",
+      "required": true
+    },
+    "actionVariant": {
+      "type": "enum",
+      "values": [
+        "primary",
+        "danger"
+      ],
+      "default": "primary"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md"
+      ],
+      "default": "md"
+    },
+    "onCancel": {
+      "type": "function",
+      "required": true
+    },
+    "onAction": {
+      "type": "function",
+      "required": true
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "surface.overlay",
+    "surface.elevated",
+    "shadow.md",
+    "border.faint",
+    "motion.overlay"
+  ],
+  "a11y": {
+    "element": "alertdialog",
+    "requirements": [
+      "role=alertdialog and aria-modal",
+      "Title is the accessible name, description is aria-describedby",
+      "Focus moves to Cancel when opened",
+      "Focus is trapped while open",
+      "Escape cancels",
+      "Overlay click does not dismiss"
+    ]
+  },
+  "doNot": [
+    "Do not invent a local confirm dialog or use window.confirm",
+    "Do not use raw hex",
+    "Do not put forms, tables, or extra actions in AlertDialog \u2014 use Modal",
+    "Do not add a close X or dismiss on overlay",
+    "Do not use more than one primary/danger action (the action button is the one)"
+  ],
+  "snippet": "<AlertDialog open={open} title=\"Delete project?\" description=\"This cannot be undone.\" actionLabel=\"Delete\" actionVariant=\"danger\" onCancel={close} onAction={remove} />"
+}

package/contracts/appheader.json

@@ -0,0 +1,140 @@
+{
+  "id": "appheader",
+  "status": "stable",
+  "intent": "Product top chrome: brand mark on the start, centered kit Input search, trailing actions. Not a page title. Not a sidebar.",
+  "useWhen": [
+    "Persistent product shell top bar with logo, global search, and utility actions",
+    "A full-bleed header above the page, not the page’s title block"
+  ],
+  "doNotUseWhen": [
+    "Page title, subtitle, Breadcrumb, or in-page actions — use PageHeader",
+    "Vertical sidebar catalog — use AppNav",
+    "Closeable product side nav — use SideNav",
+    "Horizontal site destinations and dropdowns — use NavigationMenu",
+    "Command palette overlay — use Command; AppHeader search is a kit Input"
+  ],
+  "contains": [
+    "input",
+    "button"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": false,
+      "note": "Product name next to the mark. Not an h1. Page titles belong on PageHeader."
+    },
+    "mark": {
+      "type": "string",
+      "required": false,
+      "note": "Brand letter. Defaults to the first character of title. Same idea as SideNav mark. Not a branded SVG."
+    },
+    "logo": {
+      "type": "slot",
+      "required": false,
+      "note": "Custom mark or wordmark ReactNode. Replaces the default letter mark. Consumers pass their own logo. Do not copy a file-specific brand mark into the kit."
+    },
+    "search": {
+      "type": "boolean",
+      "default": true,
+      "note": "Renders a centered kit Input. Hide only when the shell has no global search."
+    },
+    "searchPlaceholder": {
+      "type": "string",
+      "default": "Search"
+    },
+    "searchValue": {
+      "type": "string",
+      "required": false,
+      "note": "controlled. When set, pair with onSearch."
+    },
+    "defaultSearchValue": {
+      "type": "string",
+      "required": false
+    },
+    "onSearch": {
+      "type": "function",
+      "required": false,
+      "note": "(value: string) => void. Input onChange."
+    },
+    "searchShortcut": {
+      "type": "string",
+      "required": false,
+      "note": "Decorative Input end slot, e.g. ⌘K. Not a keybinding."
+    },
+    "searchId": {
+      "type": "string",
+      "required": false,
+      "note": "Passed to kit Input. Generated when omitted."
+    },
+    "actions": {
+      "type": "slot",
+      "allowedContracts": [
+        "button"
+      ],
+      "required": false,
+      "note": "kit Buttons. At most one primary. Do not put an assistant/Copilot CTA in the kit."
+    },
+    "className": {
+      "type": "string",
+      "required": false
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "header label. Defaults to title, then Application."
+    },
+    "radius": {
+      "type": "enum",
+      "values": [
+        "md",
+        "none"
+      ],
+      "default": "none",
+      "note": "Bar corners. none is a flush full-bleed bar. md is radius-surface-md for an inset floating bar."
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "text.primary",
+    "fill.brand",
+    "brand.onBrand",
+    "border.faint",
+    "border.divider",
+    "radius.control.md",
+    "radius.surfaceMd",
+    "radius.0",
+    "space.1",
+    "space.2",
+    "space.3",
+    "space.4",
+    "space.5",
+    "space.8",
+    "space.10",
+    "layout.rail",
+    "type.size.heading",
+    "type.size.label",
+    "type.weight.heading",
+    "type.weight.label"
+  ],
+  "a11y": {
+    "element": "header",
+    "requirements": [
+      "header has aria-label from ariaLabel, title, or Application",
+      "Search is kit Input type=search with aria-label from searchPlaceholder",
+      "Default letter mark is aria-hidden",
+      "Actions remain keyboard accessible",
+      "Do not use h1 — page titles belong on PageHeader"
+    ]
+  },
+  "doNot": [
+    "Do not invent TopBar, SearchBar, Logo, Masthead, or AppBar cousins",
+    "Do not use PageHeader for product chrome",
+    "Do not use AppNav, SideNav, or NavigationMenu as a top bar with search",
+    "Do not bake a product logo SVG into the kit — use logo or mark",
+    "Do not add a Copilot, assistant, or sparkle CTA",
+    "Do not restyle kit Input internals",
+    "Do not put more than one primary Button in actions",
+    "Do not use raw hex"
+  ],
+  "snippet": "<AppHeader title=\"Acme\" mark=\"A\" searchPlaceholder=\"Search\" searchShortcut=\"⌘K\" onSearch={setQuery} actions={<><Button variant=\"tertiary\" size=\"sm\" iconStart=\"Bell\" ariaLabel=\"Notifications\" /></>} />"
+}

package/contracts/appnav.json

@@ -0,0 +1,72 @@
+{
+  "id": "appnav",
+  "status": "stable",
+  "intent": "Vertical sidebar navigation with title, optional grouped catalog, and active item state.",
+  "useWhen": [
+    "Playground or product shells with a persistent left sidebar",
+    "Grouped docs/catalog IA (foundations, components, patterns)",
+    "List-detail layouts with a small flat list of section links"
+  ],
+  "doNotUseWhen": [
+    "In-page panel switching \u2014 use Tabs",
+    "Horizontal site nav \u2014 use NavigationMenu",
+    "Breadcrumb trails \u2014 not supported",
+    "Closeable product chrome \u2014 use SideNav",
+    "Product top bar with logo and search \u2014 use AppHeader"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": false
+    },
+    "items": {
+      "type": "array",
+      "itemShape": {
+        "href": "string",
+        "label": "string",
+        "active": "boolean",
+        "items": "optional array of leaf links (one subgroup level)"
+      },
+      "required": false,
+      "note": "Flat list for simple shells. Ignored when groups is provided."
+    },
+    "groups": {
+      "type": "array",
+      "itemShape": {
+        "label": "string",
+        "defaultOpen": "boolean",
+        "items": "array of AppNavItem"
+      },
+      "required": false,
+      "note": "Grouped catalog nav. Takes precedence over items when present. Groups collapse; only one is open at a time. defaultOpen sets the initial group when no leaf is active."
+    }
+  },
+  "precedence": "When both items and groups are passed, groups wins; items is ignored.",
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "surface.card",
+    "surface.muted",
+    "border.faint",
+    "action.primary"
+  ],
+  "a11y": {
+    "element": "nav",
+    "requirements": [
+      "nav has aria-label",
+      "Group labels are disclosure buttons with aria-expanded",
+      "Closed group lists are aria-hidden and inert",
+      "Active leaf uses aria-current=page",
+      "All leaves are keyboard-focusable links"
+    ]
+  },
+  "doNot": [
+    "Do not invent local Sidebar or AppNav",
+    "Do not invent Sidebar, SidebarProvider, or local nav chrome \u2014 use SideNav",
+    "Do not use raw hex",
+    "Do not use AppNav for tab panels \u2014 use Tabs",
+    "Do not nest more than one subgroup level"
+  ],
+  "snippet": "<AppNav title=\"Agentic DS Kit\" groups={[{ label: 'Components', items: [{ href: '/components#button', label: 'Button', active: true }] }]} />"
+}

package/contracts/avatar.json

@@ -0,0 +1,63 @@
+{
+  "id": "avatar",
+  "status": "stable",
+  "intent": "Face or initials for a person. Not a status chip and not a button.",
+  "useWhen": [
+    "user menus",
+    "table assignee",
+    "comment authors",
+    "profile headers"
+  ],
+  "doNotUseWhen": [
+    "status or category chips — use Badge",
+    "actions — use Button",
+    "logos/brands — ask first"
+  ],
+  "props": {
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "src": {
+      "type": "string",
+      "required": false
+    },
+    "initials": {
+      "type": "string",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    }
+  },
+  "tokens": [
+    "surface.muted",
+    "text.primary",
+    "radius.full",
+    "space.8",
+    "space.10",
+    "space.12"
+  ],
+  "a11y": {
+    "element": "span",
+    "requirements": [
+      "when image shows, img alt=name",
+      "when fallback, role=img and aria-label=name",
+      "Decorative User icon is aria-hidden"
+    ]
+  },
+  "doNot": [
+    "do not invent local Avatar",
+    "do not use raw hex",
+    "do not make Avatar clickable without a new contract",
+    "do not add AvatarGroup or a status badge on Avatar in this contract",
+    "do not use Badge for people"
+  ],
+  "snippet": "<Avatar name=\"Boris Jovanovic\" src=\"/faces/boris.jpg\" size=\"md\" />"
+}

package/contracts/avatargroup.json

@@ -0,0 +1,83 @@
+{
+  "id": "avatargroup",
+  "status": "stable",
+  "intent": "Overlapping row of kit Avatars with an optional leftover count.",
+  "useWhen": [
+    "several people on a row, card, or table cell"
+  ],
+  "doNotUseWhen": [
+    "one person — use Avatar",
+    "status chips — use Badge",
+    "actions — use Button"
+  ],
+  "contains": [
+    "avatar"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "required": true,
+      "minItems": 2,
+      "itemShape": {
+        "name": {
+          "type": "string",
+          "required": true
+        },
+        "src": {
+          "type": "string",
+          "required": false
+        },
+        "initials": {
+          "type": "string",
+          "required": false
+        }
+      }
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "max": {
+      "type": "number",
+      "default": 3,
+      "note": "how many Avatars to show before +N. If items.length <= max, no count."
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "names the group, e.g. Assignees"
+    }
+  },
+  "tokens": [
+    "surface.muted",
+    "text.secondary",
+    "surface.page",
+    "radius.full",
+    "space.px",
+    "space.2",
+    "space.8",
+    "space.10",
+    "space.12"
+  ],
+  "a11y": {
+    "element": "div",
+    "requirements": [
+      "role=group",
+      "optional aria-label names the group",
+      "leftover count uses aria-label like \"3 more\""
+    ]
+  },
+  "doNot": [
+    "Do not invent a local avatar stack",
+    "Do not wrap non-Avatar content",
+    "Do not use raw hex",
+    "Do not put a status badge on faces",
+    "Do not make the group a button"
+  ],
+  "snippet": "<AvatarGroup size=\"md\" max={3} ariaLabel=\"Assignees\" items={[{ name: \"Boris Jovanovic\" }, { name: \"Ada Jones\" }, { name: \"Mira\" }, { name: \"Leo\" }]} />"
+}