Take the colour layer from pmndrs/design-system, distribute Keypoints, compute the palette on the server

.changeset/keypoints-block.md

@@ -0,0 +1,9 @@
+---
+'@pmndrs/docs': minor
+---
+
+`Keypoints` is now a shadcn registry block, installable into any app with `npx shadcn@latest add pmndrs/docs/keypoints`. It is the first pmndrs block to be distributed this way, and the first to depend on the shared colour layer across registries — `pmndrs/design-system/md3`, for the one MD3 role it uses that shadcn has no equivalent for.
+
+Being distributable is what drove the three changes to it. It reached into this app's MDX component map for the list wrappers, so those are inlined; it imported `cn` through a path `components.json` does not alias, so the whole app is standardized on `@/lib/utils` and the duplicate `src/lib/cn.ts` is gone; and it painted its border with `border-outline-variant`, which is `border-border` by another name, so it now uses the stock token and keeps `bg-surface-dim` as the single deliberate MD3 reach.
+
+Nothing changes for authors: the same `<Keypoints>` / `<KeypointsItem>` in the same MDX, rendering the same. The source moved from `src/components/mdx/Keypoints/` to `registry/keypoints/`, alongside `registry.json` at the root.

.changeset/md3-rsc.md

@@ -0,0 +1,7 @@
+---
+'@pmndrs/docs': patch
+---
+
+The Material Design 3 palette is now computed on the server instead of in every visitor's browser. `<Mtb>` carries `'use client'`, so the colour package's palette code shipped to the client and recomputed the same values on each load. The root layout calls `builder` — the package's root export, which has no `'use client'` — and emits the CSS itself. Same rendered result, no palette code on the client. The seed is still `THEME_PRIMARY` / `THEME_SCHEME` / `THEME_CONTRAST`.
+
+Takes `pmndrs/design-system/md3-base` v0.3.0 — the shared colour layer without its baked palette, since this site supplies its own. Storybook gets that palette from an `<Mtb>` decorator, which fixes something invisible until now — the preview imports the stylesheet and rendered nothing else, so `--md-sys-color-*` was undefined there, and since the shadcn remap points the stock variables at MD3 roles, every story has been rendering colourless. Stories are worth looking at again.

.changeset/md3-tier1.md

@@ -0,0 +1,9 @@
+---
+'@pmndrs/docs': minor
+---
+
+Take the Material Design 3 colour layer from `pmndrs/design-system` instead of maintaining it here. The hand-written `@theme` mapping and the shadcn remap — around 105 lines that had to be kept in step with the colour package by hand — are replaced by one registry item, `pmndrs/design-system/md3`, which brings its own Tailwind mapping and the config it maps. `react-mcu` gives way to `material-theme-builder`, so the CSS variables are now `--md-sys-color-*`; every `bg-surface` / `text-on-surface-variant` utility keeps working untouched, because the `--color-*` names on top of them are identical.
+
+The seed moves to the poimandres slate (`#323e48`) — this is the visible change — and it now lives in exactly one place, the installed `src/lib/md3.ts`, rather than being restated in the layout and in two workflows. `THEME_PRIMARY`, `THEME_SCHEME` and `THEME_CONTRAST` still override it per deployment; a site that wants its own seed sets the workflow input, and one that doesn't inherits the pmndrs default.
+
+The five alert colours stay here, in `src/lib/mtb.ts`, which spreads the pmndrs seed and adds them. They are GitHub's palette and only this generator renders markdown alerts, so they are not the design system's to carry — but they are still harmonized against the seed, and `THEME_NOTE`, `THEME_TIP`, `THEME_IMPORTANT`, `THEME_WARNING` and `THEME_CAUTION` still work.

.github/workflows/build.yml

@@ -34,30 +34,33 @@ on:
         type: string
       discord:
         type: string
+      # Left empty on purpose: the pmndrs defaults live in src/lib/md3.ts, installed
+      # from pmndrs/design-system. Set one of these only to override the seed for a
+      # site — an empty value falls through to the shared default.
       theme_primary:
         type: string
-        default: '#323e48'
+        default: ''
       theme_scheme:
         type: string
-        default: 'tonalSpot'
+        default: ''
       theme_contrast:
         type: string
-        default: '0'
+        default: ''
       theme_note:
         type: string
-        default: '#1f6feb'
+        default: ''
       theme_tip:
         type: string
-        default: '#238636'
+        default: ''
       theme_important:
         type: string
-        default: '#8957e5'
+        default: ''
       theme_warning:
         type: string
-        default: '#d29922'
+        default: ''
       theme_caution:
         type: string
