@miragon/mcp-toolkit-ui 2.7.0 → 2.8.1

package/src/app/widget-fixture.render.test.tsx

@@ -0,0 +1,81 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { Check } from "lucide-react"
+import { ListFooter } from "../components/ListFooter.js"
+import { ICON_STROKE } from "../lib/icon-stroke.js"
+import { LocaleProvider, useLocale } from "../locale/locale-provider.js"
+import { useHostBridge } from "./host-bridge.js"
+import { WidgetFixtureHost } from "./widget-fixture.js"
+
+/**
+ * The harness gives a widget what `McpAppView` gives it in a host, so a
+ * preview in the widget playground shows what a user sees: the toolkit's
+ * strings in the host locale (`globals.locale`), the host theme on the
+ * bridge (`globals.theme`), the CI icon stroke and a toast stack.
+ */
+
+/** A widget made of toolkit chrome: the list footer's text follows the toolkit locale. */
+function Footer() {
+  return <ListFooter shown={8} total={1234} hasMore onLoadMore={() => {}} noun="Aufgaben" />
+}
+
+const render = (globals?: Record<string, unknown>, widget = Footer) =>
+  renderToStaticMarkup(<WidgetFixtureHost widget={widget} globals={globals} />)
+
+describe("WidgetFixtureHost host scope", () => {
+  it("renders the toolkit's strings and number format in globals.locale", () => {
+    const html = render({ locale: "de-DE" })
+    expect(html).toContain("Zeigt 8 von 1.234 Aufgaben")
+    expect(html).toContain("Mehr laden")
+  })
+
+  it("defaults to English and falls back to it for a blank locale", () => {
+    for (const globals of [undefined, { locale: "" }, { locale: 42 }]) {
+      const html = render(globals)
+      expect(html).toContain("Showing 8 of 1,234 Aufgaben")
+      expect(html).toContain("Load more")
+    }
+  })
+
+  it("lets a LocaleProvider around the harness win over globals.locale", () => {
+    const html = renderToStaticMarkup(
+      <LocaleProvider locale="de">
+        <WidgetFixtureHost widget={Footer} globals={{ locale: "en-US" }} />
+      </LocaleProvider>,
+    )
+    expect(html).toContain("Mehr laden")
+  })
+
+  it("leaves useLocale() of the widget alone, like McpAppView does", () => {
+    function ShowsLocale() {
+      return <p>{useLocale()}</p>
+    }
+    expect(render({ locale: "de-DE" }, ShowsLocale)).toContain("<p>en</p>")
+  })
+
+  it("reports globals.theme on the bridge", () => {
+    function ShowsTheme() {
+      return <p>{useHostBridge().theme}</p>
+    }
+    expect(render({ theme: "dark" }, ShowsTheme)).toContain("<p>dark</p>")
+    expect(render(undefined, ShowsTheme)).toContain("<p>light</p>")
+  })
+
+  it("draws Lucide icons at the view's stroke", () => {
+    expect(render(undefined, () => <Check />)).toContain(`stroke-width="${ICON_STROKE}"`)
+  })
+
+  it("mounts the toast stack as the view's one polite live region", () => {
+    // Like McpAppView's: fixed attributes, no role and no name, so the first
+    // toast lands in a region the browser already tracks. Its words (the
+    // dismiss label in the host locale) need a toast, so effects:
+    // widget-fixture.effects.test.tsx.
+    const html = render()
+    const viewport = /<div data-slot="toast-viewport"[^>]*>/.exec(html)?.[0]
+    expect(viewport).toBeDefined()
+    expect(viewport).toContain('aria-live="polite"')
+    expect(viewport).toContain('aria-atomic="false"')
+    expect(viewport).not.toContain("aria-label")
+    expect(viewport).not.toContain("role=")
+  })
+})

package/src/app/widget-fixture.tsx

@@ -1,5 +1,9 @@
 import { createContext, useContext, useMemo, type ComponentType, type ReactNode } from "react"
+import { LucideProvider } from "lucide-react"
 import type { PipelineContext, StepResult, WidgetProps } from "@miragon/mcp-toolkit-core"
