47 checks · run it on any site

The boring bits, and whether this site has actually had them done.

Not a build sequence — a list to run against a site. A new one before it ships, or one you've just inherited and need to know the state of. Name the site, work down it, come back in a fortnight and the ticks are still there. The parts it keeps referring to live in the Workbench.

Site

0/47

Foundations

What everything else sits on. Cheap to get right at the start, expensive to change once there are thirty routes.

Decide static export vs server rendering before writing routes.
`output: "export"` bans route handlers, ISR, middleware and image optimisation. Every personal site of mine is static — pick it deliberately, not by accident when the first deploy fails.
Seen innext.config.ts
hosting-shape
```
// next.config.ts
const nextConfig: NextConfig = {
  output: "export",
  images: { unoptimized: true }, // required — no optimiser in a static export
  trailingSlash: true,
  turbopack: { root: import.meta.dirname }, // pin: stray lockfiles higher up confuse it
};
```
Content in one typed file, or a CMS — never inline in components.
One `src/content/site.ts` means copy edits never touch JSX and the OG images, sitemap and JSON-LD all read from the same source of truth. Reach for Sanity only when someone other than me needs to edit it.
Seen insrc/content/site.ts/uses/ — rendered entirely from it
If a CMS resolves at build, bust the cache on every build.
The failure is silent and looks like the CMS is broken: you publish, the build goes green, the post isn't there. The host restores `.next/cache` between builds and the query hasn't changed, so Next re-serves the previous snapshot. `no-store` isn't the escape hatch — it forces dynamic rendering, which `output: "export"` rejects. A per-build nonce in an unused param changes the cache key instead. Don't key it on the commit SHA: a content-only webhook rebuild runs on the same commit.
Seen insrc/lib/blog.ts
cms-build-cache
```
// src/lib/blog.ts — cacheBust is never read by the GROQ query, only by the cache
const BUILD_NONCE = String(Date.now());

function fetchFresh<T>(query: string, params = {}): Promise<T> {
  return client.fetch<T>(query, { ...params, cacheBust: BUILD_NONCE });
}
```
Define the token block before the first component.
bg / bg-elevated / surface / border / border-strong / fg / muted / faint / accent / accent-2. Same ten names on every project, only the hexes change — so a component lifted from one site works in the next.
Seen inWorkbench — tokens Brand book — colour
Check the platform first: CSS over JS, `<details>` over an accordion lib, `<dialog>` over a modal lib, view transitions over a router animation.
Each dependency is a future upgrade, a bundle cost and a supply-chain surface.
Seen inWorkbench — Dialog, the native one
Set `<html lang>` correctly (`en-GB`, not `en`).
Screen-reader pronunciation and hyphenation. One attribute, always wrong by default.
Seen insrc/app/layout.tsx

Components & interaction

The states people forget. Check them on the built thing, not the design — that's where they go missing.

Every interactive element gets: default, hover, active, focus-visible, disabled — and loading if it does async work.
The Workbench renders the full matrix live. `:focus-visible` is the one that fails audits; `:active` is the one that makes a site feel real on mobile.
Seen inWorkbench — Button, States tab
Use `:focus-visible`, never `outline: none`.
`:focus` rings on mouse clicks look broken so people delete them entirely, which strands keyboard users. `:focus-visible` gives you both.
Seen inWorkbench — Buttonsrc/styles/kit.css
focus-visible
```
.btn:focus-visible {
  outline: 2px solid var(--color-accent);
  outline-offset: 2px;
}
```
44×44px minimum tap target, and check it on a real phone.
Icon buttons pass desktop review and fail in a coat pocket.
Loading states must not resize the element.
Swap the label for a spinner with the label's width held, or you get a layout jump on every submit.
Seen inWorkbench — Button, loading

One `@media (prefers-reduced-motion: reduce)` block that kills all of it.

Cheaper as a global sledgehammer than as per-component care.

Seen insrc/app/globals.cssBrand book — motion

reduced-motion

