division-ds 0.1.2 → 0.2.1

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>"
@@ -1408,7 +1537,7 @@
           "name": "tone",
           "type": "'signal' | 'ok' | 'warning' | 'hostile'",
           "default": "'signal'",
-          "description": "The fill colour. signal paints accent.signal.fill to match Slider. On the track in light theme that’s a 2.15:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there."
+          "description": "The fill colour. signal paints accent.signal.indicator to match Slider. On the track in light theme that’s a 2.15:1 contrast ratio, below the 3:1 a bar needs when it’s the only sign of progress. So set showValue there."
         },
         {
           "name": "className",
@@ -1609,7 +1738,7 @@
         }
       ],
       "dos": [
-        "Name the group with aria-label or a FormField legend.",
+        "Name the group: in a form, a fieldset legend that the RadioGroup points at with aria-labelledby; elsewhere, aria-label.",
         "Offer a default when one option really is the norm.",
         "Keep the set short. Past about seven options, use a Select."
       ],
@@ -1618,6 +1747,13 @@
         "Don't put a radio outside a RadioGroup. Both the roving focus and the value come from the group.",
         "Don't make choosing an option perform the action. Put a button after the group."
       ],
+      "pitfalls": [
+        {
+          "wrong": "<FormField label=\"Difficulty\" error={error}>\n  <RadioGroup>\n    <Radio value=\"easy\" />\n  </RadioGroup>\n</FormField>",
+          "right": "<fieldset aria-describedby={error ? 'difficulty-error' : undefined}>\n  <legend id=\"difficulty-label\" className=\"font-mono text-[11px] font-semibold uppercase tracking-[0.12em] text-[var(--color-text-primary)]\">\n    Difficulty\n  </legend>\n  <RadioGroup aria-labelledby=\"difficulty-label\" aria-required=\"true\" value={value} onValueChange={setValue} className=\"mt-2\">\n    {['easy', 'moderate', 'hard'].map(option => (\n      <div key={option} className=\"flex items-center gap-2\">\n        <Radio id={`difficulty-${option}`} value={option} invalid={Boolean(error)} />\n        <label htmlFor={`difficulty-${option}`} className=\"font-body text-sm\">{option}</label>\n      </div>\n    ))}\n  </RadioGroup>\n  {error ? (\n    <p id=\"difficulty-error\" className=\"mt-1.5 font-body text-sm text-[var(--color-accent-hostile-text)]\">{error}</p>\n  ) : null}\n</fieldset>",
+          "why": "FormField clones one control and gives it an id and a label; a group of radios has neither. The fieldset and legend name the group, the label styles match FormField, and the error is linked through aria-describedby. Give ErrorSummary the id of the first Radio so its link lands in the group."
+        }
+      ],
       "anatomy": [
         {
           "part": "RadioGroup",
@@ -1985,7 +2121,7 @@
         },
         {
           "part": "Item",
-          "description": "Highlighted rows use signal.fill with signal.ink. That’s the fill-selection grammar, the system’s rule for how a selection looks."
+          "description": "Highlighted rows use accent.signal.indicator with accent.signal.indicator-ink. That’s the fill-selection grammar, the system’s rule for how a selection looks."
         },
         {
           "part": "ItemIndicator",
@@ -2317,7 +2453,7 @@
         },
         {
           "part": "Range",
-          "description": "The filled span, in signal.fill."
+          "description": "The filled span, in accent.signal.indicator."
         },
         {
           "part": "Thumb",
@@ -2540,7 +2676,7 @@
         {
           "name": "spinnerVariants",
           "kind": "const",
-          "code": "export const spinnerVariants = cva(\n  // The arc takes `currentColor`, so a caller can recolour it with one text utility: Button does\n  // exactly that, so the arc matches whatever ink the button label is set in.\n  'inline-block shrink-0 text-[var(--color-accent-signal-fill)]',\n  {\n    variants: {\n      size: { sm: 'w-3.5 h-3.5', md: 'w-5 h-5', lg: 'w-6 h-6' },\n    },\n    defaultVariants: { size: 'md' },\n  }\n)",
+          "code": "export const spinnerVariants = cva(\n  // The arc takes `currentColor`, so a caller can recolour it with one text utility: Button does\n  // exactly that, so the arc matches whatever ink the button label is set in.\n  'inline-block shrink-0 text-[var(--color-accent-signal-indicator)]',\n  {\n    variants: {\n      size: { sm: 'w-3.5 h-3.5', md: 'w-5 h-5', lg: 'w-6 h-6' },\n    },\n    defaultVariants: { size: 'md' },\n  }\n)",
           "from": "src/components/atoms/spinner/Spinner"
         }
       ],
@@ -2563,7 +2699,7 @@
         },
         {
           "part": "Ring (ring)",
-          "description": "An SVG (Scalable Vector Graphics) track at 20% of currentColor, which is the surrounding text colour, plus an arc in currentColor. That's accent.signal.fill by default."
+          "description": "An SVG (Scalable Vector Graphics) track at 20% of currentColor, which is the surrounding text colour, plus an arc in currentColor. That's accent.signal.indicator by default."
         },
         {
           "part": "Blocks (conveyor)",
@@ -2714,11 +2850,11 @@
         },
         {
           "part": "Thumb",
-          "description": "A 16px (pixel) square, 3px from the track edge in both states, travelling 22px. Its position is the state signal. It's text.primary when off and accent.signal.fill when on. Held down, it stretches 4px away from the edge it rests on: to the right when off, to the left when on, so it never leaves the track. Flipped, it speeds up across the track, gets a little longer in flight and a little shorter against the far edge, then goes back to its own shape. One give, no bounce."
+          "description": "A 16px (pixel) square, 3px from the track edge in both states, travelling 22px. Its position is the state signal. It's text.primary when off and accent.signal.indicator when on. Held down, it stretches 4px away from the edge it rests on: to the right when off, to the left when on, so it never leaves the track. Flipped, it speeds up across the track, gets a little longer in flight and a little shorter against the far edge, then goes back to its own shape. One give, no bounce."
         },
         {
           "part": "Track fill",
-          "description": "The control fill, on and off. When it's on, only the border turns to signal.fill. The track doesn't fill with the accent, so the thumb is the one thing that changes colour during a flip."
+          "description": "The control fill, on and off. When it's on, only the border turns to accent.signal.indicator. The track doesn't fill with the accent, so the thumb is the one thing that changes colour during a flip."
         }
       ],
       "examples": [
@@ -2886,6 +3022,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 +3103,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 +4190,12 @@
             "ChatMessage"
           ],
           "from": "src/components/molecules/chat-message/ChatMessage"
