@chronogrove/ui 0.83.0 → 0.83.2

package/README.md

@@ -44,7 +44,7 @@ Prefer deep imports so bundles stay lean:
 | `@chronogrove/ui/widget-header`            | Widget section title row (optional Font Awesome icon, aside slot, optional metrics)                                                                                                                                                                                                                                                              |
 | `@chronogrove/ui/gatsby`                   | Color-mode Gatsby SSR/browser helpers                                                                                                                                                                                                                                                                                                            |
 
-**Additional subpaths:** The table lists the most common entry points. Also published: **`pagination`** (full bar; composes **`pagination-button`**), **`category-label`**, **`metric-badge`**, **`metric-card`**, **`muted-card-footer`**, **`status-card`**, **`widget-section`**, **`widget-call-to-action`**, **`external-link-icon`**, **`thumbnail-strip`**, **`image-thumbnails`** (`optimizeSrc` for CDN resizing; Gatsby passes a Cloudinary helper). The authoritative list is **`package.json`** → **`exports`**.
+**Additional subpaths:** The table lists the most common entry points. Also published: **`pagination`** (full bar; composes **`pagination-button`**), **`category-label`**, **`metric-badge`**, **`metric-card`**, **`muted-card-footer`**, **`status-card`**, **`widget-section`** (dashboard `<section>`; when **`id`** is passed, **`tabIndex={-1}`** defaults so hosts can **`focus`** the landmark after hash / in-page navigation), **`widget-call-to-action`**, **`external-link-icon`**, **`thumbnail-strip`**, **`image-thumbnails`** (`optimizeSrc` for CDN resizing; Gatsby passes a Cloudinary helper). The authoritative list is **`package.json`** → **`exports`**.
 
 ## Next.js (App Router)
 
@@ -67,6 +67,79 @@ Prefer deep imports so bundles stay lean:
 
 **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).
 
