@robr0/design-system 0.9.0 → 0.11.0

package/README.md

@@ -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 -->101<!-- /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)** |
+| **Design system** (`/src`) | <!-- component-count -->105<!-- /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,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 · Badge · Bar chart · Breadcrumb · Button · Button group · Card · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · 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 · Input · Instructions · Interrupt card · Kbd · Line chart · Link list · Message actions · Message card · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · 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 · Stacked bar chart · Stat · Stepper · 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 · 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 · 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 · Globe · Input · Instructions · Interrupt card · Kbd · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · 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 · Stacked bar chart · Stat · Stepper · 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
@@ -50,7 +50,7 @@ Eight parameters describe the look, and a composition is a table of token names
 
 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.
+It checks `prefers-reduced-motion` in JavaScript rather than through the motion tokens, because the CSS guard cannot see a JS-driven 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.
 
@@ -84,24 +84,29 @@ import { BarChart, LineChart } from '@robr0/design-system/charts';
   ```css
   :root { --font-family-primary: 'Inter', sans-serif; }
   ```
-- **Colours, 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. The action colour is theme-split by design (light fills run teal-08/09/10, dark inverts to teal-05/04/03), so rebranding it means re-keying those steps:
   ```css
   :root {
-    --primitive-teal-07: #7C3AED;  /* your brand color becomes the action color */
+    --primitive-teal-08: #6D31D3;  /* light fill */
+    --primitive-teal-09: #4C2293;  /* light hover */
+    --primitive-teal-10: #2E1560;  /* light active, dark label */
+    --primitive-teal-05: #A78BFA;  /* dark fill */
+    --primitive-teal-04: #C4B5FD;  /* dark hover */
+    --primitive-teal-03: #DDD6FE;  /* dark active */
     --primitive-radius-full: 12px; /* pill buttons become rounded rectangles */
   }
   ```
 
-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`.
+Icons use a bundled Material Symbols Rounded variable font (woff2): components import it themselves, so they need no extra setup. If you render raw `.material-symbols-rounded` spans of your own, import `@robr0/design-system/fonts/material-symbols.css` once. 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, and primitives are never referenced directly in components:
 
 ```
-tokens-primitives.css      --primitive-teal-07: #118AB2
+tokens-primitives.css      --primitive-teal-08: #0E6E8F
         ↓
-tokens-light/dark.css      --color-action-primary-bg: var(--primitive-teal-07)
+tokens-light/dark.css      --color-action-primary-bg: var(--primitive-teal-08)
         ↓
 Component CSS              background-color: var(--color-action-primary-bg)
 ```
@@ -159,11 +164,12 @@ CI also guards against documentation drift: generated surfaces (this README's co
 ## Running locally
 
 ```bash
+npm install              # once, at the root: the website is an npm workspace, so this installs both
+
 # Storybook (the library's dev sandbox)
 npm run storybook        # http://localhost:6006
 
