@erclx/canon 4.8.0 → 4.9.0

package/src/design/components.ts

@@ -0,0 +1,118 @@
+/**
+ * The component layer, beside the token layer in `@/design/tokens`.
+ *
+ * A token says what a value is and a component says what a repeated piece of
+ * interface is made of. The two repairs that produced this layer are both cases
+ * where the tokens were already right and the surface still read as unrelated
+ * to itself, so a token file alone would not have caught either.
+ *
+ * It has two members and it is provisional at two. Two repairs is thin evidence
+ * for an abstraction, and the honest position is a layer that says it has two
+ * rather than one padded out with speculative members to look settled. A third
+ * real instance is what decides whether the shape below holds.
+ *
+ * It does not live in `.claude/DESIGN.md`. `standards/design.md` keeps CSS class
+ * names out of that record and says they live in code, which is here.
+ */
+
+export interface Component {
+  readonly name: string
+  /** Why the component exists, carried into the emitted stylesheet as a comment. */
+  readonly note: string
+  /** Custom properties this component reads, so a consumer can check it has them. */
+  readonly reads: readonly string[]
+  readonly rules: string
+}
+
+/**
+ * A dot and a word, never a bordered chip. The jump menus already said written
+ * and planned with a filled or hollow dot, so a status badge that spelled the
+ * same fact in uppercase inside a border was a second vocabulary for something
+ * the system already had one of.
+ */
+const STATUS: Component = {
+  name: 'status',
+  note: [
+    'A dot and a word, not a pill. A bordered uppercase chip is a second',
+    'vocabulary for a fact the dot already carries, so the marker is the only',
+    'status shape and `.is-done` is the only variant.',
+  ].join('\n   '),
+  reads: [
+    '--color-border',
+    '--color-accent',
+    '--color-muted',
+    '--radius-marker',
+  ],
+  rules: `.status {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.42rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  letter-spacing: 0;
+  text-transform: none;
+  color: var(--color-muted);
+  white-space: nowrap;
+}
+
+.status::before {
+  content: '';
+  width: 6px;
+  height: 6px;
+  flex: none;
+  border-radius: var(--radius-marker);
+  background: var(--color-border);
+}
+
+.status.is-done::before {
+  background: var(--color-accent);
+}`,
+}
+
+/**
+ * Every scrolling region, the page included. Scoping this to one component is
+ * what left an outline rail, code blocks, and scrolling tables on the browser
+ * default beside a styled sibling, which reads as two designs on one page.
+ */
+const SCROLLBAR: Component = {
+  name: 'scrollbar',
+  note: [
+    'Every scrolling region takes the same bar, the page included. Scoping it',
+    'to one component leaves its neighbors on the browser default, which is',
+    'what reads as two designs on one page. `scrollbar-color` covers Firefox',
+    'and the `::-webkit-` rules cover the rest, both from the same two tokens',
+    'so the two engines cannot drift apart.',
+  ].join('\n   '),
+  reads: ['--color-border', '--color-muted', '--color-background'],
+  rules: `* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-border) transparent;
+}
+
+*::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+
+*::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+*::-webkit-scrollbar-thumb {
+  border-radius: var(--radius-marker);
+  background: var(--color-border);
+  /* Inset by painting a border in the page color, which is what keeps the
+     thumb off the edges without a second element. */
+  border: 3px solid var(--color-background);
+}
+
+*::-webkit-scrollbar-thumb:hover {
+  background: var(--color-muted);
+}
+
+*::-webkit-scrollbar-corner {
+  background: transparent;
+}`,
+}
+
+export const COMPONENTS: readonly Component[] = [STATUS, SCROLLBAR]

package/src/design/contrast.ts