@media (prefers-reduced-motion: reduce) {
  html { scroll-behavior: auto; }
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Design the empty, error and one-item states, not just the happy list of six.
The demo data is always three-to-six perfect items. Production is zero or four hundred.
Seen inWorkbench — Empty state
Real `<label for>`, `aria-invalid` on bad fields, error text tied by `aria-describedby`.
Placeholder-as-label is invisible once typing starts and unreadable to assistive tech.
Seen inWorkbench — Field

SEO & metadata

Twenty minutes of work that decides whether any of it gets found. Usually the part an inherited site is missing entirely.

Set `metadataBase` + a title template in the root layout.

Without `metadataBase` every OG/Twitter image URL ships relative and no crawler resolves it.

Seen insrc/app/layout.tsx

metadata-base

export const metadata: Metadata = {
  metadataBase: new URL(site.url),
  title: { default: `${site.name} — ${site.role}`, template: `%s — ${site.name}` },
  description,
  alternates: { canonical: site.url, types: { "application/rss+xml": "/feed.xml" } },
  robots: { index: true, follow: true },
};

Unique title + description per route. No inherited defaults.
Duplicate descriptions across a site is the single most common Search Console complaint.
Seen insrc/lib/seo.ts
1200×630 OG image for every shareable page.
Generate them with `next/og` from the same content file — Assets & meta has the template. A site-wide fallback `og.png` for everything else.
Seen inAssets & meta — the templatesrc/lib/og.tsx

`sitemap.ts` and `robots.ts`, both generated from the routes list.

Hand-maintained sitemaps go stale the first time you add a page.

Seen insrc/app/sitemap.tssrc/app/robots.ts

sitemap-robots

// src/app/sitemap.ts
import type { MetadataRoute } from "next";
import { site, projects } from "@/content/site";

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    { url: `${site.url}/`, lastModified: lastEdited("src/app/page.tsx") },
    ...projects.filter(p => p.deepDive).map(p => ({ url: `${site.url}${p.deepDive}/` })),
  ];
}

`lastmod` only. Google ignores `changefreq` and `priority` outright.
Both have been ignored for years — priority especially, because everyone set every page to 1. `lastmod` is the one hint that's still read, so derive it from the last commit touching the route rather than typing dates by hand. If you can't work out a real date, ship no `lastmod` at all: an implausible one gets the whole file distrusted.
Seen insrc/app/sitemap.ts
sitemap-lastmod
```
function lastEdited(...paths: string[]): Date | undefined {
  try {
    const iso = execFileSync("git", ["log", "-1", "--format=%cI", "--", ...paths],
      { encoding: "utf8" }).trim();
    return iso ? new Date(iso) : undefined;
  } catch {
    return undefined; // shallow clone or no git — omit rather than invent
  }
}
```
A page you don't want indexed needs `noindex` **and** a robots `Disallow`.
They do different jobs and neither covers the other. `Disallow` alone doesn't remove anything from the index — Google will happily list a URL it was never allowed to crawl, titled from whatever links to it. `noindex` alone works, but only once the crawler has spent the visit. Not being in the sitemap and not being in the nav count for nothing.
Seen insrc/app/robots.tssrc/app/card/page.tsx

JSON-LD `@graph` linking the WebSite to the Person/Organization behind it.

Gets you the name + logo treatment in results instead of a bare blue link.

Seen insrc/app/layout.tsx

jsonld

const jsonLd = {
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "WebSite", "@id": `${site.url}/#website`, url: site.url, name: site.name,
      publisher: { "@id": `${site.url}/#person` } },
    { "@type": "Person", "@id": `${site.url}/#person`, name: site.name,
      url: site.url, image: `${site.url}/icon.svg`, sameAs: [site.links.linkedin] },
  ],
};
// <Script id="ld" type="application/ld+json">{JSON.stringify(jsonLd)}</Script>

One node per real thing, referenced by `@id`. Never describe the same thing twice.
The tempting shortcut is to inline `author: { "@type": "Person", name }` on every article. Now there are two Person nodes on the page and nothing says they're the same human, so neither accumulates the signal — the whole point of the graph is that one node gets referenced from everywhere. Same rule for publisher and `isPartOf`. Then check each type's required fields: `BlogPosting` wants headline, image, datePublished, dateModified, author.
Seen insrc/app/blog/[slug]/page.tsxRich Results Test — paste the built URL ↗
jsonld-entities
```
// layout defines it once
{ "@type": "Person", "@id": `${site.url}/#person`, name, url, image, sameAs: [...] }

