agentic-ds-kit 0.1.0

package/contracts/progresssteps.json

@@ -0,0 +1,91 @@
+{
+  "id": "progresssteps",
+  "status": "stable",
+  "intent": "Ordered wizard steps as numbered circles with a connecting line. Complete, current, upcoming, and optional error. Horizontal or vertical. One piece.",
+  "useWhen": [
+    "Checkout, onboarding, or multi-step forms",
+    "A required sequence the user walks through in order",
+    "Numbered steps with complete, current, and upcoming"
+  ],
+  "doNotUseWhen": [
+    "A determinate percent 0 to 100 — use Progress",
+    "A vertical now/next/later roadmap — use Timeline",
+    "Peer views the user can switch freely — use Tabs",
+    "Paging a list or table — use Pagination"
+  ],
+  "props": {
+    "steps": {
+      "type": "array",
+      "required": true,
+      "note": "{ id, label, description?, status?: complete|current|upcoming|error }[]. Status is derived from current when omitted."
+    },
+    "current": {
+      "type": "number",
+      "default": 0,
+      "note": "0-based index of the current step. Pass steps.length to mark every step complete."
+    },
+    "orientation": {
+      "type": "enum",
+      "values": ["horizontal", "vertical"],
+      "default": "horizontal",
+      "note": "horizontal is the Untitled UI default. vertical stacks marker, then copy."
+    },
+    "size": {
+      "type": "enum",
+      "values": ["sm", "md"],
+      "default": "md",
+      "note": "Marker is space-6 (sm) or space-8 (md)."
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "nav label. Defaults to Progress."
+    }
+  },
+  "tokens": [
+    "fill.strong",
+    "fill.brandSubtle",
+    "fill.danger",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "text.brand",
+    "text.danger",
+    "icon.inverse",
+    "surface.card",
+    "border.faint",
+    "border.strong",
+    "border.brand",
+    "radius.full",
+    "space.1",
+    "space.2",
+    "space.3",
+    "space.4",
+    "space.6",
+    "space.8",
+    "type.size.bodySm",
+    "type.size.label",
+    "type.size.caption",
+    "type.weight.label",
+    "type.weight.body",
+    "motion.interactionDuration"
+  ],
+  "a11y": {
+    "element": "nav > ol",
+    "requirements": [
+      "nav with aria-label Progress or ariaLabel",
+      "Ordered list of steps",
+      "Current step sets aria-current=step",
+      "Marker is aria-hidden; status is announced as Completed, Current, Upcoming, or Error with step n of m"
+    ]
+  },
+  "doNot": [
+    "Do not invent StepItem, Stepper, ProgressStep, or Icon cousins",
+    "Do not use Progress for ordered wizard steps",
+    "Do not use Timeline for numbered checkout or onboarding steps",
+    "Do not use Tabs for a required sequence",
+    "Do not use raw hex",
+    "Do not copy Untitled UI CSS or hex"
+  ],
+  "snippet": "<ProgressSteps current={1} steps={[{ id: 'details', label: 'Your details', description: 'Name and email' }, { id: 'company', label: 'Company details' }]} />"
+}

package/contracts/radiogroup.json

