@robr0/design-system 0.13.0 → 0.14.0

package/README.md

@@ -18,8 +18,8 @@ The **live site** is the portfolio built on the design system. **Storybook** is
 | Part | Description |
 |---|---|
 | **Portfolio website** (`/website`) | Next.js app with case studies, work history, writing, and about pages, all built exclusively with the design system components below. **[Live site →](https://robertritacca.com/)** |
-| **Design system** (`/src`) | <!-- component-count -->114<!-- /component-count --> React components, a three-tier token architecture, dark mode, a WebGL2 ambient background that themes itself from your tokens, and a full documentation site. Built to production standards. **[Storybook →](https://design-system-iota-one.vercel.app/?path=/docs/robr0-ds--docs)** |
-| **AI layer** (`ai` components in `/src`, chat in `/website`, `/evals`) | A site-wide chat that answers questions about the work: built from the library's own `ai` components, grounded in a corpus generated from the site's published content, and scored by a golden-set eval. |
+| **Design system** (`/src`) | <!-- component-count -->120<!-- /component-count --> React components, a three-tier token architecture, dark mode, a WebGL2 ambient background that themes itself from your tokens, and a full documentation site. Built to production standards. **[Storybook →](https://design-system-iota-one.vercel.app/?path=/docs/robr0-ds--docs)** |
+| **AI layer** (`ai` components in `/src`, chat in `/website`, `/evals`) | A site-wide chat that answers questions about the work: built from the library's own `ai` components, grounded in a corpus generated from the site's published content, and scored by a golden-set eval. An MCP endpoint serves the same public data, plus the component prop API, to any agent. |
 
 ---
 
@@ -28,7 +28,7 @@ The **live site** is the portfolio built on the design system. **Storybook** is
 ### Components
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent status · AI button · Alert · Alert dialog · Anchor nav · App layout · App sidebar · Area chart · Avatar · Avatar group · Badge · Bar chart · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gauge · Globe · Input · Instructions · Interrupt card · Kbd · Legend tile · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Reasoning · Scatter chart · Section title · Segmented control · Selection card · Shader field · Skeleton · Slider · Source chip · Sparkline · Spinner · Split pane · Stacked bar chart · Stat · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Tooltip · Tree view · Treemap
+Accordion · Agent plan · Agent status · AI button · Alert · Alert dialog · Anchor nav · App layout · App sidebar · Area chart · Avatar · Avatar group · Badge · Banner · Bar chart · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gauge · Globe · Hover card · Image compare · Input · Instructions · Interrupt card · Kbd · Legend tile · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Scatter chart · Section title · Segmented control · Selection card · Shader field · Skeleton · Slider · Source chip · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Tooltip · Tree view · Treemap
 <!-- component-list:end -->
 
 ### Ambient background
@@ -136,6 +136,12 @@ The answering half is a Claude-backed route (`website/src/app/api/chat/route.ts`
 
 Answers are measured, not assumed. `evals/chat` holds a golden set that runs through the real route (persona, corpus, guardrails, all of it) with `npm run eval:chat`; it costs real API calls, so it runs on demand and never in CI. A second validator fails the build when a golden-set fact is missing from the corpus, which keeps the eval and the site describing the same system.
 
+The AI layer also serves machines directly. The live site exposes a Model Context Protocol endpoint at `https://robertritacca.com/api/mcp`: a stateless Streamable HTTP server with five tools covering the component list, per-component prop APIs, the design tokens, install setup, and full-text search over the same corpus the chat reads. No key, no account; every tool reads only published, generated data. The prop API is built from the same JSDoc that produces the published `.d.ts`, so an agent consuming the package reads the exact contract npm ships:
+
+```bash
+claude mcp add --transport http robr0-ds https://robertritacca.com/api/mcp
+```
+
 ---
 
 ## Tech

package/components/Banner/Banner.css

@@ -0,0 +1,110 @@
+/* ============================================
+   BANNER COMPONENT
+   Full-width page-level status strip
+   ============================================ */
+
+.ds-banner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--gap-lg);
+  width: 100%;
+  padding: var(--padding-sm) var(--padding-lg);
+}
+
+.ds-banner__body {
+  display: flex;
+  align-items: center;
+  gap: var(--gap-sm);
+  min-width: 0;
+}
+
+.ds-banner--center .ds-banner__body {
+  flex: 1;
+  justify-content: center;
+}
+
+.ds-banner__icon {
+  --icon-size: var(--icon-size-sm);
+  flex-shrink: 0;
+}
+
+.ds-banner__content {
+  margin: 0;
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  font-weight: var(--font-paragraph-sm-weight);
+  line-height: var(--font-paragraph-sm-line-height);
+  letter-spacing: var(--font-paragraph-sm-letter-spacing);
+}
+
+.ds-banner__title {
+  font-family: var(--font-paragraph-sm-em-family);
+  font-weight: var(--font-paragraph-sm-em-weight);
+}
+
+.ds-banner__action {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+/* ============================================
+   DISMISS
+   ============================================ */
+
+.ds-banner__dismiss {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--padding-xxs);
+  border: none;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+  border-radius: var(--radius-full);
+  flex-shrink: 0;
+  transition: opacity var(--motion-duration-fast) var(--motion-ease-standard);
+}
+
+.ds-banner__dismiss .material-symbols-rounded {
+  --icon-size: var(--icon-size-sm);
+}
+
+.ds-banner__dismiss:hover {
+  opacity: 0.7;
+}
+
+.ds-banner__dismiss:focus-visible {
+  outline: 2px solid var(--color-action-primary-bg);
+  outline-offset: 2px;
+}
+
+/* ============================================
+   VARIANTS
+   ============================================ */
+
+.ds-banner--info {
+  background-color: var(--color-status-info-bg);
+  color: var(--color-status-info-text);
+}
+
+.ds-banner--positive {
+  background-color: var(--color-status-positive-bg);
+  color: var(--color-status-positive-text);
+}
+
+.ds-banner--warning {
+  background-color: var(--color-status-warning-bg);
+  color: var(--color-status-warning-text);
+}
+
+.ds-banner--error {
+  background-color: var(--color-status-error-bg);
+  color: var(--color-status-error-text);
+}
+
+.ds-banner--neutral {
+  background-color: var(--color-status-neutral-bg);
+  color: var(--color-status-neutral-text);
+}

package/components/Banner/Banner.d.ts

@@ -0,0 +1,36 @@
+import { default as React } from 'react';
+/** Props owned by Banner itself — everything else falls through to the root node. */
+type BannerOwnProps = {
+    /** Status variant determines colour and default icon */
+    variant?: 'info' | 'positive' | 'warning' | 'error' | 'neutral';
+    /** Short leading emphasis before the body text. Deliberately shadows the native `title` attribute — a banner never needs a hover tooltip. */
+    title?: string;
+    /** Banner body content — a single line of text, rendered inside the banner's paragraph */
+    children?: React.ReactNode;
+    /** Custom icon override — Material Symbol name */
+    icon?: string;
+    /** Action slot on the trailing edge, for a compact Button or link */
+    action?: React.ReactNode;
+    /** Whether the banner shows a dismiss button */
+    dismissible?: boolean;
+    /** Callback when the dismiss button is clicked */
+    onDismiss?: () => void;
+    /** Horizontal alignment of the banner content */
+    align?: 'start' | 'center';
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface BannerProps extends BannerOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof BannerOwnProps> {
+}
+/**
+ * Full-width status strip for page-level announcements: a release notice, a
+ * degraded-service warning, an environment flag. The third sibling in the
+ * feedback family — Alert sits inline in the layout, Toast interrupts and
+ * leaves, Banner spans the page and stays until dismissed.
+ *
+ * Stateless like Alert: `dismissible` shows the close control and `onDismiss`
+ * reports the click; removing the banner is the consumer's render decision.
+ * Forwards a ref to the root element and spreads unrecognised props onto it.
+ */
+export declare const Banner: React.ForwardRefExoticComponent<BannerProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/Banner/Banner.js

@@ -0,0 +1,59 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import React from "react";
+import "./Banner.css";
+import "../../fonts/material-symbols.css";
+const defaultIcons = {
+  info: "info",
+  positive: "check_circle",
+  warning: "warning",
+  error: "error",
+  neutral: "campaign"
+};
+const Banner = React.forwardRef(
+  ({
+    variant = "info",
+    title,
+    children,
+    icon,
+    action,
+    dismissible = false,
+    onDismiss,
+    align = "start",
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-banner";
+    const classes = [
+      baseClass,
+      `${baseClass}--${variant}`,
+      align === "center" ? `${baseClass}--center` : "",
+      className
+    ].filter(Boolean).join(" ");
+    const iconName = icon || defaultIcons[variant];
+    return /* @__PURE__ */ jsxs("div", { ...rest, ref, className: classes, role: "status", children: [
+      /* @__PURE__ */ jsxs("div", { className: `${baseClass}__body`, children: [
+        /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon material-symbols-rounded`, "aria-hidden": "true", children: iconName }),
+        /* @__PURE__ */ jsxs("p", { className: `${baseClass}__content`, children: [
+          title && /* @__PURE__ */ jsx("strong", { className: `${baseClass}__title`, children: title }),
+          title && children ? " " : null,
+          children
+        ] }),
+        action && /* @__PURE__ */ jsx("span", { className: `${baseClass}__action`, children: action })
+      ] }),
+      dismissible && /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          className: `${baseClass}__dismiss`,
+          onClick: onDismiss,
+          "aria-label": "Dismiss banner",
+          children: /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", "aria-hidden": "true", children: "close" })
+        }
+      )
+    ] });
+  }
+);
+Banner.displayName = "Banner";
+export {
+  Banner
+};

package/components/ContributionGraph/ContributionGraph.css

@@ -4,14 +4,20 @@
    day, coloured by the contribution colour ramp
    ============================================ */
 
+/* Card chrome, header, and padding come from the shared chart styles
+   (Chart.css); this file owns the grid, legend, and cell ramp. */
+
 .ds-contribution-graph {
   --ds-contribution-cell: 12px;
   --ds-contribution-gap: 3px;
 
+  min-width: 0;
+}
+
+.ds-contribution-graph__content {
   display: flex;
   flex-direction: column;
   gap: var(--gap-sm);
-  width: 100%;
   min-width: 0;
 }
 

package/components/ContributionGraph/ContributionGraph.d.ts

@@ -9,6 +9,12 @@ export interface ContributionDay {
 export interface ContributionGraphProps {
     /** One entry per day, ordered oldest to newest */
     days: ContributionDay[];
+    /** Chart title, in the shared chart header. */
+    title?: string;
+    /** Description text below the title. */
+    subtitle?: string;
+    /** Strip the card chrome (border, padding, fill) when the chart sits inside another panel that supplies the surface */
+    bare?: boolean;
     /** Summary line shown under the grid, e.g. "496 contributions in the last year" */
     caption?: string;
     /** Show month labels above the grid */
@@ -22,5 +28,7 @@ export interface ContributionGraphProps {
  * ContributionGraph renders a GitHub-style contribution heatmap:
  * one cell per day, arranged in weekday rows and week columns,
  * coloured by activity level via the --color-chart-contribution-* ramp.
+ * It wears the chart family's card chrome (title, subtitle, padding) and
+ * takes `bare` to drop it inside a panel that supplies the surface.
  */
-export declare const ContributionGraph: ({ days, caption, showMonthLabels, showLegend, className, }: ContributionGraphProps) => import("react").JSX.Element;
+export declare const ContributionGraph: ({ days, title, subtitle, bare, caption, showMonthLabels, showLegend, className, }: ContributionGraphProps) => import("react").JSX.Element;

package/components/ContributionGraph/ContributionGraph.js

@@ -1,4 +1,5 @@
 import { jsxs, jsx } from "react/jsx-runtime";
+import "../Chart/Chart.css";
 import "./ContributionGraph.css";
 const MONTH_LABELS = [
   "Jan",
@@ -62,6 +63,9 @@ const buildMonthLabels = (weeks) => {
 };
 const ContributionGraph = ({
   days,
+  title,
+  subtitle,
+  bare = false,
   caption,
   showMonthLabels = true,
   showLegend = true,
@@ -69,53 +73,65 @@ const ContributionGraph = ({
 }) => {
   const weeks = buildWeeks(days);
   const monthLabels = buildMonthLabels(weeks);
-  const classes = ["ds-contribution-graph", className].filter(Boolean).join(" ");
+  const chartClass = "ds-chart";
+  const classes = [
+    chartClass,
+    bare && `${chartClass}--bare`,
+    "ds-contribution-graph",
+    className
+  ].filter(Boolean).join(" ");
   const columnTemplate = `repeat(${weeks.length}, minmax(var(--ds-contribution-cell), 1fr))`;
   return /* @__PURE__ */ jsxs("div", { className: classes, children: [
-    /* @__PURE__ */ jsxs("div", { className: "ds-contribution-graph__scroll", children: [
-      showMonthLabels && /* @__PURE__ */ jsx(
-        "div",
-        {
-          className: "ds-contribution-graph__months",
-          style: { gridTemplateColumns: columnTemplate },
-          "aria-hidden": "true",
-          children: monthLabels.map(({ weekIndex, label }) => /* @__PURE__ */ jsx(
-            "span",
-            {
-              className: "ds-contribution-graph__month-label",
-              style: { gridColumnStart: weekIndex + 1 },
-              children: label
-            },
-            `${label}-${weekIndex}`
-          ))
-        }
-      ),
-      /* @__PURE__ */ jsx(
-        "div",
-        {
-          className: "ds-contribution-graph__grid",
-          style: { gridTemplateColumns: columnTemplate },
-          role: "img",
-          "aria-label": caption ?? "Contribution activity",
-          children: weeks.map((week, weekIndex) => /* @__PURE__ */ jsx("div", { className: "ds-contribution-graph__week", children: week.map(
-            (day, dayIndex) => day ? /* @__PURE__ */ jsx(
-              "div",
+    (title || subtitle) && /* @__PURE__ */ jsx("div", { className: `${chartClass}__header`, children: /* @__PURE__ */ jsxs("div", { className: `${chartClass}__header-text`, children: [
+      title && /* @__PURE__ */ jsx("h3", { className: `${chartClass}__title`, children: title }),
+      subtitle && /* @__PURE__ */ jsx("p", { className: `${chartClass}__subtitle`, children: subtitle })
+    ] }) }),
+    /* @__PURE__ */ jsxs("div", { className: `${chartClass}__body ds-contribution-graph__content`, children: [
+      /* @__PURE__ */ jsxs("div", { className: "ds-contribution-graph__scroll", children: [
+        showMonthLabels && /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: "ds-contribution-graph__months",
+            style: { gridTemplateColumns: columnTemplate },
+            "aria-hidden": "true",
+            children: monthLabels.map(({ weekIndex, label }) => /* @__PURE__ */ jsx(
+              "span",
               {
-                className: `ds-contribution-graph__cell ds-contribution-graph__cell--level-${day.level}`,
-                title: formatTooltip(day)
+                className: "ds-contribution-graph__month-label",
+                style: { gridColumnStart: weekIndex + 1 },
+                children: label
               },
-              day.date
-            ) : /* @__PURE__ */ jsx("div", { className: "ds-contribution-graph__cell ds-contribution-graph__cell--empty" }, `pad-${dayIndex}`)
-          ) }, weekIndex))
-        }
-      )
-    ] }),
-    (caption || showLegend) && /* @__PURE__ */ jsxs("div", { className: "ds-contribution-graph__footer", children: [
-      caption && /* @__PURE__ */ jsx("span", { className: "ds-contribution-graph__caption", children: caption }),
-      showLegend && /* @__PURE__ */ jsxs("div", { className: "ds-contribution-graph__legend", "aria-hidden": "true", children: [
-        /* @__PURE__ */ jsx("span", { className: "ds-contribution-graph__legend-label", children: "Less" }),
-        [0, 1, 2, 3, 4].map((level) => /* @__PURE__ */ jsx("div", { className: `ds-contribution-graph__cell ds-contribution-graph__cell--level-${level}` }, level)),
-        /* @__PURE__ */ jsx("span", { className: "ds-contribution-graph__legend-label", children: "More" })
+              `${label}-${weekIndex}`
+            ))
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: "ds-contribution-graph__grid",
+            style: { gridTemplateColumns: columnTemplate },
+            role: "img",
+            "aria-label": caption ?? "Contribution activity",
+            children: weeks.map((week, weekIndex) => /* @__PURE__ */ jsx("div", { className: "ds-contribution-graph__week", children: week.map(
+              (day, dayIndex) => day ? /* @__PURE__ */ jsx(
+                "div",
+                {
+                  className: `ds-contribution-graph__cell ds-contribution-graph__cell--level-${day.level}`,
+                  title: formatTooltip(day)
+                },
+                day.date
+              ) : /* @__PURE__ */ jsx("div", { className: "ds-contribution-graph__cell ds-contribution-graph__cell--empty" }, `pad-${dayIndex}`)
+            ) }, weekIndex))
+          }
+        )
+      ] }),
+      (caption || showLegend) && /* @__PURE__ */ jsxs("div", { className: "ds-contribution-graph__footer", children: [
+        caption && /* @__PURE__ */ jsx("span", { className: "ds-contribution-graph__caption", children: caption }),
+        showLegend && /* @__PURE__ */ jsxs("div", { className: "ds-contribution-graph__legend", "aria-hidden": "true", children: [
+          /* @__PURE__ */ jsx("span", { className: "ds-contribution-graph__legend-label", children: "Less" }),
+          [0, 1, 2, 3, 4].map((level) => /* @__PURE__ */ jsx("div", { className: `ds-contribution-graph__cell ds-contribution-graph__cell--level-${level}` }, level)),
+          /* @__PURE__ */ jsx("span", { className: "ds-contribution-graph__legend-label", children: "More" })
+        ] })
       ] })
     ] })
   ] });

package/components/EmptyState/EmptyState.css

@@ -13,6 +13,11 @@
   gap: var(--gap-md); /* 16px */
   padding: var(--padding-xl); /* 32px */
   width: 100%;
+  /* width: 100% plus own padding — border-box locally (as ContactCard,
+     Checkbox, Composer, SelectionCard and Textarea do), so a consumer
+     without a global reset doesn't get a horizontal scrollbar wherever
+     this is embedded. */
+  box-sizing: border-box;
 }
 
 /* ============================================

package/components/FunnelChart/FunnelChart.css

@@ -9,9 +9,10 @@
    token-only.
    ============================================ */
 
-/* Base */
+/* Base — card chrome, header, and padding come from the shared chart
+   styles (Chart.css); this file owns the stage row alone. */
 
-.ds-funnel-chart {
+.ds-funnel-chart__stages {
   display: flex;
   align-items: center;
   gap: var(--gap-xxs);

package/components/FunnelChart/FunnelChart.d.ts

@@ -15,7 +15,13 @@ export interface FunnelStage {
 type FunnelChartOwnProps = {
     /** Ordered stages, first stage widest. Each later stage's height is its share of the first. */
     data: FunnelStage[];
-    /** Chart height in pixels. */
+    /** Chart title, in the shared chart header. */
+    title?: string;
+    /** Description text below the title. */
+    subtitle?: string;
+    /** Strip the card chrome (border, padding, fill) when the chart sits inside another panel that supplies the surface */
+    bare?: boolean;
+    /** Chart area height in pixels. */
     height?: number;
     /**
      * Floor percentage for a stage's height, so steep drop-offs stay readable.
@@ -32,9 +38,11 @@ export interface FunnelChartProps extends FunnelChartOwnProps, Omit<React.Compon
  * step down with each stage's share of the first, each carrying a centred
  * percentage pill. Pure JSX and CSS computed from props: no recharts, no
  * hooks, no browser APIs, so it deliberately omits 'use client' and renders
- * from a Server Component. Degenerate data stays safe: an empty array
- * renders an empty root, and a zero or negative first value draws every
- * stage at the floor height.
+ * from a Server Component. It wears the chart family's card chrome (title,
+ * subtitle, padding) and takes `bare` to drop it inside a Panel, like every
+ * other chart. Degenerate data stays safe: an empty array renders an empty
+ * stage row, and a zero or negative first value draws every stage at the
+ * floor height.
  */
 export declare const FunnelChart: React.ForwardRefExoticComponent<FunnelChartProps & React.RefAttributes<HTMLDivElement>>;
 export {};

package/components/FunnelChart/FunnelChart.js

@@ -1,11 +1,27 @@
-import { jsx, jsxs } from "react/jsx-runtime";
+import { jsxs, jsx } from "react/jsx-runtime";
 import React from "react";
+import "../Chart/Chart.css";
 import "./FunnelChart.css";
 const SERIES_COUNT = 7;
 const FunnelChart = React.forwardRef(
-  ({ data, height = 190, minStageShare = 16, className = "", style, ...rest }, ref) => {
+  ({
+    data,
+    title,
+    subtitle,
+    bare = false,
+    height = 190,
+    minStageShare = 16,
+    className = "",
+    ...rest
+  }, ref) => {
     const baseClass = "ds-funnel-chart";
-    const classes = [baseClass, className].filter(Boolean).join(" ");
+    const chartClass = "ds-chart";
+    const classes = [
+      chartClass,
+      bare && `${chartClass}--bare`,
+      baseClass,
+      className
+    ].filter(Boolean).join(" ");
     const firstValue = data.length > 0 ? data[0].value : 0;
     const clampShare = (share) => Math.min(Math.max(share, minStageShare), 100);
     const stages = data.map((stage, i) => ({
@@ -14,32 +30,36 @@ const FunnelChart = React.forwardRef(
       color: `var(--color-chart-series-${i % SERIES_COUNT + 1})`
     }));
     const ariaLabel = stages.length > 0 ? `Funnel: ${stages.map((s) => `${s.label} ${s.displayValue ?? s.value.toLocaleString()}`).join(", ")}` : "Funnel, no data";
-    return /* @__PURE__ */ jsx(
-      "div",
-      {
-        ...rest,
-        ref,
-        className: classes,
-        style: { ...style, height },
-        role: "img",
-        "aria-label": ariaLabel,
-        children: stages.map((stage, i) => /* @__PURE__ */ jsx(
-          "div",
-          {
-            className: `${baseClass}__stage`,
-            style: {
-              "--funnel-stage-size": stage.share,
-              "--funnel-stage-color": stage.color
+    return /* @__PURE__ */ jsxs("div", { ...rest, ref, className: classes, children: [
+      (title || subtitle) && /* @__PURE__ */ jsx("div", { className: `${chartClass}__header`, children: /* @__PURE__ */ jsxs("div", { className: `${chartClass}__header-text`, children: [
+        title && /* @__PURE__ */ jsx("h3", { className: `${chartClass}__title`, children: title }),
+        subtitle && /* @__PURE__ */ jsx("p", { className: `${chartClass}__subtitle`, children: subtitle })
+      ] }) }),
+      /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: `${chartClass}__body ${baseClass}__stages`,
+          style: { height },
+          role: "img",
+          "aria-label": ariaLabel,
+          children: stages.map((stage, i) => /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: `${baseClass}__stage`,
+              style: {
+                "--funnel-stage-size": stage.share,
+                "--funnel-stage-color": stage.color
+              },
+              children: /* @__PURE__ */ jsxs("span", { className: `${baseClass}__pct`, children: [
+                Math.round(firstValue > 0 ? stage.value / firstValue * 100 : 0),
+                "%"
+              ] })
             },
-            children: /* @__PURE__ */ jsxs("span", { className: `${baseClass}__pct`, children: [
-              Math.round(firstValue > 0 ? stage.value / firstValue * 100 : 0),
-              "%"
-            ] })
-          },
-          `${stage.label}-${i}`
-        ))
-      }
-    );
+            `${stage.label}-${i}`
+          ))
+        }
+      )
+    ] });
   }
 );
 FunnelChart.displayName = "FunnelChart";

package/components/Gauge/Gauge.css

@@ -1,20 +1,34 @@
 /* ============================================
    GAUGE COMPONENT
    Radial dial for a single bounded reading.
-   Colour flows through `color` — the value arc
-   and reading draw with currentColor, so a tone
-   is one custom property swap.
+   Card chrome, header, and padding come from
+   the shared chart styles (Chart.css) — this
+   file owns the dial alone. Colour flows
+   through `color`: the value arc draws with
+   currentColor, so a tone is one custom
+   property swap.
    ============================================ */
 
-/* Base */
+/* Base — the dial centres in the shared chart body */
 
-.ds-gauge {
+.ds-gauge__body {
+  display: flex;
+  justify-content: center;
+}
+
+/* Unlike the fluid recharts bodies, the dial has intrinsic size — a bare
+   gauge shrink-wraps it so it sits inline in a Stat row or tile. */
+.ds-gauge.ds-chart--bare {
+  width: auto;
+  display: inline-flex;
+}
+
+.ds-gauge__dial {
   position: relative;
   display: inline-flex;
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
-  color: var(--color-action-primary-bg);
 }
 
 .ds-gauge__svg {
@@ -25,7 +39,7 @@
 
 .ds-gauge__track {
   fill: none;
-  stroke: var(--color-bg-container-tertiary);
+  stroke: var(--color-bg-container-secondary);
   stroke-linecap: round;
 }
 
@@ -48,12 +62,15 @@
   pointer-events: none;
 }
 
+/* The centre pair mirrors the chart family's radial centre label:
+   a light sub-display numeral over a caption. */
+
 .ds-gauge__value {
-  font-family: var(--font-heading-3-family);
-  font-size: var(--font-heading-3-size);
-  font-weight: var(--font-heading-3-weight);
-  line-height: var(--font-heading-3-line-height);
-  letter-spacing: var(--font-heading-3-letter-spacing);
+  font-family: var(--font-sub-display-family);
+  font-size: var(--font-sub-display-size);
+  font-weight: var(--font-sub-display-weight);
+  line-height: var(--font-sub-display-line-height);
+  letter-spacing: var(--font-sub-display-letter-spacing);
   color: var(--color-text-primary);
 }
 
@@ -69,7 +86,7 @@
 /* Tones */
 
 .ds-gauge--accent {
-  color: var(--color-action-primary-bg);
+  color: var(--color-chart-series-1);
 }
 
 /* The status hues come from the border tokens, not the text tokens: the