best-practices: Styling (self-host your stylesheet)

[topkoa]

Summary

Third of four gap-closing PRs. Adds a "Styling" section. The app's compiled stylesheet only contains the utility classes the bundled code uses — so a plugin installed at runtime (plugin manager, shared folder, community) renders unstyled unless it ships its own CSS. A shipping blocker that wasn't covered.

Rules (38–39)

• 38 — Ship your own compiled stylesheet via styles. Point styles at a compiled CSS file (under assets/) containing every class your screen needs. Don't assume a utility class exists because the app uses a similar one — especially arbitrary-value utilities (w-[37px], bg-slate-800/50) that are generated on demand and almost never in the app's sheet. Ship the compiled output, not a config.
• 39 — Build it to coexist. Base/preflight reset off (corePlugins.preflight = false) so you don't re-style the whole app; selectors scoped to your screen (rule 10); never the Tailwind Play CDN or a runtime CSS-in-JS/JIT (slow, unavailable offline — feedBack is local-first, recompiles on the main thread); bump version to cache-bust the sheet.

Added a "Styling" checklist block; Shipping renumbered to 40–44 (contiguous 1–44).

Scope & stacking

Docs only. Stacked on #10. Full stack: … → #9 → #10 → #11 (one more: diagnostics). mkdocs build --strict + check_versions.py pass.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ed066e0e-9c31-4c9e-8da7-0f59d99675d3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/best-practices-styling

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds best-practice guidance for plugin styling so runtime-installed plugins don’t render unstyled due to missing utility classes in the Host’s compiled stylesheet.

Changes:

• Introduces a new Styling section with rules to ship a compiled plugin stylesheet via styles.
• Documents coexistence constraints (disable global reset, scope selectors, avoid CDN/runtime CSS engines, bump version to cache-bust assets).
• Updates Shipping rule numbering and adds a matching styling checklist block; records the change in CHANGELOG.md.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
spec/best-practices.md	Adds “Styling” rules (38–39), renumbers “Shipping” (40–44), and extends the publish checklist with styling guidance.
CHANGELOG.md	Notes the addition of the new “Styling” best-practices section and its key requirements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.