Skip to main content

Consumer cookbook

mattriley.tools migration cookbook

This page documents the shared-component handoff for mattriley.tools, the first proving Snurble consumer. Use it as the durable pattern guide for adopting the shared surface while keeping consumer-owned behavior intact.

Migration boundary

Durable package contract
Snurble package-contract changes and this cookbook page can ship independently of any one consumer rollout branch.
Local-only validation proof
A `mattriley.tools` migration branch can use packed tarballs or file refs to prove the shared surface works, but those dependency refs and any related lockfile churn do not get committed.
Registry adoption checkpoint
The committed consumer manifest switch waits for published prerelease package versions, then reruns the full consumer validation surface against those registry installs.

Component mapping

The migration replaces repeated layout, shell, and presentation patterns while keeping generated data, README rendering, and the consumer's document-shell obligations local. The current shared surface was shaped by mattriley.tools adoption and now also includes the profile, social, project, and experience primitives documented elsewhere in this site. This cookbook stays focused on the mattriley.tools shell, catalog, and detail-page integration seams that still need consumer-specific handling during adoption.

Local structure Snurble replacement Notes
src/layouts/Layout.astro + page-level <main> Layout + local wrapper Compose Snurble Layout under a consumer-owned wrapper so title suffixes, favicons, head tags, app CSS, and <main> semantics stay local.
Homepage hero + section wrappers Hero + Section + PageShell + Stack Keep the two catalog sections, their copy, and their independent sync timestamps while moving repeated shell and spacing structure into shared primitives.
Hand-written catalog tables DataTable Preserve the tool table's four columns and the plugin table's three-column contract; keep the generated data source untouched.
Detail-page panels and grouped copy Panel + Stack + Section Use shared surface and spacing primitives, but keep README rendering and route data flow in mattriley.tools.
Metadata dl + install command MetaList + CodeSnippet Tool detail pages can move install content into shared snippet styling; plugin pages keep metadata + README only and still do not grow an install section.
global.css rules Selective handoff Only shared shell/table/panel/meta/install chrome moves to Snurble; eyebrow rules, README markdown styling, and other site-specific CSS stay local for now.

Wrapper layout pattern

Keep the consumer shell honest

Shared Layout should own token import and document scaffolding, but mattriley.tools still needs a tiny local wrapper for title suffixes, favicons, remaining global CSS, and page-owned <main>.

That wrapper is also the right place to preserve any head tags or app-level metadata that Snurble intentionally does not generalize yet.

Example wrapper 

---
import { Layout } from "@matt-riley/ui-astro";
import "../styles/global.css";

interface Props {
  title: string;
  description?: string;
}

const { title, description } = Astro.props;
const pageTitle = title === "mattriley.tools" ? title : `${title} | mattriley.tools`;
---

<Layout title={pageTitle} description={description}>
  <link slot="head" rel="icon" type="image/svg+xml" href="/favicon.svg" />
  <link slot="head" rel="icon" href="/favicon.ico" />
  <main>
    <slot />
  </main>
</Layout>

CSS carve-out

Moves to shared components

  • page shell width and padding
  • hero spacing and typography
  • panel chrome and grouped spacing
  • catalog table chrome and code-snippet treatment
  • metadata list spacing and typography

Stays local for now

  • README markdown styling and image/table glue
  • eyebrow or source-of-truth copy styling that Snurble does not own
  • favicon and site-specific head affordances
  • any route-specific tweaks tied to generated content semantics

Local validation loop

The migration is only honest once both Snurble packages can be packed together, installed into a clean non-workspace consumer checkout, and validated end to end. Keep this smoke loop local until published prerelease versions are ready for committed consumer adoption. 

SMOKE_DIR=$(pwd)/artifacts/mattriley-tools-smoke
mkdir -p "$SMOKE_DIR"
pnpm --dir packages/tokens pack --pack-destination "$SMOKE_DIR"
pnpm --dir packages/ui-astro pack --pack-destination "$SMOKE_DIR"

# from the Snurble repo root, then switch into ../mattriley.tools
cd ../mattriley.tools
pnpm add "$SMOKE_DIR"/matt-riley-design-tokens-*.tgz   "$SMOKE_DIR"/matt-riley-ui-astro-*.tgz
pnpm run lint && pnpm test && pnpm run build

# do not commit any file refs or lockfile changes created for this loop