@erclx/aitk 1.3.0 → 1.4.0

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

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

package/docs/agents/output-shape.md

@@ -46,6 +46,19 @@ Help skips the banner. The `Usage:` line sits directly on `├`. Help writes to
 
 `--json` and `--names` keep stdout clean and machine-readable. The frame still renders on stderr (open, banner, close) so the stream discipline is consistent across modes. Consumers that only read stdout see pure data.
 
+## Color
+
+Escape sequences reach a destination that renders them and nowhere else. The question is asked per stream rather than once for the process, so a run piping its data while keeping a terminal on stderr still gets color on the frame.
+
+Either condition alone turns color off:
+
+- `NO_COLOR` is set to any non-empty value, whatever that value says
+- The destination is not a terminal, which covers a pipe, a file, and a captured session
+
+The frame survives both. `┌`, `│`, `├`, `└`, and the `✓ ! + - ✗` marks are structure rather than color, and they are what lets a captured run still read as one block. A caller wanting neither the frame nor the color reads `--json` instead.
+
+Terminal control is a separate question this section does not cover. The cursor and key sequences an interactive prompt writes run only where a terminal already exists.
+
 ## Process exit
 
 A command action sets `process.exitCode` and returns. Calling `process.exit()` there ends the process before a stdout write drains, which truncates piped output at the 64K pipe buffer while still reporting the right exit code. Redirecting to a file hides the truncation, so it surfaces only through a pipe, which is what a check has to use to catch it.

package/docs/visual-design-workflow.md

