@robr0/design-system 0.6.0 → 0.7.0

package/LICENSE

@@ -1,6 +1,21 @@
-MIT License
+Copyright (c) 2026 Rob Ritacca. All rights reserved, except as granted below.
 
-Copyright (c) 2026 Rob Ritacca
+This repository holds two kinds of material under two different licenses.
+The SOFTWARE is free to use under the MIT License. The CONTENT is not
+licensed for reuse.
+
+If you installed this as an npm package, you received the Software only.
+The MIT License below is the license for everything in that package.
+
+
+================================================================================
+SOFTWARE — MIT License
+================================================================================
+
+Applies to the design system and the code that builds and documents it:
+component source and CSS, the design tokens, Storybook stories, the build,
+generator and validator scripts, configuration, and the website's application
+code (layouts, routing, hooks, and UI components).
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +34,39 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+
+================================================================================
+CONTENT — All rights reserved
+================================================================================
+
+Applies to the authored material published on robertritacca.com and stored in
+this repository, including:
+
+  - Written prose on any page: body copy, headings, descriptions, and
+    microcopy across the website and the root specification documents.
+  - Case studies and the client work they describe
+    (website/src/app/work/, website/src/data/case-studies.json).
+  - Essays and long-form writing
+    (website/src/app/writing/, website/src/data/essays.json).
+  - The project journal entries (website/src/data/site-updates.json).
+  - Photographs, illustrations, client logos, cover images, and other media.
+  - The name "Rob Ritacca", the RR logo and wordmark, and any likeness,
+    photograph, biography, or professional history of Rob Ritacca.
+
+No license is granted to this material. Without prior written permission you
+may not copy, reproduce, republish, mirror, redistribute, sell, or create
+derivative works from it, and you may not use it to train, fine-tune, or
+otherwise build a machine learning model. You may not present it as your own
+work, and you may not use the name, logo, likeness, or professional history of
+Rob Ritacca to imply authorship, endorsement, or affiliation.
+
+You are welcome to read the site, quote short passages with attribution and a
+link to the source, link to any page, and use automated tools to read and cite
+pages as a human reader would. Nothing here restricts rights you already have
+under applicable copyright law.
+
+Client logos and trademarks shown in case studies belong to their respective
+owners and appear as references to real work, not as a grant of any rights.
+
+Permission requests: rob.ritacca@gmail.com

package/README.md

@@ -5,7 +5,7 @@
 [![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, the AI-ready React design system behind it, and the AI layer that lets the site answer questions about itself. Claude Code builds all of it 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 `porting-guide.md` for rebuilding the site chat inside another design system), 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.
+A personal portfolio site, the AI-ready React design system behind it, and the AI layer that lets the site answer questions about itself. Claude Code builds all of it 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)**
 
@@ -18,7 +18,7 @@ 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 -->78<!-- /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)** |
+| **Design system** (`/src`) | <!-- component-count -->79<!-- /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. |
 
 ---
@@ -28,9 +28,32 @@ The **live site** is the portfolio built on the design system. **Storybook** is
 ### Components
 
 <!-- component-list:start -->
-Accordion · Agent status · AI button · Alert · Alert dialog · App layout · App sidebar · Avatar · Badge · Breadcrumb · Button · Button group · Card · Carousel · Chart · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Colour picker · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Field · Figure · File input · Input · Instructions · Interrupt card · Kbd · Link list · Message actions · Message card · Navigation · Nav list · Pagination · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radio button · Reasoning · Section title · Segmented control · Selection card · Skeleton · Slider · Source chip · Spinner · Stat · Swatch · Table · Tabs · Textarea · Timeline · Toast · Toggle group · Toggle switch · Tool call · Tooltip
+Accordion · Agent status · AI button · Alert · Alert dialog · App layout · App sidebar · Avatar · Badge · Breadcrumb · Button · Button group · Card · Carousel · Chart · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Colour picker · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Field · Figure · File input · Input · Instructions · Interrupt card · Kbd · Link list · Message actions · Message card · Navigation · Nav list · Pagination · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radio button · Reasoning · Section title · Segmented control · Selection card · Shader field · Skeleton · Slider · Source chip · Spinner · Stat · Swatch · Table · Tabs · Textarea · Timeline · Toast · Toggle group · Toggle switch · Tool call · Tooltip
 <!-- component-list:end -->
 
