WORK-053
ID:WORK-053Status:ready

CSS Fallback Resolution for Third-Party Packages

Priority:mediumComplexity:moderateMilestone:v1.0.0
claude/align-sidenav-styling-4MuxV View source

Criteria completion

No incremental history — criteria tracking started on Apr 17.

Relationships

Implements 1
Related 1
Branches 3
claude/align-sidenav-styling-4MuxV current ready
claude/file-naming-convention-LJdwR readymain readychangeset-release/main ready
History 3
  1. 2637549
    Content editedby Björn Andersson
    chore(plan): create v1.0.0 milestone, complete v0.9.0, fix acceptance cr
  2. a129a9e
    Content editedby Claude
    Assign all new work items (WORK-051–068) to v0.9.0 milestone
  3. 2f24c14
    Created (ready)by Claude
    Add work items for SPEC-001 and SPEC-002

Summary

Third-party community packages (e.g., @refrakt-community/dnd-5e) may ship default CSS as a fallback. When a theme (like Lumina) doesn't provide CSS for a community rune, the pipeline should fall back to the package's own styles/ directory. The resolution order is: theme CSS first, package CSS second.

Currently the SvelteKit plugin's CSS tree-shaking only checks the theme directory. It needs to also check the source package when no theme CSS exists.

Acceptance Criteria

  • SvelteKit plugin checks theme's styles/runes/{block}.css first for each rune
  • If no theme CSS exists and the rune comes from a third-party package, check the package's styles/runes/{block}.css
  • CSS from the winning source is imported into the build
  • assembleThemeConfig provenance map is used to locate the source package directory
  • refrakt inspect --audit reports which rune CSS comes from the theme vs. package fallback
  • Official packages (@refrakt-md/*) are not affected — they ship zero CSS, Lumina provides all their styling

Approach

  1. In the SvelteKit plugin's CSS tree-shaking logic, after checking the theme directory and finding no match, consult the provenance map from assembleThemeConfig to find the source package
  2. If the source package has a styles/runes/ directory with a matching CSS file, import that as fallback
  3. Theme authors can override any package fallback CSS by placing their own file with the same block name in their styles/runes/ directory
  4. The audit output in refrakt inspect should distinguish between theme-provided and package-fallback CSS coverage

References

  • SPEC-001 (Community Runes — Theme Integration)
  • WORK-001 (Official Rune Packages — CSS handling)