@chronogrove/ui 0.79.0 → 0.81.0

package/README.md

@@ -18,28 +18,49 @@ Use **`pnpm publish`** for releases so `workspace:` dependencies in dependents a
 
 Prefer deep imports so bundles stay lean:
 
-| Import path                         | Contents                                                                                           |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `@chronogrove/ui`                   | `ChronogroveThemeProvider`                                                                         |
-| `@chronogrove/ui/theme`             | Default Theme UI theme object + named exports                                                      |
-| `@chronogrove/ui/provider`          | `ChronogroveThemeProvider`                                                                         |
-| `@chronogrove/ui/color-mode`        | Storage key, reconcile event, SSR inline builders, `resolveChronogroveSurfaceColors`, browser sync |
-| `@chronogrove/ui/emotion-cache`     | `createChronogroveEmotionCache`, `getChronogroveEmotionCache`                                      |
-| `@chronogrove/ui/button`            | Theme UI `components` button                                                                       |
-| `@chronogrove/ui/color-toggle`      | Theme UI + `@theme-toggles/react` toggle                                                           |
-| `@chronogrove/ui/skip-nav`          | `SkipNavLink`, `SkipNavContent`                                                                    |
-| `@chronogrove/ui/is-dark-mode`      | `colorMode === 'dark'` helper                                                                      |
-| `@chronogrove/ui/color-utils`       | `hexToRgb`, `hexToRgba`, `BUTTON_PRIMARY_COLORS`                                                   |
-| `@chronogrove/ui/action-button`     | Outline CTA as `<button>` or `<a>`                                                                 |
-| `@chronogrove/ui/pagination-button` | Compact paginator control                                                                          |
-| `@chronogrove/ui/lazy-load`         | Defer children until in viewport (`react-intersection-observer`)                                   |
-| `@chronogrove/ui/header`            | Masthead shell (`variant: styles.Header`)                                                          |
-| `@chronogrove/ui/page-header`       | Blog-style `h1` heading (`p-name`)                                                                 |
-| `@chronogrove/ui/gatsby`            | Color-mode Gatsby SSR/browser helpers                                                              |
+| Import path                                | Contents                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@chronogrove/ui`                          | `ChronogroveThemeProvider`                                                                                                                                                                                                                                                                                                                       |
+| `@chronogrove/ui/theme`                    | Default Theme UI theme object + named exports                                                                                                                                                                                                                                                                                                    |
+| `@chronogrove/ui/provider`                 | `ChronogroveThemeProvider`                                                                                                                                                                                                                                                                                                                       |
+| `@chronogrove/ui/color-mode`               | Storage key, reconcile event, SSR inline builders, `chronogroveHeadTheme` (RSC-safe), `resolveChronogroveSurfaceColors`, `useDocumentColorModeSurface`, browser sync, `reconcileThemeUiColorModeOnNavigation`                                                                                                                                    |
+| `@chronogrove/ui/animated-page-background` | **`ChronogroveAnimatedPageBackground`** — same stack as the Gatsby home: fixed `z-index: 0`, light = solid theme background, dark = **three.js** Color Bends + scroll-linked gradient overlay and parallax (`three` is a dependency of this package). **Not** the same as `page-backdrop`.                                                       |
+| `@chronogrove/ui/color-bends`              | **`ColorBends`** — lower-level three.js gradient background used inside `ChronogroveAnimatedPageBackground`. Prefer the full **`animated-page-background`** or **`@chronogrove/ui/next`** shell unless you need the raw component.                                                                                                               |
+| `@chronogrove/ui/page-backdrop`            | **`ChronogrovePageBackdrop`** — lightweight alternative: fixed `z-index: 0` fill without WebGL (CSS gradients in dark mode). Use when you cannot ship `three`.                                                                                                                                                                                   |
+| `@chronogrove/ui/next`                     | **Next.js App Router helpers:** `ChronogroveNextRootLayoutHead` (RSC `<head>` injections), `ChronogroveNextEmotionRegistry`, `ChronogroveNextAppShell` (theme + three.js background + surface sync + soft-nav reconcile), `ChronogroveNextThemeUiColorModeRouteSync` (standalone). Requires `next` (peer, optional for the rest of the package). |
+| `@chronogrove/ui/action-card-layout`       | **`actionCardPinnedLayoutSx`** — layout `sx` for `Card variant="actionCard"` (matches GitHub pinned cards).                                                                                                                                                                                                                                      |
+| `@chronogrove/ui/emotion-cache`            | `createChronogroveEmotionCache`, `getChronogroveEmotionCache`                                                                                                                                                                                                                                                                                    |
+| `@chronogrove/ui/button`                   | Theme UI `components` button                                                                                                                                                                                                                                                                                                                     |
+| `@chronogrove/ui/color-toggle`             | Theme UI + `@theme-toggles/react` `Expand`                                                                                                                                                                                                                                                                                                       |
+| `@chronogrove/ui/color-toggle-styles`      | CSS for the toggle (`Expand.css` + sizing); `@import` once in global CSS (see `examples/chronogrove-next/app/globals.css`)                                                                                                                                                                                                                       |
+| `@chronogrove/ui/skip-nav`                 | `SkipNavLink`, `SkipNavContent`                                                                                                                                                                                                                                                                                                                  |
+| `@chronogrove/ui/is-dark-mode`             | `colorMode === 'dark'` helper                                                                                                                                                                                                                                                                                                                    |
+| `@chronogrove/ui/color-utils`              | `hexToRgb`, `hexToRgba`, `BUTTON_PRIMARY_COLORS`                                                                                                                                                                                                                                                                                                 |
+| `@chronogrove/ui/action-button`            | Outline CTA as `<button>` or `<a>`                                                                                                                                                                                                                                                                                                               |
+| `@chronogrove/ui/pagination-button`        | Compact paginator control                                                                                                                                                                                                                                                                                                                        |
+| `@chronogrove/ui/lazy-load`                | Defer children until in viewport (`react-intersection-observer`)                                                                                                                                                                                                                                                                                 |
+| `@chronogrove/ui/header`                   | Masthead shell (`variant: styles.Header`)                                                                                                                                                                                                                                                                                                        |
+| `@chronogrove/ui/page-header`              | Blog-style `h1` heading (`p-name`)                                                                                                                                                                                                                                                                                                               |
+| `@chronogrove/ui/gatsby`                   | Color-mode Gatsby SSR/browser helpers                                                                                                                                                                                                                                                                                                            |
 
 ## Next.js (App Router)
 
-Anything using `useColorMode`, `useThemeUI`, or the provider must run in a **client** component (`'use client'`). Stack **Emotion** `CacheProvider` (with the `meta[name="emotion-insertion-point"]` pattern) **outside** `ChronogroveThemeProvider`. Detailed integration is tracked as follow-up work in the repo roadmap.
+**Reference app:** [`examples/chronogrove-next`](../../examples/chronogrove-next) (`chronogrove-next`). Run `pnpm --filter chronogrove-next dev` from the repo root.
+
+**Prefer `@chronogrove/ui/next`** for the standard wiring: `ChronogroveNextRootLayoutHead` in `<head>`, `ChronogroveNextEmotionRegistry` wrapping the body tree, and `ChronogroveNextAppShell` (or compose the lower-level exports yourself).
+
+**Server vs client**
+
+- **Server `layout`:** Keep the root layout a Server Component. **Do not** import `@chronogrove/ui/theme` here—it loads `theme-ui`’s `merge` and triggers React `createContext`, which Next.js disallows in RSC. Use **`ChronogroveNextRootLayoutHead`** from `@chronogrove/ui/next`, or manually pass **`chronogroveHeadTheme`** from `@chronogrove/ui/color-mode` to `resolveChronogroveSurfaceColors` and emit **in order**: `<meta name="emotion-insertion-point" content="" />`, then the Theme UI no-flash script, HTML background script, and fallback CSS (same composition as [`buildThemeUiColorModeHeadComponents`](./src/gatsby/build-theme-ui-color-mode-head-components.js) in `@chronogrove/ui/gatsby`).
+- **Client Emotion registry + theme:** Use **`ChronogroveNextEmotionRegistry`** from `@chronogrove/ui/next`, or wrap the app in Emotion’s `CacheProvider` with a **per-request** cache with `key: 'css'` and Next’s `useServerInsertedHTML` ([Next.js: CSS-in-JS](https://nextjs.org/docs/app/building-your-application/styling/css-in-js)). **Do not** rely on `getChronogroveEmotionCache()` for SSR—it is a browser-oriented singleton. Import the **full** theme from `@chronogrove/ui/theme` only inside client components. Anything using `useColorMode`, `useThemeUI`, or `ChronogroveThemeProvider` must be `'use client'`. **Order:** `CacheProvider` (registry) **outside** `ChronogroveThemeProvider` **inside** `<body>`.
+- **Document surface (match Gatsby `RootWrapper`):** **`ChronogroveNextAppShell`** calls **`useDocumentColorModeSurface`** from `@chronogrove/ui/color-mode` once. It syncs `document.documentElement`’s `theme-ui-*` class, `data-theme-ui-color-mode`, and inline page background from the **resolved** Theme UI theme (`rawColors` / `colors.background`). Without it, Emotion can win the cascade over head fallback CSS and panel tokens (`bg: 'panel-background'`) may not update in dark mode after hydration.
+- **Animated page background (match Gatsby home):** **`ChronogroveNextAppShell`** includes **`ChronogroveAnimatedPageBackground`** (three.js Color Bends). For a **CSS-only** backdrop without `three`, use **`ChronogrovePageBackdrop`** from `@chronogrove/ui/page-backdrop` instead and compose your own shell. Content should sit in a **`position: relative; z-index: 1`** wrapper.
+- **Soft navigations:** **`ChronogroveNextAppShell`** includes **`ChronogroveNextThemeUiColorModeRouteSync`**, which calls `reconcileThemeUiColorModeOnNavigation` after pathname changes (not on initial mount). Running reconcile on mount can fight `useColorMode` toggles. Gatsby’s equivalent is `onRouteUpdateThemeUiColorMode` (no initial `onRouteUpdate`).
+- **Hydration:** Set `suppressHydrationWarning` on `<html>` and `<body>`. The inline no-flash / background scripts run before React hydrates and update `<html>` (`theme-ui-*` classes, `data-theme-ui-color-mode`, background), so the DOM no longer matches the server-rendered markup—React would warn without this flag (similar to [next-themes](https://github.com/pacocoursey/next-themes) on Next.js App Router).
+
+**Imports:** Prefer `@chronogrove/ui/color-mode` for head builders and SPA reconcile. Reserve `@chronogrove/ui/gatsby` for Gatsby hooks (`onPreRenderHTML`, `onRenderBody` helpers).
+
+**JSX + bundlers:** Primitives such as [`button`](./src/button.js) use [`Box`](https://theme-ui.com/components/box) from `@theme-ui/components` with an `as` prop for native elements, so `sx` works with Gatsby’s classic JSX runtime and Next’s SWC without a Theme UI file pragma. Jest uses [`babel.config.cjs`](./babel.config.cjs) (automatic JSX).
 
 ## Changelog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.79.0",
+  "version": "0.81.0",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,9 @@
     "url": "https://github.com/chrisvogt/gatsby-theme-chronogrove.git",
     "directory": "packages/ui"
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "**/*.css"
+  ],
   "exports": {
     ".": {
       "import": "./src/index.js",
@@ -35,6 +37,7 @@
       "import": "./src/color-toggle.js",
       "default": "./src/color-toggle.js"
     },
+    "./color-toggle-styles": "./src/color-toggle-styles.css",
     "./skip-nav": {
       "import": "./src/skip-nav/index.js",
       "default": "./src/skip-nav/index.js"
@@ -63,10 +66,50 @@
       "import": "./src/pagination-button.js",
       "default": "./src/pagination-button.js"
     },
+    "./pagination": {
+      "import": "./src/pagination.js",
+      "default": "./src/pagination.js"
+    },
+    "./category-label": {
+      "import": "./src/category-label.js",
+      "default": "./src/category-label.js"
+    },
+    "./external-link-icon": {
+      "import": "./src/external-link-icon.js",
+      "default": "./src/external-link-icon.js"
+    },
+    "./metric-badge": {
+      "import": "./src/metric-badge.js",
+      "default": "./src/metric-badge.js"
+    },
+    "./metric-card": {
+      "import": "./src/metric-card.js",
+      "default": "./src/metric-card.js"
+    },
+    "./muted-card-footer": {
+      "import": "./src/muted-card-footer.js",
+      "default": "./src/muted-card-footer.js"
+    },
+    "./status-card": {
+      "import": "./src/status-card.js",
+      "default": "./src/status-card.js"
+    },
+    "./widget-section": {
+      "import": "./src/widget-section.js",
+      "default": "./src/widget-section.js"
+    },
+    "./widget-call-to-action": {
+      "import": "./src/widget-call-to-action.js",
+      "default": "./src/widget-call-to-action.js"
+    },
     "./lazy-load": {
       "import": "./src/lazy-load.js",
       "default": "./src/lazy-load.js"
     },
+    "./next": {
+      "import": "./src/next/index.js",
+      "default": "./src/next/index.js"
+    },
     "./header": {
       "import": "./src/header.js",
       "default": "./src/header.js"
@@ -75,15 +118,37 @@
       "import": "./src/page-header.js",
       "default": "./src/page-header.js"
     },
+    "./page-backdrop": {
+      "import": "./src/page-backdrop.js",
+      "default": "./src/page-backdrop.js"
+    },
+    "./animated-page-background": {
+      "import": "./src/animated-page-background/index.js",
+      "default": "./src/animated-page-background/index.js"
+    },
+    "./color-bends": {
+      "import": "./src/animated-page-background/ColorBends.js",
+      "default": "./src/animated-page-background/ColorBends.js"
+    },
+    "./action-card-layout": {
+      "import": "./src/action-card-layout.js",
+      "default": "./src/action-card-layout.js"
+    },
     "./gatsby": {
       "import": "./src/gatsby/index.js",
       "default": "./src/gatsby/index.js"
     }
   },
   "peerDependencies": {
+    "next": "^14.0.0 || ^15.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@emotion/cache": "^11.14.0",
     "@emotion/react": "^11.14.0",
@@ -91,17 +156,19 @@
     "@theme-ui/components": "^0.17.4",
     "@theme-ui/presets": "^0.17.4",
     "react-intersection-observer": "^10.0.3",
-    "theme-ui": "^0.17.4"
+    "theme-ui": "^0.17.4",
+    "three": "^0.183.2"
   },
   "devDependencies": {
-    "@babel/core": "^7.28.5",
-    "@babel/preset-env": "^7.28.5",
+    "@babel/core": "^7.29.0",
+    "@babel/preset-env": "^7.29.2",
     "@babel/preset-react": "^7.28.5",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
-    "babel-jest": "^30.0.5",
+    "babel-jest": "^30.3.0",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.3.0",
+    "next": "^15.1.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5"
   },

package/src/__snapshots__/header.spec.js.snap

@@ -3,11 +3,11 @@
 exports[`Header renders with children 1`] = `
 <DocumentFragment>
   <header
