create-website-build-kit 0.1.0 → 0.1.2

package/README.md

@@ -1,14 +1,22 @@
-# create-website-build-kit
+<p align="center">
+  <img src="https://raw.githubusercontent.com/nurkamol/website-build-kit/master/site/brand/mark-light.png" width="72" height="72" alt="">
+</p>
 
-Scaffold a production marketing site: **Astro, static, on Cloudflare Workers** — with the
-gates, the migration playbook and the accessibility work already wired.
+<h1 align="center">create-website-build-kit</h1>
+
+<p align="center"><em>Your build was green. The site was wrong.</em></p>
 
 ```bash
 npm create website-build-kit@latest my-site
 ```
 
+Scaffold a production marketing site: **Astro, static, on Cloudflare Workers** — with the
+gates, the migration playbook and the accessibility work already wired.
+
 Node 22.12+. It builds green immediately, with no content, no images and no secrets.
 
+**[The method, the traps and the docs →](https://nurkamol.github.io/website-build-kit/)**
+
 ## What you get
 
 A skeleton, not a theme. It ships **no palette, no typeface and no home page** — deliberately,
@@ -45,10 +53,22 @@ Bricks — the extractable copy is the rendered HTML, never the database.
 
 ## The method
 
-The template is half of it. The other half is a Claude Code skill and the written method
-behind it, including a file of failures that were **green in a build**: clean build, clean
-types, clean deploy, wrong result.
+The template is half of it. The other half is a Claude Code skill that runs the whole job —
+discovery, stack and provider decisions, the build, then verification against the deployed
+site:
+
+```
+/plugin marketplace add nurkamol/website-build-kit
+/plugin install website-build@website-build-kit
+```
+
+Then just ask: *"Rebuild https://acmeplumbing.com on Astro and Cloudflare — we're migrating
+off Elementor."*
+
+Behind it is the written method, including a file of failures that were **green in a build**:
+clean build, clean types, clean deploy, wrong result.
 
-**https://github.com/nurkamol/website-build-kit**
+- **Site:** <https://nurkamol.github.io/website-build-kit/>
+- **Source:** <https://github.com/nurkamol/website-build-kit>
 
 MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold a production marketing site \u2014 Astro on Cloudflare Workers, with the gates, the migration playbook and the accessibility work already wired.",
   "keywords": [
     "astro",
@@ -15,7 +15,7 @@
     "wcag",
     "seo"
   ],
-  "homepage": "https://github.com/nurkamol/website-build-kit#readme",
+  "homepage": "https://nurkamol.github.io/website-build-kit/",
   "bugs": "https://github.com/nurkamol/website-build-kit/issues",
   "repository": {
     "type": "git",

package/template/.node-version

@@ -1 +1 @@
-24.2.0
+24.19.0

package/template/.pa11yci.json

@@ -1,19 +1,32 @@
 {
   "defaults": {
     "standard": "WCAG2AA",
-    "runners": ["axe", "htmlcs"],
+    "runners": [
+      "axe",
+      "htmlcs"
+    ],
     "timeout": 30000,
-    "concurrency": 4,
+    "concurrency": 1,
     "hideElements": "iframe[src*='google.com/maps'], iframe[src*='youtube.com']",
-    "chromeLaunchConfig": { "args": ["--no-sandbox"] }
+    "chromeLaunchConfig": {
+      "args": [
+        "--no-sandbox"
+      ]
+    }
   },
   "//": [
-    "One URL per template family, not every page — a homepage-only pass misses",
+    "One URL per template family, not every page \u2014 a homepage-only pass misses",
     "everything the blog does differently. Point these at `wrangler dev`",
     "(localhost:8788) while building, or at the deployed staging host.",
     "Staging emits no sitemap on purpose, which is why these are explicit.",
     "Against production you can instead run:",
-    "  npx pa11y-ci --sitemap https://example.com/sitemap-index.xml --standard WCAG2AA"
+    "  npx pa11y-ci --sitemap https://example.com/sitemap-index.xml --standard WCAG2AA",
+    "",
+    "concurrency is 1 DELIBERATELY. Above 1, pa11y intermittently reports",
+    "'Failed to run \u2014 Protocol error (Target.closeTarget)' on a random URL, which",
+    "reads as an accessibility failure and is Chrome tearing down targets.",
+    "Measured on this template: 4/5 runs failed at concurrency 4, 5/5 at 2, 0/5 at 1.",
+    "A gate that is wrong most of the time is a gate people learn to ignore."
   ],
   "urls": [
     "http://localhost:8788/",

package/template/docs/traps.md

@@ -182,7 +182,7 @@ perfectly, on time, to an empty room.
 revealing everything only if the observer never fired at all — which is the
 failure the guard actually exists for.
 
-### A the booking vendor plugin that renders nothing because of a missing attribute
+### The booking vendor's plugin renders nothing, because of a missing attribute
 
 `/schedule/` was blank. The embed had been carried over from the WordPress site
 before the booking vendor's snippet gained `locale="en"`. Without it the plugin loads,
@@ -192,13 +192,13 @@ container.
 **Symptom:** no console error, no failed request, a populated network tab and
 an empty div.
 
-**Fix:** diff the embed against a freshly generated snippet from the the booking vendor
+**Fix:** diff the embed against a freshly generated snippet from the booking vendor
 dashboard rather than debugging the plugin. Any third-party embed carried
 across a migration deserves the same check.
 
 ### A third-party widget that changes your own CSS
 
-Enabling the the booking vendor webchat took three pages from 0 accessibility errors to
+Enabling the booking vendor's webchat took three pages from 0 accessibility errors to
 failing. It injects a stylesheet into the page. Separately, its fixed overlay
 makes axe report colour-contrast violations on elements it covers, which look
 identical to real failures — `htmlcs` reported nothing and the computed colours
@@ -418,7 +418,7 @@ site, which is what `docs/runbook.md` asks for.
 
 ### "It's inside a cross-origin iframe" is not the same as "it cannot be changed"
 
-The client asked twice for the the booking vendor booking panel's white ground to match
+The client asked twice for the booking vendor's panel to match
 the cream page. The white comes from `html, body, #root { background-color:
 #ffffff }` inside vendor.com's own document — cross-origin, unreachable, and
 that was reported back as "the only lever is the booking vendor's branding settings."
@@ -901,3 +901,32 @@ grep -rnE '[a-z](https?://|[A-Z][a-z])' src/content/ | grep -vE 'iPhone|YouTube|
 ```
 
 Expect a few false positives from camelCase and brand names; read them.
+
+### The accessibility gate fails on a random URL, and it is not accessibility
+
+**Symptom:** `npm run a11y` reports `Failed to run` against one URL, a different
+one each time, with `Error: Protocol error (Target.closeTarget): No target with
+given id found`. It reads as an accessibility failure on that page. The page is
+fine, and a re-run usually blames a different page — or passes.
+
+It is Chrome tearing down browser targets while another is still closing, and it
+is driven entirely by pa11y's `concurrency`. Measured on this template, five runs
+at each setting:
+
+| `concurrency` | Runs that failed |
+| --- | --- |
+| 4 | **4 / 5** |
+| 2 | **5 / 5** |
+| 1 | **0 / 5** |
+
+Note that 2 was no better than 4 — this is a race in target teardown, not a
+resource limit, so lowering the number without going to 1 buys nothing.
+
+**Fix:** `"concurrency": 1` in `.pa11yci.json`. Four URLs sequentially is a few
+seconds; a gate that is wrong four times in five is a gate the team learns to
+ignore, and then it is worse than no gate because its silence means nothing.
+
+Worth knowing before you go hunting: this got *more* visible when the run started
+covering both colour schemes, because that doubles the number of Chrome sessions
+and so doubles the chances of hitting the race. The change that surfaced it was
+not the change that caused it.

package/template/package.json

@@ -10,7 +10,7 @@
   "scripts": {
     "dev": "astro dev",
     "check": "astro check",
-    "a11y": "pa11y-ci --config .pa11yci.json",
+    "a11y": "node scripts/check-a11y.mjs",
     "a11y:evidence": "node scripts/a11y-evidence.mjs",
     "reflow": "node scripts/check-reflow.mjs",
     "console": "node scripts/check-console.mjs",

package/template/scripts/a11y-evidence.mjs

@@ -28,9 +28,13 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { createRequire } from 'node:module';
 
+import { SCHEMES, configForScheme } from './lib/schemes.mjs';
+
 const require = createRequire(import.meta.url);
 
 const RESET = '';
@@ -72,45 +76,75 @@ const config = JSON.parse(readFileSync('.pa11yci.json', 'utf8'));
 const standard = config.defaults?.standard ?? 'WCAG2AA';
 const runners = config.defaults?.runners ?? ['htmlcs'];
 
-const args = host
-  ? ['pa11y-ci', '--sitemap', `${host}/sitemap-index.xml`, '--standard', standard, '--json']
-  : ['pa11y-ci', '--config', '.pa11yci.json', '--json'];
+/*
+ * ⚠ EVERY SCHEME, because the pack is a COMPLIANCE ARTEFACT.
+ *
+ * pa11y drives Chrome, and Chrome picks a colour scheme from the machine it
+ * runs on. A site with a light and a dark palette has two sets of contrast
+ * pairs, so a single run measures one and says nothing about the other —
+ * measured on the kit's own landing page at 4.83:1 dark and **3.91:1 light**,
+ * a real AA failure in the half nobody tested.
+ *
+ * A red CI step from that is a nuisance. A dated evidence pack claiming a site
+ * was tested when half of it was not is the thing somebody hands to a lawyer.
+ * See scripts/lib/schemes.mjs.
+ */
+const tmp = mkdtempSync(join(tmpdir(), 'a11y-evidence-'));
+
+const runScheme = (scheme) => {
+  const file = join(tmp, `${scheme}.json`);
+  writeFileSync(file, JSON.stringify(configForScheme(config, scheme), null, 2));
+
+  /* --config supplies the forced-scheme defaults either way; --sitemap only
+     replaces where the URL list comes from. */
+  const args = host
+    ? ['pa11y-ci', '--config', file, '--sitemap', `${host}/sitemap-index.xml`, '--standard', standard, '--json']
+    : ['pa11y-ci', '--config', file, '--json'];
 
-let report;
-try {
-  /* pa11y-ci exits non-zero when it finds errors, and still prints the JSON.
-     A non-zero exit here is a RESULT, not a failure to run. */
-  const out = execFileSync('npx', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
-  report = JSON.parse(out);
-} catch (error) {
-  const out = error.stdout?.toString() ?? '';
   try {
-    report = JSON.parse(out);
-  } catch {
-    console.error(
-      `${RED}✗${RESET} pa11y-ci could not run.\n` +
-        `  ${DIM}Start the site first: npm run build:staging && npx wrangler dev${RESET}\n` +
-        `  ${(error.stderr?.toString() ?? '').slice(0, 400)}`,
+    /* pa11y-ci exits non-zero when it finds errors, and still prints the JSON.
+       A non-zero exit here is a RESULT, not a failure to run. */
+    return JSON.parse(execFileSync('npx', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }));
+  } catch (error) {
+    const out = error.stdout?.toString() ?? '';
+    try {
+      return JSON.parse(out);
+    } catch {
+      console.error(
+        `${RED}✗${RESET} pa11y-ci could not run.\n` +
+          `  ${DIM}Start the site first: npm run build:staging && npx wrangler dev${RESET}\n` +
+          `  ${(error.stderr?.toString() ?? '').slice(0, 400)}`,
+      );
+      process.exit(1);
+    }
+  }
+};
+
+const passes = SCHEMES.map((scheme) => {
+  const report = runScheme(scheme);
+  const rows = Object.entries(report.results).map(([url, issues]) => ({
+    url,
+    errors: issues.filter((i) => i.type === 'error'),
+    warnings: issues.filter((i) => i.type === 'warning'),
+    notices: issues.filter((i) => i.type === 'notice'),
+  }));
+  return { scheme, rows };
+});
+
+for (const { scheme, rows: schemeRows } of passes) {
+  console.log(`  ${BOLD}${scheme}${RESET}`);
+  for (const r of schemeRows) {
+    const mark = r.errors.length ? `${RED}✗${RESET}` : `${GREEN}✓${RESET}`;
+    const path = new URL(r.url).pathname;
+    console.log(
+      `    ${mark} ${path.padEnd(26)} ${String(r.errors.length).padStart(2)} error(s)   ` +
+        `${DIM}${r.warnings.length} warning(s)${RESET}`,
     );
-    process.exit(1);
   }
 }
 
-const rows = Object.entries(report.results).map(([url, issues]) => ({
-  url,
-  errors: issues.filter((i) => i.type === 'error'),
-  warnings: issues.filter((i) => i.type === 'warning'),
-  notices: issues.filter((i) => i.type === 'notice'),
-}));
-
-for (const r of rows) {
-  const mark = r.errors.length ? `${RED}✗${RESET}` : `${GREEN}✓${RESET}`;
-  const path = new URL(r.url).pathname;
-  console.log(
-    `  ${mark} ${path.padEnd(28)} ${String(r.errors.length).padStart(2)} error(s)   ` +
-      `${DIM}${r.warnings.length} warning(s)${RESET}`,
-  );
-}
+/* Kept for the sections below that report per-URL rather than per-scheme. */
+const rows = passes[0].rows;
 
 /* ── 2. Reflow, which pa11y does not cover ───────────────────────────────── */
 
@@ -152,14 +186,17 @@ if (reviewed) {
 
 /* ── 4. The pack ─────────────────────────────────────────────────────────── */
 
-const totalErrors = rows.reduce((n, r) => n + r.errors.length, 0);
+const totalErrors = passes.reduce(
+  (n, pass) => n + pass.rows.reduce((m, r) => m + r.errors.length, 0),
+  0,
+);
 const target = host ?? 'http://localhost:8788 (wrangler dev)';
 
-const issueLines = rows
-  .filter((r) => r.errors.length)
+const issueLines = passes
+  .flatMap((pass) => pass.rows.filter((r) => r.errors.length).map((r) => ({ ...r, scheme: pass.scheme })))
   .map(
     (r) =>
-      `### ${new URL(r.url).pathname}\n\n` +
+      `### ${new URL(r.url).pathname} — ${r.scheme}\n\n` +
       r.errors
         .map(
           (e) =>
@@ -189,18 +226,23 @@ Standard: **${standard}** · runners: ${runners.join(', ')}
 
 ---
 
-## 1. Automated — one URL per template family
+## 1. Automated — one URL per template family, in both colour schemes
 
-| Page | Errors | Warnings | Notices |
-| --- | --- | --- | --- |
-${rows
-  .map(
-    (r) =>
-      `| \`${new URL(r.url).pathname}\` | ${r.errors.length} | ${r.warnings.length} | ${r.notices.length} |`,
+Each page is measured twice, with \`prefers-color-scheme\` forced. A light and a dark
+palette are two sets of contrast pairs, and a single run measures one of them.
+
+| Page | Scheme | Errors | Warnings | Notices |
+| --- | --- | --- | --- | --- |
+${passes
+  .flatMap((pass) =>
+    pass.rows.map(
+      (r) =>
+        `| \`${new URL(r.url).pathname}\` | ${pass.scheme} | ${r.errors.length} | ${r.warnings.length} | ${r.notices.length} |`,
+    ),
   )
   .join('\n')}
 
-**${totalErrors} error(s) across ${rows.length} page(s).**
+**${totalErrors} error(s) across ${rows.length} page(s) × ${passes.length} scheme(s).**
 
 ${issueLines || '_No errors at this standard._'}
 

package/template/scripts/check-a11y.mjs

@@ -0,0 +1,78 @@
+/**
+ * pa11y-ci at WCAG 2.2 AA, in BOTH colour schemes.
+ *
+ *   npm run a11y                                # every URL in .pa11yci.json
+ *   npm run a11y -- --only=light                # one scheme
+ *
+ * ── WHY NOT JUST `pa11y-ci --config .pa11yci.json` ─────────────────────────
+ * Because that measures whichever scheme the machine happens to be in. See
+ * scripts/lib/schemes.mjs — the kit's own landing page passed a local run in
+ * dark mode and failed CI in light on a genuine 3.91:1 contrast pair.
+ *
+ * ── ONE SOURCE FOR THE URLS ────────────────────────────────────────────────
+ * `.pa11yci.json` stays the only place the URL list lives. The scheme is
+ * injected into a copy at run time rather than kept as a second config file,
+ * because two config files is two URL lists and one of them goes stale.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { SCHEMES, configForScheme } from './lib/schemes.mjs';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+const CONFIG = '.pa11yci.json';
+if (!existsSync(CONFIG)) {
+  console.error(`${RED}✗${RESET} ${CONFIG} not found — run this from the site root.`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const only = (args.find((a) => a.startsWith('--only=')) ?? '').replace('--only=', '');
+const schemes = only ? SCHEMES.filter((s) => s === only) : SCHEMES;
+
+if (!schemes.length) {
+  console.error(`${RED}✗${RESET} --only=${only} is not a scheme. Try: ${SCHEMES.join(', ')}`);
+  process.exit(1);
+}
+
+const base = JSON.parse(readFileSync(CONFIG, 'utf8'));
+const urlCount = (base.urls ?? []).length;
+const dir = mkdtempSync(join(tmpdir(), 'a11y-'));
+
+console.log(`${BOLD}── Accessibility · WCAG2AA ${'─'.repeat(33)}${RESET}`);
+console.log(`  ${DIM}${urlCount} URL(s) × ${schemes.length} scheme(s)${RESET}\n`);
+
+let failed = 0;
+
+for (const scheme of schemes) {
+  const file = join(dir, `${scheme}.json`);
+  writeFileSync(file, JSON.stringify(configForScheme(base, scheme), null, 2));
+
+  console.log(`${BOLD}${scheme}${RESET}`);
+  try {
+    execFileSync('npx', ['pa11y-ci', '--config', file], { stdio: 'inherit' });
+    console.log(`  ${GREEN}✓${RESET} ${scheme} clean\n`);
+  } catch {
+    failed++;
+    console.log(`  ${RED}✗${RESET} ${scheme} has errors\n`);
+  }
+}
+
+if (failed) {
+  console.error(`${RED}✗ ${failed} of ${schemes.length} scheme(s) failed${RESET}\n`);
+  process.exit(1);
+}
+
+console.log(
+  `${GREEN}✓ clean in ${schemes.join(' and ')}${RESET}` +
+    (schemes.length === 1 ? `\n  ${DIM}only one scheme measured — the other is untested${RESET}` : '') +
+    '\n',
+);

package/template/scripts/lib/schemes.mjs

@@ -0,0 +1,47 @@
+/**
+ * Colour schemes an accessibility run has to cover.
+ *
+ * ── WHY THIS EXISTS ────────────────────────────────────────────────────────
+ * A site with a light and a dark palette has TWO sets of contrast pairs, and
+ * testing one proves nothing about the other. pa11y drives Chrome, and Chrome
+ * picks a scheme from the machine it runs on — so the same page passes on a
+ * developer's laptop in dark mode and fails in CI in light, from one commit,
+ * with nothing to say which half was measured.
+ *
+ * That is not hypothetical. The kit's own landing page passed locally and
+ * failed the moment it ran on a light-mode runner:
+ *
+ *     --ink-3 on the page background   4.83:1 dark   ·   3.91:1 light
+ *
+ * A real AA failure, in the half nobody happened to test. Forcing the scheme
+ * removes the luck.
+ *
+ * ── IT RUNS BOTH EVEN WITH NO DARK MODE ────────────────────────────────────
+ * Deliberately. A fresh template ships no `prefers-color-scheme` rule at all,
+ * so the two runs are identical and cost a few seconds. The day somebody adds
+ * a dark palette is exactly the day the blind spot would otherwise open, and
+ * a check you have to remember to switch on is a check that is off.
+ */
+
+export const SCHEMES = ['light', 'dark'];
+
+/**
+ * A pa11y-ci config with the colour scheme pinned.
+ *
+ * `--force-prefers-color-scheme` makes Chrome answer the media query the same
+ * way on every machine, which is the only reason a contrast result is
+ * comparable between a laptop and a runner.
+ */
+export function configForScheme(base, scheme) {
+  const defaults = { ...(base.defaults ?? {}) };
+  const launch = { ...(defaults.chromeLaunchConfig ?? {}) };
+  const args = (launch.args ?? []).filter((a) => !a.startsWith('--force-prefers-color-scheme'));
+
+  return {
+    ...base,
+    defaults: {
+      ...defaults,
+      chromeLaunchConfig: { ...launch, args: [...args, `--force-prefers-color-scheme=${scheme}`] },
+    },
+  };
+}