@@ -24,6 +24,8 @@ The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table
 
 The `aitk:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `aitk design render` writes an HTML plus CSS preview to `.claude/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/context/design.md`.
 
+A cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
+
 ### Tools
 
 - None beyond Claude Code itself

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -28,12 +28,12 @@ import { register as sessions } from '@/commands/sessions'
 import { register as audits } from '@/commands/audits'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
-
-const GREY = '\x1b[0;90m'
-const WHITE = '\x1b[1;37m'
-const NC = '\x1b[0m'
+import { palette } from '@/ui'
 
 function showHelp(): void {
+  // The help text is the one framed surface written to stdout, so it asks
+  // about that stream rather than the stderr every other writer here uses.
+  const { GREY, NC, WHITE } = palette(process.stdout)
   const lines = [
     `${GREY}┌${NC}`,
     `${GREY}├${NC} ${WHITE}Usage:${NC} aitk [command]`,

package/src/commands/claude.ts

@@ -44,16 +44,13 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   pipeOutput,
   plural,
   select,
 } from '@/ui'
 import { describeSkew, readSkew, type SkewReport } from '@/version/skew'
 
-const GREEN = '\x1b[0;32m'
-const GREY = '\x1b[0;90m'
-const NC = '\x1b[0m'
-
 interface SeedsListOptions {
   readonly json?: boolean
   readonly names?: boolean
@@ -266,6 +263,7 @@ export function register(program: Command): void {
 }
 
 function succeed(message: string): number {
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(`${GREEN}✓ ${message}${NC}\n`)
   return 0
@@ -472,6 +470,7 @@ async function runSeedsList(opts: SeedsListOptions): Promise<number> {
     return 0
   }
 
+  const { GREY, NC } = palette(process.stderr)
   intro('aitk claude')
   logStep('Seed docs')
   for (const listing of listings) {
@@ -531,6 +530,7 @@ async function runSkillsDrift(
     // is the moment a skew warning is worth most, since an old binary is one
     // reason the cache and the CLI disagree in the first place.
     if (skew.state === 'behind') {
+      const { GREY, NC } = palette(process.stderr)
       process.stderr.write(`${GREY}${describeSkew(skew)}${NC}\n`)
     }
   }

package/src/commands/design.ts

@@ -2,12 +2,7 @@ import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { renderDesignDoc } from '@/design/render'
-
-const GREY = '\x1b[0;90m'
-const WHITE = '\x1b[1;37m'
-const RED = '\x1b[0;31m'
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
+import { palette } from '@/ui'
 
 export function register(program: Command): void {
   const design = program
@@ -22,6 +17,7 @@ export function register(program: Command): void {
     .action((opts: { source: string; out: string }) => {
       const sourcePath = resolve(process.cwd(), opts.source)
       const outDir = resolve(process.cwd(), opts.out)
+      const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
       if (!existsSync(sourcePath)) {
         process.stderr.write(
           `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${opts.source} not found\n${GREY}└${NC}\n`,

package/src/commands/feedback.ts

@@ -4,10 +4,7 @@ import type { Command } from 'commander'
 import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
 import { PROJECT_ROOT } from '@/project-root'
 import { createGithubIssue } from '@/github'
-import { frameError, frameSuccess } from '@/ui'
-
-const YELLOW = '\x1b[0;33m'
-const NC = '\x1b[0m'
+import { frameError, frameSuccess, palette } from '@/ui'
 
 function readStdin(): Promise<string> {
   return new Promise((resolveStream, rejectStream) => {
@@ -88,6 +85,7 @@ export function register(program: Command): void {
           process.exitCode = 1
           return
         }
+        const { NC, YELLOW } = palette(process.stderr)
         process.stderr.write(
           `${YELLOW}! gh unavailable, wrote local scratch instead${NC}\n`,
         )

package/src/commands/gov.ts

@@ -30,12 +30,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
 const RULES_REL = join('.claude', 'rules')
 
@@ -461,6 +459,7 @@ async function runInstall(
     )
   }
 
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(`${GREEN}✓ Rules installed${NC}\n`)
   return 0
@@ -510,6 +509,7 @@ async function runBuild(target: string): Promise<number> {
   await writeFile(output, buildRulesPayload(files))
   logAdd(PAYLOAD_REL)
 
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(
     `${GREEN}✓ Rules built (${files.length} rules → ${PAYLOAD_REL})${NC}\n`,

package/src/commands/init.ts

@@ -6,11 +6,7 @@ import { type InitFlags, parseSkip, planInit } from '@/init/plan'
 import { runDomains } from '@/init/run'
 import { buildSteps } from '@/init/steps'
 import { resolveTarget } from '@/target'
-import { intro, logInfo, logStep, logWarn, outro, select } from '@/ui'
-
-const GREEN = '\x1b[0;32m'
-const YELLOW = '\x1b[0;33m'
-const NC = '\x1b[0m'
+import { intro, logInfo, logStep, logWarn, outro, palette, select } from '@/ui'
 
 interface InitOptions {
   /** Always present: the option falls back to `DEFAULT_STACK`. */
@@ -107,6 +103,8 @@ async function runInit(
   outro()
   process.stderr.write('\n')
 
+  const { GREEN, NC, YELLOW } = palette(process.stderr)
+
   if (failed.length === 0) {
     process.stderr.write(
       `${GREEN}✓ Project initialized (${plan.total} domains)${NC}\n`,

package/src/commands/slides.ts

@@ -5,12 +5,7 @@ import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
 import type { Variant } from '@/slides/styles'
-import { intro, outro } from '@/ui'
-
-const GREY = '\x1b[0;90m'
-const GREEN = '\x1b[0;32m'
-const RED = '\x1b[0;31m'
-const NC = '\x1b[0m'
+import { intro, outro, palette } from '@/ui'
 
 export function register(program: Command): void {
   const slides = program
@@ -44,6 +39,7 @@ export function register(program: Command): void {
           }
           const variant = parseVariant(opts.variant)
           const mirror = resolveMirror(opts.mirror)
+          const { GREEN, GREY, NC, RED } = palette(process.stderr)
           intro('Render slides')
           const result = await renderSlidesDoc(sourcePath, outDir, {
             variant,
@@ -81,6 +77,7 @@ export function register(program: Command): void {
         process.stdout.write(`${JSON.stringify(LAYOUTS)}\n`)
         return
       }
+      const { GREEN, GREY, NC } = palette(process.stderr)
       intro('Slide layouts')
       for (const layout of LAYOUTS) {
         process.stderr.write(
@@ -121,6 +118,7 @@ function fail(message: string): never {
  */
 function reportFailure(error: unknown): void {
   if (!(error instanceof SlidesError)) throw error
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${error.message}\n${GREY}└${NC}\n`,
   )

package/src/commands/snippets.ts

