@elabs-ai/components-ai 4.0.0 → 4.2.0

package/src/templates-ai-assistant.stories.tsx

@@ -9,6 +9,7 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
 import { AppIcon } from "@elabs-ai/components-icons";
 import {
+  Button,
   Sidebar,
   SidebarContent,
   SidebarGroup,
@@ -31,7 +32,7 @@ import {
   MessageContent,
   MessageResponse,
 } from "./index";
-import { Bot, History, Home, Settings } from "lucide-react";
+import { Bot, History, Home, MessageSquare, Settings } from "lucide-react";
 
 interface ChatMessage {
   id: string;
@@ -101,8 +102,27 @@ function AiAssistantTemplate() {
             <ConversationContent>
               {messages.length === 0 ? (
                 <ConversationEmptyState
+                  icon={<MessageSquare className="size-8" aria-hidden="true" />}
                   title="Start the conversation"
                   description="Ask anything to begin."
+                  actions={
+                    <>
+                      <Button
+                        onClick={() => send("What can you help me with?")}
+                        size="sm"
+                        variant="outline"
+                      >
+                        What can you help me with?
+                      </Button>
+                      <Button
+                        onClick={() => send("Summarize my recent activity")}
+                        size="sm"
+                        variant="outline"
+                      >
+                        Summarize my recent activity
+                      </Button>
+                    </>
+                  }
                 />
               ) : (
                 messages.map((m) => (

package/src/test-results.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { StatusBadge, StatusIcon, type Status } from "@elabs-ai/components-ui";
+import { StatusBadge, StatusIcon, useLocale, type Status } from "@elabs-ai/components-ui";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { ChevronRightIcon } from "lucide-react";
@@ -64,7 +64,7 @@ export const TestResultsDuration = ({
 
   return (
     <span
-      className={cn("shrink-0 text-muted-foreground text-sm tabular-nums", className)}
+      className={cn("shrink-0 text-muted-foreground text-body tabular-nums", className)}
       {...props}
     >
       {children ?? formatDuration(summary.duration)}
@@ -76,6 +76,7 @@ export type TestResultsSummaryProps = HTMLAttributes<HTMLDivElement>;
 
 export const TestResultsSummary = ({ className, children, ...props }: TestResultsSummaryProps) => {
   const { summary } = useContext(TestResultsContext);
+  const { t } = useLocale();
 
   if (!summary) {
     return null;
@@ -86,16 +87,16 @@ export const TestResultsSummary = ({ className, children, ...props }: TestResult
       {children ?? (
         <>
           <StatusBadge size="sm" status="complete">
-            {summary.passed} passed
+            {t("ai.testResults.passedCount", { count: summary.passed })}
           </StatusBadge>
           {summary.failed > 0 && (
             <StatusBadge size="sm" status="failed">
-              {summary.failed} failed
+              {t("ai.testResults.failedCount", { count: summary.failed })}
             </StatusBadge>
           )}
           {summary.skipped > 0 && (
             <StatusBadge size="sm" status="skipped">
-              {summary.skipped} skipped
+              {t("ai.testResults.skippedCount", { count: summary.skipped })}
             </StatusBadge>
           )}
         </>
@@ -134,6 +135,7 @@ export const TestResultsProgress = ({
   ...props
 }: TestResultsProgressProps) => {
   const { summary } = useContext(TestResultsContext);
+  const { t, formatNumber } = useLocale();
 
   if (!summary) {
     return null;
@@ -156,11 +158,14 @@ export const TestResultsProgress = ({
               style={{ width: `${failedPercent}%` }}
             />
           </div>
-          <div className="flex justify-between text-muted-foreground text-xs tabular-nums">
+          <div className="flex justify-between text-muted-foreground text-meta tabular-nums">
             <span>
-              {summary.passed}/{summary.total} tests passed
+              {t("ai.testResults.testsPassed", { passed: summary.passed, total: summary.total })}
+            </span>
+            <span>
+              {formatNumber(passedPercent, { maximumFractionDigits: 0 })}
+              {"%"}
             </span>
-            <span>{passedPercent.toFixed(0)}%</span>
           </div>
         </>
       )}
@@ -247,7 +252,7 @@ export const TestSuiteName = ({ className, children, ...props }: TestSuiteNamePr
     >
       <ChevronRightIcon className="size-4 shrink-0 text-muted-foreground transition-transform duration-fast ease-standard motion-reduce:transition-none group-data-[state=open]:rotate-90" />
       <TestStatusIcon status={status} />
-      <span className="min-w-0 flex-1 truncate font-medium text-sm">{children ?? name}</span>
+      <span className="min-w-0 flex-1 truncate font-medium text-body">{children ?? name}</span>
     </CollapsibleTrigger>
   );
 };
@@ -265,20 +270,35 @@ export const TestSuiteStats = ({
   className,
   children,
   ...props
-}: TestSuiteStatsProps) => (
-  <div
-    className={cn("ms-auto flex shrink-0 items-center gap-3 text-xs tabular-nums", className)}
-    {...props}
-  >
-    {children ?? (
-      <>
-        {passed > 0 && <span className="text-success-text">{passed} passed</span>}
-        {failed > 0 && <span className="text-destructive-text">{failed} failed</span>}
-        {skipped > 0 && <span className="text-muted-foreground">{skipped} skipped</span>}
-      </>
-    )}
-  </div>
-);
+}: TestSuiteStatsProps) => {
+  const { t } = useLocale();
+  return (
+    <div
+      className={cn("ms-auto flex shrink-0 items-center gap-3 text-meta tabular-nums", className)}
+      {...props}
+    >
+      {children ?? (
+        <>
+          {passed > 0 && (
+            <span className="text-success-text">
+              {t("ai.testResults.passedCount", { count: passed })}
+            </span>
+          )}
+          {failed > 0 && (
+            <span className="text-destructive-text">
+              {t("ai.testResults.failedCount", { count: failed })}
+            </span>
+          )}
+          {skipped > 0 && (
+            <span className="text-muted-foreground">
+              {t("ai.testResults.skippedCount", { count: skipped })}
+            </span>
+          )}
+        </>
+      )}
+    </div>
+  );
+};
 
 export type TestSuiteContentProps = ComponentProps<typeof CollapsibleContent>;
 
@@ -328,7 +348,7 @@ export const TestDuration = ({ className, children, ...props }: TestDurationProp
 
   return (
     <span
-      className={cn("shrink-0 text-muted-foreground text-xs tabular-nums", className)}
+      className={cn("shrink-0 text-muted-foreground text-meta tabular-nums", className)}
       {...props}
     >
       {children ?? `${duration}ms`}
@@ -365,7 +385,7 @@ export const Test = ({ name, status, duration, className, children, ...props }:
   return (
     <TestContext.Provider value={contextValue}>
       <div
-        className={cn("flex min-w-0 items-center gap-2 ps-10 pe-4 py-2 text-sm", className)}
+        className={cn("flex min-w-0 items-center gap-2 ps-10 pe-4 py-2 text-body", className)}
         {...props}
       >
         {children ?? (
@@ -391,7 +411,7 @@ export const TestError = ({ className, children, ...props }: TestErrorProps) =>
 export type TestErrorMessageProps = HTMLAttributes<HTMLParagraphElement>;
 
 export const TestErrorMessage = ({ className, children, ...props }: TestErrorMessageProps) => (
-  <p className={cn("font-medium text-destructive-text text-sm", className)} {...props}>
+  <p className={cn("font-medium text-destructive-text text-body", className)} {...props}>
     {children}
   </p>
 );
@@ -400,7 +420,7 @@ export type TestErrorStackProps = HTMLAttributes<HTMLPreElement>;
 
 export const TestErrorStack = ({ className, children, ...props }: TestErrorStackProps) => (
   <pre
-    className={cn("mt-2 overflow-auto font-mono text-destructive-text text-xs", className)}
+    className={cn("mt-2 overflow-auto font-mono text-destructive-text text-meta", className)}
     {...props}
   >
     {children}

package/src/token-usage.stories.tsx

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { TokenUsage, TokenUsageTrigger } from "./token-usage";
+const meta = {
+  title: "AI/TokenUsage",
+  component: TokenUsage,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The context-WINDOW usage ring: a compact `usedTokens` / `maxTokens` dial that opens a hover card with the input/output token split and, when `modelId` is known, an estimated cost. It was called `Context` until it was renamed for exactly this reason — the chat workspace’s right rail is `AI/ContextPanel`, a different component with a confusingly similar old name. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).",
+      },
+    },
+  },
+} satisfies Meta<typeof TokenUsage>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  render: () => (
+    <TokenUsage usedTokens={2400} maxTokens={8000}>
+      <TokenUsageTrigger />
+    </TokenUsage>
+  ),
+};

package/src/token-usage.test.tsx

@@ -0,0 +1,92 @@
+import type { LanguageModelUsage } from "ai";
+import { DEFAULT_MESSAGES, LocaleProvider } from "@elabs-ai/components-ui";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TokenUsage, TokenUsageCache, TokenUsageReasoning } from "./token-usage";
+
+// `LanguageModelUsage`'s reasoning/cache figures live under nested detail
+// objects (`outputTokenDetails.reasoningTokens`, `inputTokenDetails.cacheReadTokens`).
+// ai@6 also carried deprecated flat top-level aliases (`reasoningTokens`,
+// `cachedInputTokens`); ai@7 removed them. This mock deliberately omits the
+// flat aliases so the test only passes if the components read the nested path.
+const usage: LanguageModelUsage = {
+  inputTokens: 1000,
+  inputTokenDetails: {
+    noCacheTokens: 600,
+    cacheReadTokens: 400,
+    cacheWriteTokens: 0,
+  },
+  outputTokens: 200,
+  outputTokenDetails: {
+    textTokens: 150,
+    reasoningTokens: 50,
+  },
+  totalTokens: 1200,
+};
+
+describe("TokenUsage usage readouts (#30, ai@7 LanguageModelUsage shape)", () => {
+  it("TokenUsageReasoning reads outputTokenDetails.reasoningTokens, not a flat field", () => {
+    render(
+      <TokenUsage maxTokens={8000} usage={usage} usedTokens={1200}>
+        <TokenUsageReasoning />
+      </TokenUsage>,
+    );
+    expect(screen.getByText("Reasoning")).toBeInTheDocument();
+    expect(screen.getByText("50")).toBeInTheDocument();
+  });
+
+  it("TokenUsageCache reads inputTokenDetails.cacheReadTokens, not a flat field", () => {
+    render(
+      <TokenUsage maxTokens={8000} usage={usage} usedTokens={1200}>
+        <TokenUsageCache />
+      </TokenUsage>,
+    );
+    expect(screen.getByText("Cache")).toBeInTheDocument();
+    expect(screen.getByText("400")).toBeInTheDocument();
+  });
+
+  it("renders nothing when the nested detail objects report zero", () => {
+    const zeroUsage: LanguageModelUsage = {
+      ...usage,
+      inputTokenDetails: { ...usage.inputTokenDetails, cacheReadTokens: 0 },
+      outputTokenDetails: { ...usage.outputTokenDetails, reasoningTokens: 0 },
+    };
+    const { container } = render(
+      <TokenUsage maxTokens={8000} usage={zeroUsage} usedTokens={1200}>
+        <TokenUsageReasoning />
+        <TokenUsageCache />
+      </TokenUsage>,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+});
+
+describe("TokenUsage locale keys (#141, ai.context.* renamed to ai.tokenUsage.*)", () => {
+  it("the shipped dictionary defines no ai.context.* key", () => {
+    const staleKeys = Object.keys(DEFAULT_MESSAGES).filter((key) => key.startsWith("ai.context."));
+    expect(staleKeys).toEqual([]);
+  });
+
+  it("renders its labels from the ai.tokenUsage.* namespace, not a stale fallback", () => {
+    render(
+      <LocaleProvider
+        messages={{
+          "ai.tokenUsage.reasoning": "Custom reasoning label",
+          "ai.tokenUsage.cache": "Custom cache label",
+        }}
+      >
+        <TokenUsage maxTokens={8000} usage={usage} usedTokens={1200}>
+          <TokenUsageReasoning />
+          <TokenUsageCache />
+        </TokenUsage>
+      </LocaleProvider>,
+    );
+    // A component still reading the old `ai.context.*` namespace would ignore
+    // this override and keep rendering the untranslated English default
+    // ("Reasoning" / "Cache") instead.
+    expect(screen.getByText("Custom reasoning label")).toBeInTheDocument();
+    expect(screen.getByText("Custom cache label")).toBeInTheDocument();
+    expect(screen.queryByText("Reasoning")).not.toBeInTheDocument();
+    expect(screen.queryByText("Cache")).not.toBeInTheDocument();
+  });
+});

package/src/{context.tsx → token-usage.tsx}

@@ -18,50 +18,56 @@ const ICON_STROKE_WIDTH = 2;
 
 type ModelId = string;
 
-interface ContextSchema {
+interface TokenUsageSchema {
   usedTokens: number;
   maxTokens: number;
   usage?: LanguageModelUsage;
   modelId?: ModelId;
 }
 
-const ContextContext = createContext<ContextSchema | null>(null);
+const TokenUsageContext = createContext<TokenUsageSchema | null>(null);
 
-const useContextValue = () => {
-  const context = useContext(ContextContext);
+const useTokenUsageValue = () => {
+  const context = useContext(TokenUsageContext);
 
   if (!context) {
-    throw new Error("Context components must be used within Context");
+    throw new Error("TokenUsage components must be used within TokenUsage");
   }
 
   return context;
 };
 
-export type ContextProps = ComponentProps<typeof HoverCard> & ContextSchema;
+export type TokenUsageProps = ComponentProps<typeof HoverCard> & TokenUsageSchema;
 
-export const Context = ({ usedTokens, maxTokens, usage, modelId, ...props }: ContextProps) => {
+export const TokenUsage = ({
+  usedTokens,
+  maxTokens,
+  usage,
+  modelId,
+  ...props
+}: TokenUsageProps) => {
   const contextValue = useMemo(
     () => ({ maxTokens, modelId, usage, usedTokens }),
     [maxTokens, modelId, usage, usedTokens],
   );
 
   return (
-    <ContextContext.Provider value={contextValue}>
+    <TokenUsageContext.Provider value={contextValue}>
       <HoverCard closeDelay={0} openDelay={0} {...props} />
-    </ContextContext.Provider>
+    </TokenUsageContext.Provider>
   );
 };
 
-const ContextIcon = () => {
+const TokenUsageIcon = () => {
   const { t } = useLocale();
-  const { usedTokens, maxTokens } = useContextValue();
+  const { usedTokens, maxTokens } = useTokenUsageValue();
   const circumference = 2 * Math.PI * ICON_RADIUS;
   const usedPercent = usedTokens / maxTokens;
   const dashOffset = circumference * (1 - usedPercent);
 
   return (
     <svg
-      aria-label={t("ai.context.usage")}
+      aria-label={t("ai.tokenUsage.usage")}
       height="20"
       role="img"
       style={{ color: "currentcolor" }}
@@ -94,11 +100,11 @@ const ContextIcon = () => {
   );
 };
 
-export type ContextTriggerProps = ComponentProps<typeof Button>;
+export type TokenUsageTriggerProps = ComponentProps<typeof Button>;
 
-export const ContextTrigger = ({ children, ...props }: ContextTriggerProps) => {
+export const TokenUsageTrigger = ({ children, ...props }: TokenUsageTriggerProps) => {
   const { formatNumber } = useLocale();
-  const { usedTokens, maxTokens } = useContextValue();
+  const { usedTokens, maxTokens } = useTokenUsageValue();
   const usedPercent = usedTokens / maxTokens;
   const renderedPercent = formatNumber(usedPercent, {
     maximumFractionDigits: 1,
@@ -110,28 +116,28 @@ export const ContextTrigger = ({ children, ...props }: ContextTriggerProps) => {
       {children ?? (
         <Button type="button" variant="ghost" {...props}>
           <span className="font-medium text-muted-foreground">{renderedPercent}</span>
-          <ContextIcon />
+          <TokenUsageIcon />
         </Button>
       )}
     </HoverCardTrigger>
   );
 };
 
-export type ContextContentProps = ComponentProps<typeof HoverCardContent>;
+export type TokenUsageContentProps = ComponentProps<typeof HoverCardContent>;
 
-export const ContextContent = ({ className, ...props }: ContextContentProps) => (
+export const TokenUsageContent = ({ className, ...props }: TokenUsageContentProps) => (
   <HoverCardContent className={cn("min-w-60 divide-y overflow-hidden p-0", className)} {...props} />
 );
 
-export type ContextContentHeaderProps = ComponentProps<"div">;
+export type TokenUsageContentHeaderProps = ComponentProps<"div">;
 
-export const ContextContentHeader = ({
+export const TokenUsageContentHeader = ({
   children,
   className,
   ...props
-}: ContextContentHeaderProps) => {
+}: TokenUsageContentHeaderProps) => {
   const { formatNumber } = useLocale();
-  const { usedTokens, maxTokens } = useContextValue();
+  const { usedTokens, maxTokens } = useTokenUsageValue();
   const usedPercent = usedTokens / maxTokens;
   const displayPct = formatNumber(usedPercent, {
     maximumFractionDigits: 1,
@@ -148,7 +154,7 @@ export const ContextContentHeader = ({
     <div className={cn("w-full space-y-2 p-3", className)} {...props}>
       {children ?? (
         <>
-          <div className="flex items-center justify-between gap-3 text-xs">
+          <div className="flex items-center justify-between gap-3 text-meta">
             <p>{displayPct}</p>
             <p className="font-mono text-muted-foreground">
               {used} / {total}
@@ -163,23 +169,27 @@ export const ContextContentHeader = ({
   );
 };
 
-export type ContextContentBodyProps = ComponentProps<"div">;
+export type TokenUsageContentBodyProps = ComponentProps<"div">;
 
-export const ContextContentBody = ({ children, className, ...props }: ContextContentBodyProps) => (
+export const TokenUsageContentBody = ({
+  children,
+  className,
+  ...props
+}: TokenUsageContentBodyProps) => (
   <div className={cn("w-full p-3", className)} {...props}>
     {children}
   </div>
 );
 
-export type ContextContentFooterProps = ComponentProps<"div">;
+export type TokenUsageContentFooterProps = ComponentProps<"div">;
 
-export const ContextContentFooter = ({
+export const TokenUsageContentFooter = ({
   children,
   className,
   ...props
-}: ContextContentFooterProps) => {
-  const { formatNumber } = useLocale();
-  const { modelId, usage } = useContextValue();
+}: TokenUsageContentFooterProps) => {
+  const { formatNumber, t } = useLocale();
+  const { modelId, usage } = useTokenUsageValue();
   const costUSD = modelId
     ? getUsage({
         modelId,
@@ -197,14 +207,14 @@ export const ContextContentFooter = ({
   return (
     <div
       className={cn(
-        "flex w-full items-center justify-between gap-3 bg-secondary p-3 text-xs",
+        "flex w-full items-center justify-between gap-3 bg-secondary p-3 text-meta",
         className,
       )}
       {...props}
     >
       {children ?? (
         <>
-          <span className="text-muted-foreground">Total cost</span>
+          <span className="text-muted-foreground">{t("ai.tokenUsage.totalCost")}</span>
           <span>{totalCost}</span>
         </>
       )}
@@ -222,11 +232,11 @@ const TokensWithCost = ({ tokens, costText }: { tokens?: number; costText?: stri
   );
 };
 
-export type ContextInputUsageProps = ComponentProps<"div">;
+export type TokenUsageInputProps = ComponentProps<"div">;
 
-export const ContextInputUsage = ({ className, children, ...props }: ContextInputUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
+export const TokenUsageInput = ({ className, children, ...props }: TokenUsageInputProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
   const inputTokens = usage?.inputTokens ?? 0;
 
   if (children) {
@@ -249,18 +259,18 @@ export const ContextInputUsage = ({ className, children, ...props }: ContextInpu
   });
 
   return (
-    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Input</span>
+    <div className={cn("flex items-center justify-between text-meta", className)} {...props}>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.input")}</span>
       <TokensWithCost costText={inputCostText} tokens={inputTokens} />
     </div>
   );
 };
 
-export type ContextOutputUsageProps = ComponentProps<"div">;
+export type TokenUsageOutputProps = ComponentProps<"div">;
 
-export const ContextOutputUsage = ({ className, children, ...props }: ContextOutputUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
+export const TokenUsageOutput = ({ className, children, ...props }: TokenUsageOutputProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
   const outputTokens = usage?.outputTokens ?? 0;
 
   if (children) {
@@ -283,23 +293,25 @@ export const ContextOutputUsage = ({ className, children, ...props }: ContextOut
   });
 
   return (
-    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Output</span>
+    <div className={cn("flex items-center justify-between text-meta", className)} {...props}>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.output")}</span>
       <TokensWithCost costText={outputCostText} tokens={outputTokens} />
     </div>
   );
 };
 
-export type ContextReasoningUsageProps = ComponentProps<"div">;
+export type TokenUsageReasoningProps = ComponentProps<"div">;
 
-export const ContextReasoningUsage = ({
+export const TokenUsageReasoning = ({
   className,
   children,
   ...props
-}: ContextReasoningUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
-  const reasoningTokens = usage?.reasoningTokens ?? 0;
+}: TokenUsageReasoningProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
+  // `reasoningTokens` moved under `outputTokenDetails` in ai@7 (the flat,
+  // deprecated top-level alias from ai@6 was removed).
+  const reasoningTokens = usage?.outputTokenDetails?.reasoningTokens ?? 0;
 
   if (children) {
     return children;
@@ -321,19 +333,21 @@ export const ContextReasoningUsage = ({
   });
 
   return (
-    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Reasoning</span>
+    <div className={cn("flex items-center justify-between text-meta", className)} {...props}>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.reasoning")}</span>
       <TokensWithCost costText={reasoningCostText} tokens={reasoningTokens} />
     </div>
   );
 };
 
-export type ContextCacheUsageProps = ComponentProps<"div">;
+export type TokenUsageCacheProps = ComponentProps<"div">;
 
-export const ContextCacheUsage = ({ className, children, ...props }: ContextCacheUsageProps) => {
-  const { formatNumber } = useLocale();
-  const { usage, modelId } = useContextValue();
-  const cacheTokens = usage?.cachedInputTokens ?? 0;
+export const TokenUsageCache = ({ className, children, ...props }: TokenUsageCacheProps) => {
+  const { formatNumber, t } = useLocale();
+  const { usage, modelId } = useTokenUsageValue();
+  // `cachedInputTokens` moved under `inputTokenDetails.cacheReadTokens` in
+  // ai@7 (the flat, deprecated top-level alias from ai@6 was removed).
+  const cacheTokens = usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 
   if (children) {
     return children;
@@ -355,8 +369,8 @@ export const ContextCacheUsage = ({ className, children, ...props }: ContextCach
   });
 
   return (
-    <div className={cn("flex items-center justify-between text-xs", className)} {...props}>
-      <span className="text-muted-foreground">Cache</span>
+    <div className={cn("flex items-center justify-between text-meta", className)} {...props}>
+      <span className="text-muted-foreground">{t("ai.tokenUsage.cache")}</span>
       <TokensWithCost costText={cacheCostText} tokens={cacheTokens} />
     </div>
   );

package/src/tool-result-card.stories.tsx

@@ -9,7 +9,15 @@ import { ToolResultCard } from "./tool-result-card";
 const meta = {
   title: "AI/ToolResultCard",
   component: ToolResultCard,
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT produced-artifact card; a console transcript renders the same moment through `Terminal/TerminalToolCall` — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). A separate component from `AI/Tool` by design: `Tool` is the step that RAN (JSON behind disclosure), `ToolResultCard` hosts what it produced — a chart, a table, a file preview — as `children`, on the elevation channel (raised fill, no border).",
+      },
+    },
+  },
   tags: ["autodocs"],
 } satisfies Meta<typeof ToolResultCard>;
 export default meta;

package/src/tool.stories.tsx

@@ -8,9 +8,19 @@ import {
   ToolOutput,
   statusFromToolState,
 } from "./tool";
-const meta = { title: "AI/Tool", component: Tool, parameters: { layout: "padded" } } satisfies Meta<
-  typeof Tool
->;
+const meta = {
+  title: "AI/Tool",
+  component: Tool,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT tool-call row; the console skin is `Terminal/TerminalToolCall`, and both speak the same success / error / pending vocabulary — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). `Tool` owns the rail-and-inspect idiom: a header carrying the derived tool name, a `StatusBadge` and a business summary, with the raw payload behind a default-collapsed `ToolDetails`. The artifact a call PRODUCED is `AI/ToolResultCard` instead.",
+      },
+    },
+  },
+} satisfies Meta<typeof Tool>;
 export default meta;
 type Story = StoryObj<typeof meta>;
 // JSON-behind-disclosure is the package default (#192, research 10 §B.5): the