@erclx/canon 4.64.0 → 4.65.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.64.0",
+  "version": "4.65.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/governance/rules/ui/440-surface-capture.md

@@ -4,6 +4,7 @@ paths:
   - '**/routes/**/*.{tsx,jsx,vue,svelte,astro}'
   - '**/pages/**/*.{tsx,jsx,vue,svelte,astro}'
   - '**/app/**/page.{tsx,jsx}'
+  - '**/components/**/*.{tsx,jsx,vue,svelte,astro}'
   - '**/*.html'
 ---
 
@@ -13,6 +14,7 @@ paths:
 
 - A surface is anything the project renders for a person to look at. A framework route is one. A page the project generates is another, whoever generates it.
 - Judge a generated page by the same rule as a route. Reading its markup reports nothing about how it composes.
+- A component the production build strips out is not a surface, such as a dev-only scenario switcher gated behind a build flag. The build removes it before anything renders, so no comparison exists to capture.
 
 ## When to capture
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.64.0",
+  "version": "4.65.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -41,9 +41,10 @@
     "bootstrap": "./scripts/core/bootstrap.sh",
     "canon:sandbox": "canon sandbox",
     "canon:sandbox:reset": "canon sandbox reset",
-    "web:tokens": "canon design css --no-components > web/src/styles/tokens.css.new && (echo '/* Generated by `canon design css --no-components`. Regenerate with `bun run web:tokens`. Do not hand-edit. */'; cat web/src/styles/tokens.css.new) > web/src/styles/tokens.css && rm web/src/styles/tokens.css.new",
+    "web:tokens": "bun src/cli.ts design css --no-components > web/src/styles/tokens.css.new && (echo '/* Generated by `canon design css --no-components`. Regenerate with `bun run web:tokens`. Do not hand-edit. */'; cat web/src/styles/tokens.css.new) > web/src/styles/tokens.css && rm web/src/styles/tokens.css.new",
     "web:dev": "cd web && astro dev",
-    "web:build": "bun run web:tokens && cd web && astro check && astro build",
+    "web:favicon": "bun scripts/core/regen-web-favicon.ts",
+    "web:build": "bun run web:tokens && bun run web:favicon && cd web && astro check && astro build",
     "web:preview": "cd web && astro preview",
     "web:e2e": "cd web && playwright test"
   },

package/scripts/core/regen-web-favicon.ts