-# Portfolio + documentation website (npm workspace: install once at the root)
-npm install
+# Portfolio + documentation website
 npm run dev --workspace website   # http://localhost:3000
 ```
 

package/components/AgentPlan/AgentPlan.css

@@ -16,7 +16,8 @@
   width: 100%;
   background-color: var(--color-bg-container-primary);
   border: var(--border-xs) solid var(--color-bg-container-border);
-  border-radius: var(--radius-md);
+  /* The chat furniture's shared 24px shell — see ToolCall. */
+  border-radius: var(--radius-xl);
   overflow: hidden;
 }
 
@@ -29,7 +30,8 @@
   align-items: center;
   gap: var(--gap-sm);
   width: 100%;
-  padding: var(--padding-sm) var(--padding-md);
+  /* 20px sides — the card family's shared content inset. */
+  padding: var(--padding-sm) var(--padding-lg);
   background: none;
   border: none;
   text-align: left;
@@ -121,7 +123,7 @@
   display: flex;
   flex-direction: column;
   margin: 0;
-  padding: var(--padding-sm-md) var(--padding-md);
+  padding: var(--padding-sm-md) var(--padding-lg);
   list-style: none;
 }
 
@@ -229,3 +231,12 @@
   white-space: nowrap;
   border: 0;
 }
+
+/* Icons take the colour of the text around them. Explicit, not just
+   inherited by default: a consumer stylesheet that sets a colour on
+   .material-symbols-rounded itself (a common global default) would
+   otherwise override inheritance and detach the icon from the state
+   colours this component sets on its parents. */
+.ds-agent-plan .material-symbols-rounded {
+  color: inherit;
+}

package/components/AiButton/AiButton.css

@@ -60,7 +60,7 @@
   position: absolute;
   inset: 0;
   border-radius: inherit;
-  padding: var(--border-xs);
+  padding: var(--border-md);
   background: conic-gradient(
     from var(--ds-ai-button-angle),
     var(--color-ai-gradient-start),

package/components/Alert/Alert.css

@@ -250,3 +250,12 @@
 .ds-alert--neutral .ds-alert__dismiss {
   color: var(--color-status-neutral-text);
 }
+
+/* Icons take the colour of the text around them. Explicit, not just
+   inherited by default: a consumer stylesheet that sets a colour on
+   .material-symbols-rounded itself (a common global default) would
+   otherwise override inheritance and detach the icon from the state
+   colours this component sets on its parents. */
+.ds-alert .material-symbols-rounded {
+  color: inherit;
+}

package/components/AlertDialog/AlertDialog.css

@@ -11,12 +11,14 @@
   align-items: center;
   justify-content: center;
   opacity: 0;
+  visibility: hidden; /* keeps panel controls out of the tab order when closed */
   pointer-events: none;
-  transition: opacity var(--motion-duration-base) var(--motion-ease-standard);
+  transition: opacity var(--motion-duration-base) var(--motion-ease-standard), visibility var(--motion-duration-base) var(--motion-ease-standard);
 }
 
 .ds-alert-dialog--open {
   opacity: 1;
+  visibility: visible;
   pointer-events: auto;
 }
 

package/components/AlertDialog/AlertDialog.js

@@ -7,6 +7,7 @@ import "./AlertDialog.css";
 import "../../fonts/material-symbols.css";
 const emptySubscribe = () => () => {
 };
+const FOCUSABLE = 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
 const AlertDialog = ({
   open,
   onOpenChange,
@@ -53,9 +54,7 @@ const AlertDialog = ({
         return;
       }
       if (e.key === "Tab" && panel) {
-        const focusable = panel.querySelectorAll(
-          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-        );
+        const focusable = panel.querySelectorAll(FOCUSABLE);
         if (focusable.length === 0) return;
         const first = focusable[0];
         const last = focusable[focusable.length - 1];

package/components/AppSidebar/AppSidebar.css

@@ -166,12 +166,17 @@
   cursor: pointer;
   overflow: hidden;
   text-align: left;
-  transition: background-color var(--motion-duration-fast) var(--motion-ease-standard), padding var(--motion-duration-slow) var(--motion-ease-emphasized);
+  /* The row renders as an <a> when the item carries an href. */
+  text-decoration: none;
+  transition: background-color var(--motion-duration-fast) var(--motion-ease-standard), padding var(--motion-duration-slow) var(--motion-ease-emphasized), margin var(--motion-duration-slow) var(--motion-ease-emphasized);
 }
 
+/* Inset via margin + reduced padding (12 + 8 = the 20px the label sat at
+   before), so the pill floats off the rail edges while the icon and label
+   keep their exact x-positions against the category labels above. */
 .ds-app-sidebar--expanded .ds-app-sidebar__btn {
-  width: 100%;
-  padding: var(--padding-sm) var(--padding-lg);
+  margin: 0 var(--padding-sm-md);
+  padding: var(--padding-sm);
   justify-content: space-between;
 }
 
@@ -282,6 +287,9 @@
   align-items: center;
   gap: 8px;
   height: 40px;
+  /* The same edge inset the parent pills get; sub-items only render while
+     the rail is expanded, so this needs no state selector. */
+  margin-right: var(--padding-sm-md);
   padding: var(--padding-sm);
   border-radius: var(--radius-full);
   background: transparent;
@@ -292,6 +300,8 @@
   text-align: left;
   overflow: hidden;
   white-space: nowrap;
+  /* The row renders as an <a> when the sub-item carries an href. */
+  text-decoration: none;
   transition: background-color var(--motion-duration-fast) var(--motion-ease-standard);
 }
 
@@ -432,3 +442,12 @@
     padding: var(--padding-lg) 0;
   }
 }
+
+/* Icons take the colour of the text around them. Explicit, not just
+   inherited by default: a consumer stylesheet that sets a colour on
+   .material-symbols-rounded itself (a common global default) would
+   otherwise override inheritance and detach the icon from the state
+   colours this component sets on its parents. */
+.ds-app-sidebar .material-symbols-rounded {
+  color: inherit;
+}

package/components/AppSidebar/AppSidebar.d.ts

@@ -4,8 +4,10 @@ export interface AppSidebarSubItem {
     key: string;
     /** Display label */
     label: string;
-    /** Click handler */
+    /** Click handler — also fires on a link sub-item, so a consumer can route client-side */
     onClick?: () => void;
+    /** Renders the sub-item as a real link to this URL instead of a button */
+    href?: string;
 }
 export interface AppSidebarItem {
     /** Unique key for this item */
@@ -14,8 +16,10 @@ export interface AppSidebarItem {
     icon: string;
     /** Display label (shown when expanded) */
     label: string;
-    /** Click handler */
+    /** Click handler — also fires on a link item, so a consumer can route client-side */
     onClick?: () => void;
+    /** Renders the item as a real link to this URL instead of a button. Ignored when the item has children, whose row is the accordion toggle */
+    href?: string;
     /** Sub-items — turns this into an accordion */
     children?: AppSidebarSubItem[];
 }

package/components/AppSidebar/AppSidebar.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsxs, jsx } from "react/jsx-runtime";
+import { jsxs, jsx, Fragment } from "react/jsx-runtime";
 import React, { useState, useCallback } from "react";
 import "./AppSidebar.css";
 import "../../fonts/material-symbols.css";
@@ -187,14 +187,43 @@ const AppSidebar = ({
           const hasChildren = item.children && item.children.length > 0;
           const isOpen = openKeys.has(item.key);
           const isActive = activeKey === item.key;
-          return /* @__PURE__ */ jsxs(React.Fragment, { children: [
-            /* @__PURE__ */ jsxs(
-              "button",
+          const isLink = Boolean(item.href) && !hasChildren;
+          const itemClasses = [
+            `${baseClass}__btn`,
+            isActive ? `${baseClass}__btn--active` : ""
+          ].filter(Boolean).join(" ");
+          const itemContent = /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsxs("span", { className: `${baseClass}__btn-left`, children: [
+              /* @__PURE__ */ jsx("span", { className: `${baseClass}__btn-icon material-symbols-rounded`, children: item.icon }),
+              /* @__PURE__ */ jsx("span", { className: `${baseClass}__btn-label`, children: item.label })
+            ] }),
+            hasChildren && /* @__PURE__ */ jsx(
+              "span",
               {
                 className: [
-                  `${baseClass}__btn`,
-                  isActive ? `${baseClass}__btn--active` : ""
+                  `${baseClass}__btn-chevron material-symbols-rounded`,
+                  isOpen ? `${baseClass}__btn-chevron--open` : ""
                 ].filter(Boolean).join(" "),
+                children: "chevron_right"
+              }
+            )
+          ] });
+          return /* @__PURE__ */ jsxs(React.Fragment, { children: [
+            isLink ? /* @__PURE__ */ jsx(
+              "a",
+              {
+                className: itemClasses,
+                href: item.href,
+                onClick: () => item.onClick?.(),
+                "aria-current": isActive ? "page" : void 0,
+                title: !isExpanded ? item.label : void 0,
+                children: itemContent
+              }
+            ) : /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                className: itemClasses,
                 onClick: () => {
                   if (hasChildren && isExpanded) {
                     toggleAccordion(item.key);
@@ -202,23 +231,9 @@ const AppSidebar = ({
                   item.onClick?.();
                 },
                 "aria-expanded": hasChildren ? isOpen : void 0,
+                "aria-current": isActive ? "page" : void 0,
                 title: !isExpanded ? item.label : void 0,
-                children: [
-                  /* @__PURE__ */ jsxs("span", { className: `${baseClass}__btn-left`, children: [
-                    /* @__PURE__ */ jsx("span", { className: `${baseClass}__btn-icon material-symbols-rounded`, children: item.icon }),
-                    /* @__PURE__ */ jsx("span", { className: `${baseClass}__btn-label`, children: item.label })
-                  ] }),
-                  hasChildren && /* @__PURE__ */ jsx(
-                    "span",
-                    {
-                      className: [
-                        `${baseClass}__btn-chevron material-symbols-rounded`,
-                        isOpen ? `${baseClass}__btn-chevron--open` : ""
-                      ].filter(Boolean).join(" "),
-                      children: "chevron_right"
-                    }
-                  )
-                ]
+                children: itemContent
               }
             ),
             hasChildren && /* @__PURE__ */ jsx(
@@ -228,20 +243,36 @@ const AppSidebar = ({
                   `${baseClass}__sub-items`,
                   isOpen && isExpanded ? `${baseClass}__sub-items--open` : ""
                 ].filter(Boolean).join(" "),
-                children: item.children.map((sub) => /* @__PURE__ */ jsxs("div", { className: `${baseClass}__sub-item`, children: [
-                  /* @__PURE__ */ jsx("div", { className: `${baseClass}__sub-line` }),
-                  /* @__PURE__ */ jsx(
-                    "button",
-                    {
-                      className: [
-                        `${baseClass}__sub-btn`,
-                        activeSubKey === sub.key ? `${baseClass}__sub-btn--active` : ""
-                      ].filter(Boolean).join(" "),
-                      onClick: sub.onClick,
-                      children: /* @__PURE__ */ jsx("span", { className: `${baseClass}__sub-label`, children: sub.label })
-                    }
-                  )
-                ] }, sub.key))
+                children: item.children.map((sub) => {
+                  const subActive = activeSubKey === sub.key;
+                  const subClasses = [
+                    `${baseClass}__sub-btn`,
+                    subActive ? `${baseClass}__sub-btn--active` : ""
+                  ].filter(Boolean).join(" ");
+                  const subLabel = /* @__PURE__ */ jsx("span", { className: `${baseClass}__sub-label`, children: sub.label });
+                  return /* @__PURE__ */ jsxs("div", { className: `${baseClass}__sub-item`, children: [
+                    /* @__PURE__ */ jsx("div", { className: `${baseClass}__sub-line` }),
+                    sub.href ? /* @__PURE__ */ jsx(
+                      "a",
+                      {
+                        className: subClasses,
+                        href: sub.href,
+                        onClick: sub.onClick,
+                        "aria-current": subActive ? "page" : void 0,
+                        children: subLabel
+                      }
+                    ) : /* @__PURE__ */ jsx(
+                      "button",
+                      {
+                        type: "button",
+                        className: subClasses,
+                        onClick: sub.onClick,
+                        "aria-current": subActive ? "page" : void 0,
+                        children: subLabel
+                      }
+                    )
+                  ] }, sub.key);
+                })
               }
             )
           ] }, item.key);

package/components/Card/Card.css

@@ -76,7 +76,9 @@
 .ds-card--case-study {
   height: auto;
   min-width: 0;
-  padding: 0;
+  /* The cover is inset, not full-bleed: 12px of card around a 12px-radius
+     cover keeps the corners concentric with the card's 24px shell. */
+  padding: var(--padding-sm-md);
   gap: 0;
   overflow: hidden;
   cursor: pointer;
@@ -103,6 +105,7 @@
   width: 100%;
   aspect-ratio: 940 / 480;
   overflow: hidden;
+  border-radius: var(--radius-md);
   background: var(--color-bg-container-secondary);
 }
 
@@ -142,7 +145,9 @@
   display: flex;
   flex-direction: column;
   gap: var(--gap-sm);
-  padding: var(--padding-lg);
+  /* 8px on top of the card's 12px inset: text lands 20px from the card edge
+     (the old full-bleed body padding) and sits slightly inside the cover. */
+  padding: var(--padding-md) var(--padding-sm) var(--padding-sm-md);
 }
 
 .ds-card--case-study__eyebrow {

package/components/CardStack/CardStack.css

@@ -0,0 +1,106 @@
+/* ============================================
+   CARD STACK COMPONENT
+   A deck showing one card, the rest peeking out
+   beneath. Forward flips lift the top card away;
+   backward flips drop it in from above. Depth
+   offsets are percentages of the card itself, so
+   the choreography scales with whatever card the
+   deck holds.
+   ============================================ */
+
+/* Base */
+
+.ds-card-stack {
+  /* How far each buried card peeks out below the one above it. */
+  --ds-card-stack-peek: var(--gap-md);
+
+  position: relative;
+  display: grid;
+  border-radius: var(--radius-xl);
+  padding-bottom: calc(var(--ds-card-stack-peek) * var(--ds-card-stack-depth, 0));
+  outline: none;
+}
+
+.ds-card-stack:focus-visible {
+  outline: var(--border-md) solid var(--color-action-primary-bg);
+  outline-offset: var(--padding-xxs);
+}
+
+/* Items — every card occupies the same cell; position is one transform. */
+
+.ds-card-stack__item {
+  grid-area: 1 / 1;
+  /* An opaque page-colour backing behind each card: the system's cards sit on
+     translucent surfaces, and without this the buried cards read through the
+     top one. Rounded to Card's radius; a deck of differently shaped cards
+     repoints --ds-card-stack-card-radius. */
+  background: var(--color-bg-page-primary);
+  border-radius: var(--ds-card-stack-card-radius, var(--radius-xl));
+  transform-origin: 50% 100%;
+  transform: translateY(calc(var(--ds-card-stack-peek) * var(--ds-card-stack-pos, 0)))
+    scale(calc(1 - 0.04 * var(--ds-card-stack-pos, 0)));
+  transition:
+    transform var(--motion-duration-deliberate) var(--motion-ease-emphasized),
+    opacity var(--motion-duration-deliberate) var(--motion-ease-emphasized);
+}
+
+/* Deeper than the visible peek: parked at the last slot, faded out. */
+.ds-card-stack__item--buried {
+  opacity: 0;
+  transform: translateY(calc(var(--ds-card-stack-peek) * var(--ds-card-stack-depth, 0)))
+    scale(calc(1 - 0.04 * var(--ds-card-stack-depth, 0)));
+}
+
+/* Flipped away with loop off: lifted out of view, above the deck. */
+.ds-card-stack__item--gone {
+  opacity: 0;
+  transform: translateY(-12%) scale(0.98);
+}
+
+/* Flip choreography — the lift is a fraction of the card's own height. */
+
+.ds-card-stack__item--leaving {
+  animation: ds-card-stack-leave var(--motion-duration-deliberate) var(--motion-ease-emphasized)
+    both;
+}
+
+.ds-card-stack__item--entering {
+  animation: ds-card-stack-enter var(--motion-duration-deliberate) var(--motion-ease-entrance)
+    both;
+}
+
+@keyframes ds-card-stack-leave {
+  from {
+    transform: translateY(0) rotate(0deg) scale(1);
+    opacity: 1;
+  }
+  to {
+    transform: translateY(-18%) rotate(-3deg) scale(0.98);
+    opacity: 0;
+  }
+}
+
+@keyframes ds-card-stack-enter {
+  from {
+    transform: translateY(-18%) rotate(-3deg) scale(0.98);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0) rotate(0deg) scale(1);
+    opacity: 1;
+  }
+}
+
+/* Screen-reader announcement of the deck position. */
+
+.ds-card-stack__sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/components/CardStack/CardStack.d.ts

@@ -0,0 +1,44 @@
+import { default as React } from 'react';
+/** Props owned by CardStack itself — everything else falls through to the root `<div>`. */
+type CardStackOwnProps = {
+    /** The cards, in order. The first child starts on top. */
+    children?: React.ReactNode;
+    /**
+     * Controlled top card, as an index into `children`. Pair with
+     * `onIndexChange`. Omit to let the stack own its position.
+     */
+    index?: number;
+    /** Initial top card when uncontrolled. */
+    defaultIndex?: number;
+    /** Fires when the top card changes, with the new index. */
+    onIndexChange?: (index: number) => void;
+    /** How many card edges peek out behind the top card. */
+    peek?: number;
+    /** Wrap from the last card back to the first. Off, the stack stops at both ends. */
+    loop?: boolean;
+    /**
+     * Clicking the top card flips to the next. Clicks that land on a link or
+     * control inside the card are left alone, so a card can still carry its
+     * own actions.
+     */
+    advanceOnClick?: boolean;
+    /** Accessible name for the stack, e.g. "Open roles". */
+    label?: string;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface CardStackProps extends CardStackOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof CardStackOwnProps> {
+}
+/**
+ * CardStack — a deck of cards showing one at a time, the rest peeking out
+ * beneath it. Flipping forward lifts the top card up and away while the next
+ * one rises into place; flipping back drops the previous card in from above.
+ * The stack is the pattern, not the cards: any children work, Card and
+ * EntityCard are the intended fillings, and every card should share one size
+ * so the deck keeps its shape.
+ *
+ * Flip by clicking the top card, or with the arrow keys when the stack has
+ * focus. Cards behind the top one are inert until their turn.
+ */
+export declare const CardStack: React.ForwardRefExoticComponent<CardStackProps & React.RefAttributes<HTMLDivElement>>;
+export {};