@erclx/aitk 1.3.0 → 1.5.0

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.