@@ -0,0 +1,67 @@
+/**
+ * Writes web/public/favicon.svg from assets/brand/mark.svg and the design
+ * source's two accent values.
+ *
+ * The page is the fourth surface to carry the mark as a favicon and the only
+ * one that can answer for itself. `regen-hero.sh` and `src/design/render.ts`
+ * each bake a single literal, because both embed the mark as a data URI and a
+ * data URI has no CSS context. A file served at its own URL does have one, so
+ * this copy carries a `prefers-color-scheme` branch and tracks the reader's
+ * theme rather than picking one accent for everybody.
+ *
+ * `web/public/favicon.svg` was a symlink to the source before this, and the
+ * source fills `currentColor`, which resolves to black with no CSS context.
+ * That is what painted the tab icon black on every surface the page reaches.
+ * The source keeps `currentColor`, since the hero topbar embeds the same file
+ * inline and wants it to inherit.
+ */
+import { writeFileSync } from 'node:fs'
+
+const root = new URL('../..', import.meta.url).pathname
+
+const mark = (await Bun.file(`${root}assets/brand/mark.svg`).text()).trim()
+if (!mark) {
+  console.error('regen-web-favicon: assets/brand/mark.svg read empty')
+  process.exit(1)
+}
+
+const tokenCss = await Bun.file(`${root}web/src/styles/tokens.css`).text()
+const read = (name: string): string => {
+  const match = tokenCss.match(
+    new RegExp(`--color-${name}:\\s*(#[0-9a-fA-F]{3,8})`),
+  )
+  if (!match) {
+    console.error(
+      `regen-web-favicon: tokens.css carries no --color-${name}, refusing to write a colorless favicon`,
+    )
+    process.exit(1)
+  }
+  return match[1] as string
+}
+
+const dark = read('accent')
+const light = read('light-accent')
+
+// The shapes only, with the source's authoring comment dropped. Both fills are
+// replaced by a rule rather than an attribute so one branch can flip both.
+const shapes = mark
+  .replace(/<!--[\s\S]*?-->/, '')
+  .trim()
+  .replace(/^<svg[^>]*>/, '')
+  .replace(/<\/svg>$/, '')
+  .replaceAll(' fill="currentColor"', '')
+  .trim()
+
+const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80">
+  <style>
+    path, rect { fill: ${light}; }
+    @media (prefers-color-scheme: dark) { path, rect { fill: ${dark}; } }
+  </style>
+  ${shapes.replace(/\n\s*/g, '\n  ')}
+</svg>
+`
+
+writeFileSync(`${root}web/public/favicon.svg`, svg)
+console.log(
+  `regen-web-favicon: wrote web/public/favicon.svg (${light} / ${dark})`,
+)

package/src/design/base.css

@@ -16,9 +16,13 @@
   --color-success: #61c454;
   --color-light-background: #faf7f2;
   --color-light-surface: #f4efe6;
+  --color-light-chrome: #ede4d6;
   --color-light-text: #1a1815;
+  --color-light-text-body: #3d3630;
+  --color-light-text-secondary: #5c544b;
   --color-light-muted: #726b62;
   --color-light-accent: #a4471c;
+  --color-light-success: #2d6b22;
   --color-light-border: #e4dcd0;
   --space-xs: 6px;
   --space-sm: 12px;
@@ -53,15 +57,16 @@
   --radius-marker: 999px;
 }
 
-/* The record declares no light counterpart for chrome, text-body, text-secondary, success, so
-   a light-ground surface using one is reading a dark value. Declare the
-   counterpart in src/design/tokens.ts rather than overriding it here. */
 [data-theme='light'] {
   --color-background: var(--color-light-background);
   --color-surface: var(--color-light-surface);
+  --color-chrome: var(--color-light-chrome);
   --color-text: var(--color-light-text);
+  --color-text-body: var(--color-light-text-body);
+  --color-text-secondary: var(--color-light-text-secondary);
   --color-muted: var(--color-light-muted);
   --color-accent: var(--color-light-accent);
+  --color-success: var(--color-light-success);
   --color-border: var(--color-light-border);
 }
 

package/src/design/tokens.ts

@@ -180,12 +180,29 @@ export const TOKENS: DesignTokens = {
       intent: 'cards and panels on a light ground',
       value: '#f4efe6',
     },
+    {
+      role: 'light-chrome',
+      intent: 'the window titlebar, one step above the canvas',
+      value: '#ede4d6',
+    },
     {
       role: 'light-text',
       intent: 'primary text on a light ground',
       value: '#1a1815',
       grounds: LIGHT_GROUNDS,
     },
+    {
+      role: 'light-text-body',
+      intent: 'default body copy on a light ground',
+      value: '#3d3630',
+      grounds: LIGHT_GROUNDS,
+    },
+    {
+      role: 'light-text-secondary',
+      intent: 'labels, captions, supporting copy on a light ground',
+      value: '#5c544b',
+      grounds: LIGHT_GROUNDS,
+    },
     {
       role: 'light-muted',
       intent: 'secondary text on a light ground',
@@ -198,6 +215,12 @@ export const TOKENS: DesignTokens = {
       value: '#a4471c',
       grounds: LIGHT_GROUNDS,
     },
+    {
+      role: 'light-success',
+      intent: 'confirmations, rendered and in the terminal, on light',
+      value: '#2d6b22',
+      grounds: ['light-background'],
+    },
     {
       role: 'light-border',
       intent: 'rules and panel edges on light',

package/src/gate/stages.ts

@@ -220,10 +220,11 @@ export const STAGES: readonly Stage[] = [
     success: 'Tooling paths clean',
   },
   {
-    // `.claude/DESIGN.md` and the base stylesheet are both written from
-    // `src/design/tokens.ts` and neither is edited by hand. Two artifacts from
-    // one source is the cost of the token move, and a render step that has to
-    // run is only safe while something fails when it did not, which is this.
+    // `.claude/DESIGN.md`, the base stylesheet, the web stylesheet, and the
+    // tab icon are all written from `src/design/tokens.ts` and none is edited
+    // by hand. Four artifacts from one source is the cost of the token move,
+    // and a render step that has to run is only safe while something fails
+    // when it did not, which is this.
     id: 'design',
     label: 'Design',
     checks: [
@@ -244,6 +245,28 @@ export const STAGES: readonly Stage[] = [
         failure:
           'The base stylesheet drifted from the token source. Run bun run check and commit src/design/base.css.',
       },
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'web:tokens'],
+        failure: 'Web token regen failed',
+      },
+      {
+        kind: 'drift',
+        pathspec: 'web/src/styles/tokens.css',
+        failure:
+          'The web stylesheet drifted from the token source. Run bun run check and commit web/src/styles/tokens.css.',
+      },
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'web:favicon'],
+        failure: 'Web favicon regen failed',
+      },
+      {
+        kind: 'drift',
+        pathspec: 'web/public/favicon.svg',
+        failure:
+          'The tab icon drifted from the token source. Run bun run check and commit web/public/favicon.svg.',
+      },
     ],
     success: 'Design source clean',
   },

package/tooling/web/reference.md

@@ -110,7 +110,7 @@ Append rows:
 
 `canon tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. It counts them with a recursive find carrying no depth limit, so the section folders the seed writes satisfy the assertion without a change to it. Do not flatten the layout to protect that check. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.
 
-`governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a route changes. It fires on route and page files rather than on every component, so a shared component changing every screen fires nothing and the operator runs the capture by hand.
+`governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
 
 The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there.