division-ds 0.1.1 → 0.2.0

package/public/docs/components/tool-call.md

@@ -0,0 +1,105 @@
+# ToolCall
+
+> A tool the assistant ran, shown right where it ran. It has the status as a word and a small symbol, a title, the tool name and how long it took, with the input and output folded away behind a button.
+
+- **Best for:** An assistant reply that ran a tool, such as a query, a lookup or a calculation.
+- **Not for:** An action with side effects that needs a yes first: use ApprovalRequest.
+- Molecule. Source: `src/components/molecules/tool-call/ToolCall.tsx`
+- Rendered docs page: `/components/tool-call`
+
+## Import
+
+```tsx
+import { ToolCall } from 'src/components/molecules/tool-call/ToolCall'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` |  | Required. The tool's own name, shown in a monospaced font. |
+| `title` | `string` |  | A plain-language description of the call, shown above the name. |
+| `status` | `'running' \| 'done' \| 'failed'` |  | Required. Shown as a word, a symbol and a colour. |
+| `duration` | `string` |  | How long it took, for example "1.2 s". |
+| `input` | `ReactNode` |  | What the assistant sent the tool. Folded away by default. |
+| `output` | `ReactNode` |  | What came back. Folded away by default. |
+| `defaultOpen` | `boolean` | `false` | Starts with the details showing. |
+| `className` | `string` |  | Added to the panel. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type ToolCallStatus = 'running' | 'done' | 'failed'
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Running, done and failed
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-3">
+  <ToolCall name="query_stock_levels" title="Read stock levels at Depot 4" status="running" />
+  <ToolCall
+    name="query_stock_levels"
+    title="Read stock levels at Depot 4"
+    status="done"
+    duration="1.2 s"
+    input={'{ "depot": 4, "below_reorder_point": true }'}
+    output={'[\n  { "sku": "K-41", "on_hand": 6, "reorder_at": 10 },\n  { "sku": "TP-08", "on_hand": 3, "reorder_at": 8 }\n]'}
+  />
+  <ToolCall
+    name="fetch_supplier_lead_times"
+    title="Check supplier lead times"
+    status="failed"
+    duration="4.0 s"
+    output="Timed out after 4 s. The supplier feed did not answer."
+  />
+</div>
+```
+
+### Without a title, details open
+
+```tsx
+<div className="flex w-full max-w-xl flex-col gap-3">
+  <ToolCall
+    name="count_pallets"
+    status="done"
+    duration="0.3 s"
+    input={'{ "depot": 4, "bay": 2 }'}
+    output="14 pallets"
+    defaultOpen
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to "Show details". |
+| `Enter` `Space` | Shows or hides the input and output. |
+
+## Do
+
+- Give each call a title a person understands: "Read stock levels at Depot 4", not just the function name.
+- Show the call even when it's boring. Seeing the work is how a reader learns to trust it, or to catch a mistake.
+- Mention a failure in the reply text too, along with what the assistant did instead.
+
+## Don't
+
+- Don't give a call its own live region (an area screen readers announce on change). The thread's busy status speaks for the whole turn.
+- Don't open the details by default for long payloads. The reply is what matters, and the payload is the evidence.
+- Don't use a ToolCall for something with a side effect the person hasn't agreed to. Ask with ApprovalRequest first.
+
+## Anatomy
+
+- **Panel**: A thin frame on surface.raised. It's marked as a separate block, so the message's screen reader announcement skips it.
+- **Status glyph**: A Spinner while running, a check when done, an alert circle when failed. Decoration only.
+- **Title and name**: The title written for people, then the tool's own name in a monospaced font. With no title, the name comes first.
+- **Status badge**: Running, Done or Failed as a word in the tone's colour. Colour is never the only signal.
+- **Duration**: In a monospaced font with equal-width digits, for example "1.2 s".
+- **Details**: A "Show details" button (with aria-expanded, which tells screen readers whether it's open) above Input and Output. Those wrap onto new lines instead of scrolling sideways.

package/public/docs/components/tooltip.md

@@ -0,0 +1,106 @@
+# Tooltip
+
+> Extra text that shows on hover or focus. It never holds information people can only get there. It doesn't appear on touch screens, it goes away, and someone may never trigger it.
+
+- **Best for:** Extra detail on hover or focus for an element that can take focus, such as an IconButton.
+- **Not for:** The only label, or the only explanation of an error. Use the label prop or visible text.
+- Atom. Source: `src/components/atoms/tooltip/Tooltip.tsx`
+- Rendered docs page: `/components/tooltip`
+
+## Import
+
+```tsx
+import { Tooltip, TooltipProvider } from 'src/components/atoms/tooltip/Tooltip'
+```
+
+## Requires
+
+- One <TooltipProvider> near the root of the app. AppShell and the demo layout each mount one, so a screen doesn't add its own.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `content` | `string` |  | Required. The extra text. |
+| `children` | `ReactElement` |  | A single element that can take focus. |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Which side of the trigger the content opens on. |
+| `className` | `string` |  | Merged with the content’s classes. Later Tailwind utilities (the small styling classes this system uses) win. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### On a button
+
+```tsx
+<Tooltip content="Sends the manifest to the depot; can't be undone once confirmed.">
+  <Button>Dispatch</Button>
+</Tooltip>
+```
+
+### On an icon button
+
+```tsx
+<Tooltip content="Uses the last known GPS fix, not live signal.">
+  <IconButton label="Recalculate route">
+    <Compass aria-hidden="true" className="w-4 h-4" />
+  </IconButton>
+</Tooltip>
+```
+
+### Sides
+
+```tsx
+<Tooltip content="Opens above the trigger." side="top">
+  <Button variant="secondary">Top</Button>
+</Tooltip>
+<Tooltip content="Opens right of the trigger." side="right">
+  <Button variant="secondary">Right</Button>
+</Tooltip>
+<Tooltip content="Opens below the trigger." side="bottom">
+  <Button variant="secondary">Bottom</Button>
+</Tooltip>
+<Tooltip content="Opens left of the trigger." side="left">
+  <Button variant="secondary">Left</Button>
+</Tooltip>
+```
+
+### Keyboard
+
+```tsx
+<p className="text-sm text-[var(--color-text-secondary)] max-w-md">
+  Press Tab to move to the trigger and the tooltip appears. Press Escape and it goes away,
+  without you moving the pointer. That's a rule in WCAG 2.2 (the Web Content Accessibility
+  Guidelines, the public rulebook for making websites usable by people with disabilities).
+  Its success criterion (SC) 1.4.13 says this kind of content has to stay dismissible (you
+  can close it), hoverable (you can move the pointer onto it) and persistent (it stays
+  until you do).
+</p>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to the trigger and shows the tooltip. Tabbing on to the next element hides it again. |
+| `Esc` | Dismisses it without moving the pointer. That's required by SC 1.4.13, a success criterion (one numbered rule) in WCAG, the Web Content Accessibility Guidelines. |
+
+## Do
+
+- Use it for the extra detail, never the essential one.
+- Put it on an element that can take focus. A tooltip on a <div> doesn't reach anyone using a keyboard.
+- Keep it to one sentence.
+- Pair it with an IconButton whose label already names the action. Then the tooltip adds detail instead of repeating the name.
+
+## Don't
+
+- Don't put a tooltip on a disabled control. It can't take focus, so nobody can reach the tooltip.
+- Don't put interactive content inside one. A tooltip is text only and never takes focus.
+- Don't use it as the only label for an icon button. label does that job.
+- Don't make it the only place an error is explained.
+
+## Anatomy
+
+- **Provider**: Mounted once in AppShell. It sets the 300ms (millisecond) delay, and the 150ms skip window for moving between triggers.
+- **Trigger**: Uses asChild, so no wrapper element is added and the focus order stays as it was.
+- **Content**: Portalled, meaning it's rendered in a separate layer of the page, outside its trigger. It enters with motion token M1, is capped at 260px (pixels) wide and has the cut bottom-right corner. It's a single object with its own fill and holds nothing that takes focus, so the cut doesn't need an unclipped wrapper. The trigger, not the panel, is what takes focus.

package/public/manifest/components.json

@@ -1,6 +1,125 @@
 {
   "generatedBy": "scripts/build-agent-docs.mjs",
   "components": [
+    {
+      "name": "AiLabel",
+      "title": "AI label",
+      "tier": "atoms",
+      "slug": "ai-label",
+      "summary": "Marks content as made by AI, and on request says why. Given an explanation, the mark is a button that opens a short note right under it, with an optional list of sources. It is a disclosure (a button that shows and hides a region), not a tooltip or a popover: a tooltip can't hold links and never shows on a touch screen, and the system has no popover.",
+      "useWhen": "Marking a block of text, a value or a field that an AI wrote, so the person knows to check it.",
+      "notFor": "A status or a category: use Badge. A field the AI filled: give the field aiValue, which marks it itself.",
+      "source": "src/components/atoms/ai-label/AiLabel.tsx",
+      "docs": "/docs/components/ai-label.md",
+      "imports": [
+        {
+          "names": [
+            "AiLabel"
+          ],
+          "from": "src/components/atoms/ai-label/AiLabel"
+        }
+      ],
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": "'Generated by AI'",
+          "description": "The mark's words, and the button's name. Say what the AI made: 'AI summary', 'AI draft'."
+        },
+        {
+          "name": "explanation",
+          "type": "ReactNode",
+          "description": "Why this is AI content and what to do about it, in a sentence or two: what it was made from, and that it needs checking. Without it the mark is static text and nothing opens."
+        },
+        {
+          "name": "sources",
+          "type": "AiLabelSource[]",
+          "description": "{ label, href } for each thing the content was made from. Listed under the explanation; ignored without one."
+        },
+        {
+          "name": "renderLink",
+          "type": "(props: LinkRenderProps) => ReactNode",
+          "default": "a plain anchor",
+          "description": "How each source link is drawn. Pass your router's link component for sources inside the app."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "description": "Merged with the root's classes. When Tailwind utility classes clash, the later one wins."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "description": "Passed through to the root div."
+        },
+        {
+          "name": "...rest",
+          "type": "HTMLAttributes<HTMLDivElement>",
+          "description": "Every native attribute, onto the root div."
+        }
+      ],
+      "api": [
+        {
+          "name": "AiLabelSource",
+          "kind": "type",
+          "code": "export type AiLabelSource = { label: string; href: string }",
+          "from": "src/components/atoms/ai-label/AiLabel"
+        }
+      ],
+      "keyboard": [
+        {
+          "keys": [
+            "Tab"
+          ],
+          "does": "Moves focus to the mark when it has an explanation, then into any source links once open."
+        },
+        {
+          "keys": [
+            "Enter",
+            "Space"
+          ],
+          "does": "Opens or closes the explanation. Focus stays on the button."
+        }
+      ],
+      "dos": [
+        "Put it right above or beside the AI content it marks, not in a page header far away.",
+        "Say in the explanation what the AI used and that the person should check it, the way GitLab's 'Verify before use' does.",
+        "Name the sources when there are any. Showing where it came from is how a reader decides whether to trust it."
+      ],
+      "donts": [
+        "Don't put it inside a <label>. A button inside a label is read into the field's name; put it beside the label.",
+        "Don't mark everything. A label on every line is a label on nothing.",
+        "Don't rely on the colour. The words say AI; ai.text only helps you find them."
+      ],
+      "anatomy": [
+        {
+          "part": "Mark",
+          "description": "A sparkle and the label in uppercase mono, in ai.text. Static text when there is no explanation."
+        },
+        {
+          "part": "Disclosure button",
+          "description": "With an explanation, the mark is a button with aria-expanded and a chevron that turns when open. Its name is the label."
+        },
+        {
+          "part": "Explanation",
+          "description": "A region right under the button, edged in ai.border, in text.secondary. Hidden until asked for, then next in the reading order."
+        },
+        {
+          "part": "Sources",
+          "description": "Optional. A list of links under the explanation, drawn through renderLink."
+        }
+      ],
+      "examples": [
+        {
+          "caption": "Static mark",
+          "source": "<AiLabel />"
+        },
+        {
+          "caption": "With an explanation and sources",
+          "source": "<div className=\"flex flex-col gap-2 max-w-md\">\n  <AiLabel\n    label=\"AI summary\"\n    explanation=\"Summarised from the three most recent reviews of this replica. It can miss details or get them wrong: verify before you rely on it.\"\n    sources={[\n      { label: 'Review by Ilse Varga', href: '#review-1' },\n      { label: 'Review by Tomas Brandt', href: '#review-2' },\n    ]}\n  />\n  <p className=\"text-sm text-[var(--color-text-primary)]\">\n    Reviewers find the gearbox quiet and the hop-up easy to tune; two mention a loose stock.\n  </p>\n</div>"
+        }
+      ]
+    },
     {
       "name": "Avatar",
       "title": "Avatar",
@@ -952,6 +1071,11 @@
           "default": "'Clear'",
           "description": "The clear button’s name. If the page has more than one, say what it clears: ‘Clear call sign’."
         },
+        {
+          "name": "aiValue",
+          "type": "string",
+          "description": "The value an AI proposed. While the field holds exactly this value it shows the AI-filled state: an ai.border edge, a faint ai.wash tint and a sparkle mark that describes the field as Filled by AI. Once the person changes it, the field looks normal again and a Revert to suggestion button puts the value back through onChange (no button on a disabled or read-only field). An invalid field keeps its invalid border."
+        },
         {
           "name": "wrapperClassName",
           "type": "string",
@@ -986,7 +1110,7 @@
           "keys": [
             "Tab"
           ],
-          "does": "Moves focus to the input, then to its clear button and reveal toggle if they are there."
+          "does": "Moves focus to the input, then to its revert, clear and reveal buttons if they are there."
         },
         {
           "keys": [
@@ -1015,7 +1139,8 @@
         "Don't set invalid without saying what's wrong.",
         "Don't disable a field to make it read-only. Use readOnly, which you can still focus and copy from.",
         "Don't add clearable to a search field. Search already has its own clear button and the Escape key.",
-        "Don't build your own show-password button next to a revealable field. You'll end up with two."
+        "Don't build your own show-password button next to a revealable field. You'll end up with two.",
+        "Don't set aiValue on a field the person filled in themselves. The AI look says the machine wrote it."
       ],
       "anatomy": [
         {
@@ -1032,7 +1157,7 @@
         },
         {
           "part": "Adornments",
-          "description": "Optional extras inside the right edge, in this order: the count in mono (a fixed-width typeface), the clear button and the reveal toggle. Turning on any of them wraps the input in a relative box (wrapperClassName styles it) and sizes the right padding to fit them, so text never runs underneath. With none on, the input is bare, with no wrapper."
+          "description": "Optional extras inside the right edge, in this order: the AI mark or its revert button, the count in mono (a fixed-width typeface), the clear button and the reveal toggle. Turning on any of them wraps the input in a relative box (wrapperClassName styles it) and sizes the right padding to fit them, so text never runs underneath. With none on, the input is bare, with no wrapper."
         },
         {
           "part": "Placeholder",
@@ -1064,6 +1189,10 @@
           "caption": "Clear button",
           "source": "<div className=\"w-full max-w-xs\">\n  <FormField label=\"Call sign\">\n    <Input clearable clearLabel=\"Clear call sign\" defaultValue=\"Anvil-3\" />\n  </FormField>\n</div>"
         },
+        {
+          "caption": "Filled by AI, with a revert",
+          "source": "<div className=\"w-full max-w-xs\">\n  <FormField label=\"Call sign\" help=\"Suggested from your last order. Edit it and the revert button appears.\">\n    <Input aiValue=\"Anvil-3\" defaultValue=\"Anvil-3\" />\n  </FormField>\n</div>"
+        },
         {
           "caption": "Labelled the manual way",
           "source": "<div className=\"flex flex-col gap-1 text-sm max-w-xs\">\n  <label htmlFor=\"input-docs-callsign\">Call sign</label>\n  <Input id=\"input-docs-callsign\" aria-describedby=\"input-docs-callsign-help\" />\n  <p id=\"input-docs-callsign-help\" className=\"text-xs text-[var(--color-text-secondary)]\">\n    Letters, numbers and a hyphen. FormField will set this pattern up for you.\n  </p>\n</div>"
@@ -2886,6 +3015,11 @@
           "default": "4",
           "description": "The browser's own rows attribute. Size it to the answer you expect."
         },
+        {
+          "name": "aiValue",
+          "type": "string",
+          "description": "The value an AI proposed, with the same contract as Input. The mark and the revert button sit in the top right corner. While the field holds exactly this value it shows the AI-filled state: an ai.border edge, a faint ai.wash tint and a sparkle mark that describes the field as Filled by AI. Once the person changes it, the field looks normal again and a Revert to suggestion button puts the value back through onChange (no button on a disabled or read-only field). An invalid field keeps its invalid border."
+        },
         {
           "name": "className",
           "type": "string",
@@ -2962,6 +3096,10 @@
           "caption": "States",
           "source": "<label className=\"flex flex-col gap-1 text-sm w-full max-w-xs\">\n  Invalid\n  <Textarea invalid defaultValue=\"Site coordinates unclear\" />\n</label>\n<label className=\"flex flex-col gap-1 text-sm w-full max-w-xs\">\n  Disabled\n  <Textarea disabled defaultValue=\"Locked until review closes\" />\n</label>\n{/* read-only is a different state from disabled and looks different — the text stays\n    selectable and the control stays in the tab order, so `read-only:text-[...]` dims the\n    text without the disabled fill. It was styled but never demonstrated. */}\n<label className=\"flex flex-col gap-1 text-sm w-full max-w-xs\">\n  Read-only\n  <Textarea readOnly defaultValue=\"Submitted 14:02, no further edits\" />\n</label>"
         },
+        {
+          "caption": "Filled by AI, with a revert",
+          "source": "const AI_NOTES = 'Ships with two midcaps and a sling. Ask for the 1.2 J spring if you play indoors.'\n\n<div className=\"flex flex-col gap-2 w-full max-w-sm\">\n  <label htmlFor=\"ai-notes\" className=\"text-sm\">Order notes</label>\n  <AiLabel explanation=\"Drafted from the replica's listing. Check the details before you send it.\" />\n  <Textarea id=\"ai-notes\" aiValue={AI_NOTES} defaultValue={AI_NOTES} />\n</div>"
+        },
         {
           "caption": "With a counter",
           "source": "function CounterExample() {\n  const max = 140\n  const [value, setValue] = useState('')\n  return (\n    <label className=\"flex flex-col gap-1 text-sm w-full max-w-xs\">\n      Field day summary\n      <Textarea\n        value={value}\n        onChange={e => setValue(e.target.value)}\n        maxLength={max}\n        aria-describedby=\"textarea-docs-counter\"\n      />\n      <span id=\"textarea-docs-counter\" className=\"text-xs text-[var(--color-text-secondary)]\">\n        {value.length} / {max}\n      </span>\n    </label>\n  )\n}\n\n<CounterExample />"
@@ -4045,6 +4183,12 @@
             "ChatMessage"
           ],
           "from": "src/components/molecules/chat-message/ChatMessage"
+        },
+        {
+          "names": [
+            "ResponseFeedback"
+          ],
+          "from": "src/components/molecules/chat-message/ResponseFeedback"
         }
       ],
       "requires": [
@@ -4086,6 +4230,21 @@
           "name": "className",
           "type": "string",
           "description": "Goes on the article."
+        },
+        {
+          "name": "onSubmit (ResponseFeedback)",
+          "type": "(vote: 'helpful' | 'not-helpful') => void | Promise<void>",
+          "description": "Required. Runs on a thumbs up or down. Return a promise to show \"Submitting feedback\" until it settles; a rejection puts the buttons back."
+        },
+        {
+          "name": "onDetail (ResponseFeedback)",
+          "type": "(text: string) => void",
+          "description": "Offers an optional, dismissable \"what was wrong\" box after a Not helpful vote. Leave it out for no such step."
+        },
+        {
+          "name": "className (ResponseFeedback)",
+          "type": "string",
+          "description": "Goes on the group."
         }
       ],
       "api": [
@@ -4094,6 +4253,12 @@
           "kind": "type",
           "code": "export type ChatMessageRole = 'user' | 'assistant' | 'system'",
           "from": "src/components/molecules/chat-message/ChatMessage"
+        },
+        {
+          "name": "FeedbackVote",
+          "kind": "type",
+          "code": "export type FeedbackVote = 'helpful' | 'not-helpful'",
+          "from": "src/components/molecules/chat-message/ResponseFeedback"
         }
       ],
       "keyboard": [
@@ -4108,7 +4273,8 @@
         "Keep streaming true until the last piece of text has arrived, then set it to false once.",
         "Put tool calls and approvals in the assistant message where they happened, in order with its text.",
         "Use a system line for events in the conversation itself: stopped, retried, context cleared.",
-        "Give every message an author, including a system line (\"Status\"). It names the article."
+        "Give every message an author, including a system line (\"Status\"). It names the article.",
+        "Put ResponseFeedback in the actions of a generated reply once it has finished streaming, so a vote rates the whole reply."
       ],
       "donts": [
         "Don't animate the text in yourself. useStreamedText or your stream supplies it, and the thread handles announcing it.",
@@ -4145,7 +4311,7 @@
         },
         {
           "part": "Actions",
-          "description": "Small buttons under an assistant message: Copy, Retry."
+          "description": "Small buttons under an assistant message: Copy, Retry, and ResponseFeedback (thumbs up and down)."
         },
         {
           "part": "System line",
@@ -4160,6 +4326,10 @@
         {
           "caption": "While the reply is still streaming in: aria-busy, an ARIA (Accessible Rich Internet Applications) attribute that tells screen readers the message isn't finished, and a cursor that doesn't blink",
           "source": "<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage role=\"assistant\" author=\"Assistant\" streaming>\n    Depot 4 holds 1,240 replicas across 38 lines. The busiest\n  </ChatMessage>\n</div>"
+        },
+        {
+          "caption": "Feedback on a reply: thumbs up or down, one vote, and an optional detail step after Not helpful",
+          "source": "const pretendSend = () => new Promise<void>(resolve => setTimeout(resolve, 800))\n\n<div className=\"flex w-full max-w-xl flex-col gap-6\">\n  <ChatMessage\n    role=\"assistant\"\n    author=\"Assistant\"\n    actions={<ResponseFeedback onSubmit={pretendSend} onDetail={() => {}} />}\n  >\n    Depot 4 holds 1,240 replicas. Eleven are below their reorder point.\n  </ChatMessage>\n</div>"
         }
       ]
     },
@@ -5655,6 +5825,12 @@
           "type": "readonly string[]",
           "description": "Ready-made prompts shown as chips. Clicking one submits it."
         },
+        {
+          "name": "editableSuggestions",
+          "type": "boolean",
+          "default": "false",
+          "description": "Clicking a suggestion puts its text in the box to edit instead of sending it. Use it when a person will likely change the prompt first. The chips then stay usable while busy."
+        },
         {
           "name": "placeholder",
           "type": "string",
@@ -5723,7 +5899,7 @@
         },
         {
           "part": "Suggestions",
-          "description": "A group of chips above the box. Clicking one submits its text. They're disabled while busy."
+          "description": "A group of chips above the box. Clicking one submits its text (disabled while busy), or with editableSuggestions puts it in the box to edit."
         },
         {
           "part": "Box",
@@ -7306,6 +7482,11 @@
           "type": "{ label: string; altText: string; onAction: () => void }",
           "description": "Optional. Radix (the library the toast is built on) requires altText: what to do somewhere else if someone can't reach the toast in time."
         },
+        {
+          "name": "replace (ToastOptions)",
+          "type": "string",
+          "description": "Optional. Closes any open toast raised with the same string as this one opens, so an action repeated quickly (\"Alert acknowledged\" three times) shows one toast instead of a stack."
+        },
         {
           "name": "useToast()",
           "type": "{ toast: (options: ToastOptions) => string; dismiss: (id: string) => void }",
@@ -7316,7 +7497,7 @@
         {
           "name": "ToastOptions",
           "kind": "type",
-          "code": "export type ToastOptions = {\n  title: string\n  description?: string\n  tone?: Tone\n  /** ms before it leaves on its own. Default 5000; 8000 for hostile. */\n  duration?: number\n  /** Radix requires altText: the way to do the same thing for someone who cannot reach the toast\n   *  before it leaves. */\n  action?: { label: string; altText: string; onAction: () => void }\n}",
+          "code": "export type ToastOptions = {\n  title: string\n  description?: string\n  tone?: Tone\n  /** ms before it leaves on its own. Default 5000; 8000 for hostile. */\n  duration?: number\n  /** Radix requires altText: the way to do the same thing for someone who cannot reach the toast\n   *  before it leaves. */\n  action?: { label: string; altText: string; onAction: () => void }\n  /** Any open toast raised with the same string closes as this one opens, so a repeated action\n   *  (\"Alert acknowledged\" three times) shows one toast, not a stack over the page. */\n  replace?: string\n}",
           "from": "src/components/molecules/toast/Toast"
         },
         {
@@ -7350,6 +7531,7 @@
         "Use a toast to confirm something the person just did.",
         "Give every action an altText that says where else it can be done.",
         "Keep the title under about six words.",
+        "After an action runs, focus goes back to where it was before it entered the toast. If the action changes the page (Undo puts a row back), move focus to what changed yourself.",
         "A toast follows the innermost open overlay (a dialog or panel on top of the page). If it's raised while one is open, or is already showing when one opens, it shows inside that overlay, and it moves back to the page corner when the overlay closes. AlertDialog is the exception: its toasts always show in the page corner, above the scrim (the dimmed layer behind the dialog)."
       ],
       "donts": [

package/public/manifest/tokens.json

@@ -740,6 +740,45 @@
         "light": "The dimmed leading-zero pad. 3.82:1 on surface.base, 22% of text.primary's 17.55:1 there, against the dark theme's 31%. Light theme needs a LIGHTER step than text.muted for the same role: muted aliases neutral.500 and measures 11.44:1 here, 65% of ink, which does not read as dimmed and out-shouts the signal.fill numeral it is padding (3.14:1 on this surface). neutral.400 would land at 6.58:1 and 38% of ink, closer to dark's share but more than twice the contrast of the digits beside it, so neutral.300 is the step that keeps the pad quieter than what it pads."
       }
     },
+    {
+      "name": "--color-ai-text",
+      "layer": "semantic",
+      "value": {
+        "dark": "#78b7ff",
+        "light": "#004593"
+      },
+      "use": "Text or an icon that marks something as made by AI: the AiLabel mark, the AI glyph in a field an AI filled. Always beside a word, never colour alone.",
+      "measured": {
+        "dark": "Measured by the gate: 9.55:1 on surface.base, 9.08:1 on surface.sunken, 8.32:1 on surface.raised. One step lighter than accent.info.text (info.500) so AI marks and status text do not read as the same thing.",
+        "light": "Measured by the gate: 8.39:1 on surface.base, 5.75:1 on surface.sunken, 8.92:1 on surface.raised. info.700 reached only 3.49:1 on surface.sunken, so the light theme takes info.800."
+      }
+    },
+    {
+      "name": "--color-ai-border",
+      "layer": "semantic",
+      "value": {
+        "dark": "#78b7ff",
+        "light": "#004593"
+      },
+      "use": "The boundary of a form field whose value an AI filled and the person has not changed. Input and Textarea paint it from aiValue; do not paint it by hand.",
+      "measured": {
+        "dark": "The edge of a field an AI filled. 7.91:1 on the AI-filled field (ai.wash over the control fill), far above the 3:1 SC 1.4.11 floor. Same stop as ai.text; a separate token because a boundary and text carry different floors.",
+        "light": "The edge of a field an AI filled. 5.24:1 on the AI-filled field (ai.wash over surface.sunken). Same stop as ai.text; a separate token because a boundary and text carry different floors."
+      }
+    },
+    {
+      "name": "--color-ai-wash",
+      "layer": "semantic",
+      "value": {
+        "dark": "rgba(90, 167, 255, 0.1)",
+        "light": "rgba(0, 99, 213, 0.08)"
+      },
+      "use": "The faint tint inside a field an AI filled, laid over the control fill. Input and Textarea paint it; nothing else should.",
+      "measured": {
+        "dark": "Tint laid over the control fill of an AI-filled field. Text on it is text.primary and gated (composited over surface.sunken). Never a fill on its own, never under coloured text other than ai.text.",
+        "light": "Tint laid over the control fill of an AI-filled field. Text on it is text.primary and gated (composited over surface.sunken)."
+      }
+    },
     {
       "name": "--color-focus-ring",
       "layer": "semantic",