+## Global CSS, Prism / third-party CSS, and fonts
+
+Styles load in three layers. Understanding the split prevents accidental duplicates and keeps each host's build minimal.
+
+### Layer order
+
+| #   | Layer                                           | Mechanism                                                                                                                                                                                                               |
+| --- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **Head — color-mode + Emotion insertion point** | Gatsby: `theme/gatsby-ssr.js` + `@chronogrove/ui/gatsby` helpers. Next: `ChronogroveNextRootLayoutHead` from `@chronogrove/ui/next`. Emit before any `<style>` tags so Emotion and Theme UI no-flash scripts run first. |
+| 2   | **Theme UI globals (`theme.global`)**           | `ChronogroveThemeProvider` renders `<Global styles={theme.global} />` via Emotion. This applies identical baseline CSS under both Gatsby and Next as long as the provider wraps the app. No extra import needed.        |
+| 3   | **Host global CSS**                             | Each host owns its plain-CSS files. See below for Gatsby and Next specifics.                                                                                                                                            |
+
+### Gatsby
+
+The theme's own global CSS entry is the side-effect import block in [`theme/gatsby-browser.js`](../../theme/gatsby-browser.js):
+
+```javascript
+import './src/styles/global.css' // layout, .sr-only, Prism overrides
+import 'lightgallery/css/lightgallery.css'
+import 'lightgallery/css/lg-thumbnail.css'
+import 'lightgallery/css/lg-zoom.css'
+import 'prismjs/themes/prism-solarizedlight.css'
+import 'prismjs/plugins/line-numbers/prism-line-numbers.css'
+```
+
+[`theme/src/styles/global.css`](../../theme/src/styles/global.css) also contains `@import '@chronogrove/ui/color-toggle-styles'` for the theme toggle animation.
+
+Prism is **tightly coupled to `gatsby-remark-prismjs`** (configured in [`theme/gatsby-config.js`](../../theme/gatsby-config.js)). The CSS theme and helper overrides (`.gatsby-highlight`, line-number padding, etc.) only make sense when that plugin is active. They are intentionally kept in the Gatsby theme rather than in this package.
+
+Sites that shadow or extend the theme can add additional side-effect imports in their own `gatsby-browser.js` alongside (not instead of) the theme's entry.
+
+### Next.js (App Router)
+
+The reference app is [`examples/chronogrove-next`](../../examples/chronogrove-next). Its [`app/globals.css`](../../examples/chronogrove-next/app/globals.css) shows the minimal baseline:
+
+```css
+/* Required if you use ColorToggle */
+@import '@chronogrove/ui/color-toggle-styles';
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  background-color: var(--theme-ui-colors-background);
+  -webkit-font-smoothing: antialiased;
+}
+```
+
+Import `globals.css` once from the root `layout.jsx`/`layout.tsx` — the same file that renders `ChronogroveNextRootLayoutHead` and `ChronogroveNextEmotionRegistry`. See [`examples/chronogrove-next/app/layout.jsx`](../../examples/chronogrove-next/app/layout.jsx).
+
+For syntax highlighting in a Next MDX pipeline, use whatever highlighter fits your setup (e.g. [Shiki via rehype-pretty-code](https://rehype-pretty.pages.dev/)) and load only its CSS. There is no dependency on `prismjs` in this package, and you should not add the Prism CSS from the Gatsby theme to a Next app unless your MDX pipeline explicitly emits Prism class names.
+
+### Fonts
+
+The default Chronogrove theme uses **system font stacks** only (defined in [`src/theme.js`](./src/theme.js)):
+
+```js
+sans: '-apple-system, BlinkMacSystemFont, avenir next, ..., sans-serif'
+mono: 'Menlo, Consolas, ..., monospace'
+```
+
+No `@font-face` rules or external font URLs are shipped by this package. Web fonts are **host-owned**:
+
+- **Next.js:** use [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to load faces with zero layout shift; then pass the resulting CSS variable or family name into a theme override: `{ fonts: { body: 'var(--font-inter), sans-serif' } }`.
+- **Gatsby:** use [`gatsby-plugin-google-gtag`](https://www.gatsbyjs.com/plugins/gatsby-plugin-google-gtag/) or a `<link>` in `gatsby-ssr.js`, then extend `theme.fonts` in your `gatsby-config.js` theme options.
+
+Changing `theme.fonts` is the only hook needed; `ChronogroveThemeProvider` merges the override automatically via Theme UI.
+
+### Font Awesome (icons)
+
+`@chronogrove/ui` depends on `@fortawesome/fontawesome-svg-core` and `@fortawesome/react-fontawesome` for `WidgetHeader`. Icon **definitions** (e.g. `faGithub`) come from a kit you add to your own app — see the `WidgetHeader + icons` bullet in the [Next.js](#nextjs-app-router) section above.
+
 ## Changelog
 
 Releases are recorded in the repository root [`CHANGELOG.md`](../../CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronogrove/ui",
-  "version": "0.83.0",
+  "version": "0.83.2",
   "description": "Chronogrove Theme UI theme, color mode helpers, and shared UI primitives",
   "license": "MIT",
   "type": "module",
@@ -138,6 +138,18 @@
       "import": "./src/action-card-layout.js",
       "default": "./src/action-card-layout.js"
     },
+    "./article-column-container": {
+      "import": "./src/article-column-container.js",
+      "default": "./src/article-column-container.js"
+    },
+    "./home-dashboard-layout": {
+      "import": "./src/home-dashboard-layout.js",
+      "default": "./src/home-dashboard-layout.js"
+    },
+    "./page-shell-layout": {
+      "import": "./src/page-shell-layout.js",
+      "default": "./src/page-shell-layout.js"
+    },
     "./thumbnail-strip": {
       "import": "./src/thumbnail-strip.js",
       "default": "./src/thumbnail-strip.js"

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

@@ -115,8 +115,8 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
         "paddingLeft": "8px",
       },
       "&:hover, &:focus": {
-        "boxShadow": "lg",
-        "transform": "scale(1.015)",
+        "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)",
+        "transform": "translateY(-3px) scale(1.008)",
       },
       ".card-media": {
         "mb": 2,
@@ -145,7 +145,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       "height": "100%",
       "padding": 3,
       "textDecoration": "none",
-      "transition": "all 200ms ease-in-out",
+      "transition": "transform 200ms ease-in-out, box-shadow 200ms ease-in-out",
     },
     "StatusCardDark": {
       "backgroundColor": "#1e2530",
@@ -175,8 +175,8 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
     },
     "actionCard": {
       "&:hover, &:focus": {
-        "boxShadow": "lg",
-        "transform": "scale(1.015)",
+        "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)",
+        "transform": "translateY(-3px) scale(1.008)",
       },
       "WebkitBackdropFilter": "blur(10px)",
       "a": {
@@ -196,7 +196,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       ],
       "padding": 3,
       "textDecoration": "none",
-      "transition": "all 200ms ease-in-out",
+      "transition": "transform 200ms ease-in-out, box-shadow 200ms ease-in-out",
     },
     "aiSummary": {
       "@keyframes blink": {
@@ -356,7 +356,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       "backdropFilter": "blur(12px) saturate(150%)",
       "bg": "panel-background",
       "borderRadius": "card",
-      "boxShadow": "default",
+      "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 4px 12px rgba(66,46,163,0.08)",
       "color": "text",
       "flexGrow": 1,
       "fontSize": [
@@ -762,8 +762,8 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
     },
     "InstagramItem": {
       "&:hover, &:focus": {
-        "boxShadow": "lg",
-        "transform": "scale(1.015)",
+        "boxShadow": "0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)",
+        "transform": "translateY(-3px) scale(1.008)",
       },
       "background": "none",
       "border": "none",
@@ -772,7 +772,7 @@ exports[`Theme Configuration a snapshot of the configuration matches the snapsho
       "cursor": "pointer",
       "overflow": "hidden",
       "p": 0,
-      "transition": "all 200ms ease-in-out",
+      "transition": "transform 200ms ease-in-out, box-shadow 200ms ease-in-out",
     },
     "IntroExperienceSlide": {
       "&.active-slide": {

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

@@ -3,29 +3,34 @@
 exports[`WidgetHeader matches the snapshot 1`] = `
 <DocumentFragment>
   <header
-    class="css-7pzsne"
+    class="css-ubozo4"
   >
     <div
-      class="css-s076pz"
+      class="css-3vwaby"
     >
-      <h2
-        class="css-16f4ihe"
+      <div
+        aria-hidden="true"
+        class="css-1muvmnm"
       >
         <span
-          class="css-2s41mq"
-        >
-          <span
-            aria-hidden="true"
-            data-icon="spotify"
-            data-testid="fa-icon"
-          />
-        </span>
-        Neat & Interesting Widget
-      </h2>
+          aria-hidden="true"
+          data-icon="spotify"
+          data-testid="fa-icon"
+        />
+      </div>
       <div
-        class="sidebar-content"
+        class="css-m8374l"
       >
-        Sidebar
+        <h2
+          class="css-1tfs9qy"
+        >
+          Neat & Interesting Widget
+        </h2>
+        <div
+          class="sidebar-content"
+        >
+          Sidebar
+        </div>
       </div>
     </div>
   </header>

package/src/article-column-container.js

@@ -0,0 +1,23 @@
+import React from 'react'
+import { Container } from '@theme-ui/components'
+
+/**
+ * Primary text column width for MDX posts, blog index, and about-style pages.
+ * Keep in sync wherever the article measure must match (Gatsby post template, blog index, etc.).
+ */
+export const articleColumnContainerSx = {
+  position: 'relative',
+  width: ['', '', 'max(80ch, 50vw)'],
+  lineHeight: 1.7
+}
+
+/**
+ * Theme UI `Container` with {@link articleColumnContainerSx}. Pass `sx` to merge (e.g. `flexGrow: 1` on the blog index).
+ */
+export function ArticleColumnContainer({ children, sx = {}, ...rest }) {
+  return (
+    <Container sx={{ ...articleColumnContainerSx, ...sx }} {...rest}>
+      {children}
+    </Container>
+  )
+}

package/src/article-column-container.spec.js

@@ -0,0 +1,40 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import { ArticleColumnContainer, articleColumnContainerSx } from './article-column-container.js'
+
+describe('articleColumnContainerSx', () => {
+  it('defines the shared article measure', () => {
+    expect(articleColumnContainerSx).toMatchObject({
+      position: 'relative',
+      width: ['', '', 'max(80ch, 50vw)'],
+      lineHeight: 1.7
+    })
+  })
+})
+
+describe('ArticleColumnContainer', () => {
+  it('renders children with merged sx', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <ArticleColumnContainer sx={{ flexGrow: 1 }} data-testid='ac'>
+          <span>body</span>
+        </ArticleColumnContainer>
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByTestId('ac')).toContainElement(screen.getByText('body'))
+  })
+
+  it('renders with base article sx when sx is omitted', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <ArticleColumnContainer data-testid='ac-base'>
+          <span>only-base</span>
+        </ArticleColumnContainer>
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByTestId('ac-base')).toContainElement(screen.getByText('only-base'))
+  })
+})

package/src/color-utils.js

@@ -6,13 +6,38 @@
 /** Fallback RGB string when hex is invalid (blue) */
 const HEX_TO_RGB_FALLBACK = '74, 158, 255'
 
+/**
+ * Normalizes #rgb / #rgba shorthand, #rrggbb, or #rrggbbaa to #rrggbb for RGB extraction.
+ * Appending two hex digits to 3-digit theme colors (e.g. `#111` + `22`) is not valid CSS.
+ *
+ * @param {string} hex
+ * @returns {string|null} `#rrggbb` or null if not parseable as hex
+ */
+export const normalizeHexToRrggbb = hex => {
+  if (typeof hex !== 'string') return null
+  const raw = hex.trim().replace(/^#/, '')
+  if (!raw || !/^[a-f\d]+$/i.test(raw)) return null
+  if (raw.length === 3) {
+    return `#${[...raw].map(c => c + c).join('')}`
+  }
+  if (raw.length === 4) {
+    const [r, g, b] = raw
+    return `#${r}${r}${g}${g}${b}${b}`
+  }
+  if (raw.length === 6) return `#${raw}`
+  if (raw.length === 8) return `#${raw.slice(0, 6)}`
+  return null
+}
+
 /**
  * Converts hex color to RGB string for use in rgba()
- * @param {string} hex - Hex color code (with or without #)
+ * @param {string} hex - Hex color code (with or without #); 3- and 4-digit shorthand supported
  * @returns {string} RGB values as comma-separated string (e.g. "66, 46, 163")
  */
 export const hexToRgb = hex => {
-  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex)
+  const rrggbb = normalizeHexToRrggbb(hex)
+  if (!rrggbb) return HEX_TO_RGB_FALLBACK
+  const result = /^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(rrggbb)
   if (!result) return HEX_TO_RGB_FALLBACK
   return `${parseInt(result[1], 16)}, ${parseInt(result[2], 16)}, ${parseInt(result[3], 16)}`
 }

package/src/color-utils.spec.js

@@ -1,10 +1,39 @@
-import { hexToRgb, hexToRgba, BUTTON_PRIMARY_COLORS } from './color-utils'
+import { hexToRgb, hexToRgba, normalizeHexToRrggbb, BUTTON_PRIMARY_COLORS } from './color-utils'
+
+describe('normalizeHexToRrggbb', () => {
+  it('expands 3-digit shorthand', () => {
+    expect(normalizeHexToRrggbb('#111')).toBe('#111111')
+    expect(normalizeHexToRrggbb('#fff')).toBe('#ffffff')
+    expect(normalizeHexToRrggbb('abc')).toBe('#aabbcc')
+  })
+
+  it('expands 4-digit shorthand to RGB only', () => {
+    expect(normalizeHexToRrggbb('#f0f8')).toBe('#ff00ff')
+  })
+
+  it('passes through 6-digit and strips alpha from 8-digit', () => {
+    expect(normalizeHexToRrggbb('#112233')).toBe('#112233')
+    expect(normalizeHexToRrggbb('#11223344')).toBe('#112233')
+  })
+
+  it('returns null for invalid input', () => {
+    expect(normalizeHexToRrggbb('')).toBeNull()
+    expect(normalizeHexToRrggbb('not-hex')).toBeNull()
+    expect(normalizeHexToRrggbb('#12')).toBeNull()
+    expect(normalizeHexToRrggbb(null)).toBeNull()
+  })
+})
 
 describe('hexToRgb', () => {
   it('converts hex with hash to RGB', () => {
     expect(hexToRgb('#422EA3')).toBe('66, 46, 163')
   })
 
+  it('converts 3-digit shorthand (theme text colors)', () => {
+    expect(hexToRgb('#111')).toBe('17, 17, 17')
+    expect(hexToRgb('#fff')).toBe('255, 255, 255')
+  })
+
   it('converts hex without hash to RGB', () => {
     expect(hexToRgb('4a9eff')).toBe('74, 158, 255')
   })
@@ -23,6 +52,10 @@ describe('hexToRgba', () => {
     expect(hexToRgba('#422EA3', 0.5)).toBe('rgba(66, 46, 163, 0.5)')
   })
 
+  it('supports 3-digit shorthand with fractional alpha', () => {
+    expect(hexToRgba('#111', 34 / 255)).toBe('rgba(17, 17, 17, 0.13333333333333333)')
+  })
+
   it('accepts hex without hash', () => {
     expect(hexToRgba('4a9eff', 1)).toBe('rgba(74, 158, 255, 1)')
   })

package/src/home-dashboard-layout.js

@@ -0,0 +1,58 @@
+import React from 'react'
+import { Box, Grid } from '@theme-ui/components'
+
+/** Theme UI `Grid` `columns` for the home dashboard: single column until `md`, then sidebar + main. */
+export const homeDashboardGridColumns = [
+  null,
+  null,
+  'minmax(200px, 0.375fr) minmax(0, 1.625fr)',
+  'minmax(200px, 0.4fr) minmax(0, 1.6fr)'
+]
+
+export const homeDashboardGridGap = [null, 4]
+
+/** Default aside spacing; merge with site-specific `sx` (e.g. sticky side nav in demos). */
+export const homeDashboardAsideSx = {
+  mb: [4, null]
+}
+
+/** Rounded “glass” panel shell around the main home column (matches gatsby-theme-chronogrove home). */
+export const homeDashboardMainShellSx = {
+  position: 'relative',
+  borderTopRightRadius: '3em',
+  borderTopLeftRadius: '.5em',
+  px: [3, 4],
+  pt: [2, 3]
+}
+
+export const homeDashboardMainInnerMaxWidthSx = {
+  maxWidth: '1200px'
+}
+
+/** Outer stack below the page chrome on the home template (`minHeight`, top padding). */
+export const homeDashboardPageOuterSx = {
+  minHeight: '500px',
+  pt: 3,
+  px: 0
+}
+
+/**
+ * Two-column home dashboard grid (sidebar + main). Pass full `main` node so callers can set
+ * `role="main"`, skip-nav targets, footer, and microformats in one place.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.aside
+ * @param {React.ReactNode} props.main
+ * @param {import('theme-ui').ThemeUIStyleObject} [props.asideSx] merged after {@link homeDashboardAsideSx}
+ * @param {React.ComponentProps<typeof Grid>} [props.gridProps] forwarded to `Grid`
+ */
+export function HomeDashboardGrid({ aside, main, asideSx = {}, gridProps = {}, ...gridRest }) {
+  return (
+    <Grid columns={homeDashboardGridColumns} gap={homeDashboardGridGap} {...gridProps} {...gridRest}>
+      <Box as='aside' sx={{ ...homeDashboardAsideSx, ...asideSx }}>
+        {aside}
+      </Box>
+      {main}
+    </Grid>
+  )
+}

package/src/home-dashboard-layout.spec.js

@@ -0,0 +1,60 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import {
+  HomeDashboardGrid,
+  homeDashboardAsideSx,
+  homeDashboardGridColumns,
+  homeDashboardGridGap,
+  homeDashboardMainInnerMaxWidthSx,
+  homeDashboardMainShellSx,
+  homeDashboardPageOuterSx
+} from './home-dashboard-layout.js'
+
+describe('home dashboard layout tokens', () => {
+  it('exports grid columns and gap used by the Gatsby home template', () => {
+    expect(homeDashboardGridColumns[2]).toContain('minmax(200px')
+    expect(homeDashboardGridGap).toEqual([null, 4])
+    expect(homeDashboardAsideSx).toEqual({ mb: [4, null] })
+    expect(homeDashboardMainShellSx.borderTopRightRadius).toBe('3em')
+    expect(homeDashboardMainInnerMaxWidthSx.maxWidth).toBe('1200px')
+    expect(homeDashboardPageOuterSx.minHeight).toBe('500px')
+  })
+})
+
+describe('HomeDashboardGrid', () => {
+  it('renders aside and main slots', () => {
+    render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid aside={<span>nav</span>} main={<div data-testid='main'>content</div>} />
+      </ChronogroveThemeProvider>
+    )
+    expect(screen.getByText('nav')).toBeInTheDocument()
+    expect(screen.getByTestId('main')).toHaveTextContent('content')
+  })
+
+  it('merges asideSx onto the aside', () => {
+    const { container } = render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid aside={<span>a</span>} main={<span>b</span>} asideSx={{ position: 'sticky' }} />
+      </ChronogroveThemeProvider>
+    )
+    const aside = container.querySelector('aside')
+    expect(aside).toBeTruthy()
+  })
+
+  it('forwards gridProps to Grid', () => {
+    const { container } = render(
+      <ChronogroveThemeProvider theme={chronogroveTheme}>
+        <HomeDashboardGrid
+          aside={<span>l</span>}
+          main={<span>r</span>}
+          gridProps={{ 'data-testid': 'hdg', id: 'home-dash-grid' }}
+        />
+      </ChronogroveThemeProvider>
+    )
+    expect(container.querySelector('#home-dash-grid')).toBeTruthy()
+  })
+})

package/src/page-shell-layout.js

@@ -0,0 +1,57 @@
+import React from 'react'
+import { Box } from '@theme-ui/components'
+
+import { SkipNavContent, SkipNavLink } from './skip-nav/index.js'
+
+/**
+ * Default page chrome: skip link, optional header and footer slots, and a main landmark (unless disabled).
+ * Wire Gatsby-specific nav/footer and Zustand-driven `paddingBottom` from the site package.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children
+ * @param {boolean} [props.disableMainWrapper]
+ * @param {boolean} [props.hideHeader] when true, `header` is not rendered
+ * @param {boolean} [props.hideFooter] when true, `footer` is not rendered
+ * @param {boolean} [props.transparentBackground]
+ * @param {number|string} [props.paddingBottom] bottom padding (e.g. room for a fixed audio bar)
+ * @param {React.ReactNode} [props.header] placed inside `<header role="banner">` when not hidden
+ * @param {React.ReactNode} [props.footer]
+ */
+export function ChronogrovePageShell({
+  children,
+  disableMainWrapper = false,
+  hideHeader = false,
+  hideFooter = false,
+  transparentBackground = false,
+  paddingBottom = 0,
+  header = null,
+  footer = null
+}) {
+  return (
+    <Box
+      sx={{
+        backgroundColor: transparentBackground ? 'transparent' : 'background',
+        display: 'flex',
+        flexDirection: 'column',
+        flexGrow: 1,
+        color: theme => theme?.colors?.text,
+        pb: paddingBottom
+      }}
+    >
+      <SkipNavLink />
+
+      {!hideHeader && header ? <header role='banner'>{header}</header> : null}
+
+      {disableMainWrapper ? (
+        children
+      ) : (
+        <Box as='main' role='main'>
+          <SkipNavContent />
+          {children}
+        </Box>
+      )}
+
+      {!hideFooter && footer ? footer : null}
+    </Box>
+  )
+}

package/src/page-shell-layout.spec.js

@@ -0,0 +1,71 @@
+import React from 'react'
+import { render, screen } from '@testing-library/react'
+import { ChronogroveThemeProvider } from './provider.js'
+import chronogroveTheme from './theme.js'
+
+import { ChronogrovePageShell } from './page-shell-layout.js'
+
+function shellRender(ui) {
+  return render(<ChronogroveThemeProvider theme={chronogroveTheme}>{ui}</ChronogroveThemeProvider>)
+}
+
+describe('ChronogrovePageShell', () => {
+  it('renders skip link, header, main with skip target, children, and footer', () => {
+    shellRender(
+      <ChronogrovePageShell header={<span>hdr</span>} footer={<span>ftr</span>} paddingBottom='12px'>
+        <span>inner</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByText('inner')).toBeInTheDocument()
+    expect(screen.getByText('hdr')).toBeInTheDocument()
+    expect(screen.getByText('ftr')).toBeInTheDocument()
+    expect(document.querySelector('main[role="main"]')).toBeTruthy()
+  })
+
+  it('omits header when hideHeader', () => {
+    shellRender(
+      <ChronogrovePageShell hideHeader header={<span>no</span>} footer={null}>
+        <span>x</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.queryByText('no')).not.toBeInTheDocument()
+  })
+
+  it('omits footer when hideFooter', () => {
+    shellRender(
+      <ChronogrovePageShell hideFooter footer={<span>no</span>}>
+        <span>x</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.queryByText('no')).not.toBeInTheDocument()
+  })
+
+  it('renders children without main wrapper when disableMainWrapper', () => {
+    shellRender(
+      <ChronogrovePageShell disableMainWrapper>
+        <span data-testid='bare'>bare</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByTestId('bare')).toBeInTheDocument()
+    expect(document.querySelector('main[role="main"]')).toBeFalsy()
+  })
+
+  it('uses transparent background when requested', () => {
+    const { container } = shellRender(
+      <ChronogrovePageShell transparentBackground>
+        <span>t</span>
+      </ChronogrovePageShell>
+    )
+    expect(container.firstChild).toBeTruthy()
+  })
+
+  it('does not render a banner when header is null', () => {
+    shellRender(
+      <ChronogrovePageShell header={null}>
+        <span>no-banner</span>
+      </ChronogrovePageShell>
+    )
+    expect(screen.getByText('no-banner')).toBeInTheDocument()
+    expect(document.querySelector('header[role="banner"]')).toBeFalsy()
+  })
+})

package/src/theme.js

@@ -14,11 +14,12 @@ const fonts = {
 }
 
 export const floatOnHover = {
-  transition: 'all 200ms ease-in-out',
+  transition: 'transform 200ms ease-in-out, box-shadow 200ms ease-in-out',
 
   '&:hover, &:focus': {
-    transform: 'scale(1.015)',
-    boxShadow: 'lg'
+    transform: 'translateY(-3px) scale(1.008)',
+    boxShadow:
+      '0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 8px 20px rgba(66,46,163,0.14)'
   }
 }
 
@@ -81,7 +82,9 @@ export const card = {
   borderRadius: 'card',
   bg: 'panel-background',
   color: 'text',
-  boxShadow: 'default',
+  // Layered paper-stack shadow: each layer is a 1px offset slice, the final spread is the ambient
+  boxShadow:
+    '0 1px 0 rgba(0,0,0,0.06), 0 2px 0 rgba(0,0,0,0.04), 0 3px 0 rgba(0,0,0,0.03), 0 4px 12px rgba(66,46,163,0.08)',
   flexGrow: 1,
   padding: 3,
   fontSize: [1, 2],

package/src/widget-header.js

@@ -2,88 +2,177 @@ import React from 'react'
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
 import { Box, Heading } from '@theme-ui/components'
 
-import ProfileMetricsBadge from './profile-metrics-badge.js'
+import { hexToRgba, normalizeHexToRrggbb } from './color-utils.js'
 
-const baseHeaderStyles = {
-  display: 'flex',
-  flexDirection: ['column', 'row'],
-  alignItems: ['center', 'baseline'],
-  justifyContent: ['center', 'space-between'],
-  gap: [2, 3],
-  flexWrap: 'wrap',
-  pb: 2,
-  // Soft separator: visible but not harsh (gray[4] in theme scale; fallback ~12% black)
-  borderBottom: '1px solid',
-  borderColor: theme => theme?.colors?.gray?.[4] ?? 'rgba(0,0,0,0.12)'
-}
-
-/**
- * Groups headline + CTA so they sit together on the left; metrics stay on the right.
- * Always row so headline + CTA stay on one line at every breakpoint (including mobile).
- */
-const titleGroupStyles = {
-  display: 'flex',
-  flexDirection: 'row',
-  alignItems: 'baseline',
-  gap: [1, 2],
-  order: 1
-}
+/** Alpha matching prior intent of appending `22` to 8-digit #RRGGBBAA (34/255) */
+const METRIC_CHIP_BORDER_ALPHA = 34 / 255
 
 /**
- * Override default heading margin, padding, and line-height so the headline and CTA
- * align on the same baseline at every breakpoint. Theme/global styles often add
- * vertical space to h2; zeroing it and using a tight line-height prevents offset.
- * Baseline alignment for icon + text keeps the headline baseline consistent.
+ * WidgetHeader
+ *
+ * Social-dashboard section headline: a large clean heading paired with square
+ * data-chip metrics. No horizontal rules — section identity comes from the
+ * colored icon chip and typographic weight alone.
+ *
+ * Layout:
+ *   [icon chip] [Heading]  [CTA aside]          [metrics chips →]
+ *
+ * The icon chip is a small square badge (accent bg, white icon) that reads like
+ * a label on a physical card index tab. Metrics are monospaced square chips:
+ * number + unit in a bordered box, no rounded pills.
  */
-const headingStyles = {
-  fontSize: [4, 5],
-  display: 'flex',
-  alignItems: 'baseline',
-  m: 0,
-  py: 0,
-  pt: 0,
-  pb: 0,
-  lineHeight: 1
-}
-
-const metricsStyles = {
-  order: 2
-}
-
 const WidgetHeader = ({ aside, children, icon, metrics, metricsLoading }) => {
   const hasMetrics = (Array.isArray(metrics) && metrics.length > 0) || metricsLoading
+
+  // Placeholder chips while loading
+  const metricsToShow = metricsLoading ? [{}, {}] : Array.isArray(metrics) ? metrics : []
+
   return (
     <Box
       as='header'
       sx={{
-        ...baseHeaderStyles,
-        // Extra margin below header when metrics are present so spacing matches Latest Posts (no metrics)
+        display: 'flex',
+        flexDirection: ['column', 'row'],
+        alignItems: ['flex-start', 'center'],
+        justifyContent: ['flex-start', 'space-between'],
+        gap: [2, 3],
+        flexWrap: 'wrap',
+        pb: 3,
         mb: hasMetrics ? 4 : 2
       }}
     >
-      <Box sx={titleGroupStyles}>
-        <Heading as='h2' sx={headingStyles}>
-          {icon && (
+      {/* Left cluster: icon chip (center-aligned) + heading/CTA sub-row (baseline-aligned) */}
+      <Box
+        sx={{
+          display: 'flex',
+          flexDirection: 'row',
+          alignItems: 'center',
+          gap: 2,
+          order: 1,
+          minWidth: 0
+        }}
+      >
+        {/* Colored square icon chip — center-aligned with the heading block */}
+        {icon && (
+          <Box
+            aria-hidden='true'
+            sx={{
+              flexShrink: 0,
+              width: '32px',
+              height: '32px',
+              borderRadius: '6px',
+              backgroundColor: 'primary',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              boxShadow: theme =>
+                `inset 0 -2px 0 rgba(0,0,0,0.2), 0 1px 3px rgba(${theme.colors?.primaryRgb ?? '66,46,163'},0.3)`
+            }}
+          >
+            <FontAwesomeIcon icon={icon} style={{ width: 14, height: 14, color: '#fff' }} />
+          </Box>
+        )}
+
+        {/* Heading + CTA aside: baseline-aligned with each other, same as original */}
+        <Box
+          sx={{
+            display: 'flex',
+            flexDirection: 'row',
+            alignItems: 'baseline',
+            gap: [1, 2],
+            minWidth: 0
+          }}
+        >
+          <Heading
+            as='h2'
+            sx={{
+              fontSize: [4, 5],
+              fontFamily: 'heading',
+              fontWeight: 'bold',
+              lineHeight: 1,
+              m: 0,
+              p: 0,
+              textShadow: '0 1px 0 rgba(255,255,255,0.5), 0 -1px 0 rgba(0,0,0,0.07)',
+              letterSpacing: '-0.01em'
+            }}
+          >
+            {children}
+          </Heading>
+
+          {aside}
+        </Box>
+      </Box>
+
+      {/* Right cluster: square metric chips */}
+      {hasMetrics && (
+        <Box
+          sx={{
+            display: 'flex',
+            flexDirection: 'row',
+            gap: '6px',
+            alignItems: 'center',
+            order: 2,
+            flexShrink: 0
+          }}
+        >
+          {metricsToShow.map(({ displayName, id, value } = {}, idx) => (
             <Box
-              as='span'
+              key={id || idx}
               sx={{
                 display: 'inline-flex',
-                alignItems: 'baseline',
-                mr: 2,
-                fontSize: 4,
-                '& svg': { width: '1em', height: '1em' }
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                minWidth: '52px',
+                px: '6px',
+                py: '4px',
+                borderRadius: '4px',
+                border: '1px solid',
+                // Text-based border: theme `text` is often 3-digit hex (#111 / #fff); appending
+                // `22` for alpha is invalid CSS — use rgba() from expanded hex instead.
+                borderColor: theme => {
+                  const text = theme?.colors?.text ?? '#111'
+                  const base = normalizeHexToRrggbb(text)
+                  return base ? hexToRgba(base, METRIC_CHIP_BORDER_ALPHA) : 'rgba(17, 17, 17, 0.133)'
+                },
+                // panel-background is defined for both light + dark in chronogrove-theme-surface-colors
+                backgroundColor: 'panel-background',
+                ...(metricsLoading
+                  ? {
+                      animation: 'cgPulse 1.4s ease-in-out infinite',
+                      opacity: 0.5
+                    }
+                  : {})
               }}
             >
-              <FontAwesomeIcon icon={icon} aria-hidden='true' />
+              <Box
+                sx={{
+                  fontFamily: 'monospace',
+                  fontSize: '0.8rem',
+                  fontWeight: 'bold',
+                  lineHeight: 1.1,
+                  color: 'primary',
+                  letterSpacing: '-0.02em'
+                }}
+              >
+                {value ?? '—'}
+              </Box>
+              <Box
+                sx={{
+                  fontFamily: 'heading',
+                  fontSize: '0.6rem',
+                  fontWeight: 'normal',
+                  lineHeight: 1.2,
+                  color: 'textMuted',
+                  textTransform: 'uppercase',
+                  letterSpacing: '0.06em',
+                  whiteSpace: 'nowrap'
+                }}
+              >
+                {displayName ?? ''}
+              </Box>
             </Box>
-          )}
-          {children}
-        </Heading>
-        {aside}
-      </Box>
-      {((Array.isArray(metrics) && metrics.length > 0) || metricsLoading) && (
-        <Box sx={metricsStyles}>
-          <ProfileMetricsBadge compact isLoading={metricsLoading} metrics={metrics} />
+          ))}
         </Box>
       )}
     </Box>

package/src/widget-header.spec.js

@@ -29,22 +29,25 @@ describe('WidgetHeader', () => {
     const metrics = [{ displayName: 'Stars', id: 's', value: 12 }]
     const { getByText } = render(
       <ThemeUIProvider theme={chronogroveTheme}>
-        <WidgetHeader metrics={metrics}>Title</WidgetHeader>
+        <WidgetHeader icon={mockIcon} metrics={metrics}>
+          Title
+        </WidgetHeader>
       </ThemeUIProvider>
     )
-    expect(getByText('12 Stars')).toBeInTheDocument()
+    expect(getByText('12')).toBeInTheDocument()
+    expect(getByText('Stars')).toBeInTheDocument()
   })
 
   it('renders loading metrics placeholders when metricsLoading', () => {
-    const { container } = render(
+    render(
       <ThemeUIProvider theme={chronogroveTheme}>
-        <WidgetHeader metrics={[]} metricsLoading>
+        <WidgetHeader icon={mockIcon} metrics={[]} metricsLoading>
           Title
         </WidgetHeader>
       </ThemeUIProvider>
     )
-    const badges = container.querySelectorAll('[class*="css-"]')
-    expect(badges.length).toBeGreaterThan(0)
+    const placeholders = screen.getAllByText('—')
+    expect(placeholders).toHaveLength(2)
   })
 
   it('renders without icon', () => {
@@ -57,20 +60,73 @@ describe('WidgetHeader', () => {
     expect(screen.queryByTestId('fa-icon')).not.toBeInTheDocument()
   })
 
-  it('uses borderColor fallback when gray[4] is missing', () => {
-    const themeMissingGray4 = {
+  it('renders metric chips when theme omits gray scale entries', () => {
+    const themeMissingGray = {
       ...chronogroveTheme,
       colors: {
         ...chronogroveTheme.colors,
-        gray: { 0: '#111', 1: '#222', 2: '#333', 3: '#444' }
+        gray: undefined
       }
     }
-    const { container } = render(
-      <ThemeUIProvider theme={themeMissingGray4}>
-        <WidgetHeader>Border test</WidgetHeader>
+    render(
+      <ThemeUIProvider theme={themeMissingGray}>
+        <WidgetHeader icon={mockIcon} metrics={[{ displayName: 'X', id: 'x', value: 1 }]}>
+          Border test
+        </WidgetHeader>
       </ThemeUIProvider>
     )
-    expect(container.querySelector('header')).toBeTruthy()
     expect(screen.getByText('Border test')).toBeInTheDocument()
+    expect(screen.getByText('1')).toBeInTheDocument()
+    expect(screen.getByText('X')).toBeInTheDocument()
+  })
+
+  it('renders icon chip when theme omits primaryRgb (shadow fallback)', () => {
+    const colorsRest = { ...chronogroveTheme.colors }
+    delete colorsRest.primaryRgb
+    const themeNoPrimaryRgb = { ...chronogroveTheme, colors: colorsRest }
+    render(
+      <ThemeUIProvider theme={themeNoPrimaryRgb}>
+        <WidgetHeader icon={mockIcon}>Chip</WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('Chip')).toBeInTheDocument()
+    expect(screen.getByTestId('fa-icon')).toBeInTheDocument()
+  })
+
+  it('renders metric chip border when theme omits colors.text (fallback)', () => {
+    const colorsRest = { ...chronogroveTheme.colors }
+    delete colorsRest.text
+    const themeNoText = { ...chronogroveTheme, colors: colorsRest }
+    render(
+      <ThemeUIProvider theme={themeNoText}>
+        <WidgetHeader icon={mockIcon} metrics={[{ displayName: 'Y', id: 'y', value: 2 }]}>
+          T
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('2')).toBeInTheDocument()
+    expect(screen.getByText('Y')).toBeInTheDocument()
+  })
+
+  it('handles metrics array with undefined entry (default destructuring)', () => {
+    render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader icon={mockIcon} metrics={[undefined]}>
+          T
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('—')).toBeInTheDocument()
+  })
+
+  it('uses metricsToShow empty array when metrics is not an array', () => {
+    render(
+      <ThemeUIProvider theme={chronogroveTheme}>
+        <WidgetHeader icon={mockIcon} metrics={null}>
+          No metrics prop array
+        </WidgetHeader>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('No metrics prop array')).toBeInTheDocument()
   })
 })

package/src/widget-section.js

@@ -13,7 +13,7 @@ const sectionSx = {
 /**
  * Wraps a dashboard widget: vertical spacing and optional fatal-error overlay.
  */
-const WidgetSection = ({ children, hasFatalError, id, styleOverrides = {}, ...props }) => {
+const WidgetSection = ({ children, hasFatalError, id, styleOverrides = {}, tabIndex, ...props }) => {
   const { colorMode } = useThemeUI()
   const darkMode = isDarkMode(colorMode)
 
@@ -30,6 +30,7 @@ const WidgetSection = ({ children, hasFatalError, id, styleOverrides = {}, ...pr
           : {})
       }}
       {...(id ? { id } : {})}
+      tabIndex={id ? (tabIndex ?? -1) : tabIndex}
       {...props}
     >
       {hasFatalError && (

package/src/widget-section.spec.js

@@ -36,6 +36,38 @@ describe('WidgetSection', () => {
     expect(document.getElementById('w1')).toBeTruthy()
   })
 
+  it('sets tabIndex -1 when id is provided so the section can receive programmatic focus', () => {
+    useThemeUI.mockReturnValue({ colorMode: 'default' })
+    render(
+      <ThemeUIProvider theme={{}}>
+        <WidgetSection id='w1'>x</WidgetSection>
+      </ThemeUIProvider>
+    )
+    expect(document.getElementById('w1')).toHaveAttribute('tabindex', '-1')
+  })
+
+  it('respects an explicit tabIndex when id is provided', () => {
+    useThemeUI.mockReturnValue({ colorMode: 'default' })
+    render(
+      <ThemeUIProvider theme={{}}>
+        <WidgetSection id='w1' tabIndex={0}>
+          x
+        </WidgetSection>
+      </ThemeUIProvider>
+    )
+    expect(document.getElementById('w1')).toHaveAttribute('tabindex', '0')
+  })
+
+  it('does not set tabIndex when id is omitted', () => {
+    useThemeUI.mockReturnValue({ colorMode: 'default' })
+    render(
+      <ThemeUIProvider theme={{}}>
+        <WidgetSection>plain</WidgetSection>
+      </ThemeUIProvider>
+    )
+    expect(screen.getByText('plain').closest('section')).not.toHaveAttribute('tabindex')
+  })
+
   it('shows fatal error overlay', () => {
     useThemeUI.mockReturnValue({ colorMode: 'dark' })
     render(