@@ -0,0 +1,81 @@
+import type { ColorToken } from '@/design/tokens'
+import { TOKENS } from '@/design/tokens'
+
+/** WCAG 2.1 AA for body copy. Every role a surface renders as text clears it. */
+export const AA_TEXT = 4.5
+
+/** WCAG 2.1 AA for a large or non-text element, kept as the floor a reading is read against. */
+export const AA_NON_TEXT = 3
+
+const HEX = /^#[0-9a-fA-F]{6}$/
+
+/**
+ * Relative luminance per WCAG 2.1. Only six-digit hex is accepted, since the
+ * record also carries ANSI codes that no ratio applies to and silently reading
+ * one as a color would report a passing number for a value nothing renders.
+ */
+export function luminance(hex: string): number {
+  if (!HEX.test(hex)) throw new Error(`Not a six-digit hex color: ${hex}`)
+
+  const channels = [1, 3, 5].map(
+    (start) => parseInt(hex.slice(start, start + 2), 16) / 255,
+  )
+  const linear = channels.map((channel) =>
+    channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4,
+  )
+
+  return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2]
+}
+
+/** The WCAG ratio between two colors, lighter over darker, from 1 to 21. */
+export function contrastRatio(a: string, b: string): number {
+  const [lighter, darker] = [luminance(a), luminance(b)].sort(
+    (first, second) => second - first,
+  )
+
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+export interface Reading {
+  readonly role: string
+  readonly ground: string
+  readonly ratio: number
+  readonly passes: boolean
+}
+
+/**
+ * Every reading the record declares, one per role and ground pair. A role
+ * naming no ground contributes none, which is what keeps a ground itself and
+ * the three ANSI roles out of the set rather than measured against something
+ * they never sit on.
+ */
+export function readings(
+  tokens: readonly ColorToken[] = TOKENS.color,
+): Reading[] {
+  const values = new Map(tokens.map((token) => [token.role, token.value]))
+  const out: Reading[] = []
+
+  for (const token of tokens) {
+    for (const ground of token.grounds ?? []) {
+      const behind = values.get(ground)
+      if (behind === undefined) {
+        throw new Error(`${token.role} names an unknown ground: ${ground}`)
+      }
+
+      const ratio = contrastRatio(token.value, behind)
+      out.push({
+        role: token.role,
+        ground,
+        ratio,
+        passes: ratio >= AA_TEXT,
+      })
+    }
+  }
+
+  return out
+}
+
+/** Readings below AA, which is the list the test asserts is empty. */
+export function failing(tokens?: readonly ColorToken[]): Reading[] {
+  return readings(tokens).filter((reading) => !reading.passes)
+}

package/src/design/css.ts

@@ -0,0 +1,142 @@
+import { COMPONENTS } from '@/design/components'
+import type { DesignTokens } from '@/design/tokens'
+import { TOKENS } from '@/design/tokens'
+
+/**
+ * The form a CSS surface takes the source in. Custom properties carry the token
+ * layer and plain rules carry the component layer, which is the whole of what a
+ * stylesheet needs from `@/design/tokens` and `@/design/components`.
+ *
+ * The property names match the ones `@/design/render` already emits from a
+ * parsed document, so the toolkit's own source and a target's hand-authored
+ * `.claude/DESIGN.md` produce one vocabulary rather than two.
+ */
+
+/** A role name as it appears in a custom property. */
+export function slug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+}
+
+/** Only a value a browser can render becomes a property. ANSI codes do not. */
+function hasHexValue(value: string): boolean {
+  return value !== '' && !value.startsWith('ANSI')
+}
+
+/**
+ * Dark role each `light-` role stands in for. Read off the names rather than
+ * declared twice, so a light role added to the record joins the theme block
+ * with no edit here.
+ */
+function lightCounterparts(tokens: DesignTokens): Map<string, string> {
+  const roles = new Set(tokens.color.map((token) => token.role))
+  const pairs = new Map<string, string>()
+
+  for (const token of tokens.color) {
+    if (!token.role.startsWith('light-')) continue
+    const dark = token.role.slice('light-'.length)
+    if (roles.has(dark)) pairs.set(dark, token.role)
+  }
+
+  return pairs
+}
+
+/**
+ * Text roles with no light counterpart, named in the emitted stylesheet rather
+ * than filled in. Inventing a value for one would put a color in the system
+ * that no surface ever read off anything, which is the failure this whole
+ * consolidation exists to end.
+ */
+export function unmappedOnLight(tokens: DesignTokens = TOKENS): string[] {
+  const pairs = lightCounterparts(tokens)
+
+  return tokens.color
+    .filter(
+      (token) =>
+        !token.role.startsWith('light-') &&
+        hasHexValue(token.value) &&
+        !pairs.has(token.role),
+    )
+    .map((token) => token.role)
+}
+
+function tokenProperties(tokens: DesignTokens): string[] {
+  const lines: string[] = []
+
+  for (const token of tokens.color) {
+    if (!hasHexValue(token.value)) continue
+    lines.push(`  --color-${slug(token.role)}: ${token.value};`)
+  }
+
+  for (const step of tokens.spacing) {
+    lines.push(`  --space-${slug(step.step)}: ${step.value};`)
+  }
+
+  for (const role of tokens.typography) {
+    lines.push(`  --type-${slug(role.role)}-size: ${role.size};`)
+    lines.push(`  --type-${slug(role.role)}-lh: ${role.lineHeight};`)
+  }
+
+  for (const border of tokens.borders) {
+    if (border.radius === 'none') continue
+    lines.push(`  --radius-${slug(border.role)}: ${border.radius};`)
+  }
+
+  return lines
+}
+
+/**
+ * The light theme, as a remap of the roles the record declares a `light-`
+ * counterpart for. A consumer that never opts in renders the dark set, which is
+ * what every surface here does today.
+ */
+function lightBlock(tokens: DesignTokens): string {
+  const pairs = [...lightCounterparts(tokens)]
+    .map(
+      ([dark, light]) =>
+        `  --color-${slug(dark)}: var(--color-${slug(light)});`,
+    )
+    .join('\n')
+
+  const gap = unmappedOnLight(tokens)
+  const notice =
+    gap.length === 0
+      ? ''
+      : `/* The record declares no light counterpart for ${gap.join(', ')}, so\n   a light-ground surface using one is reading a dark value. Declare the\n   counterpart in src/design/tokens.ts rather than overriding it here. */\n`
+
+  return `${notice}[data-theme='light'] {
+${pairs}
+}`
+}
+
+function componentBlock(): string {
+  return COMPONENTS.map(
+    (component) => `/* ${component.name}
+   ${component.note} */
+
+${component.rules}`,
+  ).join('\n\n')
+}
+
+export interface CssOptions {
+  /** Prepended as a comment, naming what wrote the file and from where. */
+  readonly banner?: string
+  /** Component rules ride along by default; a token-only consumer opts out. */
+  readonly components?: boolean
+}
+
+export function buildDesignCss(
+  tokens: DesignTokens = TOKENS,
+  options: CssOptions = {},
+): string {
+  const banner =
+    options.banner === undefined ? '' : `/* ${options.banner} */\n\n`
+  const root = [':root {', ...tokenProperties(tokens), '}'].join('\n')
+  const parts = [root, lightBlock(tokens)]
+
+  if (options.components !== false) parts.push(componentBlock())
+
+  return `${banner}${parts.join('\n\n')}\n`
+}

