npm - @erclx/canon - Versions diffs - 4.8.1 → 4.9.1 - Mend

@erclx/canon 4.8.1 → 4.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/claude/.claude-plugin/plugin.json +1 -1
package/claude/skills/claude-teach/SKILL.md +11 -1
package/docs/agents/commands.md +10 -3
package/docs/agents/install-and-sync.md +23 -1
package/docs/agents/teach.md +2 -0
package/docs/target-projects.md +6 -4
package/docs/visual-design-workflow.md +2 -0
package/package.json +1 -1
package/src/commands/design.ts +147 -5
package/src/commands/migrate.ts +27 -4
package/src/commands/sync.ts +3 -5
package/src/commands/teach.ts +72 -0
package/src/design/adapter.ts +59 -0
package/src/design/base.css +123 -0
package/src/design/components.ts +118 -0
package/src/design/contrast.ts +81 -0
package/src/design/css.ts +142 -0
package/src/design/document.ts +143 -0
package/src/design/regen.ts +56 -0
package/src/design/render.ts +43 -9
package/src/design/tokens.ts +315 -0
package/src/gate/stages.ts +28 -0
package/src/migrate/records.ts +71 -1
package/src/slides/styles.ts +42 -15
package/src/sync/check.ts +41 -0
package/src/sync/engine.ts +28 -7
package/src/sync/stamp.ts +5 -4
package/src/sync/target.ts +4 -1
package/src/teach/workspace.ts +57 -0

package/src/design/render.ts CHANGED Viewed

@@ -2,6 +2,7 @@ import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Cell, DesignDoc, Row } from '@/design/parse'
 import { parseDesignDoc } from '@/design/parse'