@@ -21,12 +21,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 const SNIPPETS_REL = '.claude/snippets'
 
 const PASS_THROUGH_VERBS = ['create'] as const
@@ -180,6 +178,7 @@ async function runInstall(
   }
   await recordStamp(createSnippetsAdapter(PROJECT_ROOT), resolved, new Date())
 
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(`${GREEN}✓ Snippets installed${NC}\n`)
   return 0

package/src/commands/standards.ts

@@ -21,13 +21,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const GREY = '\x1b[0;90m'
-const NC = '\x1b[0m'
-
 interface InstallOptions {
   /** Always present: the option falls back to `ALL_SELECTION`. */
   readonly only: string
@@ -196,6 +193,7 @@ async function runInstall(target: string, selection: string): Promise<number> {
   await recordStamp(createStandardsAdapter(PROJECT_ROOT), resolved, new Date())
 
   outro()
+  const { GREEN, GREY, NC } = palette(process.stderr)
   process.stderr.write(
     `\n${GREEN}✓ Standards installed${NC} ${GREY}(${files.length} files)${NC}\n`,
   )

package/src/commands/sync.ts

@@ -29,13 +29,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
 } from '@/ui'
 import { describeSkew } from '@/version/skew'
 
-const GREY = '\x1b[0;90m'
-const YELLOW = '\x1b[0;33m'
-const NC = '\x1b[0m'
-
 const SYNC_ARGS: Record<SyncDomain, readonly string[]> = {
   standards: ['standards', 'sync'],
   snippets: ['snippets', 'sync'],
@@ -180,6 +177,7 @@ function renderCheck(report: CheckReport): void {
   )
   if (uncovered.length === 0) return
 
+  const { GREY, NC } = palette(process.stderr)
   process.stderr.write(
     `${GREY}Unstamped: ${uncovered.join(', ')}. Run the matching sync to record one.${NC}\n`,
   )
@@ -338,6 +336,7 @@ async function runSync(target: string): Promise<number> {
   if (typeof resolved === 'number') return resolved
 
   const git = createGitRunner(resolved)
+  const { GREY, NC, YELLOW } = palette(process.stderr)
 
   logStep('Checking working tree')
   if (!isTreeClean(await git.status([]))) {

package/src/commands/tooling.ts

@@ -28,12 +28,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 const PASS_THROUGH_VERBS = ['ref', 'create', 'verify'] as const
 
 interface SyncOptions {
@@ -256,6 +254,7 @@ async function runSync(
   report(result, includeReferences)
 
   const mode = resolveWriteMode(opts)
+  const { GREEN, NC } = palette(process.stderr)
 
   if (result.totalChanges === 0) {
     // The stamp is a write like any other, so a run with no authority to write

package/src/commands/transcripts.ts

@@ -1,12 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { ensureYtDlp, fetchOne } from '@/transcripts/fetch'
-
-const GREY = '\x1b[0;90m'
-const WHITE = '\x1b[1;37m'
-const RED = '\x1b[0;31m'
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
+import { palette } from '@/ui'
 
 interface TranscriptOptions {
   out: string
@@ -24,6 +19,7 @@ export function register(program: Command): void {
     )
     .action(async (url: string, opts: TranscriptOptions) => {
       const outDir = resolve(process.cwd(), opts.out)
+      const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
       process.stderr.write(
         `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}aitk transcripts${NC}\n`,
       )

package/src/commands/wiki.ts

@@ -9,6 +9,7 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 import {
@@ -20,9 +21,6 @@ import {
   WIKI_INDEX_REL,
 } from '@/wiki/init'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 export function register(program: Command): void {
   const wiki = program
     .command('wiki')
@@ -59,6 +57,7 @@ async function runInit(target: string): Promise<number> {
   }
 
   const plan = planWikiInit(resolved)
+  const { GREEN, NC } = palette(process.stderr)
 
   logStep(`Scanning ${WIKI_DIR_REL}`)
   if (plan.changes.includes('dir')) logAdd(WIKI_DIR_REL)

package/src/design/parse.ts

@@ -1,6 +1,19 @@
 import { readFileSync } from 'node:fs'
 
-export type Row = Record<string, string>
+/**
+ * One table cell, split into the value a renderer emits and whether the record
+ * marked it as unsourced.
+ *
+ * The marker sits inside the cell rather than in a trailing column, because a
+ * trailing marker breaks the table parse. Splitting it out here is what keeps a
+ * swatch or a font sample built from the value alone.
+ */
+export interface Cell {
+  value: string
+  tagged: boolean
+}
+
+export type Row = Record<string, Cell>
 
 export interface DesignDoc {
   personality: string
@@ -12,6 +25,11 @@ export interface DesignDoc {
   iconography: string
 }
 
+const VERIFY_TAG = /\s*\?\s*verify\s*$/
+
+/** A cell whose whole content is one balanced code span and nothing else. */
+const CODE_SPAN = /^`([^`]*)`$/
+
 export function parseDesignDoc(path: string): DesignDoc {
   const raw = readFileSync(path, 'utf8')
   const sections = splitSections(raw)
@@ -58,22 +76,41 @@ function table(body: string | undefined): Row[] {
   if (!body) return []
   const rows = body.split('\n').filter((l) => l.trim().startsWith('|'))
   if (rows.length < 2) return []
-  const headers = splitRow(rows[0])
+  const headers = splitRow(rows[0]).map((c) => c.value)
   const data = rows.slice(2)
   return data.map((line) => {
     const cells = splitRow(line)
     const row: Row = {}
     headers.forEach((h, i) => {
-      row[h] = (cells[i] ?? '').trim()
+      row[h] = cells[i] ?? emptyCell()
     })
     return row
   })
 }
 
-function splitRow(line: string): string[] {
+function emptyCell(): Cell {
+  return { value: '', tagged: false }
+}
+
+function splitRow(line: string): Cell[] {
   return line
     .replace(/^\s*\|/, '')
     .replace(/\|\s*$/, '')
     .split('|')
-    .map((c) => c.trim().replace(/\s*\?\s*verify\s*$/, ''))
+    .map(parseCell)
+}
+
+/**
+ * The tag is tested against the cell with any surrounding code span removed,
+ * since a value wrapping itself in backticks puts one after the tag and an
+ * end-anchored test misses it there. The span is restored around the clean
+ * value so an untagged cell and a tagged one carry the same formatting.
+ */
+function parseCell(raw: string): Cell {
+  const trimmed = raw.trim()
+  const span = trimmed.match(CODE_SPAN)
+  const inner = span ? span[1] : trimmed
+  if (!VERIFY_TAG.test(inner)) return { value: trimmed, tagged: false }
+  const value = inner.replace(VERIFY_TAG, '')
+  return { value: span ? `\`${value}\`` : value, tagged: true }
 }

package/src/design/render.ts

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import type { DesignDoc, Row } from '@/design/parse'
+import type { Cell, DesignDoc, Row } from '@/design/parse'
 import { parseDesignDoc } from '@/design/parse'
 
 export interface RenderResult {
@@ -28,29 +28,99 @@ function slug(s: string): string {
     .replace(/(^-|-$)/g, '')
 }
 
+function cell(row: Row, key: string): Cell {
+  return row[key] ?? { value: '', tagged: false }
+}
+
+/** The value alone. Every swatch, sample, and custom property is built from it. */
+function val(row: Row, key: string): string {
+  return cell(row, key).value
+}
+
+/** The marker, rendered beside a value rather than inside it. */
+function mark(row: Row, key: string): string {
+  return cell(row, key).tagged
+    ? ' <span class="verify" title="No source anchors this value">? verify</span>'
+    : ''
+}
+
+/** A displayed cell: its escaped text, then its marker when it carries one. */
+function cellText(row: Row, key: string): string {
+  return escape(val(row, key)) + mark(row, key)
+}
+
+interface Confidence {
+  tagged: number
+  total: number
+}
+
+/**
+ * The columns the confidence ratio reads, fixed by `standards/design.md`. The
+ * first column of each table names its row, and `Multiplier` and `When used`
+ * restate what the row already carries, so none of them is something a source
+ * could anchor and none belongs in the denominator.
+ */
+const ANCHORABLE = {
+  borders: ['Radius', 'Width'],
+  color: ['Intent', 'Value'],
+  spacing: ['Value'],
+  typography: ['Family', 'Weight', 'Size', 'Line height'],
+} as const
+
+/**
+ * A cell counts when it carries a tag, or when it holds a value in a column a
+ * source could anchor. A blank the record left unfilled is neither, and so is a
+ * row name. Counting a tagged cell whichever column it sits in is what keeps a
+ * marker the preview draws from sitting outside the ratio printed beside it.
+ */
+function confidence(doc: DesignDoc): Confidence {
+  const tables: ReadonlyArray<readonly [Row[], readonly string[]]> = [
+    [doc.color, ANCHORABLE.color],
+    [doc.typography, ANCHORABLE.typography],
+    [doc.spacing, ANCHORABLE.spacing],
+    [doc.borders, ANCHORABLE.borders],
+  ]
+  let tagged = 0
+  let total = 0
+  for (const [rows, columns] of tables) {
+    for (const row of rows) {
+      for (const [key, c] of Object.entries(row)) {
+        if (!c.tagged && (!c.value || !columns.includes(key))) continue
+        total += 1
+        if (c.tagged) tagged += 1
+      }
+    }
+  }
+  return { tagged, total }
+}
+
 function buildCss(doc: DesignDoc): string {
   const lines: string[] = [':root {']
   for (const row of doc.color) {
-    if (row['Value']) {
-      lines.push(`  --color-${slug(row['Role'])}: ${row['Value']};`)
+    if (val(row, 'Value')) {
+      lines.push(`  --color-${slug(val(row, 'Role'))}: ${val(row, 'Value')};`)
     }
   }
   for (const row of doc.spacing) {
-    if (row['Value']) {
-      lines.push(`  --space-${slug(row['Step'])}: ${row['Value']};`)
+    if (val(row, 'Value')) {
+      lines.push(`  --space-${slug(val(row, 'Step'))}: ${val(row, 'Value')};`)
     }
   }
   for (const row of doc.typography) {
-    if (row['Size']) {
-      lines.push(`  --type-${slug(row['Role'])}-size: ${row['Size']};`)
+    if (val(row, 'Size')) {
+      lines.push(
+        `  --type-${slug(val(row, 'Role'))}-size: ${val(row, 'Size')};`,
+      )
     }
-    if (row['Line height']) {
-      lines.push(`  --type-${slug(row['Role'])}-lh: ${row['Line height']};`)
+    if (val(row, 'Line height')) {
+      lines.push(
+        `  --type-${slug(val(row, 'Role'))}-lh: ${val(row, 'Line height')};`,
+      )
     }
   }
   for (const row of doc.borders) {
-    if (row['Radius']) {
-      lines.push(`  --radius-${slug(row['Role'])}: ${row['Radius']};`)
+    if (val(row, 'Radius')) {
+      lines.push(`  --radius-${slug(val(row, 'Role'))}: ${val(row, 'Radius')};`)
     }
   }
   lines.push('}')
@@ -75,6 +145,14 @@ function buildHtml(doc: DesignDoc): string {
     sectionLine('Motion', doc.motion),
     sectionLine('Iconography', doc.iconography),
   ]
+  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; }'
+    : ''
+  const verb = tagged === 1 ? 'carries' : 'carry'
+  const summary = tagged
+    ? `\n<p class="note">${total - tagged} of ${total} cells are anchored to a source. The other ${tagged} ${verb} <code>? verify</code>, so nothing anchors them yet.</p>`
+    : ''
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -91,12 +169,12 @@ function buildHtml(doc: DesignDoc): string {
   .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; }
+  .empty { color: #999; font-style: italic; }${verifyStyle}
 </style>
 </head>
 <body>
 <h1>Design tokens</h1>
-<p class="note">Generated from <code>.claude/DESIGN.md</code> by <code>aitk design render</code>. Token preview only, not a screen mock.</p>
+<p class="note">Generated from <code>.claude/DESIGN.md</code> by <code>aitk design render</code>. Token preview only, not a screen mock.</p>${summary}
 ${sections.join('\n')}
 </body>
 </html>
@@ -112,11 +190,12 @@ function sectionColor(rows: Row[]): string {
   if (!rows.length) return ''
   const body = rows
     .map((r) => {
-      const swatch = r['Value']
-        ? `<span class="swatch" style="background:${escape(r['Value'])}"></span>`
+      const value = val(r, 'Value')
+      const swatch = value
+        ? `<span class="swatch" style="background:${escape(value)}"></span>`
         : '<span class="swatch"></span>'
-      const value = r['Value'] || '<span class="empty">unset</span>'
-      return `<tr><td>${swatch}${escape(r['Role'] ?? '')}</td><td>${escape(r['Intent'] ?? '')}</td><td><code>${value}</code></td></tr>`
+      const shown = value ? escape(value) : '<span class="empty">unset</span>'
+      return `<tr><td>${swatch}${cellText(r, 'Role')}</td><td>${cellText(r, 'Intent')}</td><td><code>${shown}</code>${mark(r, 'Value')}</td></tr>`
     })
     .join('\n')
   return `<h2>Color</h2>\n<table><thead><tr><th>Role</th><th>Intent</th><th>Value</th></tr></thead><tbody>${body}</tbody></table>`
@@ -126,12 +205,12 @@ function sectionTypography(rows: Row[]): string {
   if (!rows.length) return ''
   const body = rows
     .map((r) => {
-      const family = r['Family'] || 'system-ui'
-      const weight = r['Weight'] || '400'
-      const size = r['Size'] || '16px'
-      const lh = r['Line height'] || '1.4'
+      const family = val(r, 'Family') || 'system-ui'
+      const weight = val(r, 'Weight') || '400'
+      const size = val(r, 'Size') || '16px'
+      const lh = val(r, 'Line height') || '1.4'
       const sample = `<span style="font-family:${escape(family)};font-weight:${escape(weight)};font-size:${escape(size)};line-height:${escape(lh)}">The quick brown fox</span>`
-      return `<tr><td>${escape(r['Role'] ?? '')}</td><td>${escape(family)}</td><td>${escape(weight)}</td><td>${escape(size)}</td><td>${escape(lh)}</td><td>${sample}</td></tr>`
+      return `<tr><td>${cellText(r, 'Role')}</td><td>${escape(family)}${mark(r, 'Family')}</td><td>${escape(weight)}${mark(r, 'Weight')}</td><td>${escape(size)}${mark(r, 'Size')}</td><td>${escape(lh)}${mark(r, 'Line height')}</td><td>${sample}</td></tr>`
     })
     .join('\n')
   return `<h2>Typography</h2>\n<table><thead><tr><th>Role</th><th>Family</th><th>Weight</th><th>Size</th><th>Line height</th><th>Sample</th></tr></thead><tbody>${body}</tbody></table>`
@@ -141,11 +220,11 @@ function sectionSpacing(rows: Row[]): string {
   if (!rows.length) return ''
   const body = rows
     .map((r) => {
-      const value = r['Value'] || ''
+      const value = val(r, 'Value')
       const bar = value
         ? `<span class="bar" style="width:${escape(value)}"></span>`
         : '<span class="empty">unset</span>'
-      return `<tr><td>${escape(r['Step'] ?? '')}</td><td>${escape(r['Multiplier'] ?? '')}</td><td><code>${escape(value || 'unset')}</code></td><td>${bar}</td></tr>`
+      return `<tr><td>${cellText(r, 'Step')}</td><td>${cellText(r, 'Multiplier')}</td><td><code>${escape(value || 'unset')}</code>${mark(r, 'Value')}</td><td>${bar}</td></tr>`
     })
     .join('\n')
   return `<h2>Spacing</h2>\n<table><thead><tr><th>Step</th><th>Multiplier</th><th>Value</th><th>Sample</th></tr></thead><tbody>${body}</tbody></table>`
@@ -155,10 +234,10 @@ function sectionBorders(rows: Row[]): string {
   if (!rows.length) return ''
   const body = rows
     .map((r) => {
-      const radius = r['Radius'] || '0'
-      const width = r['Width'] || '1px'
+      const radius = val(r, 'Radius') || '0'
+      const width = val(r, 'Width') || '1px'
       const sample = `<span style="display:inline-block;width:2rem;height:1.5rem;background:#eee;border:${escape(width)} solid #888;border-radius:${escape(radius)};vertical-align:middle"></span>`
-      return `<tr><td>${escape(r['Role'] ?? '')}</td><td><code>${escape(radius)}</code></td><td><code>${escape(width)}</code></td><td>${escape(r['When used'] ?? '')}</td><td>${sample}</td></tr>`
+      return `<tr><td>${cellText(r, 'Role')}</td><td><code>${escape(radius)}</code>${mark(r, 'Radius')}</td><td><code>${escape(width)}</code>${mark(r, 'Width')}</td><td>${cellText(r, 'When used')}</td><td>${sample}</td></tr>`
     })
     .join('\n')
   return `<h2>Borders</h2>\n<table><thead><tr><th>Role</th><th>Radius</th><th>Width</th><th>When used</th><th>Sample</th></tr></thead><tbody>${body}</tbody></table>`

package/src/sync/engine.ts

@@ -22,12 +22,10 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 /**
  * One installed file in three path flavours: absolute, relative to the
  * domain's installed root, and relative to the target. Adapters match on
@@ -304,6 +302,7 @@ export async function runDomainSync(
   }
 
   const plan = planSync(adapter, resolved)
+  const { GREEN, GREY, NC } = palette(process.stderr)
 
   if (
     !existsSync(adapter.installedRoot(resolved)) &&
@@ -358,7 +357,7 @@ export async function runDomainSync(
 
   outro()
   process.stderr.write(
-    `${GREEN}✓ Sync complete${NC} \x1b[0;90m(${count} ${adapter.unit})${NC}\n`,
+    `${GREEN}✓ Sync complete${NC} ${GREY}(${count} ${adapter.unit})${NC}\n`,
   )
   return 0
 }

package/src/sync/workflow.ts

@@ -19,13 +19,11 @@ import {
   logStep,
   logWarn,
   outro,
+  palette,
   pipeOutput,
   select,
 } from '@/ui'
 
-const GREEN = '\x1b[0;32m'
-const NC = '\x1b[0m'
-
 const PROTECTED_BRANCHES: readonly string[] = ['main', 'master']
 
 export type WorkflowChoice = 'pr' | 'commit' | 'cancel'
@@ -195,6 +193,7 @@ function promptChoice(canOpenPullRequest: boolean): Promise<WorkflowChoice> {
 }
 
 function succeed(message: string): number {
+  const { GREEN, NC } = palette(process.stderr)
   outro()
   process.stderr.write(`\n${GREEN}✓ ${message}${NC}\n`)
   return 0

package/src/ui.ts

@@ -1,11 +1,60 @@
-const GREEN = '\x1b[0;32m'
-const RED = '\x1b[0;31m'
-const YELLOW = '\x1b[0;33m'
-const WHITE = '\x1b[1;37m'
-const GREY = '\x1b[0;90m'
-const NC = '\x1b[0m'
+export interface Palette {
+  readonly GREEN: string
+  readonly RED: string
+  readonly YELLOW: string
+  readonly WHITE: string
+  readonly GREY: string
+  readonly NC: string
+}
+
+const COLOR: Palette = {
+  GREEN: '\x1b[0;32m',
+  RED: '\x1b[0;31m',
+  YELLOW: '\x1b[0;33m',
+  WHITE: '\x1b[1;37m',
+  GREY: '\x1b[0;90m',
+  NC: '\x1b[0m',
+}
+
+/**
+ * The blank palette keeps every frame character and drops only the escapes, so
+ * a captured run still reads as one block.
+ */
+const PLAIN: Palette = {
+  GREEN: '',
+  RED: '',
+  YELLOW: '',
+  WHITE: '',
+  GREY: '',
+  NC: '',
+}
+
+/**
+ * `NO_COLOR` follows the published convention, where any non-empty value turns
+ * color off whatever the value says.
+ */
+export function supportsColor(stream: { isTTY?: boolean }): boolean {
+  const optOut = process.env.NO_COLOR
+  if (optOut !== undefined && optOut !== '') return false
+  return stream.isTTY === true
+}
+
+/**
+ * The question is asked per stream rather than once for the process. The framed
+ * output goes to stderr and a structured record to stdout, so a run piping only
+ * its data keeps a terminal on stderr and keeps its color there. This is a
+ * third question again from `isNonInteractive`, which answers whether a caller
+ * can be prompted rather than whether a destination renders escapes.
+ *
+ * Read at write time rather than at import, so nothing freezes an answer taken
+ * before the caller's environment was in place.
+ */
+export function palette(stream: { isTTY?: boolean }): Palette {
+  return supportsColor(stream) ? COLOR : PLAIN
+}
 
 export function intro(title: string): void {
+  const { GREY, NC, WHITE } = palette(process.stderr)
   process.stderr.write(`${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${title}${NC}\n`)
 }
 
@@ -15,18 +64,22 @@ export function intro(title: string): void {
  * leaving stdout clean for JSON and lists.
  */
 export function logInfo(message: string): void {
+  const { GREEN, GREY, NC } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${GREEN}✓${NC} ${message}\n`)
 }
 
 export function logWarn(message: string): void {
+  const { GREY, NC, YELLOW } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${YELLOW}!${NC} ${message}\n`)
 }
 
 export function logAdd(message: string): void {
+  const { GREEN, GREY, NC } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${GREEN}+${NC} ${message}\n`)
 }
 
 export function logRemove(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${RED}-${NC} ${message}\n`)
 }
 
@@ -36,14 +89,17 @@ export function logRemove(message: string): void {
  * exit code rather than terminating mid-write.
  */
 export function logError(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC} ${RED}✗${NC} ${message}\n`)
 }
 
 export function logStep(message: string): void {
+  const { GREY, NC, WHITE } = palette(process.stderr)
   process.stderr.write(`${GREY}│${NC}\n${GREY}├${NC} ${WHITE}${message}${NC}\n`)
 }
 
 export function outro(): void {
+  const { GREY, NC } = palette(process.stderr)
   process.stderr.write(`${GREY}└${NC}\n`)
 }
 
@@ -53,6 +109,7 @@ export function outro(): void {
  * such as a pull request body or the output of a git mutation.
  */
 export function pipeOutput(text: string): void {
+  const { GREY, NC } = palette(process.stderr)
   const lines = text.replace(/\n$/, '').split('\n')
   process.stderr.write(
     `${lines.map((line) => `${GREY}│${NC}  ${line}`).join('\n')}\n`,
@@ -65,12 +122,14 @@ export function plural(count: number, noun: string): string {
 }
 
 export function frameError(message: string): void {
+  const { GREY, NC, RED } = palette(process.stderr)
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,
   )
 }
 
 export function frameSuccess(command: string, target: string): void {
+  const { GREEN, GREY, NC, WHITE } = palette(process.stderr)
   process.stderr.write(
     `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}${command}${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${target}\n${GREY}└${NC}\n`,
   )
@@ -92,6 +151,7 @@ export async function select<Value>(opts: {
   nonInteractiveDefault?: boolean
 }): Promise<Value> {
   const { message, options } = opts
+  const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
   const count = options.length
   let cursor = 0
 

package/standards/design.md

@@ -34,6 +34,16 @@ Does not govern:
 - Plain English over technical notation. If a section could be removed and the developer would still build correctly from wireframes and code alone, remove it.
 - Keep table headers and role names intact so the render tooling can parse the token tables.
 
+## The uncertainty tag
+
+A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
+
+The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it. The preview also reports how many cells are anchored against how many are tagged, which is the reading a reviewer takes the record's overall confidence from.
+
+Which columns that ratio reads is fixed by the table rather than by the record. The first column of each table names its row, and `Multiplier` and `When used` restate what the row already carries, so none of them is something a source could anchor and none is counted. That leaves `Intent` and `Value` in Color, `Family`, `Weight`, `Size`, and `Line height` in Typography, `Value` in Spacing, and `Radius` and `Width` in Borders. A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
+
+A prose section takes its uncertainty inline instead, in a sentence saying what is proposed and what has yet to confirm it. A tag appended to a paragraph renders verbatim.
+
 ## Sections
 
 Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `## Motion`, and `## Iconography`. The token tables carry fixed headers the renderer reads.