+        },
+        {
+          "names": [
+            "ResponseFeedback"
+          ],
+          "from": "src/components/molecules/chat-message/ResponseFeedback"
         }
       ],
       "requires": [
@@ -4086,6 +4237,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 +4260,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 +4280,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 +4318,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 +4333,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>"
         }
       ]
     },
@@ -4747,7 +4924,7 @@
         {
           "name": "children",
           "type": "ReactElement",
-          "description": "Exactly one control: Input, Textarea, Select or QuantityStepper. A label set on a Select or QuantityStepper child is replaced by the FormField label."
+          "description": "Exactly one control: Input, Textarea, Select or QuantityStepper. A label set on a Select or QuantityStepper child is replaced by the FormField label. An id you give the control is kept (point an ErrorSummary entry at it); without one, FormField makes one up."
         },
         {
           "name": "className",
@@ -5655,6 +5832,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 +5906,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",

package/public/manifest/tokens.json

@@ -564,7 +564,11 @@
       "name": "--color-accent-signal-fill",
       "layer": "semantic",
       "value": "#f2550f",
-      "use": "A solid block in the brand orange: the primary Button, a solid signal Badge. Put accent.signal.ink on it, never text.primary."
+      "use": "A solid block in the brand colour, exactly as chosen: the primary Button, IconButton, a solid signal Badge. Put accent.signal.ink on it, never text.primary. Never use it as the only sign of a state; use accent.signal.indicator.",
+      "measured": {
+        "dark": "The brand colour, exactly as chosen: Button, IconButton and solid Badge backgrounds, and brand decoration. Text on it is accent.signal.ink. Never the only sign of a state; that is accent.signal.indicator. The theme builder never moves it.",
+        "light": "The brand colour, exactly as chosen: Button, IconButton and solid Badge backgrounds, and brand decoration. Text on it is accent.signal.ink. Never the only sign of a state; that is accent.signal.indicator. The theme builder never moves it."
+      }
     },
     {
       "name": "--color-accent-signal-text",
@@ -585,7 +589,28 @@
       "value": "#0a0602",
       "use": "Text and icons on accent.signal.fill.",
       "measured": {
-        "dark": "5.85:1 on accent.signal.fill"
+        "dark": "5.85:1 on accent.signal.fill",
+        "light": "5.85:1 on accent.signal.fill"
+      }
+    },
+    {
+      "name": "--color-accent-signal-indicator",
+      "layer": "semantic",
+      "value": "#f2550f",
+      "use": "The accent where colour alone shows a state or value: a checked control, Switch on, Progress, Slider, Rating stars, the current item in Sidebar, Navbar, Tabs, SegmentedControl, Stepper and highlighted menu rows. Put accent.signal.indicator-ink on it.",
+      "measured": {
+        "dark": "The accent where colour alone marks a state or a value: checked controls, Switch on, Progress, Slider, Rating stars, the current item of Sidebar, Navbar, Tabs, SegmentedControl, Stepper and highlighted menu rows, and the hero numerals. 5.80:1 on surface.base. Same stop as accent.signal.fill here; the theme builder moves it to a nearby stop when a chosen accent is too pale or too dark to reach 3:1, and leaves accent.signal.fill alone.",
+        "light": "The accent where colour alone marks a state or a value: checked controls, Switch on, Progress, Slider, Rating stars, the current item of Sidebar, Navbar, Tabs, SegmentedControl, Stepper and highlighted menu rows, and the hero numerals. 3.14:1 on surface.base. Same stop as accent.signal.fill here; the theme builder moves it to a nearby stop when a chosen accent is too pale or too dark to reach 3:1, and leaves accent.signal.fill alone."
+      }
+    },
+    {
+      "name": "--color-accent-signal-indicator-ink",
+      "layer": "semantic",
+      "value": "#0a0602",
+      "use": "Text and icons on accent.signal.indicator.",
+      "measured": {
+        "dark": "Text and icons on accent.signal.indicator. 5.85:1. The theme builder picks white or this dark ink, whichever reaches 4.5:1.",
+        "light": "Text and icons on accent.signal.indicator. 5.85:1. The theme builder picks white or this dark ink, whichever reaches 4.5:1."
       }
     },
     {
@@ -595,7 +620,7 @@
       "use": "The faint orange hover wash under a nav item or an inactive tab.",
       "measured": {
         "dark": "Hover wash under a nav item or an inactive tab. Text on it is text.primary and gated. The focus ring and a checked control's fill drop under 3:1 on it in light theme, so neither is ever drawn on it.",
-        "light": "Hover wash under a nav item or an inactive tab. Text on it is text.primary and gated. The focus ring and a checked control's fill drop under 3:1 on it in light theme, so neither is ever drawn on it."
+        "light": "Hover wash under a nav item or an inactive tab. Text on it is text.primary and gated. A checked control's indicator drops under 3:1 on it in light theme and the focus ring is not gated on it, so neither is ever drawn on it."
       }
     },
     {
@@ -740,11 +765,56 @@
         "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",
-      "value": "#f2550f",
-      "use": "The keyboard focus outline. Use it only in focus-visible:outline-[var(--color-focus-ring)], with a 2px outline and a 2px offset."
+      "value": {
+        "dark": "#f2550f",
+        "light": "#c6440b"
+      },
+      "use": "The keyboard focus outline. Use it only in focus-visible:outline-[var(--color-focus-ring)], with a 2px outline and a 2px offset.",
+      "measured": {
+        "light": "4.51:1 on surface.base. A step darker than accent.signal.fill, which reaches only 3.14:1 on the light page: the ring is the one mark every keyboard user depends on, so it gets a margin."
+      }
     },
     {
       "name": "--color-chart-series-1",