+import { colorValue } from '@/design/tokens'
 export interface RenderResult {
   htmlPath: string
@@ -135,6 +136,38 @@ function escape(s: string): string {
     .replace(/"/g, '&quot;')
 }
+/**
+ * The preview page's own chrome, read off the toolkit's design source rather
+ * than written as literals here.
+ *
+ * It takes a `--preview-` prefix rather than the `--color-` one the sheet beside
+ * it emits, because that sheet is built from whichever document is being
+ * previewed. A target's record is free to declare a role this page also uses,
+ * and sharing one name would let the page being previewed repaint the page
+ * doing the previewing.
+ *
+ * The light roles are the ones read, since the preview is a light document.
+ */
+function previewChrome(): string {
+  const roles: ReadonlyArray<readonly [string, string]> = [
+    ['paper', 'light-background'],
+    ['panel', 'light-surface'],
+    ['ink', 'light-text'],
+    ['muted', 'light-muted'],
+    ['rule', 'light-border'],
+    ['accent', 'light-accent'],
+  ]
+  const lines = roles
+    .map(([name, role]) => {
+      const value = colorValue(role)
+      return value === undefined ? '' : `    --preview-${name}: ${value};`
+    })
+    .filter((line) => line !== '')
+  return ['  :root {', ...lines, '  }'].join('\n')
+}
 function buildHtml(doc: DesignDoc): string {
   const sections = [
     sectionPersonality(doc.personality),
@@ -147,7 +180,7 @@ function buildHtml(doc: DesignDoc): string {
   ]
   const { tagged, total } = confidence(doc)
   const verifyStyle = tagged
-    ? '\n  .verify { color: #a4471c; font-size: 12px; font-weight: 600; margin-left: 0.35rem; white-space: nowrap; }'
+    ? '\n  .verify { color: var(--preview-accent); font-size: 12px; font-weight: 600; margin-left: 0.35rem; white-space: nowrap; }'
     : ''
   const verb = tagged === 1 ? 'carries' : 'carry'
   const summary = tagged
@@ -160,16 +193,17 @@ function buildHtml(doc: DesignDoc): string {
 <title>Design tokens</title>
 <link rel="stylesheet" href="design.css">
 <style>
-  body { font-family: system-ui, sans-serif; margin: 2rem; max-width: 960px; color: #222; }
+${previewChrome()}
+  body { font-family: system-ui, sans-serif; margin: 2rem; max-width: 960px; color: var(--preview-ink); background: var(--preview-paper); }
   h1 { margin-top: 0; }
-  h2 { margin-top: 2rem; border-bottom: 1px solid #ddd; padding-bottom: 0.25rem; }
+  h2 { margin-top: 2rem; border-bottom: 1px solid var(--preview-rule); padding-bottom: 0.25rem; }
   table { border-collapse: collapse; width: 100%; margin-top: 0.5rem; }
-  th, td { text-align: left; padding: 0.5rem 0.75rem; border-bottom: 1px solid #eee; font-size: 14px; }
-  th { background: #f7f7f7; font-weight: 600; }
-  .swatch { display: inline-block; width: 1.5rem; height: 1.5rem; border-radius: 4px; border: 1px solid #ddd; vertical-align: middle; margin-right: 0.5rem; }
-  .bar { display: inline-block; height: 1rem; background: #888; border-radius: 2px; vertical-align: middle; }
-  .note { color: #666; font-size: 13px; margin-top: 0.5rem; }
-  .empty { color: #999; font-style: italic; }${verifyStyle}
+  th, td { text-align: left; padding: 0.5rem 0.75rem; border-bottom: 1px solid var(--preview-rule); font-size: 14px; }
+  th { background: var(--preview-panel); font-weight: 600; }
+  .swatch { display: inline-block; width: 1.5rem; height: 1.5rem; border-radius: 4px; border: 1px solid var(--preview-rule); vertical-align: middle; margin-right: 0.5rem; }
+  .bar { display: inline-block; height: 1rem; background: var(--preview-muted); border-radius: 2px; vertical-align: middle; }
+  .note { color: var(--preview-muted); font-size: 13px; margin-top: 0.5rem; }
+  .empty { color: var(--preview-muted); font-style: italic; }${verifyStyle}
 </style>
 </head>
 <body>

package/src/design/tokens.ts ADDED Viewed

@@ -0,0 +1,315 @@
+/**
+ * The design system's one source of values.
+ *
+ * `.claude/DESIGN.md` is rendered from this module rather than read by it, so
+ * the document a person opens is a view and this file is the fact. Every
+ * rendering surface reads from here in the form it can take: a CSS surface
+ * takes custom properties through `@/design/css`, and the slide renderer takes
+ * bare hex through `bareHex` below, because PowerPoint has no concept of a
+ * custom property.
+ *
+ * The two artifacts can disagree, which is what the `design` gate stage exists
+ * to catch. Nothing else compares them.
+ */
+/** A color role, its purpose, and the value every surface renders it at. */
+export interface ColorToken {
+  readonly role: string
+  readonly intent: string
+  readonly value: string
+  /**
+   * Roles this one is rendered on top of, named rather than spelled so a ground
+   * moving carries every reading measured against it. Empty on a ground itself
+   * and on a role with no hex value to measure.
+   */
+  readonly grounds?: readonly string[]
+  /**
+   * No rendering surface exercises this value yet, so it is a declaration the
+   * system has not tested rather than one it has. Rendered as `? verify`.
+   */
+  readonly verify?: boolean
+}
+export interface TypeToken {
+  readonly role: string
+  readonly family: string
+  readonly weight: string
+  readonly size: string
+  readonly lineHeight: string
+  readonly verify?: readonly ('family' | 'weight' | 'size' | 'lineHeight')[]
+}
+export interface SpaceToken {
+  readonly step: string
+  readonly multiplier: string
+  readonly value: string
+}
+export interface BorderToken {
+  readonly role: string
+  readonly radius: string
+  readonly width: string
+  readonly when: string
+  readonly verify?: readonly ('radius' | 'width')[]
+}
+export interface DesignTokens {
+  readonly personality: string
+  readonly color: readonly ColorToken[]
+  readonly colorNote: string
+  readonly typography: readonly TypeToken[]
+  readonly typographyNote: string
+  readonly spacing: readonly SpaceToken[]
+  readonly spacingNote: string
+  readonly borders: readonly BorderToken[]
+  readonly bordersNote: string
+  readonly motion: string
+  readonly iconography: string
+  readonly preamble: string
+}
+/** The one monospace stack every surface that renders text declares. */
+const MONO = 'Noto Sans Mono, DejaVu Sans Mono, monospace'
+const DARK_GROUNDS = ['background', 'surface'] as const
+const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
+export const TOKENS: DesignTokens = {
+  preamble: [
+    'This document is rendered from `src/design/tokens.ts` by `canon design regen`, and the `design` stage of `bun run check` fails when the two disagree. Edit the module, never this file.',
+    '',
+    'The values below are the system rather than a reading of one. Until 2026-09-01 this record transcribed two surfaces and agreed with nothing else, which is what made a change to it reach nobody. The slide theme, the token preview, and a teach workspace stylesheet now read the module this file is rendered from, so a value changed there changes what all three render.',
+    '',
+    'Two surfaces still carry their own copies. The rendered hero at `assets/hero.html` is written by `scripts/core/regen-hero.sh` against a committed capture, and the terminal framing in `scripts/lib/ui.sh` and `src/ui.ts` writes ANSI rather than hex. The dark half below is the palette the hero carries, so the two agree today by value and not yet by construction.',
+  ].join('\n'),
+  personality: [
+    'Warm neutrals carry the frame under a single rust accent, rendered in the same monospace the terminal uses. The subject picks the register rather than taste: a toolkit whose primary surface is a shell has no proportional voice available, so the rendered surfaces match the terminal instead of the reverse. One accent carries every count, link, and primary action. Promoting a second and third into structural roles is what reads as a generated interface, so the palette stays at one.',
+  ].join('\n'),
+  colorNote: [
+    'Every role clears WCAG AA at 4.5:1 against each ground it declares, asserted in `src/design/contrast.test.ts`. Two corrections landed with this record becoming the source. The light `muted` step moved from `#7A736A`, which read 4.38 and 4.09 against the two light grounds, and the dark `accent` moved off the `#C8602E` the slide theme carried, which read 4.36 and 3.99 against the two dark ones. Both now sit on the values below.',
+    '',
+    'Success, warning, and error hold ANSI codes because that is what `scripts/lib/ui.sh` writes, and no rendered surface implements an equivalent. Giving them a hex value would invent a mapping no file has, so they carry no contrast reading either.',
+  ].join('\n'),
+  color: [
+    {
+      role: 'background',
+      intent: 'page canvas',
+      value: '#191512',
+    },
+    {
+      role: 'surface',
+      intent: 'cards, panels, raised blocks',
+      value: '#211c19',
+    },
+    {
+      role: 'border',
+      intent: 'every rule and panel edge',
+      value: '#2f2823',
+    },
+    {
+      role: 'text',
+      intent: 'headings, counts, emphasized runs',
+      value: '#f4efe9',
+      grounds: DARK_GROUNDS,
+    },
+    {
+      role: 'text-body',
+      intent: 'default body copy',
+      value: '#c9c0b7',
+      grounds: DARK_GROUNDS,
+    },
+    {
+      role: 'text-secondary',
+      intent: 'labels, captions, supporting copy',
+      value: '#a79d94',
+      grounds: DARK_GROUNDS,
+    },
+    {
+      role: 'muted',
+      intent: 'the faintest step, trailing notes',
+      value: '#948a81',
+      grounds: DARK_GROUNDS,
+    },
+    {
+      role: 'accent',
+      intent: 'install command, mark, primary action',
+      value: '#e0724b',
+      grounds: DARK_GROUNDS,
+    },
+    { role: 'success', intent: 'terminal confirmations', value: 'ANSI 32' },
+    { role: 'warning', intent: 'terminal cautions', value: 'ANSI 33' },
+    { role: 'error', intent: 'terminal failures', value: 'ANSI 31' },
+    {
+      role: 'light-background',
+      intent: 'page canvas on a light ground',
+      value: '#faf7f2',
+    },
+    {
+      role: 'light-surface',
+      intent: 'cards and panels on a light ground',
+      value: '#f4efe6',
+    },
+    {
+      role: 'light-text',
+      intent: 'primary text on a light ground',
+      value: '#1a1815',
+      grounds: LIGHT_GROUNDS,
+    },
+    {
+      role: 'light-muted',
+      intent: 'secondary text on a light ground',
+      value: '#726b62',
+      grounds: LIGHT_GROUNDS,
+    },
+    {
+      role: 'light-accent',
+      intent: 'links and primary action on light',
+      value: '#a4471c',
+      grounds: LIGHT_GROUNDS,
+    },
+    {
+      role: 'light-border',
+      intent: 'rules and panel edges on light',
+      value: '#e4dcd0',
+      verify: true,
+    },
+  ],
+  typographyNote: [
+    'One family covers every role. The size scale runs from 11.5 to 34 pixels across ten values, and five of them map onto a role. The other five are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
+    '',
+    'A tagged cell is one no rendering surface exercises yet, which is a declaration the system has not tested rather than one it has.',
+    '',
+    'Two rules set tracking and no others touch it. The label role carries `0.05em`, and the display role tightens to `-0.01em`.',
+  ].join('\n'),
+  typography: [
+    {
+      role: 'display',
+      family: MONO,
+      weight: '700',
+      size: '34px',
+      lineHeight: '1.3',
+    },
+    {
+      role: 'heading',
+      family: MONO,
+      weight: '700',
+      size: '19px',
+      lineHeight: '1.3',
+      verify: ['lineHeight'],
+    },
+    {
+      role: 'body',
+      family: MONO,
+      weight: '400',
+      size: '16px',
+      lineHeight: '1.65',
+      verify: ['weight'],
+    },
+    {
+      role: 'label',
+      family: MONO,
+      weight: '400',
+      size: '12px',
+      lineHeight: '1.45',
+      verify: ['weight', 'lineHeight'],
+    },
+    {
+      role: 'code',
+      family: MONO,
+      weight: '700',
+      size: '14.5px',
+      lineHeight: '1.3',
+      verify: ['lineHeight'],
+    },
+  ],
+  spacingNote: [
+    'The base is six pixels, which is the largest unit dividing the values that recur: 6, 12, 18, 24, and 30. One-off paddings at 9, 10, 11, 13, 14, 16, 22, 26, 34, and 40 pixels sit off the scale entirely and get no step.',
+    '',
+    'The outer window padding is a single declaration reading `44px 52px 38px`, and none of its three values divides by six. They carry no multiplier for that reason, and one declaration setting all three is the only thing grouping them, so they are a frame register rather than a scale.',
+  ].join('\n'),
+  spacing: [
+    { step: 'xs', multiplier: '1', value: '6px' },
+    { step: 'sm', multiplier: '2', value: '12px' },
+    { step: 'md', multiplier: '3', value: '18px' },
+    { step: 'lg', multiplier: '4', value: '24px' },
+    { step: 'xl', multiplier: '5', value: '30px' },
+    { step: 'frame-top', multiplier: 'none', value: '44px' },
+    { step: 'frame-inline', multiplier: 'none', value: '52px' },
+    { step: 'frame-bottom', multiplier: 'none', value: '38px' },
+  ],
+  bordersNote: [
+    'Every border is one pixel solid at the `border` role, and that value appears in no text role. Three radii appear, and the two blocks carrying the largest and smallest have no border at all, so radius and width are independent here rather than paired. Nothing renders a pill, so both of its cells stay tagged.',
+  ].join('\n'),
+  borders: [
+    {
+      role: 'frame',
+      radius: '12px',
+      width: 'none',
+      when: 'the outer window, radius only',
+    },
+    {
+      role: 'panel',
+      radius: '10px',
+      width: '1px',
+      when: 'cards and columns',
+    },
+    {
+      role: 'action',
+      radius: '7px',
+      width: 'none',
+      when: 'the install command block',
+    },
+    {
+      role: 'rule',
+      radius: 'none',
+      width: '1px',
+      when: 'horizontal dividers between bands',
+    },
+    {
+      role: 'pill',
+      radius: '999px',
+      width: 'none',
+      when: 'tags and status chips, none built',
+      verify: ['radius', 'width'],
+    },
+    {
+      role: 'marker',
+      radius: '999px',
+      width: 'none',
+      when: 'the status dot, sized at 6px',
+    },
+  ],
+  motion:
+    'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',
+  iconography:
+    'No icon library is installed. The surfaces draw literal glyph characters, `✦` for the hero mark and `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing, and a custom icon has no place to load from.',
+}
+/** A role's value, or `undefined` where the record declares no such role. */
+export function colorValue(role: string): string | undefined {
+  return TOKENS.color.find((token) => token.role === role)?.value
+}
+/**
+ * The adapter the slide renderer takes. `PptxGenJS` receives color as
+ * `{ color: theme.background }` and wants six hex digits with no leading `#`,
+ * so the shared thing is the value and this is the per-consumer form.
+ *
+ * The hex is raised to upper case because that is the spelling
+ * `src/slides/styles.ts` has always written, and the only one a diff of a
+ * rendered deck reads cleanly against.
+ */
+export function bareHex(value: string): string {
+  return value.replace(/^#/, '').toUpperCase()
+}

package/src/gate/stages.ts CHANGED Viewed

@@ -209,6 +209,34 @@ 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.
+    id: 'design',
+    label: 'Design',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['design', 'regen'],
+        failure: 'Design regen failed',
+      },
+      {
+        kind: 'drift',
+        pathspec: '.claude/DESIGN.md',
+        failure:
+          'The design record drifted from the token source. Run bun run check and commit .claude/DESIGN.md.',
+      },
+      {
+        kind: 'drift',
+        pathspec: 'src/design/base.css',
+        failure:
+          'The base stylesheet drifted from the token source. Run bun run check and commit src/design/base.css.',
+      },
+    ],
+    success: 'Design source clean',
+  },
   {
     // The claude manifest is the only route a target's ignore set travels, and
     // it is hand-maintained beside this repository's own `.gitignore` with

package/src/migrate/records.ts CHANGED Viewed

@@ -10,7 +10,12 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { type RecordRoot, RECORD_ENTRIES, spell } from '@/record-root'
+import {
+  type RecordRoot,
+  RECORD_ENTRIES,
+  RECORD_ROOTS,
+  spell,
+} from '@/record-root'
 /** The root the entries below leave, exported so the writer can prune it. */
 export const FROM_ROOT: RecordRoot = '.claude'
@@ -104,6 +109,66 @@ export function isExcludedPath(path: string): boolean {
   return EXCLUDED_SUFFIXES.some((suffix) => path.endsWith(suffix))
 }
+/**
+ * The roots holding nothing but records, so a path under one is a record
+ * whatever it is named.
+ *
+ * `.canon/` qualifies by construction. `.claude/ARCHITECTURE.md` fixes the rule
+ * that every gitignored session record moves there and nothing tracked ever
+ * lands there, which covers a record folder `RECORD_ENTRIES` has yet to learn
+ * about. The old root is the one that cannot take a whole-root reading, and it
+ * is derived by exclusion rather than named, so a third root added later reads
+ * as records-only unless someone says otherwise.
+ */
+const RECORD_ONLY_ROOTS: readonly RecordRoot[] = RECORD_ROOTS.filter(
+  (root) => root !== FROM_ROOT,
+)
+/**
+ * Every prefix under which a path is a record rather than a file to sweep.
+ *
+ * The asymmetry is the point. A whole-root prefix is correct for the new root
+ * and wrong for the old one, which is mixed: this repository tracks 163 files
+ * under `.claude/`, and a target's installed `.claude/rules/core/035-tasks.md`
+ * is the file the sweep exists to repoint, so a bare `.claude/` prefix strands
+ * it silently. The old root is therefore entry-scoped, through `spell` so the
+ * one naming variant stays decided in `record-root.ts`.
+ *
+ * Joined with a literal separator rather than through `join`, the way
+ * `EXCLUDED_PREFIXES` already is. These are matched against what `git ls-files`
+ * returns, which is forward-slashed on every platform, where `join` would spell
+ * a backslash on Windows and match nothing.
+ */
+const RECORD_PREFIXES: readonly string[] = [
+  ...RECORD_ONLY_ROOTS,
+  ...RECORD_ENTRIES.map((entry) => `${FROM_ROOT}/${spell(FROM_ROOT, entry)}`),
+]
+/**
+ * Whether a path is a record artifact, which the sweep passes over entirely.
+ *
+ * Separate from `isExcludedPath`, which reports what it skips because a reader
+ * has to check those by hand. A record artifact is never something to check,
+ * and a target's record tree is large enough that reporting each one would bury
+ * the handful of exclusions that matter.
+ *
+ * A record folder becomes visible to the sweep at the moment `canon tooling
+ * sync claude` prunes the twelve old ignore entries down to one `.canon/` line,
+ * which is the step the documented first-run order puts immediately before this
+ * verb. Without this predicate the run that follows reads the memory pen and
+ * the groundwork trails as source and rewrites them.
+ *
+ * The three retired flat archives stay outside this, the way `CITATION` already
+ * leaves them alone: `.claude/plans-archive/x.md` does not start with
+ * `.claude/plans/`, and widening the entry list to catch it would change what
+ * `MOVED_ENTRIES` means for the folder half of the verb.
+ */
+export function isRecordArtifact(path: string): boolean {
+  return RECORD_PREFIXES.some(
+    (prefix) => path === prefix || path.startsWith(`${prefix}/`),
+  )
+}
 /**
  * Marks a line naming the old root on purpose.
  *
@@ -244,6 +309,11 @@ export function planRecordsMove(
   let kept = 0
   for (const source of sources) {
+    // Silently, and ahead of the exclusion test. The command boundary filters
+    // these out before it reads them, so this is what keeps the pure function
+    // correct under a direct call rather than what the verb relies on.
+    if (isRecordArtifact(source.path)) continue
     if (isExcludedPath(source.path)) {
       // Only an excluded file that actually carries a citation is reported. The
       // predicate covers every test file in the tree, so counting them all would

package/src/slides/styles.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+import { bareHex, colorValue } from '@/design/tokens'
 export type Variant = 'light' | 'dark'
 export interface Theme {
@@ -8,20 +10,17 @@ export interface Theme {
   accent: string
 }
-const LIGHT: Theme = {
-  background: 'FAF7F2',
-  surface: 'F4EFE6',
-  ink: '1A1815',
-  muted: '7A736A',
-  accent: 'A4471C',
-}
-const DARK: Theme = {
-  background: '1A1815',
-  surface: '23201C',
-  ink: 'F4EFE6',
-  muted: 'A39C92',
-  accent: 'C8602E',
+/**
+ * Which role in `@/design/tokens` fills each slot of a slide theme. The names
+ * differ because a deck names a slot by what sits in it and the record names a
+ * role by what it is for, and mapping the two here is the whole of the adapter.
+ */
+const ROLES: Record<keyof Theme, readonly [dark: string, light: string]> = {
+  background: ['background', 'light-background'],
+  surface: ['surface', 'light-surface'],
+  ink: ['text', 'light-text'],
+  muted: ['text-secondary', 'light-muted'],
+  accent: ['accent', 'light-accent'],
 }
 export const FONTS = {
@@ -39,6 +38,34 @@ export const TYPE = {
   caption: 11,
 } as const
+/**
+ * Builds a theme from the design source in the form this renderer can take.
+ *
+ * `src/slides/render.ts` hands color to `PptxGenJS` as `{ color: theme.background }`
+ * and PowerPoint has no concept of a custom property, so the shared thing is the
+ * value and bare hex is the per-consumer form. Every CSS surface takes the same
+ * values through `@/design/css` instead.
+ *
+ * A role the record does not declare throws rather than rendering a slide in a
+ * default nobody chose, since a missing color reaches a reader as a deck that
+ * looks wrong with nothing saying why.
+ */
 export function buildTheme(variant: Variant): Theme {
-  return variant === 'dark' ? DARK : LIGHT
+  const pick = (slot: keyof Theme): string => {
+    const role = ROLES[slot][variant === 'dark' ? 0 : 1]
+    const value = colorValue(role)
+    if (value === undefined) {
+      throw new Error(`The design record declares no ${role} role`)
+    }
+    return bareHex(value)
+  }
+  return {
+    background: pick('background'),
+    surface: pick('surface'),
+    ink: pick('ink'),
+    muted: pick('muted'),
+    accent: pick('accent'),
+  }
 }

package/src/sync/check.ts CHANGED Viewed

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { basename, join, sep } from 'node:path'
 import { execa } from 'execa'
 import { gitEnv } from '@/git-env'
+import { createDesignAdapter, DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { createGovAdapter, rulesSourceDir } from '@/gov/adapter'
 import { loadGovStack, resolveMissingRules, resolveRules } from '@/gov/stacks'
 import { planSync, type ScanEntry, type SyncAdapter } from '@/sync/engine'
@@ -36,9 +37,16 @@ import { readSkew, type SkewReport } from '@/version/skew'
  * three lookups below have no entry to offer it. Standards and snippets left
  * the list with their install channels: nothing writes either corpus into a
  * target, so there is no installed copy to attribute.
+ *
+ * Design joins as a scanned domain rather than a stamp-only one because its
+ * base file is attributed the same way a rule is, and its install marker is
+ * what keeps it off a target that never asked for it: a project with no
+ * `.claude/design/` is never scanned, so design values arrive on an install
+ * rather than on the next sync.
  */
 export const SCANNED_DOMAINS = [
   'governance',
+  'design',
 ] as const satisfies readonly StampDomain[]
 export type ScannedDomain = (typeof SCANNED_DOMAINS)[number]
@@ -50,14 +58,17 @@ export type ScannedDomain = (typeof SCANNED_DOMAINS)[number]
  */
 const SYNCED_SOURCES: Record<ScannedDomain, string> = {
   governance: 'governance/rules/',
+  design: 'src/design/',
 }
 const ADAPTERS: Record<ScannedDomain, (root: string) => SyncAdapter> = {
   governance: createGovAdapter,
+  design: createDesignAdapter,
 }
 const INSTALL_MARKERS: Record<ScannedDomain, readonly string[]> = {
   governance: ['.claude', 'rules'],
+  design: DESIGN_INSTALL_DIR.split(sep),
 }
 export interface StateCounts {
@@ -187,6 +198,36 @@ export interface CheckReport {
   readonly skew: SkewReport
 }
+/**
+ * Scanned domains a target takes deliberately rather than by being managed.
+ *
+ * An absent one is a choice, so it is never reported as unstamped. Governance
+ * wants the opposite reading, since a managed target without it has yet to
+ * install what every project is expected to carry, and naming it is the only
+ * place that shows up.
+ */
+export const OPT_IN_DOMAINS: readonly ScannedDomain[] = ['design']
+/**
+ * Scanned domains this target should have stamped and has not, which is the
+ * one line a domain nobody installed ever appears on.
+ *
+ * An unmigrated domain is excluded because the relocation is its remedy rather
+ * than a sync, and an opt-in domain the target does not hold is excluded
+ * because there is nothing there to stamp and the sync it would name refuses.
+ */
+export function uncoveredDomains(report: CheckReport): ScannedDomain[] {
+  const unmigrated = new Set(report.unmigrated.map((entry) => entry.domain))
+  const installed = new Set(report.domains.map((entry) => entry.domain))
+  return SCANNED_DOMAINS.filter(
+    (domain) =>
+      !report.covers.includes(domain) &&
+      !unmigrated.has(domain) &&
+      (!OPT_IN_DOMAINS.includes(domain) || installed.has(domain)),
+  )
+}
 export function installedStampDomains(target: string): ScannedDomain[] {
   return SCANNED_DOMAINS.filter((domain) =>
     isDirectory(join(target, ...INSTALL_MARKERS[domain])),