@erclx/canon 4.8.1 → 4.9.0

package/src/design/tokens.ts

@@ -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

@@ -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/slides/styles.ts

@@ -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

@@ -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])),

package/src/sync/engine.ts

@@ -139,6 +139,8 @@ export interface SyncAdapter {
   collectMissing?(target: string): RetiredSurface[]
   /** Dropped from the walk, so neither matching nor orphaned. */
   isExcluded?(file: InstalledFile): boolean
+  /** Glob the walk lists. Defaults to `DEFAULT_INSTALL_PATTERN`. */
+  readonly installPattern?: string
   /**
    * Top-level folder under `installedRoot` that is project-authored by
    * location rather than by the name inference `locateSource` runs.
@@ -158,15 +160,26 @@ export interface SyncAdapter {
 }
 
 /**
- * Lists installed markdown, dotfiles included. `Bun.Glob` skips entries
- * beginning with a dot unless `dot` is set, and every domain installs under
- * `.claude/`, so a nested dot-directory would silently drop out of the walk.
+ * What a domain installs, when it installs something other than markdown.
+ * Design ships a stylesheet, and every other domain ships prose.
  */
-export function listInstalled(root: string, target: string): InstalledFile[] {
+export const DEFAULT_INSTALL_PATTERN = '**/*.md'
+
+/**
+ * Lists installed files matching the domain's pattern, dotfiles included.
+ * `Bun.Glob` skips entries beginning with a dot unless `dot` is set, and every
+ * domain installs under `.claude/`, so a nested dot-directory would silently
+ * drop out of the walk.
+ */
+export function listInstalled(
+  root: string,
+  target: string,
+  pattern: string = DEFAULT_INSTALL_PATTERN,
+): InstalledFile[] {
   if (!existsSync(root)) return []
 
   return [
-    ...new Bun.Glob('**/*.md').scanSync({
+    ...new Bun.Glob(pattern).scanSync({
       cwd: root,
       onlyFiles: true,
       dot: true,
@@ -192,7 +205,11 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
   const hashes = stampedHashes(readStamp(target), adapter.stamp?.domain)
   const walked = new Set<string>()
 
-  for (const file of listInstalled(adapter.installedRoot(target), target)) {
+  for (const file of listInstalled(
+    adapter.installedRoot(target),
+    target,
+    adapter.installPattern,
+  )) {
     if (adapter.isExcluded?.(file) === true) continue
     walked.add(toStampKey(file.rel))
 
@@ -562,7 +579,11 @@ export async function recordStamp(
 
   const hashes: Record<string, string> = {}
 
-  for (const file of listInstalled(adapter.installedRoot(target), target)) {
+  for (const file of listInstalled(
+    adapter.installedRoot(target),
+    target,
+    adapter.installPattern,
+  )) {
     if (adapter.isExcluded?.(file) === true) continue
     if (isProjectAuthored(adapter, file)) continue
 

package/src/sync/stamp.ts

@@ -6,16 +6,17 @@ import { execa } from 'execa'
 import { recordTarget } from '@/targets/registry'
 
 /**
- * Domains the stamp can record. Governance attributes file by file through the
- * sync engine. Tooling runs its own inject and manifest machinery, so it
- * records the stack chain it resolved instead and carries no file hashes.
+ * Domains the stamp can record. Governance and design both attribute file by
+ * file through the sync engine. Tooling runs its own inject and manifest
+ * machinery, so it records the stack chain it resolved instead and carries no
+ * file hashes.
  *
  * A stamp written before the standards or snippets install channel closed
  * still carries a `standards` or `snippets` record. `isStamp` ignores the key
  * and `sortDomains` drops it on the next write, so the target loses a domain
  * nothing can refresh rather than losing the whole file.
  */
-export const STAMP_DOMAINS = ['governance', 'tooling'] as const
+export const STAMP_DOMAINS = ['governance', 'design', 'tooling'] as const
 
 export type StampDomain = (typeof STAMP_DOMAINS)[number]
 

package/src/sync/target.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
+import { DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { isDirectory } from '@/target'
 
-export const SYNC_DOMAINS = ['governance', 'claude'] as const
+export const SYNC_DOMAINS = ['governance', 'design', 'claude'] as const
 
 export type SyncDomain = (typeof SYNC_DOMAINS)[number]
 
@@ -13,6 +14,7 @@ export interface DomainState {
 
 const DOMAIN_MARKERS: Record<SyncDomain, string> = {
   governance: join('.claude', 'rules'),
+  design: DESIGN_INSTALL_DIR,
   claude: '.claude',
 }
 
@@ -24,6 +26,7 @@ const DOMAIN_MARKERS: Record<SyncDomain, string> = {
  */
 const DOMAIN_PATHS: Record<SyncDomain, readonly string[]> = {
   governance: ['.claude/rules/', '.claude/GOV.md'],
+  design: ['.claude/design/'],
   claude: ['.gitignore'],
 }
 

package/src/teach/workspace.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
+import { buildDesignCss } from '@/design/css'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { type BodyLine, bodyLines } from '@/markdown/scan'
 import { recordDir } from '@/record-root'
@@ -841,3 +842,59 @@ export async function defineTerms(
 
   return { ok: true, slug: found.slug, path, defined: terms }
 }
+
+export interface StylesheetWritten {
+  readonly ok: true
+  readonly slug: string
+  /** Relative to the root, so a caller prints a path a reader can open. */
+  readonly path: string
+  /** False when the workspace already held one and this call left it alone. */
+  readonly written: boolean
+}
+
+export type StylesheetOutcome = StylesheetWritten | TeachRefused
+
+const STYLESHEET_BANNER = [
+  'Seeded by `canon teach stylesheet` from the design source in',
+  'src/design/tokens.ts. The tokens and the two components below are the',
+  'system this workspace renders in. Add lesson rules under them and read a',
+  'value through its custom property rather than restating the hex, which is',
+  'what let one workspace fork the palette from every other.',
+].join('\n   ')
+
+/**
+ * Writes a workspace's one stylesheet from the design source.
+ *
+ * Every workspace used to carry a hand-authored copy, which is how the course
+ * palette forked once per workspace. The name is fixed at `TEACH_STYLESHEET`
+ * and the folder at `TEACH_ASSETS` for the same reason a second lesson has to
+ * reach the file the first one wrote, and this is what puts the values in it.
+ *
+ * An existing stylesheet is left alone rather than replaced. A workspace adds
+ * lesson rules to this file as it goes, so overwriting would discard them, and
+ * `--force` is the caller saying it wants the seed back.
+ */
+export async function writeStylesheet(
+  root: string,
+  selector: string,
+  force = false,
+): Promise<StylesheetOutcome> {
+  const found = await readWorkspace(root, selector)
+  if (!found.ok) return found
+
+  const workspace = found.workspace
+  const rel = join(workspace.path, TEACH_ASSETS, TEACH_STYLESHEET)
+  const path = join(root, rel)
+
+  if (existsSync(path) && !force) {
+    return { ok: true, slug: workspace.slug, path: rel, written: false }
+  }
+
+  await mkdir(join(root, workspace.path, TEACH_ASSETS), { recursive: true })
+  await writeFile(
+    path,
+    buildDesignCss(undefined, { banner: STYLESHEET_BANNER }),
+  )
+
+  return { ok: true, slug: workspace.slug, path: rel, written: true }
+}