package/src/design/document.ts

@@ -0,0 +1,143 @@
+import type {
+  BorderToken,
+  ColorToken,
+  DesignTokens,
+  SpaceToken,
+  TypeToken,
+} from '@/design/tokens'
+import { TOKENS } from '@/design/tokens'
+
+/**
+ * Renders `.claude/DESIGN.md` from the token source.
+ *
+ * The document is the view and `@/design/tokens` is the fact, which is the one
+ * thing that changed when this record stopped being a transcript of two other
+ * surfaces. A reader opening the document reads what the surfaces render,
+ * because both come from the same module.
+ *
+ * Tables are emitted the way Prettier serializes them, padded to the widest
+ * cell in each column, so the formatting stage and this writer agree and the
+ * file has one shape rather than two writers fighting over it.
+ */
+
+/** The tag a cell carries when no rendering surface exercises its value yet. */
+const VERIFY = ' ? verify'
+
+const MIN_COLUMN = 3
+
+export function formatTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[],
+): string {
+  const widths = headers.map((header, column) =>
+    Math.max(
+      MIN_COLUMN,
+      header.length,
+      ...rows.map((row) => (row[column] ?? '').length),
+    ),
+  )
+
+  const line = (cells: readonly string[]): string =>
+    `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(' | ')} |`
+
+  return [
+    line(headers),
+    `| ${widths.map((width) => '-'.repeat(width)).join(' | ')} |`,
+    ...rows.map(line),
+  ].join('\n')
+}
+
+function tag(value: string, tagged: boolean | undefined): string {
+  return tagged === true ? `${value}${VERIFY}` : value
+}
+
+function colorRows(tokens: readonly ColorToken[]): string[][] {
+  return tokens.map((token) => [
+    token.role,
+    token.intent,
+    tag(token.value, token.verify),
+  ])
+}
+
+function typeRows(tokens: readonly TypeToken[]): string[][] {
+  return tokens.map((token) => {
+    const tagged = new Set(token.verify ?? [])
+    return [
+      token.role,
+      tag(token.family, tagged.has('family')),
+      tag(token.weight, tagged.has('weight')),
+      tag(token.size, tagged.has('size')),
+      tag(token.lineHeight, tagged.has('lineHeight')),
+    ]
+  })
+}
+
+function spaceRows(tokens: readonly SpaceToken[]): string[][] {
+  return tokens.map((token) => [token.step, token.multiplier, token.value])
+}
+
+function borderRows(tokens: readonly BorderToken[]): string[][] {
+  return tokens.map((token) => {
+    const tagged = new Set(token.verify ?? [])
+    return [
+      token.role,
+      tag(token.radius, tagged.has('radius')),
+      tag(token.width, tagged.has('width')),
+      token.when,
+    ]
+  })
+}
+
+function section(heading: string, ...blocks: string[]): string {
+  return [`## ${heading}`, ...blocks.filter((block) => block !== '')].join(
+    '\n\n',
+  )
+}
+
+export function renderDesignDocument(tokens: DesignTokens = TOKENS): string {
+  const body = [
+    '# Design',
+    '',
+    'Authoring guidance: `standards/design.md`.',
+    '',
+    tokens.preamble,
+    '',
+    section('Personality', tokens.personality),
+    '',
+    section(
+      'Color',
+      tokens.colorNote,
+      formatTable(['Role', 'Intent', 'Value'], colorRows(tokens.color)),
+    ),
+    '',
+    section(
+      'Typography',
+      tokens.typographyNote,
+      formatTable(
+        ['Role', 'Family', 'Weight', 'Size', 'Line height'],
+        typeRows(tokens.typography),
+      ),
+    ),
+    '',
+    section(
+      'Spacing',
+      tokens.spacingNote,
+      formatTable(['Step', 'Multiplier', 'Value'], spaceRows(tokens.spacing)),
+    ),
+    '',
+    section(
+      'Borders',
+      tokens.bordersNote,
+      formatTable(
+        ['Role', 'Radius', 'Width', 'When used'],
+        borderRows(tokens.borders),
+      ),
+    ),
+    '',
+    section('Motion', tokens.motion),
+    '',
+    section('Iconography', tokens.iconography),
+  ]
+
+  return `${body.join('\n')}\n`
+}

