WORK-186
ID:WORK-186Status:done

Highlighter token rename: --shiki-* → --rf-syntax-*

Stop leaking the underlying highlighter into the public token surface. Today eleven --shiki-* custom properties sit in packages/lumina/tokens/base.css alongside --rf-* tokens, and per-rune CSS reads them directly — swapping Shiki for Prism, Starry Night, or a server-side alternative is currently a breaking change for every downstream theme and any custom user CSS. After this work item, rune CSS reads only --rf-syntax-*; the highlighter integration writes those names.

Priority:highComplexity:smallMilestone:v0.14.0Source:SPEC-048
claude/v0.14.0-spec-048-foundation View source

Criteria completion

Criteria completion: 5 of 6 (83%) checked; tracking started on May 18, no incremental history yet0%25%50%75%100%May 18Jun 15

Tracking started May 18 — check back for trends.

Relationships

Implements 1
Related 5
Branches 2
claude/v0.14.0-spec-048-foundation current done
main doneclaude/spec-053-tint-authoring-notes ready
History 1
  1. a7947bb
    Created (done)by bjornolofandersson

Acceptance Criteria

  • All --shiki-* custom properties in packages/lumina/tokens/base.css and packages/lumina/tokens/dark.css renamed to --rf-syntax-* equivalents
  • Shiki integration in packages/highlight configured to emit --rf-syntax-* via createCssVariablesTheme({ variablePrefix: '--rf-syntax-' })
  • All per-rune CSS in packages/lumina/styles/runes/ that reads syntax tokens updated to --rf-syntax-* (audit found no per-rune CSS reading --shiki-* directly; only the central token files needed renames)
  • TokenContract.syntax namespace in WORK-185 types reflects the new vocabulary
  • CSS coverage tests in packages/lumina/test/css-coverage.test.ts updated to expect --rf-syntax-* selectors (no existing syntax-token coverage references to update; tests pass)
  • A documentation note (in the SPEC-048 docs page or migration guide) explains that the highlighter is now an implementation detail behind a stable contract — themes only see --rf-syntax-* (deferred — SPEC-048 reference page doesn't exist yet; migration note rolls up with WORK-210 in Chunk 8)

Approach

Pure rename with a small Shiki config change.

Mapping (canonical list, derive remaining from --shiki-* survey):

OldNew
--shiki-foreground--rf-syntax-text
--shiki-background--rf-syntax-bg
--shiki-token-keyword--rf-syntax-keyword
--shiki-token-function--rf-syntax-function
--shiki-token-string--rf-syntax-string
--shiki-token-number--rf-syntax-number
--shiki-token-constant--rf-syntax-constant
--shiki-token-comment--rf-syntax-comment
--shiki-token-punctuation--rf-syntax-punctuation
--shiki-token-link--rf-syntax-link
--shiki-token-string-expression--rf-syntax-string-expression

(Audit the actual --shiki-* names in lumina before locking the mapping; the table above is illustrative.)

Configure Shiki with cssVariablePrefix: '--rf-syntax-' if its API supports a flat prefix, or with an explicit token-name map if it requires the longer form.

Verify by running cd site && npm run build, then loading a docs page with a code block and inspecting computed styles — confirm code blocks render identically.

Dependencies

  • WORK-185 — TokenContract.syntax namespace defined.

References

  • SPEC-048 — "Highlighter is an implementation detail" design principle
  • packages/lumina/tokens/base.css — current --shiki-* declarations
  • Shiki documentation for cssVariablePrefix configuration