WORK-186
Setting up your dashboard 0 entities found · 8/33 branches scanned
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
main View source

Criteria completion

Criteria completion: 2 of 6 (33%) checked; history from May 18 to May 180%25%50%75%100%May 18May 18

Relationships

Implements 1
Related 5
Branches 2
main current done
claude/v0.14.0-spec-048-foundation doneclaude/spec-053-tint-authoring-notes ready
History 4
  1. cd8fa11
    • ☑ All `--shiki-*` custom properties in `packages/lumina/tokens/base.css` and `packages/lumina/tokens/dark.css` renamed to `--rf-syntax-*` equivalents
    • ☑ `TokenContract.syntax` namespace in {% ref "WORK-185" /%} types reflects the new vocabulary
    by bjornolofandersson
  2. a7947bb
    Content editedby Claude
    v0.14.0 Chunk 1: SPEC-048 foundation (WORK-185, 186, 189-types)
  3. 3b92415
    Created (ready)by bjornolofandersson
  4. f73346a
    Content editedby Claude
    plan: add v0.14.0 milestone and SPEC-048 work items (WORK-185 to 191)

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