// every article points at it — no second copy
author: { "@id": `${site.url}/#person` },
publisher: { "@id": `${site.url}/#person` },
```
`BreadcrumbList` on anything nested — posts, case studies, category pages.
Swaps the raw URL line in a result for `site.com › Blog › Title`. One of the few appearance wins that's purely markup, unlike sitelinks, which are algorithmic and can't be requested. Every step has to be a URL that actually resolves or Google drops the whole trail.
Seen insrc/components/Breadcrumbs.tsx
`sameAs` pointing at every profile that's unmistakably you.
This is how Google reconciles the person on your site with the person on LinkedIn, GitHub and everywhere else, and that reconciliation is the prerequisite for any entity treatment. One link is a claim; several corroborating each other is an identity. Only list profiles you control and would happily be judged by.
Seen insrc/app/layout.tsx
Exactly one `<h1>` per page, headings in order, no skipping levels for size.
Use a class for size. Heading level is structure, not typography.
Seen inWorkbench — Prose
Alt text that says what the image means, and an empty alt when it's pure decoration.
"image" or a filename is worse than empty.
Pick trailing-slash or not, then make canonical, sitemap and internal links agree.
Mismatch = two indexed URLs per page competing with each other.
Seen innext.config.ts

Performance

Cheap wins first, and measure before touching anything else. Every one of these is checkable in a few minutes on a production build.

`next/font` with `display: "swap"`, subset to `latin`, exposed as a CSS variable.
Self-hosted, no layout shift, no third-party request to Google.
Seen insrc/app/layout.tsx
fonts
```
const inter = Inter({ variable: "--font-inter", subsets: ["latin"], display: "swap" });
```
Explicit width/height (or aspect-ratio) on every image, `priority` on the LCP one only.
Missing dimensions is the top cause of CLS. `priority` on everything is the same as on nothing.
Static export has no image optimiser — convert and resize before committing.
`images: { unoptimized: true }` isn't a setting you can revisit later, it's the whole deal: what you commit is what every visitor downloads, at full size, in whatever format you saved it. Convert to WebP at ~q80, resized to roughly 2× its display width. A 4MB screenshot is one drag-and-drop away and nothing in the build will warn you.
Seen inpublic/projects/ — all WebP, kept that way
image-optimise
```
sharp("shot.png").resize({ width: 1100 }).webp({ quality: 80 }).toFile("shot.webp");
```
`"use client"` as deep in the tree as possible.
One `use client` at the top of a page drags the whole subtree into the bundle.
Seen insrc/components/checklist/Checklist.tsx
Run Lighthouse on the production build, on mobile throttling, before launch.
`next dev` numbers are fiction.
Seen inSplit Lip Adventures — the scores
lighthouse
```
npm run build && npx serve out
npx lighthouse http://localhost:3000 --preset=desktop --view
```
Check First Load JS per route. Question anything over ~150kB.
Next 16 dropped the size column from the build output, so this stopped being free the moment it stopped being printed — which is exactly when people stopped checking. `@next/bundle-analyzer`, or read `.next/build-manifest.json`.
bundle
```
npx -y @next/bundle-analyzer@latest # or: ANALYZE=true npm run build
```

Accessibility

The non-negotiable floor. All of it is quick, and all of it is the sort of thing nobody notices until someone can't use the site.

Tab through the whole page once. Nothing invisible, nothing trapped, order matches the visual layout.
Two minutes, catches most of what an audit would.
Skip-to-content link as the first element in `<body>`.
Hidden until focused. Six lines of CSS.
Seen inWorkbench — Skip link
Check the muted/faint greys hit 4.5:1 on the real background, and note the ratio in a comment.
The subtle grey that looks best is nearly always the one that fails. Record the number so the next tweak doesn't silently break it.
Seen insrc/app/globals.css
Verify the focus ring is visible on both the darkest and lightest surface.
An accent ring can vanish against an elevated card.
Seen inWorkbench — Button on a light palette
Test with reduced motion actually enabled in the OS.
The media query is easy to write and easy to get wrong.

The last mile

The final pass before handover — and the first pass on a site you've taken over, because it's the group that most often turns out to have been skipped.

`icon.svg`, `apple-icon.png` (180×180), and check the tab in light and dark browser chrome.
Assets & meta has the full set rendered at 16px. A default Next favicon in production is the cheapest possible tell.
Seen inAssets & meta — the full set at 16pxsrc/app/icon.svg
Paste the real URL into WhatsApp, Slack, LinkedIn and X and look at the card.
Validators lie about crawler caching. The chat window doesn't.
Seen inAssets & meta
A `not-found.tsx` that matches the site and links home.
Default 404s look broken, not empty.
Seen insrc/app/not-found.tsx
Then check the host actually serves it — request a URL that doesn't exist.
Writing the page and shipping the page are two different jobs. A static host has no router, so by default it serves its own grey 404, or returns 200 with your homepage — which quietly invites Google to index every typo as a duplicate. One config line, and the only way to know is to ask for a bad URL on production.
Seen inwrangler.jsonc
host-404
```
// wrangler.jsonc
"assets": { "directory": "./out", "not_found_handling": "404-page" }
```
Confirm the preview/staging deploy is `noindex` and production isn't.
Both directions of this mistake are embarrassing.
Seen insrc/app/brand/page.tsx
Open it on your actual phone. Check the safe areas and the address-bar colour.
Simulators don't show you the notch eating your sticky header.
Cmd-P if the page holds anything anyone might print (CV, invoice, itinerary).
A dark-background print is a full ink cartridge.
Decide whether you actually want analytics, then wire it once, cookie-free if possible.
"I'll add it later" means never having the launch-week numbers.
Seen insrc/app/layout.tsx
README with: what it is, how to run, how to deploy, where the content lives.
Written for me in eight months, having forgotten all of it.
Seen inREADME.md
Verify in Search Console, submit the sitemap — then come back a month later and read it.
Everything above this line is done blind. This is the only place that tells you what the crawler actually concluded: which canonical it honoured, which pages it decided were duplicates, which URL it indexed instead of the one you meant. Launch day is when you register; the value arrives weeks later, and only if you go and look.
Seen insrc/app/sitemap.ts