+### Ambient background
+
+The package ships more than components. **Shader field** is a WebGL2 canvas that sums soft Gaussian light sources into an ambient field of colour, and every source reads a semantic colour token at runtime. Override a primitive and the background re-themes with the rest of the system, in both themes, with nothing wired up:
+
+```tsx
+import { ShaderField, type ShaderFieldStatus } from '@robr0/design-system';
+
+const [status, setStatus] = useState<ShaderFieldStatus>('pending');
+
+<div style={{ position: 'fixed', inset: 0, zIndex: -1 }}>
+  {status === 'unavailable' && <YourCssFallback />}
+  <ShaderField params={{ streak: 0.4 }} onStatusChange={setStatus} />
+</div>
+```
+
+Seven parameters describe the look, and a composition is a table of token names with positions and drift periods, so a negative weight cuts a shadow through the field instead of adding light to it.
+
+It asks two things of you, both deliberate. It fills a positioned ancestor you provide, because where a background sits is a layout decision rather than a rendering one. And it never decides what to paint instead of itself: it reports `pending`, `active` or `unavailable`, and one fallback covers every way it can fail (no WebGL2, a blocked or lost GPU context, a renderer that stalls before its first frame, or `enabled={false}` as a kill switch). `pending` is the state worth handling. Paint neither layer while the context comes up, or the swap a frame later reads as two backgrounds loading in sequence.
+
+It is also the one place a `prefers-reduced-motion` check lives in JavaScript rather than in the motion tokens, because the CSS guard cannot see a `requestAnimationFrame` loop. Set the preference and it draws a single static frame.
+
+The background behind this site is that component, with eight blurred CSS discs kept painted underneath as its fallback. The **[component page](https://robertritacca.com/components/shader-field)** is a live demo, and the **[setup guide](https://robertritacca.com/docs/get-started)** has the wiring.
+
 ### 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://robertritacca.com/docs/get-started)** expands on everything in this section:
@@ -116,14 +139,14 @@ Answers are measured, not assumed. `evals/chat` holds a golden set that runs thr
 - **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
+- **Vitest + Playwright + axe**: every Storybook story runs as a render test in headless Chromium, with an accessibility audit on each
 - **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, Storybook build, and website lint + build. The story tests render every Storybook story in headless Chromium via Vitest and run an axe accessibility audit on each, so a violation fails the build exactly like a render error. 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
@@ -143,3 +166,11 @@ npm run storybook        # http://localhost:6006
 npm install
 npm run dev --workspace website   # http://localhost:3000
 ```
+
+---
+
+## License
+
+Two licenses, one repository. The **software** (components, tokens, scripts, and the website's application code) is MIT, so use it in anything. The **content** (page prose, case studies, essays, images, and the name and likeness of Rob Ritacca) is all rights reserved and not licensed for reuse. See [`LICENSE`](LICENSE) for the full terms.
+
+The npm package contains the software only.

package/components/AgentStatus/AgentStatus.css

@@ -22,8 +22,8 @@
 .ds-agent-status {
   --ds-agent-color: var(--color-text-secondary);
   --ds-agent-label-color: var(--color-text-secondary);
-  --ds-agent-shimmer-base: var(--color-text-primary);
-  --ds-agent-shimmer-sweep: var(--color-text-tertiary);
+  --ds-agent-shimmer-base: var(--color-text-tertiary);
+  --ds-agent-shimmer-sweep: var(--color-text-primary);
   --ds-agent-dot-dim: 0.2;
   --ds-agent-dot-rest: 0.82;
   --ds-agent-cycle: var(--motion-duration-loop-matrix);
@@ -33,11 +33,16 @@
   display: inline-flex;
   align-items: center;
   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);
+
+  /* The label is set in the title-body face, not the paragraph one: a status
+     is a heading for the work underneath it, not prose. The two sets share
+     16px/24px metrics, so the row's geometry is identical either way — only
+     the weight and tracking change. */
+  font-family: var(--font-title-body-family);
+  font-size: var(--font-title-body-size);
+  font-weight: var(--font-title-body-weight);
+  line-height: var(--font-title-body-line-height);
+  letter-spacing: var(--font-title-body-letter-spacing);
 }
 
 /* ============================================
@@ -112,13 +117,19 @@
 /* A gradient between the shimmer base and sweep colours, moving left to
    right: with an oversized background image, background-position 100% shows
    its right edge, 0% its left, so counting down walks the sweep band across
-   the text. */
+   the text.
+
+   The base is the dimmer colour and the sweep the brighter one, so what
+   travels is a highlight rather than a shadow — the same "the sweep only
+   brightens it" reading `waiting` has always had. The band is narrow
+   (12% of a 250% image, so under a third of the text at a time): spread
+   wide it washes the whole label at once and stops reading as movement. */
 .ds-agent-status__label--shimmer {
   background-image: linear-gradient(
     100deg,
-    var(--ds-agent-shimmer-base) 35%,
+    var(--ds-agent-shimmer-base) 44%,
     var(--ds-agent-shimmer-sweep) 50%,
-    var(--ds-agent-shimmer-base) 65%
+    var(--ds-agent-shimmer-base) 56%
   );
   background-size: 250% 100%;
   background-clip: text;
@@ -189,9 +200,13 @@
   --ds-agent-matrix-size: var(--icon-size-sm);
 
   gap: var(--gap-sm);
+
+  /* The small metrics, carrying the same title weight down a size: the scale
+     has no 14px title face, and dropping to the paragraph weight here would
+     make one size of the component read as a heading and the other as prose. */
   font-family: var(--font-paragraph-sm-family);
   font-size: var(--font-paragraph-sm-size);
-  font-weight: var(--font-paragraph-sm-weight);
+  font-weight: var(--font-title-body-weight);
   line-height: var(--font-paragraph-sm-line-height);
   letter-spacing: var(--font-paragraph-sm-letter-spacing);
 }

package/components/Card/Card.css

@@ -106,6 +106,15 @@
   background: var(--color-bg-container-secondary);
 }
 
+/* A drawn cover (the `cover` prop) fills the same slot the image would, so a
+   grid of cards keeps one cover shape whichever kind it was given. */
+.ds-card--case-study__cover-slot,
+.ds-card--case-study__cover-slot > * {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
 .ds-card--case-study__cover-image {
   width: 100%;
   height: 100%;

package/components/Card/Card.d.ts

@@ -18,6 +18,12 @@ type CardOwnProps = {
     href?: string;
     /** Cover image src */
     coverSrc?: string;
+    /**
+     * Cover content rendered in place of the image — for a cover that is drawn
+     * rather than photographed (an SVG, a chart, a live preview). Takes
+     * precedence over `coverSrc`, and fills the same fixed-ratio slot.
+     */
+    cover?: React.ReactNode;
     /** Cover image alt text */
     coverAlt?: string;
     /** Path to the company logo shown in the eyebrow */

package/components/Card/Card.js

@@ -13,6 +13,7 @@ const Card = React.forwardRef(
     className = "",
     href,
     coverSrc,
+    cover,
     coverAlt,
     companyLogo,
     companyName,
@@ -22,7 +23,7 @@ const Card = React.forwardRef(
   }, ref) => {
     if (variant === "case-study") {
       const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-wrap", children: coverSrc ? /* @__PURE__ */ jsx(
+        /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-wrap", children: cover ? /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-slot", children: cover }) : coverSrc ? /* @__PURE__ */ jsx(
           "img",
           {
             src: coverSrc,

package/components/Composer/Composer.css

@@ -58,8 +58,26 @@
 
 .ds-composer__content {
   display: flex;
+  /* The textarea keeps its own natural height rather than stretching to the
+     zone's — the measurement below reads it, so a stretched textarea would
+     feed its own height back in and the zone could never shrink. */
+  align-items: flex-start;
+  box-sizing: border-box;
   width: 100%;
   padding: var(--padding-md) var(--padding-lg) var(--padding-sm);
+  /* Growing and shrinking is animated, which needs two pixel heights to run
+     between — `auto` has nothing to interpolate. So the zone states its own
+     height: the measured textarea (published as --ds-composer-text-height on
+     every resize) plus the block padding it owns. The fallback is a single
+     row, which is what the shell renders before the first measurement. */
+  height: calc(
+    var(--ds-composer-text-height, var(--font-paragraph-line-height)) + var(--padding-md) +
+      var(--padding-sm)
+  );
+  /* Mid-transition the textarea is already at its new height, so the extra
+     line is clipped on the way in and released on the way out. */
+  overflow: hidden;
+  transition: height var(--motion-duration-instant) var(--motion-ease-emphasized);
 }
 
 .ds-composer__textarea {

package/components/Composer/Composer.d.ts

@@ -59,6 +59,9 @@ export interface ComposerProps extends ComposerOwnProps, Omit<React.ComponentPro
  * The textarea grows with its content up to `maxRows`, then scrolls
  * internally. Where the browser supports `field-sizing: content` the sizing
  * is fully native; elsewhere a measurement effect keeps the height in step.
+ * Either way the text zone glides between the two heights rather than
+ * snapping — 75ms, short enough to soften the step without reading as an
+ * animation. The action bar's buttons never move relative to the bar.
  *
  * Forwards a ref to the underlying `<textarea>` and spreads unrecognised
  * props onto it; `className` lands on the shell.

package/components/Composer/Composer.js

@@ -23,6 +23,7 @@ const Composer = React.forwardRef(
   }, ref) => {
     const baseClass = "ds-composer";
     const textareaRef = useRef(null);
+    const contentRef = useRef(null);
     const isControlled = value !== void 0;
     const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? "");
     const currentValue = isControlled ? value : uncontrolledValue;
@@ -40,6 +41,16 @@ const Composer = React.forwardRef(
       node.style.height = "auto";
       node.style.height = `${node.scrollHeight}px`;
     }, [currentValue]);
+    useLayoutEffect(() => {
+      const node = textareaRef.current;
+      const content = contentRef.current;
+      if (!node || !content) return;
+      const observer = new ResizeObserver(() => {
+        content.style.setProperty("--ds-composer-text-height", `${node.offsetHeight}px`);
+      });
+      observer.observe(node);
+      return () => observer.disconnect();
+    }, []);
     const submit = () => {
       if (streaming || !canSend) return;
       onSubmit?.(currentValue);
@@ -71,7 +82,7 @@ const Composer = React.forwardRef(
         onClick: handleShellClick,
         children: [
           attachments && /* @__PURE__ */ jsx("div", { className: `${baseClass}__attachments`, children: attachments }),
-          /* @__PURE__ */ jsx("div", { className: `${baseClass}__content`, children: /* @__PURE__ */ jsx(
+          /* @__PURE__ */ jsx("div", { className: `${baseClass}__content`, ref: contentRef, children: /* @__PURE__ */ jsx(
             "textarea",
             {
               ...rest,

package/components/Prose/Prose.css

@@ -192,8 +192,17 @@
    TABLES
    ============================================ */
 
+/* The table is its own scroll container. Prose styles markup it does not
+   render, so it cannot wrap the table in a scrolling div — `display: block`
+   makes the table element itself the scroller. The cost is deliberate: the
+   table sizes to its content instead of filling the container, because the
+   inner anonymous table box a block table generates cannot be stretched.
+   A clipped or shattered table is the worse failure. */
 .ds-prose table {
-  width: 100%;
+  display: block;
+  width: max-content;
+  max-width: 100%;
+  overflow-x: auto;
   border-collapse: collapse;
 }
 
@@ -207,10 +216,18 @@
   text-align: start;
 }
 
+/* Cells never break words, whatever the surrounding context does. An
+   ancestor that sets `overflow-wrap: anywhere` (ChatMessage does, so a long
+   URL cannot widen a bubble) otherwise inherits in and collapses every
+   column's minimum width to one character, which lets auto table layout
+   squeeze a heading into "Co / m / pa / ny" rather than let the table reach
+   its natural width. Holding the floor is what gives the scroll above
+   something to scroll. */
 .ds-prose th,
 .ds-prose td {
   padding: var(--padding-xs) var(--padding-sm-md);
   border-block-end: var(--border-xs) solid var(--color-divider);
+  overflow-wrap: normal;
 }
 
 /* ============================================

package/components/Reasoning/Reasoning.css

@@ -128,12 +128,16 @@
   align-items: center;
 }
 
+/* The band travels dim → bright → dim, and stays narrow, matching
+   AgentStatus's sweep stop for stop: the two sit in the same conversation,
+   so a shimmer that read differently here would look like a second effect
+   rather than the same one. */
 .ds-reasoning--streaming .ds-reasoning__summary:not(.ds-reasoning__summary--node) {
   background-image: linear-gradient(
     100deg,
-    var(--color-text-primary) 35%,
-    var(--color-text-tertiary) 50%,
-    var(--color-text-primary) 65%
+    var(--color-text-tertiary) 44%,
+    var(--color-text-primary) 50%,
+    var(--color-text-tertiary) 56%
   );
   background-size: 250% 100%;
   background-clip: text;
@@ -183,7 +187,18 @@
      the thought-for line never shifts the trace. */
   margin-left: calc(var(--icon-size-md) / 2 - var(--border-md) / 2);
   padding-left: calc(var(--icon-size-md) / 2 + var(--gap-sm-md) - var(--border-md) / 2);
-  border-left: var(--border-md) solid var(--color-divider);
+  /* The rail dissolves at its foot — the Timeline's end-of-line treatment.
+     A border can't carry a gradient, so the border only reserves the
+     geometry (transparent, same width) and the stripe is painted under it:
+     a border-box background sized to the border's own column. */
+  border-left: var(--border-md) solid transparent;
+  background:
+    linear-gradient(
+        to bottom,
+        var(--color-divider) calc(100% - var(--gap-lg) * 2),
+        var(--color-bg-container-primary-transparent)
+      )
+      left top / var(--border-md) 100% no-repeat border-box;
   color: var(--color-text-secondary);
   font-family: var(--font-paragraph-family);
   font-size: var(--font-paragraph-size);

package/components/ShaderField/ShaderField.css

@@ -0,0 +1,24 @@
+/* ShaderField — the canvas only.
+   Placement, clipping and any fade-to-page mask belong to the positioned
+   ancestor the caller provides: where the field sits is a layout decision,
+   and baking one in would make the component unusable anywhere else. */
+
+.ds-shader-field {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  display: block;
+  /* Scenery, never a target — a full-bleed canvas that swallowed clicks would
+     make whatever it covers unreachable. */
+  pointer-events: none;
+  /* Reveals only once a context is live and the first frame is drawn, so a
+     machine that cannot run the shader never shows an empty canvas — it stays
+     on the caller's fallback instead. */
+  opacity: 0;
+  transition: opacity var(--motion-duration-slower) var(--motion-ease-entrance);
+}
+
+.ds-shader-field[data-status='active'] {
+  opacity: 1;
+}

package/components/ShaderField/ShaderField.d.ts

@@ -0,0 +1,68 @@
+import { default as React } from 'react';
+import { ShaderBlob, ShaderParams } from './useShaderField';
+export type { ShaderBlob, ShaderParams, ShaderFieldParams, ShaderFieldState, } from './useShaderField';
+export { useShaderField, DEFAULT_SHADER_BLOBS, DEFAULT_SHADER_PARAMS } from './useShaderField';
+export { BLOB_COUNT } from './field.glsl';
+/**
+ * How the renderer has resolved.
+ *
+ * `pending` is the one that matters to a caller: the context is still coming
+ * up, so neither the field nor a fallback should be painted yet — showing a
+ * fallback here and swapping it a frame later reads as two backgrounds loading
+ * in sequence.
+ */
+export type ShaderFieldStatus = 'pending' | 'active' | 'unavailable';
+/** Props owned by ShaderField itself — everything else falls through to the canvas. */
+type ShaderFieldOwnProps = {
+    /**
+     * Field parameters, merged over the shipped defaults, so passing one
+     * property changes one thing. Changing them never rebuilds the GL state.
+     */
+    params?: Partial<ShaderParams>;
+    /**
+     * The light sources. Defaults to an eight-source composition on the core
+     * accent tokens. Fewer than `BLOB_COUNT` entries is fine — unused slots park
+     * off-field; more are ignored, because the shader's uniform arrays are
+     * fixed-size.
+     */
+    blobs?: readonly ShaderBlob[];
+    /**
+     * False keeps WebGL entirely unmounted and reports `unavailable`, so the
+     * caller's fallback is the whole background. This is the kill switch: a
+     * config lever, or an A/B against the fallback.
+     */
+    enabled?: boolean;
+    /**
+     * Called whenever the renderer's status changes. Drive the fallback layer's
+     * visibility from this — the component deliberately does not own one, since
+     * what to paint instead is a design decision, not a rendering one.
+     */
+    onStatusChange?: (status: ShaderFieldStatus) => void;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface ShaderFieldProps extends ShaderFieldOwnProps, Omit<React.ComponentPropsWithoutRef<'canvas'>, keyof ShaderFieldOwnProps> {
+}
+/**
+ * ShaderField paints an ambient WebGL2 field of soft Gaussian light sources,
+ * each sampling a semantic colour token at runtime — so the whole thing
+ * re-themes with `data-theme`, and with any scoped custom-property override,
+ * without the caller wiring anything up.
+ *
+ * It is scenery, not interface: nothing about it is a signal, so its motion
+ * cannot be mistaken for feedback. Two consequences follow, and both are
+ * handled here rather than left to the caller.
+ *
+ * It honours reduced motion in JavaScript. The system's motion tokens collapse
+ * under `prefers-reduced-motion`, but that guard is CSS-only and cannot see a
+ * `requestAnimationFrame` loop; a GPU-driven surface has to check the query
+ * itself. This one renders a single static frame and never starts its loop.
+ *
+ * And it always reports how it resolved. No WebGL2, a blocked or lost GPU
+ * context, a renderer that stalls before its first frame, or `enabled={false}`
+ * all arrive at `unavailable` through `onStatusChange`, so the caller can keep
+ * a plain CSS fallback painted underneath. The canvas fills its positioned
+ * ancestor and is inert to pointer events; give that ancestor the placement,
+ * the clipping and any mask.
+ */
+export declare const ShaderField: React.ForwardRefExoticComponent<ShaderFieldProps & React.RefAttributes<HTMLCanvasElement>>;

package/components/ShaderField/ShaderField.js

@@ -0,0 +1,54 @@
+import { jsx } from "react/jsx-runtime";
+import React, { useRef, useMemo, useState, useEffect } from "react";
+import { DEFAULT_SHADER_BLOBS, DEFAULT_SHADER_PARAMS, useShaderField } from "./useShaderField.js";
+import "./ShaderField.css";
+const WATCHDOG_MS = 1500;
+const ShaderField = React.forwardRef(
+  ({
+    params,
+    blobs = DEFAULT_SHADER_BLOBS,
+    enabled = true,
+    onStatusChange,
+    className = "",
+    ...rest
+  }, ref) => {
+    const canvasRef = useRef(null);
+    React.useImperativeHandle(ref, () => canvasRef.current);
+    const fieldParams = useMemo(
+      () => ({ ...DEFAULT_SHADER_PARAMS, ...params, blobs }),
+      [params, blobs]
+    );
+    const { supported, active } = useShaderField(canvasRef, fieldParams, enabled);
+    const [gaveUp, setGaveUp] = useState(false);
+    useEffect(() => {
+      if (!enabled || active || !supported) return;
+      const timer = window.setTimeout(() => setGaveUp(true), WATCHDOG_MS);
+      return () => window.clearTimeout(timer);
+    }, [enabled, active, supported]);
+    const status = !enabled || !supported ? "unavailable" : active ? "active" : gaveUp ? "unavailable" : "pending";
+    const notify = useRef(onStatusChange);
+    notify.current = onStatusChange;
+    useEffect(() => {
+      notify.current?.(status);
+    }, [status]);
+    if (!enabled) return null;
+    const classes = ["ds-shader-field", className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx(
+      "canvas",
+      {
+        ...rest,
+        ref: canvasRef,
+        className: classes,
+        "data-status": status,
+        "aria-hidden": "true"
+      }
+    );
+  }
+);
+ShaderField.displayName = "ShaderField";
+export {
+  DEFAULT_SHADER_BLOBS,
+  DEFAULT_SHADER_PARAMS,
+  ShaderField,
+  useShaderField
+};

package/components/ShaderField/field.glsl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GLSL sources for ShaderField, the system's ambient background field.
+ *
+ * This file owns the shader and BLOB_COUNT only. The blob table and every
+ * tuneable parameter are data, passed in by the caller, so a look can be
+ * retuned without touching GLSL.
+ *
+ * The field is a sum of soft Gaussian sources. It computes the true Gaussian
+ * falloff a stack of blurred CSS discs only approximates, blends in linear
+ * space so midpoints keep their saturation, warps the field with fbm noise so
+ * it flows instead of translating rigidly, and dithers away the 8-bit banding
+ * these wide, soft ramps otherwise produce.
+ *
+ * Coordinate space is chosen to match a CSS blob layer exactly, so a fallback
+ * built from absolutely-positioned discs lines up with it: origin at the
+ * container centre (`left`/`top: 50%`), one unit = container width (discs are
+ * vw-sized, and CSS percentage margins — top included — resolve against the
+ * containing block's width). Centres are therefore constants that never need
+ * re-uploading on resize.
+ *
+ * Colours arrive already converted to linear RGB (the hook does the sRGB
+ * decode once per theme change); the shader only encodes back at the end.
+ */
+/**
+ * Sizes the shader's uniform arrays, so it is a compile-time constant here
+ * rather than a length read from data. A caller may pass fewer blobs — unused
+ * slots are parked off-field — but never more; ShaderField's own default table
+ * fills it exactly, and scripts/validate-shader-background.mjs reads this
+ * number out of this file to hold the website's config to it.
+ */
+export declare const BLOB_COUNT = 8;
+export declare const vertexSource = "#version 300 es\n// Fullscreen triangle \u2014 no buffers, three vertices from gl_VertexID.\nvoid main() {\n  vec2 p = vec2((gl_VertexID << 1) & 2, gl_VertexID & 2);\n  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}\n";
+export declare const fragmentSource = "#version 300 es\nprecision highp float;\n\nuniform vec2  u_resolution;  // drawing-buffer size in pixels\nuniform float u_time;        // field time, seconds (speed applied JS-side)\nuniform vec3  u_color[8];  // linear RGB per blob\nuniform vec4  u_blob[8];   // xy = centre, z = sigma, w = emission weight\nuniform vec4  u_motion[8]; // xy = angular speeds, zw = phases\nuniform float u_intensity;   // peak-alpha ceiling\nuniform float u_warp;        // domain-warp strength\nuniform float u_scale;       // noise frequency\nuniform float u_grain;       // film-grain strength\nuniform float u_streak;      // anisotropic stretch: 0 = blobs, 1 = light streams\nuniform vec2  u_mouse;       // pointer in field coordinates (smoothed JS-side)\nuniform float u_mvel;        // smoothed pointer speed, width units/s\nuniform float u_react;       // cursor-reactivity strength\n\nout vec4 outColor;\n\n// Integer hash \u2014 WebGL2 has real uint ops, so no fract(sin()) precision\n// lottery on mobile GPUs.\nuint ihash(uvec2 p) {\n  p = p * uvec2(73333u, 7777u) ^ (p.yx >> 3u);\n  uint h = p.x ^ (p.y * 2654435761u);\n  h ^= h >> 15u;\n  h *= 2246822519u;\n  h ^= h >> 13u;\n  return h;\n}\n\nfloat rnd(ivec2 p) {\n  return float(ihash(uvec2(p)) >> 8) * (1.0 / 16777216.0);\n}\n\nfloat vnoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);\n  ivec2 c = ivec2(i);\n  return mix(\n    mix(rnd(c), rnd(c + ivec2(1, 0)), u.x),\n    mix(rnd(c + ivec2(0, 1)), rnd(c + ivec2(1, 1)), u.x),\n    u.y\n  );\n}\n\n// 3 octaves; a 4th is invisible at this softness.\nfloat fbm(vec2 p) {\n  float s = 0.0;\n  float a = 0.5;\n  for (int i = 0; i < 3; i++) {\n    s += a * vnoise(p);\n    p = p * 2.02 + vec2(17.0, 9.0);\n    a *= 0.5;\n  }\n  return s;\n}\n\nvoid main() {\n  // CSS coordinate space: origin at container centre, one unit = width,\n  // y running downward.\n  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution) / u_resolution.x;\n  p.y = -p.y;\n\n  // Light-stream axis: a fixed diagonal. Distances across the axis are\n  // magnified before the Gaussian, so every source stretches along it and\n  // the field reads as rays instead of discs.\n  float ca = cos(0.5);\n  float sa = sin(0.5);\n  mat2 toStreak = mat2(ca, -sa, sa, ca);\n  float squeeze = 1.0 + u_streak * 4.0;\n\n  // Domain warp: the field flows rather than drifts. The noise is sampled\n  // in the same anisotropic space, so the flow lines follow the streams.\n  float t = u_time;\n  vec2 ps = toStreak * p;\n  ps.y *= squeeze;\n  vec2 q = vec2(\n    fbm(ps * u_scale + vec2(0.0, t * 0.030)),\n    fbm(ps * u_scale + vec2(5.2, 1.3) - t * 0.024)\n  );\n  vec2 w = p + u_warp * (q - 0.5);\n\n  // Cursor wake: a smooth vortex around the pointer, amplified by speed.\n  // The displacement is built from the *unnormalised* offset so it falls to\n  // zero at the cursor itself. Normalising here (md/mr) made the direction\n  // spin through 360 degrees at full strength across the centre pixel, which\n  // rendered as a pinch \u2014 a cone converging to a point.\n  vec2 md = p - u_mouse;\n  float mr2 = dot(md, md);\n  float minf = exp(-mr2 / (2.0 * 0.22 * 0.22));\n  vec2 swirl = vec2(-md.y, md.x);\n  // smoothstep, not min(): a hard clamp stepped visibly as speed crossed it.\n  float stir = 0.25 + 1.3 * smoothstep(0.0, 0.8, u_mvel);\n  w += u_react * minf * stir * (swirl * 0.9 + md * 0.35);\n\n  // Accumulate true Gaussians in linear space. Positive weights emit;\n  // negative weights absorb (shadows \u2014 the eclipse disc).\n  vec3 acc = vec3(0.0);\n  float cov = 0.0;\n  float shade = 0.0;\n  for (int i = 0; i < 8; i++) {\n    vec2 c = u_blob[i].xy + 0.045 * vec2(\n      cos(u_motion[i].x * t + u_motion[i].z),\n      sin(u_motion[i].y * t + u_motion[i].w)\n    );\n    vec2 d = toStreak * (w - c);\n    d.y *= squeeze;\n    float s = u_blob[i].z;\n    float g = exp(-dot(d, d) / (2.0 * s * s));\n    float wgt = u_blob[i].w;\n    if (wgt >= 0.0) {\n      acc += u_color[i] * (g * wgt);\n      cov += g * wgt;\n    } else {\n      shade += g * -wgt;\n    }\n  }\n\n  // Glow trail: wider and softer than the swirl, and mostly velocity-driven,\n  // so a resting cursor does not park a bright dot on the field.\n  //\n  // The wake brightens whatever colour it is passing over rather than adding\n  // one of its own. Injecting u_color[0] meant the trail always wore the\n  // first blob's token \u2014 gold in the site palette, violet in beam \u2014 which\n  // read as a stray colour with no relationship to the field beneath it.\n  // Weighting by the local hue keeps the wake colour-neutral: it reads as\n  // light falling on the field, and it stays correct for any palette.\n  vec3 local = acc / max(cov, 1e-4);\n  float gfall = exp(-mr2 / (2.0 * 0.3 * 0.3));\n  float glow = u_react * gfall * (0.12 + 0.5 * smoothstep(0.0, 0.8, u_mvel));\n  acc += local * glow;\n  cov += glow;\n\n  vec3 lin = acc / max(cov, 1e-4);\n  float lit = max(cov - shade, 0.0);\n  float alpha = u_intensity * (1.0 - exp(-lit * 0.9));\n\n  vec3 srgb = pow(max(lin, vec3(0.0)), vec3(1.0 / 2.2));\n\n  // Film grain: animated hash noise. At u_grain 0 this degenerates to the\n  // \u00B11/255 dither that kills banding, so the two share one lookup.\n  uvec2 gp = uvec2(gl_FragCoord.xy) + uvec2(\n    uint(fract(t * 7.31) * 1024.0) * 7919u,\n    uint(fract(t * 3.17) * 1024.0) * 104729u\n  );\n  float gr = float(ihash(gp) & 255u) / 255.0 - 0.5;\n  srgb += gr * (1.0 / 255.0 + u_grain * 0.35);\n  // A small grain-driven alpha floor lets the sparkle read even where the\n  // field itself is empty (the reference's grainy dark scene).\n  float grainFloor = u_grain * 0.1 * (gr + 0.5);\n  alpha = clamp(alpha * (1.0 + gr * u_grain * 0.5) + grainFloor, 0.0, 1.0);\n  srgb = clamp(srgb, 0.0, 1.0);\n\n  // Premultiplied output (context is created with premultipliedAlpha: true).\n  outColor = vec4(srgb * alpha, alpha);\n}\n";