+import { ToastProvider } from "../components/Toast.js"
+import { ICON_STROKE } from "../lib/icon-stroke.js"
+import { ToolkitLocaleFallback } from "../locale/locale-provider.js"
 import { AppQueryProvider } from "../providers/query-provider.js"
 import { HostBridgeProvider, createStandaloneHostBridge } from "./host-bridge.js"
 
@@ -143,10 +147,10 @@ export function useFixtureHost(): FixtureHostValue | null {
 }
 
 /**
- * Default host-context values the harness reports. Only `theme` is read since
- * the mcp-use 2.x move (the other host globals were consumed by the 1.x
- * `window.openai` shim); the object keeps its shape so existing playground
- * setups that spread overrides keep compiling.
+ * Default host-context values the harness reports. `theme` and `locale` are
+ * read since the mcp-use 2.x move (the other host globals were consumed by
+ * the 1.x `window.openai` shim); the object keeps its shape so existing
+ * playground setups that spread overrides keep compiling.
  */
 const DEFAULT_GLOBALS = {
   theme: "light",
@@ -192,9 +196,12 @@ export interface WidgetFixtureHostProps {
    */
   tools?: Record<string, FixtureToolEntry>
   /**
-   * Host context overrides, merged over {@link DEFAULT_GLOBALS}. Since the
-   * mcp-use 2.x move only `theme` influences the simulated host; the other
-   * keys are accepted for compatibility with existing playground setups.
+   * Host context overrides, merged over {@link DEFAULT_GLOBALS}. Two keys
+   * influence the simulated host: `theme` (`"light"` | `"dark"`, reported by
+   * `useHostBridge().theme`) and `locale` (a BCP 47 tag: the toolkit's own
+   * strings and number format follow it, exactly as under `McpAppView`; a
+   * `LocaleProvider` around or inside the widget still wins). The other keys
+   * are accepted for compatibility with existing playground setups.
    */
   globals?: Record<string, unknown>
   /**
@@ -247,6 +254,10 @@ export function buildFixtureWidgetProps(
  *   would (adapted widgets report through this bridge outside a real view).
  * - **The toolkit `AppQueryProvider`** — so widgets that fetch via `useToolQuery`
  *   (e.g. generated `use*` hooks) resolve against the same registry.
+ * - **What `McpAppView` gives a widget** — the toolkit's strings in the host
+ *   locale (`globals.locale`, as `McpAppView` does with the host's), the
+ *   toast stack (`useToast()` shows real toasts) and the icon stroke of the
+ *   view (2.5), so the preview matches what a host renders.
  *
  * ### Boundaries
  * The harness simulates the **host-portable pattern** (`useHostBridge`,
@@ -282,10 +293,14 @@ export function WidgetFixtureHost({
   // The standalone host bridge is the harness's single simulation source: it
   // logs every verb through the `HostActionLog` channel for the playground's
   // activity log. Depends on the callback props directly — a fresh Provider
-  // value on callback change is fine for a dev harness. Only `globals.theme`
-  // still influences the simulated host (the remaining globals fed the 1.x
-  // `window.openai` shim).
+  // value on callback change is fine for a dev harness. `globals.theme` and
+  // `globals.locale` influence the simulated host (the remaining globals fed
+  // the 1.x `window.openai` shim).
   const bridgeTheme = (globals?.theme ?? DEFAULT_GLOBALS.theme) === "dark" ? "dark" : "light"
+  const hostLocale =
+    typeof globals?.locale === "string" && globals.locale.trim() !== ""
+      ? globals.locale
+      : DEFAULT_GLOBALS.locale
   const bridge = useMemo(
     () =>
       createStandaloneHostBridge({
@@ -308,11 +323,19 @@ export function WidgetFixtureHost({
   // widgets and raw `({ data })` widgets read their fixture from one mount.
   const RenderWidget = Widget as ComponentType<Record<string, unknown>>
 
+  // The same scope `McpAppView` puts around a widget: the toolkit's strings
+  // in the host locale, the CI icon stroke and a toast stack.
   return (
     <FixtureHostContext.Provider value={value}>
       <HostBridgeProvider bridge={bridge}>
         <AppQueryProvider callTool={callTool}>
-          <RenderWidget {...widgetProps} data={data} />
+          <ToolkitLocaleFallback locale={hostLocale}>
+            <LucideProvider strokeWidth={ICON_STROKE}>
+              <ToastProvider>
+                <RenderWidget {...widgetProps} data={data} />
+              </ToastProvider>
+            </LucideProvider>
+          </ToolkitLocaleFallback>
         </AppQueryProvider>
       </HostBridgeProvider>
     </FixtureHostContext.Provider>

package/src/app/widget-props-sheet.tsx

@@ -18,6 +18,8 @@ import {
 import { Switch } from "../primitives/switch.js"
 import { useToolkitMessages } from "../locale/locale-provider.js"
 import type { PropsSheetMessages } from "../locale/toolkit-messages.js"
+import { propFieldText, type PropFieldText } from "./builder/builder-model.js"
+import { useDisplayResolver } from "./builder/use-display-resolver.js"
 
 /**
  * Tiny JSON-Schema-driven editor for a layout cell's `props`. The
@@ -31,6 +33,12 @@ import type { PropsSheetMessages } from "../locale/toolkit-messages.js"
  *   - Nested objects/arrays/$ref/anyOf are not supported — the field
  *     shows an "edit JSON manually" hint so authors know to fall back.
  *
+ * Each field is labelled in user words: the property's `x-display` title
+ * (`PROPS_SCHEMA_DISPLAY_KEYWORD`, a key or per-locale text), else its JSON
+ * Schema `title`, else its name; the raw property name then follows as a
+ * quiet hint, and the help line is the `x-display` summary or the
+ * `description`.
+ *
  * The sheet writes a clean `Record<string, unknown>` (empty values
  * stripped) and reports `undefined` when the user clears every field, so
  * the cell's `props` field stays absent rather than `{}` — matches the
@@ -39,6 +47,7 @@ import type { PropsSheetMessages } from "../locale/toolkit-messages.js"
 
 interface JsonSchemaProperty {
   type?: string
+  title?: string
   description?: string
   enum?: unknown[]
   default?: unknown
@@ -59,6 +68,8 @@ export interface WidgetPropsSheetProps {
   open: boolean
   onOpenChange: (open: boolean) => void
   widgetId: string
+  /** The widget's human name (its title); the id then shows as a quiet hint under it. */
+  widgetTitle?: string
   schema: Record<string, unknown> | undefined
   value: Record<string, unknown> | undefined
   onApply: (next: Record<string, unknown> | undefined) => void
@@ -69,12 +80,14 @@ export function WidgetPropsSheet({
   open,
   onOpenChange,
   widgetId,
+  widgetTitle,
   schema,
   value,
   onApply,
   labels,
 }: WidgetPropsSheetProps) {
   const messages = useToolkitMessages()
+  const { locale, resolveKey } = useDisplayResolver()
   const L = { ...messages.propsSheet, ...labels }
   const obj = (schema ?? {}) as JsonSchemaObject
   const [draft, setDraft] = useState<Record<string, unknown>>(value ?? {})
@@ -109,7 +122,8 @@ export function WidgetPropsSheet({
           <SheetTitle>{L.title}</SheetTitle>
           <SheetDescription className="flex flex-col items-start gap-1">
             <span>{L.description}</span>
-            <span className="bg-muted rounded px-1 font-mono text-xs">{widgetId}</span>
+            {widgetTitle && <span className="text-foreground font-medium">{widgetTitle}</span>}
+            <span className="bg-muted text-small rounded px-1 font-mono">{widgetId}</span>
           </SheetDescription>
         </SheetHeader>
         <div className="flex flex-col gap-4 px-4 py-4">
@@ -120,6 +134,7 @@ export function WidgetPropsSheet({
               <PropertyField
                 key={key}
                 name={key}
+                text={propFieldText(key, prop as Record<string, unknown>, locale, resolveKey)}
                 prop={prop}
                 value={draft[key]}
                 unsetLabel={L.unsetOption}
@@ -156,6 +171,7 @@ export function WidgetPropsSheet({
 
 function PropertyField({
   name,
+  text,
   prop,
   value,
   unsetLabel,
@@ -163,6 +179,7 @@ function PropertyField({
   onChange,
 }: {
   name: string
+  text: PropFieldText
   prop: JsonSchemaProperty
   value: unknown
   unsetLabel: string
@@ -175,12 +192,12 @@ function PropertyField({
     const options = prop.enum.filter((v): v is string => typeof v === "string")
     const current = typeof value === "string" && value !== "" ? value : UNSET_SENTINEL
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Select
           value={current}
           onValueChange={(v) => onChange(v === UNSET_SENTINEL ? undefined : v)}
         >
-          <SelectTrigger id={id}>
+          <SelectTrigger id={id} aria-describedby={helpId(id, text)}>
             <SelectValue placeholder={unsetLabel} />
           </SelectTrigger>
           <SelectContent>
@@ -199,9 +216,10 @@ function PropertyField({
   if (prop.type === "string") {
     const current = typeof value === "string" ? value : ""
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Input
           id={id}
+          aria-describedby={helpId(id, text)}
           value={current}
           onChange={(e) => onChange(e.target.value === "" ? undefined : e.target.value)}
         />
@@ -212,9 +230,10 @@ function PropertyField({
   if (prop.type === "number" || prop.type === "integer") {
     const current = typeof value === "number" ? String(value) : ""
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Input
           id={id}
+          aria-describedby={helpId(id, text)}
           type="number"
           value={current}
           onChange={(e) => {
@@ -232,9 +251,10 @@ function PropertyField({
   if (prop.type === "boolean") {
     const current = value === true
     return (
-      <FieldShell id={id} name={name} description={prop.description}>
+      <FieldShell id={id} text={text}>
         <Switch
           id={id}
+          aria-describedby={helpId(id, text)}
           checked={current}
           onCheckedChange={(checked) => onChange(checked || undefined)}
         />
@@ -243,30 +263,51 @@ function PropertyField({
   }
 
   return (
-    <FieldShell id={id} name={name} description={prop.description}>
-      <p className="text-muted-foreground text-xs italic">{unsupportedLabel(prop.type ?? "?")}</p>
+    <FieldShell id={id} text={text}>
+      <p className="text-muted-foreground text-small italic">
+        {unsupportedLabel(prop.type ?? "?")}
+      </p>
     </FieldShell>
   )
 }
 
+/** The id of a field's help line, when it has one (its `aria-describedby`). */
+function helpId(id: string, text: PropFieldText): string | undefined {
+  return text.help ? `${id}-help` : undefined
+}
+
+/**
+ * Label (the human title), the raw property name as a quiet hint beside it
+ * (outside the label, so the accessible name stays the title), the control,
+ * and the help line it is described by.
+ */
 function FieldShell({
   id,
-  name,
-  description,
+  text,
   children,
 }: {
   id: string
-  name: string
-  description?: string
+  text: PropFieldText
   children: ReactNode
 }) {
   return (
     <div className="flex flex-col gap-1.5">
-      <label htmlFor={id} className="text-sm font-medium">
-        {name}
-      </label>
+      <div className="flex flex-wrap items-baseline gap-x-2">
+        <label htmlFor={id} className="text-sm font-medium">
+          {text.label}
+        </label>
+        {text.hint && (
+          <code data-slot="prop-name" className="text-muted-foreground text-small font-mono">
+            {text.hint}
+          </code>
+        )}
+      </div>
       {children}
-      {description ? <p className="text-muted-foreground text-xs">{description}</p> : null}
+      {text.help ? (
+        <p id={helpId(id, text)} className="text-muted-foreground text-small">
+          {text.help}
+        </p>
+      ) : null}
     </div>
   )
 }

package/src/app/widget-renderer.tsx

@@ -126,7 +126,7 @@ export function UnavailableWidget({
   return (
     <div data-slot="widget-unavailable" data-widget-id={widgetId} className={className}>
       <p>{messages.renderer.widgetUnavailable}</p>
-      <p className="mt-1 font-mono text-xs break-all">{widgetId}</p>
+      <p className="text-small mt-1 font-mono break-all">{widgetId}</p>
     </div>
   )
 }

package/src/components/DrillButton.test.tsx

@@ -0,0 +1,48 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import { ExternalLink } from "lucide-react"
+import { attribute, openingTags, userFacingTexts } from "../render-scan.js"
+import { buttonVariants } from "../primitives/button.js"
+import { DrillButton } from "./DrillButton.js"
+
+const noop = () => undefined
+const classOf = (tag: string | undefined) => attribute(tag ?? "", "class") ?? ""
+
+describe("DrillButton: the outline Button with a trailing arrow (mcp-toolkit#194)", () => {
+  it("sm is a Button size sm: 32 px, 14 px, weight 600, like the buttons beside it in a row", () => {
+    const html = renderToStaticMarkup(<DrillButton onDrill={noop}>Open</DrillButton>)
+    const [button] = openingTags(html, "button")
+    expect(classOf(button)).toBe(buttonVariants({ variant: "outline", size: "sm" }))
+    expect(classOf(button)).toMatch(/\bh-8\b/)
+    expect(classOf(button)).toMatch(/\btext-sm\b/)
+    expect(classOf(button)).toMatch(/\bfont-semibold\b/)
+    expect(attribute(button ?? "", "type")).toBe("button")
+  })
+
+  it("md is the Button default size (surface headers)", () => {
+    const html = renderToStaticMarkup(
+      <DrillButton onDrill={noop} size="md">
+        View running instances
+      </DrillButton>,
+    )
+    expect(classOf(openingTags(html, "button")[0])).toBe(
+      buttonVariants({ variant: "outline", size: "default" }),
+    )
+  })
+
+  it("keeps its words: the label, a decorative leading icon and a decorative trailing arrow", () => {
+    const html = renderToStaticMarkup(
+      <DrillButton onDrill={noop} icon={<ExternalLink />} ariaLabel="Open order o-1001">
+        Open
+      </DrillButton>,
+    )
+    const [button] = openingTags(html, "button")
+    expect(attribute(button ?? "", "aria-label")).toBe("Open order o-1001")
+    expect(userFacingTexts(html).map((t) => t.value)).toContain("Open")
+    const svgs = openingTags(html, "svg")
+    expect(svgs).toHaveLength(2)
+    expect(svgs.at(-1)).toContain("lucide-arrow-right")
+    for (const svg of svgs) expect(attribute(svg, "aria-hidden")).toBe("true")
+    expect(openingTags(html, "span")[0]).toContain('aria-hidden="true"')
+  })
+})

package/src/components/DrillButton.tsx

@@ -1,38 +1,53 @@
 import type { ReactNode } from "react"
-import { FOCUS_RING } from "../lib/focus-ring.js"
+import { ArrowRight } from "lucide-react"
+import { buttonVariants } from "../primitives/button.js"
 
 export interface DrillButtonProps {
   /** Button label. */
   children: ReactNode
   /** Drill/navigation handler — wire to in-widget navigation (e.g. `showWidget`). */
   onDrill: () => void
-  /** Optional leading glyph (e.g. a domain icon). The trailing → is always rendered. */
+  /**
+   * Optional leading icon — a Lucide icon of the domain, never a typed glyph.
+   * Decorative (`aria-hidden`). The trailing arrow is always rendered.
+   */
   icon?: ReactNode
   /** `sm` for table rows, `md` for surface headers. Default `"sm"`. */
   size?: "sm" | "md"
-  /** Accessible label when the visible text is terse. */
+  /** Accessible label when the visible text is terse; keep the visible text in it (WCAG 2.5.3). */
   ariaLabel?: string
 }
 
+/** The `Button` size each drill size is: one scale for every action of a view. */
+const BUTTON_SIZE = { sm: "sm", md: "default" } as const
+
 /**
  * The single, deterministic in-widget navigation control: a neutral outline
- * button with a trailing → that drills into a detail/sub-view. Use it for
- * every in-app drill (row "Open", header nav) so they read identically and stay
- * visually quieter than primary/agentic actions. Decoupled from any host — pass
- * an `onDrill` callback (e.g. wrapping `useHostActions().showWidget`).
+ * button with a trailing Lucide arrow that drills into a detail/sub-view. Use
+ * it for every in-app drill (row "Open", header nav) so they read identically
+ * and stay visually quieter than primary/agentic actions. Decoupled from any
+ * host — pass an `onDrill` callback (e.g. wrapping `useHostActions().showWidget`).
+ *
+ * It IS the toolkit's outline `Button` (`buttonVariants`): `sm` is 32 px,
+ * 14 px, weight 600, the size of a `Button size="sm"` or an `AskAiButton`
+ * beside it in a row; `md` is the `Button` default (36 px). The design
+ * system gives every button weight 600 and one radius.
  */
 export function DrillButton({ children, onDrill, icon, size = "sm", ariaLabel }: DrillButtonProps) {
-  const pad = size === "md" ? "px-3 py-1.5 text-sm" : "px-2.5 py-1 text-xs"
   return (
     <button
       type="button"
       onClick={onDrill}
       aria-label={ariaLabel}
-      className={`border-border text-foreground hover:border-focus hover:bg-accent hover:text-accent-foreground inline-flex items-center gap-1 rounded-md border font-medium transition-colors ${FOCUS_RING} ${pad}`}
+      className={buttonVariants({ variant: "outline", size: BUTTON_SIZE[size] })}
     >
-      {icon && <span aria-hidden="true">{icon}</span>}
+      {icon && (
+        <span aria-hidden="true" className="inline-flex">
+          {icon}
+        </span>
+      )}
       {children}
-      <span aria-hidden="true">→</span>
+      <ArrowRight aria-hidden="true" className="size-4 shrink-0" />
     </button>
   )
 }

package/src/components/EmptyState.tsx

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react"
-import { TONE_ICON } from "../lib/tone-utils.js"
+import { resolveTone, TONE_ICON } from "../lib/tone-utils.js"
 import { cn } from "../lib/utils.js"
 
 /** Heading element for an empty/error state title (the surface decides the outline level). */
@@ -50,6 +50,8 @@ export function EmptyState({
   titleAs: Title = "h3",
   className,
 }: EmptyStateProps) {
+  // An untyped tone resolves (`ok` → success); anything else stays quiet.
+  const iconTone = resolveTone(tone) === "success" ? "success" : "neutral"
   return (
     <div
       data-slot="empty-state"
@@ -60,15 +62,15 @@ export function EmptyState({
           aria-hidden="true"
           className={cn(
             "mb-1 flex items-center justify-center [&_svg:not([class*='size-'])]:size-6",
-            ICON_TONE[tone],
+            ICON_TONE[iconTone],
           )}
         >
           {icon}
         </div>
       )}
-      <Title className="text-foreground text-base font-semibold">{title}</Title>
+      <Title className="text-foreground text-body font-semibold">{title}</Title>
       {description && (
-        <p className="text-muted-foreground max-w-prose text-sm text-balance">{description}</p>
+        <p className="text-muted-foreground text-body max-w-prose text-balance">{description}</p>
       )}
       {(action || secondaryAction) && (
         <div className="mt-2 flex flex-wrap items-center justify-center gap-2">

package/src/components/ErrorState.tsx

@@ -3,7 +3,7 @@ import { CircleAlert, Info, RefreshCw, TriangleAlert, type LucideIcon } from "lu
 import { useToolkitMessages } from "../locale/locale-provider.js"
 import { Button } from "../primitives/button.js"
 import { FOCUS_RING } from "../lib/focus-ring.js"
-import { TONE_BORDER, TONE_ICON, TONE_SOFT } from "../lib/tone-utils.js"
+import { resolveTone, TONE_BORDER, TONE_ICON, TONE_SOFT } from "../lib/tone-utils.js"
 import { cn } from "../lib/utils.js"
 import type { StateHeadingLevel } from "./EmptyState.js"
 
@@ -28,7 +28,10 @@ export interface ErrorStateProps {
   retryLabel?: string
   /** Further actions after the retry button (e.g. a link to another view). */
   actions?: ReactNode
-  /** Default `"danger"`. `"warning"` for partial failures, `"info"` for notices. */
+  /**
+   * Default `"danger"`. `"warning"` for partial failures, `"info"` for
+   * notices. An untyped retired name still resolves (`error` → `danger`).
+   */
   tone?: ErrorStateTone
   /** Replace the tone's default Lucide icon. */
   icon?: LucideIcon
@@ -54,19 +57,36 @@ const STATE_ICON: Record<ErrorStateTone, LucideIcon> = {
   info: Info,
 }
 
-/** Per-variant geometry: `block` replaces a surface, `inline` sits above content. */
+/**
+ * The state's tone from whatever arrives: its three tones as is, a retired
+ * name through `resolveTone` (`error` → `danger`, `notice` → `info`), any
+ * other tone or unknown name as the default `danger`. A tone from untyped
+ * data (plain JS, the wire) never crashes the view on a missing icon.
+ */
+function stateTone(name: unknown): ErrorStateTone {
+  const tone = resolveTone(name, "danger")
+  return tone === "warning" || tone === "info" ? tone : "danger"
+}
+
+/**
+ * Per-variant geometry: `block` replaces a surface and reads as running text
+ * (16 px), `inline` is the compact alert box above content that still renders
+ * (14 px, the dense-controls exception of the type scale).
+ */
 const VARIANT = {
   block: {
     box: "gap-4 p-4",
     icon: "size-5",
-    title: "text-base",
+    title: "text-body",
+    description: "text-body",
     defaultTitleAs: "h2",
     retry: "default",
   },
   inline: {
-    box: "gap-3 px-4 py-3 text-sm",
+    box: "gap-3 px-4 py-3 text-dense",
     icon: "size-4",
-    title: "text-sm",
+    title: "text-dense",
+    description: "text-dense",
     defaultTitleAs: "p",
     retry: "outline",
   },
@@ -76,6 +96,7 @@ const VARIANT = {
     box: string
     icon: string
     title: string
+    description: string
     defaultTitleAs: StateHeadingLevel
     retry: "default" | "outline"
   }
@@ -95,13 +116,14 @@ export function ErrorState({
   onRetry,
   retryLabel,
   actions,
-  tone = "danger",
+  tone: toneProp,
   icon,
   variant = "block",
   role = "alert",
   titleAs,
   className,
 }: ErrorStateProps) {
+  const tone = stateTone(toneProp)
   const style = VARIANT[variant]
   const Icon = icon ?? STATE_ICON[tone]
   const Title = titleAs ?? style.defaultTitleAs
@@ -125,7 +147,7 @@ export function ErrorState({
       <Icon aria-hidden="true" className={cn("mt-0.5 shrink-0", style.icon, TONE_ICON[tone])} />
       <div className="flex min-w-0 flex-1 flex-col gap-1">
         <Title className={cn("font-semibold", style.title)}>{title}</Title>
-        {description && <div className="text-sm break-words">{description}</div>}
+        {description && <div className={cn("break-words", style.description)}>{description}</div>}
         {details && <ErrorDetails label={detailsLabel}>{details}</ErrorDetails>}
         <ErrorActions
           onRetry={onRetry}
@@ -146,7 +168,7 @@ export function ErrorState({
 function ErrorDetails({ label, children }: { label: string | undefined; children: ReactNode }) {
   const messages = useToolkitMessages()
   return (
-    <details className="text-xs">
+    <details className="text-small">
       <summary className={`w-fit cursor-pointer rounded-sm py-0.5 select-none ${FOCUS_RING}`}>
         {label ?? messages.common.details}
       </summary>