vscode: typography tokens for the Codev Markdown Preview (artifact canvas)

[amrmelsayed]

Problem

The Codev Markdown Preview (the @cluesmith/codev-artifact-canvas surface mounted by MarkdownPreviewProvider) inherits its typography from the host with no overrides. The package's default-theme.css ships eight --codev-canvas-* tokens but they are colors only: there is no token (or CSS rule) controlling font-size, font-family, line-height, paragraph spacing, prose width, or heading scale.

In the VSCode webview that surfaces as:

1. Font size doesn't track the editor font. The preview falls through to the webview's default body style, which uses --vscode-font-size (the workbench UI font, ~13px), not --vscode-editor-font-size. A reviewer who has bumped their editor font for readability sees no change in the preview, which is surprising for a surface that reads like a document.
2. Line-height is tight (~1.4) and inherited from the editor. Long-form prose (specs, plans, reviews) feels cramped because the inherited line-height is tuned for code, not paragraphs.
3. No paragraph rhythm, no prose-width cap, no heading-scale ratio. Headings, paragraphs, lists, and code blocks all fall through to user-agent defaults filtered through VSCode's webview styles, none of which are optimized for sustained reading.
4. No knobs. Nothing exposes any of these for tuning at the host or user level. The only available levers are global workbench zoom and the UI font setting, both of which affect the entire IDE chrome.

The eight --codev-canvas-* tokens from #945 were colors-only by design (spec 945 D4 capped the v1 token vocabulary at colors), but the canvas now has real consumers (#859 preview, #863 markers + minimap) and the v1 limit is hitting daily readability.

Proposal

Extend the canvas theming contract with a typography token tier so prose reads cleanly across hosts. GitHub's github-markdown-css metrics are the chosen baseline (it's the familiar mental model for reviewers reading PRs all day in the same area).

Tiers, in increasing order of completeness:

1. Package tokens (canvas package). Add to default-theme.css:

   • --codev-canvas-font-size (prose body, default ~16px to align with github-markdown-css)
   • --codev-canvas-font-family (prose body, GitHub-style system stack: -apple-system, BlinkMacSystemFont, "Segoe UI", ...)
   • --codev-canvas-line-height (default ~1.5)
   • --codev-canvas-paragraph-spacing (default 1em between paragraphs; lists / blockquotes / tables / pre derive from this)
   • --codev-canvas-prose-max-width (default ~72ch as an optional cap; off by default if cap breaks the host layout)
   • --codev-canvas-heading-scale-base and a scale ratio (h1…h6 either computed from the ratio or as per-level tokens; plan-gate decision)
   • --codev-canvas-code-font-family (monospace stack for pre / inline code)
   • --codev-canvas-code-font-size (default ~85% of prose, matching github-markdown-css)

   The exact final list is a plan-gate decision: too few leaves the same problem under a new name; too many bloats the public contract.

2. Host mapping (VSCode preview-template). preview-template.ts binds the package tokens to documented VSCode-theme defaults where appropriate (e.g. --codev-canvas-code-font-family: var(--vscode-editor-font-family) so code blocks track the editor font; prose tokens use the github-style stack rather than VSCode's UI font). Each binding choice gets documented inline.

3. User settings (VSCode). Expose codev.markdownPreview.fontSize, codev.markdownPreview.lineHeight, etc. as VSCode settings wired to the corresponding tokens. Tier 3 is nice-to-have, not gating.

Design notes (lock at plan-approval)

• Token granularity for headings. Two viable patterns: explicit per-element tokens (--codev-canvas-h1-size, --codev-canvas-h2-size, etc.) or scale-base + ratio (--codev-canvas-heading-scale: 1.25 with h1 computed via calc()). Lean: scale + ratio for headings, explicit tokens for paragraph and code.
• Reference baseline pinning. github-markdown-css evolves; document which commit / version's metrics we mirror so the baseline is reproducible.
• VSCode-theme alignment vs prose-readability defaults. When the VSCode editor font is set unusually (very small, monospace), should our preview override or inherit? Lean: prose-readability defaults override VSCode's editor font for prose; --codev-canvas-code-* tokens still align to the editor font for code blocks (same convention github-markdown-css follows: monospace for code, sans for prose).
• Dark-mode handling. No new tokens for dark mode; the existing color tokens already cover that. Typography tokens are theme-invariant.
• types.ts contract amendment. Spec 945 D4 calls the public token vocabulary "the locked public contract from spec-945, do not change shapes without a spec amendment." This expansion warrants a short spec amendment recorded in the issue, plan, and review (the docs-only commit is fine; no protocol gate beyond that).

Acceptance criteria

• default-theme.css exposes the typography tokens above (final list locked at plan-approval) with github-markdown-css-aligned defaults
• types.ts token-vocabulary contract amended with a spec-amendment doc trail to include the new tokens
• preview-template.ts binds the tokens to VSCode-theme defaults where appropriate; binding choices documented inline
• Prose in the markdown preview visibly reads with the new line-height, paragraph spacing, and font-size (versus the cramped v3.2.0 baseline)
• Headings render with a deliberate scale (not user-agent defaults)
• Code blocks remain monospace and track the VSCode editor font where the binding chooses that
• No regression to marker rendering (vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap #863), minimap, comment cards, or color theming
• Vitest snapshot covering the default-theme.css token list passes
• (Tier 3, if shipped) codev.markdownPreview.* settings registered in package.json and documented
• Manual dev-approval verification: open a long spec or plan in the preview, walk through readability before / after; resize the pane and confirm prose-max-width behavior matches the design call

Out of scope

• Floating TOC, quick-jump, per-heading toolbar (vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861, separate)
• Document-state surfaces (reading progress, AC progress, status badges) (vscode: markdown preview document-state surfaces — reading progress, AC progress, frontmatter status badges, reading time #862, separate)
• Marker / minimap rendering changes (vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap #863, shipped)
• Dashboard host wiring (the canvas gains the tokens; the dashboard adopts them when it renders the canvas later)
• Font subsetting / web-fonts (canvas v2)

Why PIR

Typography choices are "looks right in unit test, wrong in actual reading." Dev-approval visual review of a real spec or plan in the running preview is load-bearing for picking the right defaults. Plan-approval also needs to lock the token vocabulary deliberately, per types.ts's "locked public contract" guidance, before any code lands.

Related

• Build foundational reusable package @cluesmith/codev-artifact-canvas for cross-surface markdown artifact review #945, locked 8-token color vocabulary this extends (spec 945 D4)
• vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap #863, marker rendering + minimap (deliberately excluded typography; this issue picks it up)
• vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859, CustomTextEditor preview that owns the webview
• vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861, floating TOC + quick-jump chrome (separate UI layer)
• vscode: markdown preview document-state surfaces — reading progress, AC progress, frontmatter status badges, reading time #862, document-state surfaces (separate)
• vscode: edit + preview-side delete on review comments (make the markdown reviewer functional) #1055, comment system v2 (separate)

[amrmelsayed]

Scope expanded from font-size-only to the full typography token vocabulary (line-height, paragraph spacing, prose-max-width, heading scale, code-font tokens), with github-markdown-css as the chosen baseline. Originally-deferred typography concerns from the prior "Out of scope" section folded back in. Recommended protocol updated to PIR (visual dev-approval verification is load-bearing for typography). See updated body for full details.

[amrmelsayed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).