WORK-053
ID:WORK-053Status:ready

CSS Fallback Resolution for Third-Party Packages

Priority:mediumComplexity:moderateMilestone:v1.0.0Source:SPEC-001

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

History

  1. 59ded4a
    Content edited
  2. f262d7b
    source+SPEC-001
  3. 2637549
    milestonev0.9.0v1.0.0
  4. a129a9e
    milestone+v0.9.0
  5. 2f24c14
    Created (ready, medium, moderate, sveltekit, packages, css)