@robr0/design-system 0.3.0 → 0.4.0

package/README.md

@@ -1,15 +1,15 @@
-# robr0 — Portfolio + Design System
+# robr0: portfolio + AI-ready design system
 
 [![CI](https://github.com/robritacca-dotcom/design-system/actions/workflows/ci.yml/badge.svg)](https://github.com/robritacca-dotcom/design-system/actions/workflows/ci.yml)
 <!-- npm-badge:start -->
 [![npm](https://img.shields.io/npm/v/@robr0%2Fdesign-system?logo=npm&color=CB3837)](https://www.npmjs.com/package/@robr0/design-system)
 <!-- npm-badge:end -->
 
-A personal portfolio site built on a custom React design system I designed and engineered from scratch. The DS isn't a side project — it's the backbone every portfolio page is built on, ensuring the work is presented consistently and with the same craft standards I apply professionally.
+A personal portfolio site built on an AI-ready React design system, designed and engineered from scratch. Claude Code builds the components from the written specs in this repo (`CLAUDE.md` for the rules, `design.md` for the design language, `content-design.md` for how every word reads), and generated registries keep this README and the docs site from drifting. The design system is the backbone every portfolio page is built on, so the work is presented consistently and to the same craft standards throughout.
 
 **[→ Live site](https://robertritacca.com/)** · **[→ Storybook](https://design-system-iota-one.vercel.app/?path=/docs/robr0-ds--docs)**
 
-The **live site** is the portfolio built on the design system. **Storybook** is the interactive component explorer for the design system itself — two separate parts of this repo.
+The **live site** is the portfolio built on the design system. **Storybook** is the interactive component explorer for the design system itself. They are two separate parts of this repo.
 
 ---
 
@@ -17,8 +17,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 -->61<!-- /component-count --> React components, a three-tier token architecture, dark mode, and a full documentation site. Built to production standards. **[Storybook →](https://design-system-iota-one.vercel.app/?path=/docs/robr0-ds--docs)** |
+| **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 -->64<!-- /component-count --> React components, a three-tier token architecture, dark mode, and a full documentation site. Built to production standards. **[Storybook →](https://design-system-iota-one.vercel.app/?path=/docs/robr0-ds--docs)** |
 
 ---
 
@@ -27,12 +27,12 @@ The **live site** is the portfolio built on the design system. **Storybook** is
 ### Components
 
 <!-- component-list:start -->
-Accordion · Alert · Alert dialog · App layout · App sidebar · Avatar · Badge · Breadcrumb · Button · Button group · Card · Carousel · Chart · Checkbox · Chip · Circular button · Code block · Colour picker · Combobox · Command palette · Contact card · Context menu · Contribution graph · Date input · Date picker · Dialog · Divider · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Field · Figure · File input · Input · Instructions · Kbd · Link list · Navigation · Pagination · Popover · Progress bar · Quote · Radio button · Section title · Segmented control · Selection card · Skeleton · Slider · Spinner · Stat · Swatch · Table · Tabs · Textarea · Timeline · Toast · Toggle group · Toggle switch · Tooltip
+Accordion · Agent status · Alert · Alert dialog · App layout · App sidebar · Avatar · Badge · Breadcrumb · Button · Button group · Card · Carousel · Chart · Checkbox · Chip · Circular button · Code block · Colour picker · Combobox · Command palette · Contact card · Context menu · Contribution graph · Date input · Date picker · Dialog · Divider · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Field · Figure · File input · Input · Instructions · Kbd · Link list · Navigation · Pagination · Popover · Progress bar · Quote · Radio button · Reasoning · Section title · Segmented control · Selection card · Skeleton · Slider · Spinner · Stat · Swatch · Table · Tabs · Textarea · Timeline · Toast · Toggle group · Toggle switch · Tool call · Tooltip
 <!-- component-list:end -->
 
 ### Using the package
 
-The design system is published as [`@robr0/design-system`](https://www.npmjs.com/package/@robr0/design-system) (React 19+ is a peer dependency) — the **[full setup guide](https://www.robertritacca.com/docs/get-started)** covers install, dark mode, fonts, and re-theming:
+The design system is published as [`@robr0/design-system`](https://www.npmjs.com/package/@robr0/design-system) (React 19+ is a peer dependency). The **[full setup guide](https://robertritacca.com/docs/get-started)** covers install, dark mode, fonts, and re-theming:
 
 ```bash
 npm install @robr0/design-system
@@ -53,14 +53,14 @@ Deep imports work too (`@robr0/design-system/components/Button/Button`). Chart c
 import { BarChart, LineChart } from '@robr0/design-system/charts';
 ```
 
-**Theming and customization** happen through CSS variables — no configuration API. Components are provider-free, with one exception: wrap your tree in `ToastProvider` if (and only if) you use the toast queue via `useToast`.
+**Theming and customisation** happen through CSS variables; there is no configuration API. Components are provider-free, with one exception: wrap your tree in `ToastProvider` if (and only if) you use the toast queue via `useToast`.
 
 - **Dark mode**: set `data-theme="dark"` on the root element (light is the default).
 - **Font**: the whole type scale chains to one token. Load any font you like and override it:
   ```css
   :root { --font-family-primary: 'Inter', sans-serif; }
   ```
-- **Colors, radius, spacing**: every semantic token chains to a primitive, so overriding a primitive re-themes everything built on it:
+- **Colours, radius, spacing**: every semantic token chains to a primitive, so overriding a primitive re-themes everything built on it:
   ```css
   :root {
     --primitive-teal-07: #7C3AED;  /* your brand color becomes the action color */
@@ -68,11 +68,11 @@ import { BarChart, LineChart } from '@robr0/design-system/charts';
   }
   ```
 
-Icons use a bundled Material Symbols Rounded variable font (woff2) — no extra setup. Nunito Sans, the system's default typeface, is intentionally *not* bundled: load it yourself (e.g. Google Fonts or `next/font`) or override `--font-family-primary`.
+Icons use a bundled Material Symbols Rounded variable font (woff2), with no extra setup. Nunito Sans, the system's default typeface, is intentionally *not* bundled: load it yourself (e.g. Google Fonts or `next/font`) or override `--font-family-primary`.
 
 ### Token architecture
 
-Tokens flow in one direction — primitives are never referenced directly in components:
+Tokens flow in one direction, and primitives are never referenced directly in components:
 
 ```
 tokens-primitives.css      --primitive-teal-07: #118AB2
@@ -82,40 +82,43 @@ tokens-light/dark.css      --color-action-primary-bg: var(--primitive-teal-07)
 Component CSS              background-color: var(--color-action-primary-bg)
 ```
 
-Dark mode is driven by `data-theme="dark"` on the root element — no `prefers-color-scheme` queries in components.
+Dark mode is driven by `data-theme="dark"` on the root element, with no `prefers-color-scheme` queries in components.
 
 ### Design principles
 
-- **Single typeface**: Nunito Sans (weight 300 for display, 600 for headings, 400/500 for body)
-- **White-floor UI**: depth comes from a container color ramp, not box shadows
-- **Teal is the action color**: primary buttons and focus rings only — never decorative
-- **Five status variants**: info, positive, warning, error, neutral — shared tokens across Badge, Alert, Toast, ProgressBar
-- **Material Symbols Rounded** for all icons
+Stated as token roles on purpose — what each role resolves to is the theme, and yours to override:
 
-Full spec in [`design.md`](design.md).
+- **Style with semantic tokens, never raw values** — that is what makes one primitive override cascade through everything
+- **One typeface**, hierarchy carried by weight contrast
+- **The primary-action token means "click here"**: CTAs and focus only, never decoration
+- **Shape is a per-element-type token**, not a per-instance choice
+- **Five status roles** (info, positive, warning, error, neutral) shared by every status-bearing component
+- **Depth is token-owned**: the container ramp plus the system's elevation tokens — components don't bring their own shadows
+
+The defaults behind each role, and every component spec, live in [`design.md`](design.md).
 
 ---
 
 ## Tech
 
-- **React 19 + TypeScript** — component library
-- **Vite 7** — dev server and library build
-- **Next.js 16** — portfolio site and DS documentation
-- **Storybook 10** — component explorer
-- **Vitest + Playwright** — every Storybook story runs as a render test in headless Chromium
-- **CSS custom properties** — all theming via semantic tokens, no CSS-in-JS
+- **React 19 + TypeScript**: component library
+- **Vite 7**: dev server and library build
+- **Next.js 16**: portfolio site and design system documentation
+- **Storybook 10**: component explorer
+- **Vitest + Playwright**: every Storybook story runs as a render test in headless Chromium
+- **CSS custom properties**: all theming via semantic tokens, no CSS-in-JS
 
 ---
 
 ## Quality & CI
 
-Every push and pull request runs a GitHub Actions pipeline ([`ci.yml`](.github/workflows/ci.yml)) with four jobs: **lint + library build**, **story tests** (every Storybook story rendered in headless Chromium via Vitest), **Storybook build**, and **website lint + build**. The same checklist runs locally with one command:
+Every push and pull request runs a GitHub Actions pipeline ([`ci.yml`](.github/workflows/ci.yml)) with four jobs: lint + library build, story tests (every Storybook story rendered in headless Chromium via Vitest), Storybook build, and website lint + build. The same checklist runs locally with one command:
 
 ```bash
 npm run verify   # lint + library type-check + package build + story tests + Storybook build + website lint + build
 ```
 
-CI also guards against documentation drift: generated surfaces (this README's component count and list, the website's skills pages, the published CLAUDE.md/design.md blueprints) are rebuilt from their source registries on every build, and CI fails if the committed copies are stale. The numbers on the site are never hand-written.
+CI also guards against documentation drift: generated surfaces (this README's component count and list, the website's skills pages, the published CLAUDE.md, design.md, and content-design.md blueprints) are rebuilt from their source registries on every build, and CI fails if the committed copies are stale. The numbers on the site are never hand-written.
 
 ---
 
@@ -125,7 +128,7 @@ CI also guards against documentation drift: generated surfaces (this README's co
 # Storybook (the library's dev sandbox)
 npm run storybook        # http://localhost:6006
 
-# Portfolio + documentation website (npm workspace — install once at the root)
+# Portfolio + documentation website (npm workspace: install once at the root)
 npm install
 npm run dev --workspace website   # http://localhost:3000
 ```

package/components/AgentStatus/AgentStatus.css

@@ -0,0 +1,436 @@
+/* ============================================
+   AGENT STATUS COMPONENT
+   A dot-matrix indicator plus a line of status
+   text, reporting what an agent is doing now.
+
+   The matrix is a 4x3 grid of 12 dots, numbered
+   row-major:
+
+       1  2  3  4
+       5  6  7  8
+       9 10 11 12
+
+   Every pattern is choreography over that same
+   grid: each dot is told which of the cycle's
+   twelve slots it lights in (--ds-agent-step),
+   and dots a pattern never lights opt out of the
+   animation entirely. One grid, one cycle length,
+   fifteen patterns — so changing pattern never
+   changes the indicator's footprint or rhythm.
+   ============================================ */
+
+.ds-agent-status {
+  --ds-agent-color: var(--color-text-secondary);
+  --ds-agent-label-color: var(--color-text-secondary);
+  --ds-agent-dot-dim: 0.2;
+  --ds-agent-dot-rest: 0.82;
+  --ds-agent-cycle: var(--motion-duration-loop-matrix);
+  --ds-agent-slot: calc(var(--ds-agent-cycle) / 12);
+  --ds-agent-matrix-size: var(--icon-size-sm);
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--gap-sm);
+  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);
+}
+
+/* ============================================
+   MATRIX
+   ============================================ */
+
+.ds-agent-status__matrix {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: var(--gap-xxs);
+  flex: none;
+  width: var(--ds-agent-matrix-size);
+}
+
+.ds-agent-status__dot {
+  aspect-ratio: 1;
+  border-radius: var(--radius-full);
+  background-color: var(--ds-agent-color);
+  opacity: var(--ds-agent-dot-dim);
+  transform: scale(var(--ds-agent-dot-rest));
+}
+
+/* ============================================
+   LABEL
+   ============================================ */
+
+.ds-agent-status__label {
+  color: var(--ds-agent-label-color);
+  min-width: 0;
+}
+
+/* A gradient between the secondary text colour the label already sits at and
+   the primary text colour, sweeping left to right: with an oversized
+   background image, background-position 100% shows its right edge, 0% its
+   left, so counting down walks the bright band across the text. */
+.ds-agent-status__label--shimmer {
+  background-image: linear-gradient(
+    100deg,
+    var(--ds-agent-label-color) 35%,
+    var(--color-text-primary) 50%,
+    var(--ds-agent-label-color) 65%
+  );
+  background-size: 250% 100%;
+  background-clip: text;
+  -webkit-background-clip: text;
+  color: transparent;
+  animation: ds-agent-shimmer var(--motion-duration-loop-shimmer)
+    var(--motion-ease-linear) infinite;
+}
+
+/* ============================================
+   STATES
+   The three working states are deliberately
+   monochrome. Colour is reserved for the states
+   where it carries meaning: waiting on a person,
+   finished, failed.
+   ============================================ */
+
+.ds-agent-status--idle {
+  --ds-agent-color: var(--color-text-tertiary);
+  --ds-agent-label-color: var(--color-text-tertiary);
+}
+
+.ds-agent-status--waiting {
+  --ds-agent-color: var(--color-status-warning-text);
+  --ds-agent-label-color: var(--color-status-warning-text);
+}
+
+.ds-agent-status--done {
+  --ds-agent-color: var(--color-status-positive-text);
+  --ds-agent-label-color: var(--color-status-positive-text);
+}
+
+.ds-agent-status--error {
+  --ds-agent-color: var(--color-status-error-text);
+  --ds-agent-label-color: var(--color-status-error-text);
+}
+
+/* Terminal states fill the matrix solid — the shape itself reads as finished */
+.ds-agent-status--done .ds-agent-status__dot,
+.ds-agent-status--error .ds-agent-status__dot {
+  opacity: 1;
+  transform: none;
+}
+
+/* ============================================
+   SIZES
+   ============================================ */
+
+.ds-agent-status--md {
+  --ds-agent-matrix-size: var(--icon-size-md);
+
+  gap: var(--gap-sm-md);
+  font-family: var(--font-paragraph-family);
+  font-size: var(--font-paragraph-size);
+  font-weight: var(--font-paragraph-weight);
+  line-height: var(--font-paragraph-line-height);
+  letter-spacing: var(--font-paragraph-letter-spacing);
+}
+
+/* ============================================
+   VARIANTS
+   ============================================ */
+
+.ds-agent-status--bar {
+  display: flex;
+  width: 100%;
+  padding: var(--padding-xs) var(--padding-sm-md);
+  background-color: var(--color-bg-container-secondary);
+  border: var(--border-xs) solid var(--color-bg-container-border);
+  border-radius: var(--radius-md);
+}
+
+/* ============================================
+   ANIMATION ENGINE
+   Each dot blinks once per cycle, offset by the
+   slot its pattern assigns it.
+   ============================================ */
+
+.ds-agent-status--animated .ds-agent-status__dot {
+  animation: ds-agent-dot var(--ds-agent-cycle) var(--motion-ease-standard) infinite;
+  animation-delay: calc(var(--ds-agent-step, 0) * var(--ds-agent-slot));
+}
+
+/* A dot ramps up over roughly one slot and falls away over three, so the
+   leading edge arrives as smoothly as the trail leaves. Popping straight to
+   full opacity reads as a strobe at this size. */
+@keyframes ds-agent-dot {
+  0% {
+    opacity: var(--ds-agent-dot-dim);
+    transform: scale(var(--ds-agent-dot-rest));
+  }
+
+  10% {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  35%,
+  100% {
+    opacity: var(--ds-agent-dot-dim);
+    transform: scale(var(--ds-agent-dot-rest));
+  }
+}
+
+/* Fill sweep holds each column lit until the band has passed */
+@keyframes ds-agent-dot-fill {
+  0% {
+    opacity: var(--ds-agent-dot-dim);
+    transform: scale(var(--ds-agent-dot-rest));
+  }
+
+  8%,
+  74% {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  86%,
+  100% {
+    opacity: var(--ds-agent-dot-dim);
+    transform: scale(var(--ds-agent-dot-rest));
+  }
+}
+
+/* Breathe swells the whole matrix rather than travelling through it */
+@keyframes ds-agent-dot-breathe {
+  0%,
+  100% {
+    opacity: var(--ds-agent-dot-dim);
+    transform: scale(var(--ds-agent-dot-rest));
+  }
+
+  50% {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+@keyframes ds-agent-shimmer {
+  from {
+    background-position-x: 100%;
+  }
+
+  to {
+    background-position-x: 0%;
+  }
+}
+
+/* ============================================
+   PATTERNS
+   One block per pattern: the slot each dot
+   lights in, and the dots it leaves dark.
+   ============================================ */
+
+/* Braille — a 2x3 cell rotating, the right half dark */
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(1) { --ds-agent-step: 0; }
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(2) { --ds-agent-step: 2; }
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(6) { --ds-agent-step: 4; }
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(10) { --ds-agent-step: 6; }
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 8; }
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(5) { --ds-agent-step: 10; }
+
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(3),
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(4),
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(7),
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(8),
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(11),
+.ds-agent-status--braille .ds-agent-status__dot:nth-child(12) {
+  animation: none;
+}
+
+/* Orbit — clockwise around the perimeter, core dark */
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(1) { --ds-agent-step: 0; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(2) { --ds-agent-step: 1; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(3) { --ds-agent-step: 2; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(4) { --ds-agent-step: 3; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(8) { --ds-agent-step: 4; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 5; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 6; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(10) { --ds-agent-step: 7; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 8; }
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(5) { --ds-agent-step: 9; }
+
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(6),
+.ds-agent-status--orbit .ds-agent-status__dot:nth-child(7) {
+  animation: none;
+}
+
+/* Breathe — every dot together, on its own swell */
+.ds-agent-status--animated.ds-agent-status--breathe .ds-agent-status__dot {
+  animation-name: ds-agent-dot-breathe;
+}
+
+/* Snake — boustrophedon, one dot at a time */
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(1) { --ds-agent-step: 0; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(2) { --ds-agent-step: 1; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(3) { --ds-agent-step: 2; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(4) { --ds-agent-step: 3; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(8) { --ds-agent-step: 4; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(7) { --ds-agent-step: 5; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(6) { --ds-agent-step: 6; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(5) { --ds-agent-step: 7; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 8; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(10) { --ds-agent-step: 9; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 10; }
+.ds-agent-status--snake .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 11; }
+
+/* Fill sweep — columns light and hold, a band wiping left to right */
+.ds-agent-status--animated.ds-agent-status--fill-sweep .ds-agent-status__dot {
+  animation-name: ds-agent-dot-fill;
+}
+
+.ds-agent-status--fill-sweep .ds-agent-status__dot:nth-child(4n + 1) { --ds-agent-step: 0; }
+.ds-agent-status--fill-sweep .ds-agent-status__dot:nth-child(4n + 2) { --ds-agent-step: 3; }
+.ds-agent-status--fill-sweep .ds-agent-status__dot:nth-child(4n + 3) { --ds-agent-step: 6; }
+.ds-agent-status--fill-sweep .ds-agent-status__dot:nth-child(4n) { --ds-agent-step: 9; }
+
+/* Pulse — rings expanding from the core */
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(6),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(7) { --ds-agent-step: 0; }
+
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(2),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(3),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(5),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(8),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(10),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 4; }
+
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(1),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(4),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(9),
+.ds-agent-status--pulse .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 8; }
+
+/* Columns — odd columns, then even */
+.ds-agent-status--columns .ds-agent-status__dot:nth-child(odd) { --ds-agent-step: 0; }
+.ds-agent-status--columns .ds-agent-status__dot:nth-child(even) { --ds-agent-step: 6; }
+
+/* Checkerboard — the two parities alternating */
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(1),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(3),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(6),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(8),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(9),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 0; }
+
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(2),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(4),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(5),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(7),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(10),
+.ds-agent-status--checkerboard .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 6; }
+
+/* Scan — a single column travelling left to right */
+.ds-agent-status--scan .ds-agent-status__dot:nth-child(4n + 1) { --ds-agent-step: 0; }
+.ds-agent-status--scan .ds-agent-status__dot:nth-child(4n + 2) { --ds-agent-step: 3; }
+.ds-agent-status--scan .ds-agent-status__dot:nth-child(4n + 3) { --ds-agent-step: 6; }
+.ds-agent-status--scan .ds-agent-status__dot:nth-child(4n) { --ds-agent-step: 9; }
+
+/* Rain — drops falling down each column, columns out of phase */
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(1) { --ds-agent-step: 0; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(5) { --ds-agent-step: 2; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 4; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(2) { --ds-agent-step: 4; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(6) { --ds-agent-step: 6; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(10) { --ds-agent-step: 8; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(3) { --ds-agent-step: 2; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(7) { --ds-agent-step: 4; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 6; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(4) { --ds-agent-step: 6; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(8) { --ds-agent-step: 8; }
+.ds-agent-status--rain .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 10; }
+
+/* Cascade — column by column, top to bottom */
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(1) { --ds-agent-step: 0; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(5) { --ds-agent-step: 1; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 2; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(2) { --ds-agent-step: 3; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(6) { --ds-agent-step: 4; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(10) { --ds-agent-step: 5; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(3) { --ds-agent-step: 6; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(7) { --ds-agent-step: 7; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 8; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(4) { --ds-agent-step: 9; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(8) { --ds-agent-step: 10; }
+.ds-agent-status--cascade .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 11; }
+
+/* Sparkle — a fixed scatter, so it reads as random without being random */
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(1) { --ds-agent-step: 7; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(2) { --ds-agent-step: 2; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(3) { --ds-agent-step: 10; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(4) { --ds-agent-step: 4; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(5) { --ds-agent-step: 0; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(6) { --ds-agent-step: 9; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(7) { --ds-agent-step: 5; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(8) { --ds-agent-step: 11; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 3; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(10) { --ds-agent-step: 8; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 1; }
+.ds-agent-status--sparkle .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 6; }
+
+/* Wave rows — whole rows breaking top to bottom */
+.ds-agent-status--wave-rows .ds-agent-status__dot:nth-child(-n + 4) { --ds-agent-step: 0; }
+.ds-agent-status--wave-rows .ds-agent-status__dot:nth-child(n + 5):nth-child(-n + 8) { --ds-agent-step: 4; }
+.ds-agent-status--wave-rows .ds-agent-status__dot:nth-child(n + 9) { --ds-agent-step: 8; }
+
+/* Helix — two strands crossing, everything off-strand dark */
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(1),
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 0; }
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(6) { --ds-agent-step: 3; }
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(3),
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 6; }
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(8) { --ds-agent-step: 9; }
+
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(2),
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(4),
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(5),
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(7),
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(10),
+.ds-agent-status--helix .ds-agent-status__dot:nth-child(12) {
+  animation: none;
+}
+
+/* Diagonal swipe — anti-diagonals, top-left to bottom-right */
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(1) { --ds-agent-step: 0; }
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(2),
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(5) { --ds-agent-step: 2; }
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(3),
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(6),
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(9) { --ds-agent-step: 4; }
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(4),
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(7),
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(10) { --ds-agent-step: 6; }
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(8),
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(11) { --ds-agent-step: 8; }
+.ds-agent-status--diagonal-swipe .ds-agent-status__dot:nth-child(12) { --ds-agent-step: 10; }
+
+/* ============================================
+   REDUCED MOTION
+   The global guard collapses every animation to
+   its final frame, which for the matrix is dark.
+   Park it at a legible resting state instead and
+   let the label carry the meaning on its own.
+   ============================================ */
+
+@media (prefers-reduced-motion: reduce) {
+  .ds-agent-status--animated .ds-agent-status__dot {
+    animation: none;
+    opacity: 0.55;
+    transform: none;
+  }
+
+  .ds-agent-status__label--shimmer {
+    background-image: none;
+    color: var(--ds-agent-label-color);
+    animation: none;
+  }
+}

package/components/AgentStatus/AgentStatus.d.ts

@@ -0,0 +1,37 @@
+import { default as React } from 'react';
+import { AgentStatusPattern, AgentStatusState } from './AgentStatusPatterns';
+/** Props owned by AgentStatus itself — everything else falls through to the root element. */
+type AgentStatusOwnProps = {
+    /** What the agent is doing. Drives the colour, the default label, and whether the matrix animates. */
+    state?: AgentStatusState;
+    /** Status text. Falls back to a default for the state. Ignored when `children` are given. */
+    label?: string;
+    /** Which dot-matrix choreography to run. */
+    pattern?: AgentStatusPattern;
+    /**
+     * Sweep a highlight across the label while the agent is active. Defaults to
+     * on for `thinking`, `working` and `waiting`, off for the resting states.
+     */
+    shimmer?: boolean;
+    /** Indicator and text scale. */
+    size?: 'sm' | 'md';
+    /** `inline` sits in a line of content; `bar` is a full-width row for the top of a panel. */
+    variant?: 'inline' | 'bar';
+    /** Additional CSS classes */
+    className?: string;
+    /** Status text, when it needs markup the `label` string cannot express. */
+    children?: React.ReactNode;
+};
+export interface AgentStatusProps extends AgentStatusOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof AgentStatusOwnProps> {
+}
+/**
+ * AgentStatus reports what an agent is doing right now: a dot-matrix indicator
+ * beside a line of status text.
+ *
+ * Colour carries meaning rather than decoration — the three working states are
+ * monochrome, and only `waiting`, `done` and `error` take a status colour.
+ * The whole thing is one polite live region, so a screen reader hears the state
+ * change without the caller wiring anything up.
+ */
+export declare const AgentStatus: React.ForwardRefExoticComponent<AgentStatusProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/AgentStatus/AgentStatus.js

@@ -0,0 +1,53 @@
+import { jsxs, jsx } from "react/jsx-runtime";
+import React from "react";
+import "./AgentStatus.css";
+const DOT_COUNT = 12;
+const DEFAULT_LABELS = {
+  idle: "Idle",
+  thinking: "Thinking",
+  working: "Working",
+  waiting: "Waiting for you",
+  done: "Done",
+  error: "Failed"
+};
+const ACTIVE_STATES = ["thinking", "working", "waiting"];
+const AgentStatus = React.forwardRef(
+  ({
+    state = "thinking",
+    label,
+    pattern = "orbit",
+    shimmer,
+    size = "sm",
+    variant = "inline",
+    className = "",
+    children,
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-agent-status";
+    const isActive = ACTIVE_STATES.includes(state);
+    const isShimmering = shimmer ?? isActive;
+    const classes = [
+      baseClass,
+      `${baseClass}--${state}`,
+      `${baseClass}--${pattern}`,
+      `${baseClass}--${size}`,
+      `${baseClass}--${variant}`,
+      isActive ? `${baseClass}--animated` : "",
+      className
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxs("div", { ...rest, ref, className: classes, role: "status", children: [
+      /* @__PURE__ */ jsx("span", { className: `${baseClass}__matrix`, "aria-hidden": "true", children: Array.from({ length: DOT_COUNT }, (_, i) => /* @__PURE__ */ jsx("span", { className: `${baseClass}__dot` }, i)) }),
+      /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: `${baseClass}__label${isShimmering ? ` ${baseClass}__label--shimmer` : ""}`,
+          children: children ?? label ?? DEFAULT_LABELS[state]
+        }
+      )
+    ] });
+  }
+);
+AgentStatus.displayName = "AgentStatus";
+export {
+  AgentStatus
+};