daybook/issues/017-customizable-document-theme-variants.md

017 — Customizable, switchable theme variants for document artifacts

Status: Open Type: Feature / design (not a bug)

Motivation

Document artifacts (markdown, html_fragment, deck, and the json/csv viewers) are effectively locked into a single look. The poster's agent can pass a theme (report / tasks / base), but:

• There's no way for a viewer to switch an artifact's appearance — the theme is fixed at post time and can't even be changed afterward (theme isn't a PATCH-editable field; see ArtifactDetailView.patch).
• There are only three document themes, differing in more than just color.
• Recent consistency work (unifying artifact backgrounds to one off-white, issue-driven) further homogenized the look — good for consistency, but it underlines that everyone gets one palette whether they want it or not.

The ask: let people customize the colors for the different document types, keeping the same structural CSS (same elements/selectors, same layout), and provide a way to switch between variants — so the app isn't forcing a single theme on everyone.

Current state (for grounding)

• theme is a per-artifact CharField, set at create time: theme = data.get("theme") or DEFAULT_THEMES.get(kind, "base") (DEFAULT_THEMES maps markdown/html_fragment→report, deck→deck).
• Rendered pages link /static/themes/{theme}.css. Theme files: base.css, report.css, tasks.css, deck.css (+ pygments.css).
• The theme CSS hardcodes colors (e.g. report.css sets background: #faf9f6; color: #1e2b2f directly). There is no color-variable layer, so a new palette today means duplicating a whole theme file rather than swapping a few values.
• json/csv viewer styling is worse for this: it's inlined into each artifact's stored HTML at create time (wrap_json_viewer/ wrap_csv_viewer), so it can't be restyled after the fact at all without re-rendering.

Two separable pieces

1. Structure/skin separation (prerequisite). Refactor the document themes so structural rules (layout, spacing, element selectors, code highlighting) are defined once, and color lives in CSS custom properties. A "palette" then becomes a small set of variable values, not a duplicated stylesheet. This is the same pattern the app chrome already uses (daybook.css :root + [data-theme="dark"]); the artifact themes just never adopted it. Without this, "customizable colors" means maintaining N near-identical full CSS files.

Note: for json/csv to be re-skinnable, their viewer CSS needs to move from inline-baked to a linked stylesheet (or the palette needs to be linked separately), otherwise only newly-created ones can change.

2. Switching mechanism. Once palettes are swappable, decide who picks and when:

• Viewer-side switch (like the dark-mode toggle): the person browsing chooses a palette, applied at render/serve time; a personal preference persisted per user. Doesn't change the stored artifact.
• Per-artifact, editable: make theme/palette a PATCH-editable field so an artifact's look can be changed after posting.
• Per-kind or global default: a Settings option for "default palette for my markdown artifacts," etc.

These aren't mutually exclusive; a viewer-side personal default is probably the most flexible and matches the "don't force one theme on everyone" framing.

Open questions

• Preset palettes vs. user-authored CSS. "Customize the CSS" could mean (a) pick from a set of provided palettes, (b) pick colors via a UI that generates a palette, or (c) let users paste raw CSS. (c) is the most flexible but has a real downside: user CSS is an injection surface (less severe than JS — see issue #014 — but still, e.g. CSS can load external resources / exfiltrate via background-image URLs). A curated-palette or color-picker approach (a/b) avoids that; raw-CSS would need the same "trusted content only" caveat as html_full. Recommend starting with presets + maybe a color-picker, not raw CSS.
• Interaction with app light/dark mode. Artifacts currently always render light regardless of the app's dark mode. Should palettes include dark artifact variants, and should they follow the app theme or be independent?
• Scope: global vs per-user. TagColor is already global/shared across users by design; would palettes be per-user preferences instead? (Likely yes — a viewing preference, not shared state.)
• html_full stays out of this entirely (verbatim, poster owns styling).
• deck is the concrete trigger: it's intentionally dark, and the request to make backgrounds consistent stalled on it precisely because it can't just take the off-white without reworking its text colors — a palette system with proper light/dark deck variants is the real fix.

Suggested phasing

1. Refactor base/report/tasks/deck (and the json/csv viewers) to drive all colors from CSS variables — no behavior change, just makes everything else possible.
2. Ship 2–3 curated palettes per document family.
3. Add a viewer-side palette switch + persisted per-user preference (mirrors the dark-mode toggle plumbing).
4. Later, optionally: per-artifact editable palette, or a color-picker for custom palettes.

References

• planning/2026-09-02-theme_variants_and_user_palettes.md — prior design conversation on this exact topic.
• planning/framework_artifact_rendering.md — rendering/theming framework notes (incl. the "vendor locally, CSS-only" stance and future renderers).

Resolution

(pending)