-    class="css-1u8qly9"
+    class="css-1yz7e9k"
     role="banner"
   >
     <div
-      class="css-1u8qly9"
+      class="css-1yz7e9k"
     >
       <h1>
         Test Header
@@ -20,11 +20,11 @@ exports[`Header renders with children 1`] = `
 exports[`Header renders with custom styles 1`] = `
 <DocumentFragment>
   <header
-    class="css-1u8qly9"
+    class="css-1yz7e9k"
     role="banner"
   >
     <div
-      class="css-10n8us"
+      class="css-1g5wp3y"
     >
       <h1>
         Test Header with Styles
@@ -37,11 +37,11 @@ exports[`Header renders with custom styles 1`] = `
 exports[`Header renders with empty styles object 1`] = `
 <DocumentFragment>
   <header
-    class="css-1u8qly9"
+    class="css-1yz7e9k"
     role="banner"
   >
     <div
-      class="css-1u8qly9"
+      class="css-1yz7e9k"
     >
       <h1>
         Test Header with Empty Styles
@@ -54,11 +54,11 @@ exports[`Header renders with empty styles object 1`] = `
 exports[`Header renders without styles prop 1`] = `
 <DocumentFragment>
   <header
-    class="css-1u8qly9"
+    class="css-1yz7e9k"
     role="banner"
   >
     <div