-        default: '#da3633'
+        default: ''
       docker_tag:
         type: string
         default: '3'

.github/workflows/ci.yml

@@ -114,14 +114,6 @@ jobs:
             --build-env LOGO=gutenberg.jpg \
             --build-env GITHUB="https://github.com/${{ github.repository }}" \
             --build-env DISCORD="${{ secrets.DISCORD }}" \
-            --build-env THEME_PRIMARY="#323e48" \
-            --build-env THEME_SCHEME="tonalSpot" \
-            --build-env THEME_CONTRAST="0" \
-            --build-env THEME_NOTE="#1f6feb" \
-            --build-env THEME_TIP="#238636" \
-            --build-env THEME_IMPORTANT="#8957e5" \
-            --build-env THEME_WARNING="#d29922" \
-            --build-env THEME_CAUTION="#da3633" \
             --build-env CONTRIBUTORS_PAT="${{ secrets.GITHUB_TOKEN }}" \
             > deployment-url.txt
 

.storybook/main.ts

@@ -1,7 +1,11 @@
 import type { StorybookConfig } from '@storybook/nextjs-vite'
 
 const config: StorybookConfig = {
-  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)', '../src/**/*.mdx'],
+  stories: [
+    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+    '../src/**/*.mdx',
+    '../registry/**/*.stories.@(js|jsx|mjs|ts|tsx)',
+  ],
   addons: ['@storybook/addon-docs', '@storybook/addon-themes'],
   framework: '@storybook/nextjs-vite',
   staticDirs: ['../public'],

.storybook/preview.tsx

@@ -1,5 +1,7 @@
+import { docsMtb } from '@/lib/mtb'
 import type { Preview } from '@storybook/nextjs-vite'
 import { withThemeByClassName } from '@storybook/addon-themes'
+import { Mtb } from 'material-theme-builder/react'
 
 import './preview.css'
 import '../src/app/globals.css'
@@ -15,6 +17,19 @@ const preview: Preview = {
   },
   tags: ['autodocs'],
   decorators: [
+    // The app defines `--md-sys-color-*` from its root layout, which Storybook
+    // never renders — so without this, every story runs against an undefined
+    // palette. And since the shadcn remap points the stock variables at MD3
+    // roles, that takes `--background` and `--primary` down with it: components
+    // render colourless, silently, and Chromatic baselines them that way.
+    //
+    // `<Mtb>` is the client component the app deliberately avoids. Here it is
+    // the right tool: Storybook is a browser, and there is no build to hook.
+    (Story) => (
+      <Mtb {...docsMtb}>
+        <Story />
+      </Mtb>
+    ),
     withThemeByClassName({
       themes: {
         light: 'light',

components.json

@@ -18,5 +18,8 @@
     "lib": "@/lib",
     "hooks": "@/hooks"
   },
+  "rtl": false,
+  "menuColor": "default",
+  "menuAccent": "subtle",
   "registries": {}
 }

package.json

@@ -39,6 +39,7 @@
     "prettier-plugin-tailwindcss": "^0.7.2",
     "rehype-parse": "^9.0.1",
     "rehype-stringify": "^10.0.1",
+    "shadcn": "^4.18.0",
     "storybook": "^10.2.0",
     "tailwindcss": "^4.1.18",
     "tailwindcss-animate": "^1.0.7",
@@ -67,6 +68,7 @@
     "lodash-es": "^4.17.21",
     "lucide-react": "^0.563.0",
     "match-sorter": "^6.3.4",
+    "material-theme-builder": "^3.2.0",
     "mcp-handler": "^1.0.7",
     "mermaid": "^11.12.2",
     "next": "^16.1.3",
@@ -75,7 +77,6 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-icons": "^5.5.0",
-    "react-mcu": "^1.1.0",
     "rehype-github-alerts": "^3.0.0",
     "rehype-prism-plus": "^2.0.0",
     "remark-gfm": "^4.0.1",
@@ -89,8 +90,9 @@
     "dev": "NODE_OPTIONS='--inspect' next",
     "start": "next start",
     "build": "./next-build.sh",
-    "format": "prettier -w src/",
-    "lint": "eslint src/**/*.{ts,tsx} && prettier . --check",
+    "format": "prettier -w src/ registry/",
+    "lint": "eslint src/**/*.{ts,tsx} registry/ && prettier . --check",
+    "check-registry": "shadcn registry validate ./registry.json",
     "prepare": "husky && (test -f scripts/copy-fonts.sh && sh scripts/copy-fonts.sh || true)",
     "release": "changeset publish",
     "changeset": "changeset",