@@ -0,0 +1,132 @@
+{
+  "id": "radiogroup",
+  "status": "stable",
+  "intent": "Choose exactly one option from a small visible set. Custom circle, not a native radio. One piece.",
+  "useWhen": [
+    "Two to six mutually exclusive options that should stay visible",
+    "Settings where users compare options side by side"
+  ],
+  "doNotUseWhen": [
+    "Long option lists \u2014 use Select",
+    "Independent booleans \u2014 use Checkbox",
+    "Instant on/off \u2014 use Switch",
+    "Tabs for panel switching \u2014 use Tabs"
+  ],
+  "props": {
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "legend": {
+      "type": "string",
+      "required": true,
+      "note": "Fieldset legend."
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "orientation": {
+      "type": "enum",
+      "values": [
+        "vertical",
+        "horizontal"
+      ],
+      "default": "vertical"
+    },
+    "options": {
+      "type": "array",
+      "itemShape": {
+        "value": "string",
+        "label": "string",
+        "description": "string?",
+        "badge": "string?",
+        "badgeTone": "BadgeTone?",
+        "disabled": "boolean?"
+      },
+      "required": true
+    },
+    "defaultValue": {
+      "type": "string",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "required": false,
+      "note": "controlled"
+    },
+    "onChange": {
+      "type": "function",
+      "required": false,
+      "note": "(value: string) => void"
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false,
+      "note": "Locks the whole group."
+    },
+    "error": {
+      "type": "string",
+      "required": false,
+      "note": "Group error message. Tints the radios."
+    },
+    "hint": {
+      "type": "string",
+      "required": false
+    },
+    "hideLegend": {
+      "type": "boolean",
+      "default": false,
+      "note": "Keeps the legend for assistive tech, hides it visually. Use when Drawer already shows the title."
+    },
+    "layout": {
+      "type": "enum",
+      "values": [
+        "list",
+        "card"
+      ],
+      "default": "list",
+      "note": "card is bordered rows with the radio on the right. Compose Badge via option.badge."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "text.danger",
+    "text.disabled",
+    "border.strong",
+    "border.focus",
+    "action.primary",
+    "action.danger",
+    "surface.page",
+    "radius.pill",
+    "surface.card",
+    "surface.muted",
+    "radius.surfaceMd"
+  ],
+  "a11y": {
+    "element": "fieldset",
+    "requirements": [
+      "legend names the group",
+      "Each radio is a native input type=radio with a visible label",
+      "error sets aria-invalid on the group and options",
+      "Disabled options stay in the a11y tree but cannot be selected"
+    ]
+  },
+  "doNot": [
+    "Do not invent Radio, RadioGroupItem, or RadioGroupLegend cousins",
+    "Do not use a native unstyled radio with accent-color",
+    "Do not use raw hex",
+    "Do not use for tabbed content \u2014 use Tabs",
+    "Do not use for multi-select \u2014 use Checkbox"
+  ],
+  "snippet": "<RadioGroup name=\"plan\" legend=\"Plan\" size=\"lg\" defaultValue=\"pro\" options={[\n  { value: 'starter', label: 'Starter' },\n  { value: 'pro', label: 'Studio Pro' },\n]} />",
+  "contains": [
+    "badge"
+  ]
+}

package/contracts/scoreboard.json

@@ -0,0 +1,46 @@
+{
+  "id": "scoreboard",
+  "status": "stable",
+  "intent": "Metrics strip of kit Scorecards. Two to four fill the row. More than four compose Carousel.",
+  "useWhen": [
+    "Showing two or more KPIs side by side at the top of a dashboard",
+    "Replacing ad-hoc flex rows of metric boxes"
+  ],
+  "doNotUseWhen": [
+    "A single KPI \u2014 render Scorecard directly",
+    "Vertical stacks of metrics \u2014 not supported by this contract"
+  ],
+  "contains": [
+    "scorecard",
+    "carousel"
+  ],
+  "props": {
+    "items": {
+      "type": "array",
+      "itemContract": "scorecard",
+      "required": true,
+      "minItems": 2,
+      "note": "2\u20134 fill equal columns. More than 4 pages four-up in kit Carousel."
+    }
+  },
+  "tokens": [
+    "surface.page",
+    "layout.metricsMin",
+    "space.4"
+  ],
+  "a11y": {
+    "element": "section",
+    "requirements": [
+      "Expose aria-label describing the metrics group",
+      "Each child Scorecard retains its own semantics"
+    ]
+  },
+  "doNot": [
+    "Do not invent a local Scoreboard",
+    "Do not fake dividers with CSS borders between items",
+    "Do not restyle Scorecard padding or borders inside Scoreboard",
+    "Do not inline Scorecard markup \u2014 import from ui/Scorecard",
+    "More than four items \u2014 Scoreboard composes kit Carousel, do not invent a local scroller"
+  ],
+  "snippet": "<Scoreboard items={[{ label: 'Revenue', value: '$48.2k', delta: '+12.4%', trend: 'up' }, { label: 'Churn', value: '1.2%', delta: '-0.3%', trend: 'down' }, { label: 'Users', value: '12.4k', delta: '+4.1%', trend: 'up' }, { label: 'NPS', value: '64', delta: '+2', trend: 'up' }]} />"
+}

package/contracts/scorecard.json

@@ -0,0 +1,124 @@
+{
+  "id": "scorecard",
+  "status": "stable",
+  "intent": "one KPI with label, value, optional delta/trend/hint/badge",
+  "useWhen": [
+    "Showing a single metric such as revenue, users, or conversion rate"
+  ],
+  "doNotUseWhen": [
+    "Multiple metrics \u2014 use Scoreboard",
+    "Charts, sparklines, or tables \u2014 out of scope for this contract",
+    "A framed content tile \u2014 use Card",
+    "A recommended action tile \u2014 use InsightCard"
+  ],
+  "props": {
+    "label": {
+      "type": "string",
+      "required": true
+    },
+    "value": {
+      "type": "string",
+      "required": true
+    },
+    "delta": {
+      "type": "string",
+      "required": false,
+      "note": "Visible change text, e.g. '+12.4%'"
+    },
+    "trend": {
+      "type": "enum",
+      "values": [
+        "up",
+        "down",
+        "flat",
+        "neutral"
+      ],
+      "default": "neutral"
+    },
+    "hint": {
+      "type": "string",
+      "required": false,
+      "note": "Supporting context, e.g. 'vs last 30 days'"
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "badge": {
+      "type": "string",
+      "required": false,
+      "note": "kit Badge on the header, aligned with label. Compose Badge. No Tag."
+    },
+    "badgeTone": {
+      "type": "enum",
+      "values": [
+        "neutral",
+        "brand",
+        "success",
+        "warning",
+        "danger",
+        "info"
+      ],
+      "default": "neutral",
+      "note": "kit Badge tone"
+    },
+    "onClick": {
+      "type": "function",
+      "required": false,
+      "note": "When set, the whole card is a button that opens a detail view"
+    },
+    "fill": {
+      "type": "boolean",
+      "default": false,
+      "note": "Stretch to the parent width. Scoreboard passes fill so cards share the row."
+    }
+  },
+  "tokens": [
+    "surface.card",
+    "border.highlight",
+    "border.faint",
+    "border.strong",
+    "radius.surfaceMd",
+    "text.primary",
+    "text.secondary",
+    "text.muted",
+    "text.success",
+    "text.danger",
+    "type.size.caption",
+    "type.size.heading",
+    "type.size.title",
+    "type.size.metric",
+    "type.weight.caption",
+    "type.weight.metric",
+    "space.stack.sm",
+    "space.inset.md",
+    "motion.interaction",
+    "border.focus"
+  ],
+  "a11y": {
+    "element": "article",
+    "requirements": [
+      "useId for label and value",
+      "aria-labelledby when both exist",
+      "trend icon is aria-hidden",
+      "delta text is the visible change",
+      "root is a button when onClick is set"
+    ]
+  },
+  "doNot": [
+    "Do not invent a KpiCard, Stat, or MetricCard cousin",
+    "Do not use raw hex colors in styles",
+    "Do not pack multiple KPIs into one Scorecard",
+    "Do not put buttons or links inside Scorecard besides the whole-card onClick",
+    "Do not invent a local Tag or Status on Scorecard \u2014 use kit Badge via badge"
+  ],
+  "snippet": "<Scorecard label=\"Revenue\" value=\"$48.2k\" delta=\"+12.4%\" trend=\"up\" hint=\"vs last 30 days\" />",
+  "contains": [
+    "badge"
+  ]
+}

package/contracts/section.json

@@ -0,0 +1,97 @@
+{
+  "id": "section",
+  "status": "stable",
+  "intent": "Grouped page block with optional heading, description, and actions. Collapsible, chevron before the title.",
+  "useWhen": [
+    "Separating metrics, tables, or form groups on a page",
+    "Under PageHeader to structure dashboard or settings content"
+  ],
+  "doNotUseWhen": [
+    "Whole page title \u2014 use PageHeader",
+    "Framed tiles \u2014 use Card",
+    "Form legends and grouped fields \u2014 use FieldSet",
+    "Modal body layout \u2014 keep content minimal inside Modal",
+    "App-wide navigation \u2014 use AppNav",
+    "Exclusive FAQ lists \u2014 use Accordion"
+  ],
+  "props": {
+    "title": {
+      "type": "string",
+      "required": false
+    },
+    "description": {
+      "type": "string",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md",
+      "note": "Controls gap under the heading and between stacked sections via space-section tokens"
+    },
+    "actions": {
+      "type": "slot",
+      "required": false,
+      "note": "kit Buttons only. One primary per view."
+    },
+    "children": {
+      "type": "slot",
+      "required": true
+    },
+    "collapsible": {
+      "type": "boolean",
+      "default": true,
+      "note": "When title is set, a chevron sits before the title and toggles the body. False keeps the body always open."
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "default": true
+    },
+    "open": {
+      "type": "boolean",
+      "required": false,
+      "note": "controlled"
+    },
+    "onOpenChange": {
+      "type": "function",
+      "required": false,
+      "note": "(open: boolean) => void"
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.secondary",
+    "type.size.heading",
+    "type.size.bodySm",
+    "space.section.sm",
+    "space.section.md",
+    "space.section.lg",
+    "space.stack.sm",
+    "space.stack.md",
+    "space.stack.lg"
+  ],
+  "a11y": {
+    "element": "section",
+    "requirements": [
+      "title is h2 with useId",
+      "aria-labelledby when title is set",
+      "Collapse control is a button inside the h2, aria-expanded and aria-controls",
+      "Body uses hidden when collapsed"
+    ]
+  },
+  "doNot": [
+    "Do not invent a local Section or SectionHeader",
+    "Do not use raw hex",
+    "Do not frame Section \u2014 that is Card",
+    "Do not use Section as the page title \u2014 that is PageHeader",
+    "Do not embed one-off metric flex rows \u2014 use Scoreboard",
+    "Actions must be kit Buttons",
+    "Do not compose Accordion or Collapsible for page sections \u2014 Section owns collapse"
+  ],
+  "snippet": "<Section title=\"Recent activity\" description=\"Last 30 days\" actions={<Button variant=\"secondary\" size=\"sm\">View all</Button>}><Table ... /></Section>",
+  "contains": []
+}

package/contracts/select.json

@@ -0,0 +1,130 @@
+{
+  "id": "select",
+  "status": "stable",
+  "intent": "Choose one or several options from a list. Field trigger, kit DropdownMenu panel. Not a native select.",
+  "useWhen": [
+    "Choosing one value in a Field",
+    "Choosing several values from a list (multiple)",
+    "A long fixed list with local search (searchable)",
+    "Short fixed lists such as month, year, timezone, or tags"
+  ],
+  "doNotUseWhen": [
+    "Command palettes \u2014 use Command",
+    "Actions from a button \u2014 use DropdownMenu",
+    "Mutually exclusive choices with visible options \u2014 prefer RadioGroup"
+  ],
+  "contains": [
+    "dropdownmenu"
+  ],
+  "props": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "size": {
+      "type": "enum",
+      "values": [
+        "md",
+        "sm"
+      ],
+      "default": "md"
+    },
+    "options": {
+      "type": "array",
+      "itemShape": {
+        "value": "string",
+        "label": "string"
+      },
+      "required": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "default": false
+    },
+    "error": {
+      "type": "boolean",
+      "default": false
+    },
+    "multiple": {
+      "type": "boolean",
+      "default": false,
+      "note": "Several values. Menu stays open. Checks each pick. Trigger lists labels. Not a MultiSelect cousin."
+    },
+    "placeholder": {
+      "type": "string",
+      "required": false,
+      "note": "Shown until a value is picked. Muted field text. When set and no defaultValue, start empty."
+    },
+    "defaultValue": {
+      "type": "string | string[]",
+      "required": false,
+      "note": "string when single, string[] when multiple"
+    },
+    "value": {
+      "type": "string | string[]",
+      "required": false,
+      "note": "controlled"
+    },
+    "onChange": {
+      "type": "function",
+      "required": false,
+      "note": "(value: string | string[]) => void"
+    },
+    "name": {
+      "type": "string",
+      "required": false
+    },
+    "ariaLabel": {
+      "type": "string",
+      "required": false,
+      "note": "When there is no Field label, such as a DataTable Cell."
+    },
+    "itemCheck": {
+      "type": "enum",
+      "values": [
+        "check",
+        "checkbox"
+      ],
+      "default": "check",
+      "note": "checkbox composes kit Checkbox in the menu when multiple. Visual only. Not DropdownMenuCheckboxItem."
+    },
+    "maxVisible": {
+      "type": "number",
+      "required": false,
+      "note": "When multiple and selected count exceeds this, trigger shows the first labels plus a kit Badge +N. Omit to list all labels."
+    },
+    "searchable": {
+      "type": "boolean",
+      "default": false,
+      "note": "Kit Input at the top of the panel. Filters option labels. For a long fixed list. Not Command."
+    }
+  },
+  "tokens": [
+    "text.primary",
+    "text.muted",
+    "surface.card",
+    "surface.muted",
+    "border.faint",
+    "border.focus",
+    "status.danger"
+  ],
+  "a11y": {
+    "element": "button",
+    "requirements": [
+      "Trigger is a field-styled button with aria-haspopup=menu",
+      "Must have associated label via Field or ariaLabel",
+      "Each option needs a human-readable label",
+      "Selected options show a Check, or kit Checkbox when itemCheck=checkbox",
+      "Overflow count uses kit Badge on the trigger, not Tag"
+    ]
+  },
+  "doNot": [
+    "Do not use a native select",
+    "Do not use kit Button as the Select trigger \u2014 Select uses DropdownMenu triggerStyle=field",
+    "Do not invent SelectTrigger, SelectContent, SelectItem, SelectValue, SelectGroup, MultiSelect, or Combobox",
+    "Do not invent Tag for overflow \u2014 use kit Badge",
+    "Do not use raw hex",
+    "Do not use for navigation \u2014 use AppNav or links"
+  ],
+  "snippet": "<Field label=\"Fruit\" htmlFor=\"fruit\">\n  <Select id=\"fruit\" placeholder=\"Select a fruit\" options={[{ value: 'apple', label: 'Apple' }]} />\n</Field>\n<Select id=\"fruits\" multiple itemCheck=\"checkbox\" maxVisible={2} placeholder=\"Select fruits\" options={fruits} />\n<Select id=\"city\" searchable placeholder=\"Select a city\" options={cities} />"
+}

package/contracts/shimmertext.json

@@ -0,0 +1,33 @@
+{
+  "id": "shimmertext",
+  "status": "stable",
+  "intent": "Animated text for short indeterminate processing copy.",
+  "useWhen": [
+    "Generating or loading message placeholders",
+    "Swap to real content when ready"
+  ],
+  "doNotUseWhen": [
+    "Static headings or body copy",
+    "Long paragraphs of final content"
+  ],
+  "props": {
+    "children": { "type": "string", "required": true },
+    "size": {
+      "type": "enum",
+      "values": ["sm", "md", "lg"],
+      "default": "md"
+    },
+    "speed": {
+      "type": "enum|number",
+      "values": ["slow", "normal", "fast"],
+      "default": "normal"
+    }
+  },
+  "tokens": ["text.primary", "text.muted"],
+  "a11y": {
+    "element": "span",
+    "requirements": ["aria-label mirrors visible text", "Respect prefers-reduced-motion"]
+  },
+  "doNot": ["Do not use raw hex"],
+  "snippet": "<ShimmerText speed=\"normal\">Generating response…</ShimmerText>"
+}