-      class="css-1u8qly9"
+      class="css-1yz7e9k"
     >
       <h1>
         Test Header without Styles

package/src/__snapshots__/theme.spec.js.snap

@@ -130,12 +130,11 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       },
       "WebkitBackdropFilter": "blur(10px)",
       "backdropFilter": "blur(10px)",
-      "background": "var(--theme-ui-colors-panel-background)",
-      "backgroundColor": "var(--theme-ui-colors-panel-background)",
+      "bg": "panel-background",
       "border": "1px solid rgba(255, 255, 255, 0.15)",
       "borderRadius": "10px",
       "boxShadow": "0 4px 6px rgba(0, 0, 0, 0.1)",
-      "color": "var(--theme-ui-colors-panel-text)",
+      "color": "text",
       "display": "flex",
       "flexDirection": "column",
       "flexGrow": 1,
@@ -160,8 +159,8 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
     "UserProfileDark": {
       "WebkitBackdropFilter": "blur(12px) saturate(150%)",
       "backdropFilter": "blur(12px) saturate(150%)",
-      "background": "var(--theme-ui-colors-panel-background)",
       "backgroundColor": "none",
+      "bg": "panel-background",
       "borderBottom": "none",
       "borderRadius": "card",
       "boxShadow": "none",
@@ -184,12 +183,12 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
         ":hover": "pointer",
       },
       "backdropFilter": "blur(10px)",
