WORK-095
ID:WORK-095Status:ready

Vite plugin — virtual CSS module and tree-shaking

Implement virtual:refrakt/styles module that imports theme tokens, per-rune CSS, and package CSS. Supports tree-shaking to include only CSS for runes actually used in content.

Priority:highComplexity:simpleMilestone:v1.0.0Source:SPEC-031
main View source

Criteria completion

No incremental history — criteria tracking started on Apr 21.

Relationships

Implements 1
Related 1
Branches 3
main current ready
claude/file-naming-convention-LJdwR readymain readychangeset-release/main ready

Acceptance Criteria

  • virtual:refrakt/styles module resolves and loads CSS in correct order: base tokens → per-rune structural CSS → package rune CSS → user overrides
  • When injectCSS: true (default), plugin auto-imports the virtual module
  • When injectCSS: false, user imports virtual:refrakt/styles manually
  • At build time, CSS tree-shaking includes only CSS for runes found in content (via analyzeRuneUsage)
  • tint.css is always included (universal attribute)
  • Theme base CSS is always included
  • Community package CSS is included when their runes are used
  • Dev server serves full CSS (no tree-shaking) for fast iteration
  • Test: build with subset of runes, verify only their CSS is included

Approach

  1. Implement src/virtual-css.ts — generates CSS import list based on theme config and rune usage
  2. Hook into resolveId / load for virtual:refrakt/styles module ID
  3. Reuse analyzeRuneUsage() from @refrakt-md/content for tree-shaking at build time
  4. Reference packages/sveltekit/src/virtual-modules.ts for the existing virtual:refrakt/tokens pattern

Dependencies

  • WORK-094 — core plugin must exist first

References

  • SPEC-031 (CSS Strategy section)
  • packages/sveltekit/src/virtual-modules.ts — existing virtual module pattern
  • packages/lumina/styles/runes/ — per-rune CSS files