package/src/design/regen.ts

@@ -0,0 +1,56 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { buildDesignCss } from '@/design/css'
+import { renderDesignDocument } from '@/design/document'
+
+/**
+ * The two artifacts the token source produces, written by `canon design regen`
+ * and asserted for drift by the `design` stage of `bun run check`.
+ *
+ * The document is what a person reads and the stylesheet is what a target
+ * installs, and neither is edited by hand. That is the cost the operator took
+ * on when the tokens moved into a module: two artifacts where the record used
+ * to be one, and a regen step that has to run or both go stale silently. The
+ * gate stage is what keeps silently out of it.
+ */
+
+/** The rendered record, at the path `standards/design.md` fixes for it. */
+export const DESIGN_DOCUMENT = join('.claude', 'DESIGN.md')
+
+/**
+ * The base stylesheet a target installs. It sits inside `src/` because that is
+ * the folder the published package ships, and beside the module that writes it
+ * because a generated file kept away from its generator is one nobody thinks to
+ * regenerate.
+ */
+export const DESIGN_BASE_CSS = join('src', 'design', 'base.css')
+
+const BASE_BANNER = [
+  'Generated by `canon design regen` from src/design/tokens.ts. Do not edit.',
+  'This is the base half of a design install. A target overrides a value in',
+  '.claude/design/project/, which the three-way merge leaves alone, so this',
+  'file changes freely and nothing a project wrote lives in it.',
+].join('\n   ')
+
+export interface RegenResult {
+  readonly documentPath: string
+  readonly cssPath: string
+}
+
+function write(root: string, rel: string, body: string): string {
+  const path = join(root, rel)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, body)
+  return path
+}
+
+export function regenDesign(root: string): RegenResult {
+  return {
+    documentPath: write(root, DESIGN_DOCUMENT, renderDesignDocument()),
+    cssPath: write(
+      root,
+      DESIGN_BASE_CSS,
+      buildDesignCss(undefined, { banner: BASE_BANNER }),
+    ),
+  }
+}

package/src/design/render.ts

@@ -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, '"')
 }
 
+/**
+ * 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>