-      "background": "var(--theme-ui-colors-panel-background)",
+      "bg": "panel-background",
       "border": "1px solid rgba(255, 255, 255, 0.15)",
       "borderLeft": [Function],
       "borderRadius": "10px",
       "boxShadow": "0 4px 6px rgba(0, 0, 0, 0.1)",
-      "color": "var(--theme-ui-colors-panel-text)",
+      "color": "text",
       "flexGrow": 1,
       "fontSize": [
         1,
@@ -285,12 +284,12 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       },
       "WebkitBackdropFilter": "blur(10px)",
       "backdropFilter": "blur(10px)",
-      "background": "var(--theme-ui-colors-panel-background)",
+      "bg": "panel-background",
       "border": "1px solid rgba(255, 255, 255, 0.15)",
       "borderLeft": [Function],
       "borderRadius": "10px",
       "boxShadow": "0 4px 6px rgba(0, 0, 0, 0.1)",
-      "color": "var(--theme-ui-colors-panel-text)",
+      "color": "text",
       "flexGrow": 1,
       "fontSize": [
         1,
@@ -302,33 +301,48 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
     "metricCard": {
       "WebkitBackdropFilter": "blur(12px) saturate(150%)",
       "backdropFilter": "blur(12px) saturate(150%)",
-      "background": "var(--theme-ui-colors-panel-background)",
-      "backgroundColor": "var(--theme-ui-colors-panel-background)",
+      "backgroundColor": "panel-background",
+      "bg": "panel-background",
+      "border": "1px solid",
+      "borderColor": "panel-divider",
       "borderRadius": "card",
       "boxShadow": "none",
-      "color": "var(--theme-ui-colors-panel-text)",
+      "color": "text",
+      "flexGrow": 1,
+      "fontSize": [
+        1,
+        2,
+      ],
+      "padding": 3,
+      "textDecoration": "none",
+    },
+    "metricCardDark": {
+      "WebkitBackdropFilter": "blur(12px) saturate(150%)",
+      "backdropFilter": "blur(12px) saturate(150%)",
+      "backgroundColor": "#1e2530",
+      "bg": "panel-background",
+      "border": "1px solid",
+      "borderColor": "panel-divider",
+      "borderRadius": "card",
+      "boxShadow": "none",
+      "color": "text",
       "flexGrow": 1,
       "fontSize": [
         1,
         2,
       ],
       "padding": 3,
-      "span": {
-        "fontFamily": "heading",
-        "fontWeight": "bold",
-        "padding": 2,
-      },
       "textDecoration": "none",
     },
     "presentationalCard": {
       "WebkitBackdropFilter": "blur(10px)",
       "backdropFilter": "blur(10px)",
-      "background": "var(--theme-ui-colors-panel-background)",
+      "bg": "panel-background",
       "border": "1px solid rgba(255, 255, 255, 0.15)",
       "borderLeft": [Function],
       "borderRadius": "10px",
       "boxShadow": "0 4px 6px rgba(0, 0, 0, 0.1)",
-      "color": "var(--theme-ui-colors-panel-text)",
+      "color": "text",
       "flexGrow": 1,
       "fontSize": [
         1,
@@ -340,10 +354,10 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
     "primary": {
       "WebkitBackdropFilter": "blur(12px) saturate(150%)",
       "backdropFilter": "blur(12px) saturate(150%)",
-      "background": "var(--theme-ui-colors-panel-background)",
+      "bg": "panel-background",
       "borderRadius": "card",
       "boxShadow": "default",
-      "color": "var(--theme-ui-colors-panel-text)",
+      "color": "text",
       "flexGrow": 1,
       "fontSize": [
         1,
@@ -806,6 +820,11 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
         "right",
       ],
     },
+    "mutedCardFooter": {
+      "display": "flex",
+      "justifyContent": "space-between",
+      "mt": 2,
+    },
     "outlined": {
       "border": "4px solid #efefef",
     },

package/src/action-button.js

@@ -1,6 +1,6 @@
-/** @jsx jsx */
 import React from 'react'
-import { jsx, useThemeUI } from 'theme-ui'
+import { Box } from '@theme-ui/components'
+import { useThemeUI } from 'theme-ui'
 import isDarkMode from './helpers/isDarkMode.js'
 import { hexToRgb } from './color-utils.js'
 
@@ -67,16 +67,16 @@ const ActionButton = ({ children, href, onClick, variant = 'primary', size = 'me
 
   if (href) {
     return (
-      <a href={href} sx={baseStyles} {...props}>
+      <Box as='a' href={href} sx={baseStyles} {...props}>
         {content}
-      </a>
+      </Box>
     )
   }
 
   return (
-    <button type='button' onClick={onClick} sx={baseStyles} {...props}>
+    <Box as='button' type='button' onClick={onClick} sx={baseStyles} {...props}>
       {content}
-    </button>
+    </Box>
   )
 }
 

package/src/action-button.spec.js

@@ -1,5 +1,3 @@
-/** @jsx jsx */
-import { jsx } from 'theme-ui'
 import { render, screen, fireEvent } from '@testing-library/react'
 import { ThemeUIProvider } from 'theme-ui'
 
@@ -84,6 +82,20 @@ describe('ActionButton', () => {
     })
   })
 
+  it('uses dark secondary palette when color mode is dark', () => {
+    mockUseThemeUI.mockReturnValueOnce({
+      colorMode: 'dark',
+      theme: {
+        colors: {
+          primary: BUTTON_PRIMARY_COLORS.light,
+          primaryRgb: '66, 46, 163'
+        }
+      }
+    })
+    renderWithProviders(<ActionButton variant='secondary'>Secondary Dark</ActionButton>)
+    expect(screen.getByRole('button', { name: /secondary dark/i })).toHaveStyle({ color: '#888' })
+  })
+
   it('applies small size styles', () => {
     renderWithProviders(<ActionButton size='small'>Small Button</ActionButton>)
 

package/src/action-card-layout.js

@@ -0,0 +1,13 @@
+/**
+ * Layout `sx` aligned with GitHub pinned cards — pair with `Card variant="actionCard"`.
+ * @see theme/src/components/widgets/github/pinned-item-card.js
+ */
+export const actionCardPinnedLayoutSx = {
+  height: '100%',
+  display: 'flex',
+  flexDirection: 'column',
+  transition: 'transform 0.2s ease-in-out',
+  '&:hover': {
+    transform: 'translateY(-4px)'
+  }
+}

package/src/action-card-layout.spec.js

@@ -0,0 +1,13 @@
+import { actionCardPinnedLayoutSx } from './action-card-layout.js'
+
+describe('actionCardPinnedLayoutSx', () => {
+  it('exports a Theme UI sx object for action-card hover layout', () => {
+    expect(actionCardPinnedLayoutSx).toMatchObject({
+      height: '100%',
+      display: 'flex',
+      flexDirection: 'column',
+      transition: 'transform 0.2s ease-in-out'
+    })
+    expect(actionCardPinnedLayoutSx['&:hover']).toEqual({ transform: 'translateY(-4px)' })
+  })
+})

package/src/animated-page-background/ChronogroveAnimatedPageBackground.js

@@ -0,0 +1,153 @@
+'use client'
+
+import React, { useMemo, useEffect, useState } from 'react'
+import { Box } from '@theme-ui/components'
+import { useColorMode, useThemeUI } from 'theme-ui'
+
+import ColorBends from './ColorBends.js'
+import {
+  chronogroveThemeSurfaceColorsDark,
+  chronogroveThemeSurfaceColorsLight
+} from '../chronogrove-theme-surface-colors.js'
+import { hexToRgba } from '../color-utils.js'
+
+// Based on Starry Banner SVG colors: purple #800080 and gold #FFD700
+const COLOR_BENDS_COLORS = ['#800080', '#6B2F6B', '#FFD700', '#A855A8']
+const COLOR_BENDS_STYLE = { width: '100%', height: '100%' }
+
+/**
+ * Fixed viewport background: solid in light mode, Color Bends (three.js) in dark mode,
+ * plus scroll-linked gradient overlay and parallax — same behavior as the Gatsby home.
+ */
+export default function ChronogroveAnimatedPageBackground({
+  overlayHeight = 'min(112.5vh, 1500px)',
+  darkOpacity = 0.12,
+  fadeDistance = 700,
+  maxParallaxOffset = 150
+}) {
+  const [colorMode] = useColorMode()
+  const { theme } = useThemeUI()
+  const isDark = colorMode === 'dark'
+  const [overlayOpacity, setOverlayOpacity] = useState(1)
+  const [parallaxOffset, setParallaxOffset] = useState(0)
+  const [maxScrollDistance, setMaxScrollDistance] = useState(1)
+  const [mounted, setMounted] = useState(false)
+
+  const bgColorRaw =
+    theme?.rawColors?.background ||
+    theme?.colors?.background ||
+    (isDark ? chronogroveThemeSurfaceColorsDark.background : chronogroveThemeSurfaceColorsLight.background)
+
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  useEffect(() => {
+    const updateMaxScroll = () => {
+      const maxScroll = Math.max(1, document.documentElement.scrollHeight - window.innerHeight)
+      setMaxScrollDistance(maxScroll)
+    }
+
+    updateMaxScroll()
+
+    window.addEventListener('resize', updateMaxScroll, { passive: true })
+    return () => window.removeEventListener('resize', updateMaxScroll)
+  }, [])
+
+  useEffect(() => {
+    const handleScroll = () => {
+      const scrollY = window.scrollY
+      const opacity = Math.max(0, 1 - scrollY / fadeDistance)
+      setOverlayOpacity(opacity)
+
+      const scrollProgress = Math.min(scrollY / maxScrollDistance, 1)
+      const offset = scrollProgress * maxParallaxOffset
+      setParallaxOffset(offset)
+    }
+
+    handleScroll()
+
+    window.addEventListener('scroll', handleScroll, { passive: true })
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [fadeDistance, maxParallaxOffset, maxScrollDistance])
+
+  const backgroundAnimation = useMemo(
+    () =>
+      isDark ? (
+        <ColorBends
+          colors={COLOR_BENDS_COLORS}
+          rotation={30}
+          speed={0.1}
+          scale={1}
+          frequency={1}
+          warpStrength={1}
+          mouseInfluence={1}
+          parallax={1}
+          noise={0.1}
+          transparent
+          style={COLOR_BENDS_STYLE}
+        />
+      ) : null,
+    [isDark]
+  )
+
+  if (!mounted) {
+    return null
+  }
+
+  const toRgba = (color, alpha) => {
+    if (typeof color === 'string' && color.startsWith('var(')) {
+      const fallbackHex = isDark
+        ? chronogroveThemeSurfaceColorsDark.background
+        : chronogroveThemeSurfaceColorsLight.background
+      return hexToRgba(fallbackHex, alpha)
+    }
+    return hexToRgba(color, alpha)
+  }
+
+  const gradientOverlay = `linear-gradient(to bottom, ${bgColorRaw} 0%, ${bgColorRaw} 30%, ${toRgba(bgColorRaw, 0.6)} 65%, ${toRgba(bgColorRaw, 0.2)} 85%, transparent 100%)`
+
+  return (
+    <>
+      <Box
+        key={`bg-${colorMode}`}
+        aria-hidden='true'
+        sx={{
+          position: 'fixed',
+          top: 0,
+          left: 0,
+          right: 0,
+          width: '100vw',
+          height: `calc(100vh + ${maxParallaxOffset}px)`,
+          zIndex: 0,
+          overflow: 'hidden',
+          opacity: isDark ? darkOpacity : 1,
+          pointerEvents: 'none',
+          backgroundColor: bgColorRaw,
+          transform: `translateY(-${parallaxOffset}px)`,
+          willChange: 'transform'
+        }}
+      >
+        {backgroundAnimation}
+      </Box>
+
+      <Box
+        key={`overlay-${colorMode}`}
+        aria-hidden='true'
+        sx={{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          right: 0,
+          width: '100%',
+          height: overlayHeight,
+          zIndex: 0,
+          pointerEvents: 'none',
+          opacity: overlayOpacity,
+          transition: 'opacity 0.1s ease-out',
+          background: gradientOverlay
+        }}
+      />
+    </>
+  )
+}