Allow custom styling / themability of widgets

[batpad]

Started sketching out some ideas in #1, but this needs a bunch of thoughtfulness applied.

We need to

• do a bit more background research on how theming works in both JupyterLab and MyST
• define common CSS variables and styling patterns to make widgets themable in a consistent way
• define consistent patterns when dealing with 3rd party libraries (eg. ChartJS) to have theming propagate down
• allow setting of themes to widgets (or at a higher level like a global theme / applied to layout components and propagated to child widgets, etc.) and / or over-riding more granular style properties
• add documentation on creating widgets to be easily themable as well as creating new themes and applying them

This definitely seems possible to do, but is the kind of thing that's really hard to do right. @dzole0311 really appreciated your thoughts in #1, will be great to get your help thinking this through and what the best interface should be.

[dzole0311]

@batpad I jotted down some notes for us, let me know what you think. I’ll start with a small sketch for option 2 below, just to see how it feels, but wanted to share the thinking upfront. One reason I looked into this is that (as we found out) even@radix-ui/themes has react and react-dom peer dependencies which we want to avoid.

Opt 1: Vendor selected Radix css tokens

We could copy a pinned subset of Radix token CSS into the repo or fetch/vendor them from a CDN or gh tag. This would avoid depending on @radix-ui/themes directly and avoid pulling in React as a dependency.

The upside is that we get real Radix values quickly. The downside I think is that Radix Themes token files are not fully standalone as a theming system. Some pieces seem to assume .radix-themes, data-accent-color, data-radius, --scaling, --gray-a*, --black-a* etc. So if we copy them directly we need to recreate parts of Radix’s theme logic or accept that we are coupling manywidgets to Radix’s internal token structure.

Opt 2: Radix-derived manywidgets tokens

This is the option I like more. Keep the manywidgets public --mw-* namespace but use Radix as the reference for token names, scales and values.

For example, instead of exposing raw Radix tokens as the manywidgets API we would translate/adapt them:

--mw-radius-1: ...
--mw-radius-2: ...
--mw-shadow-1: ...
--mw-shadow-2: ...
--mw-color-accent: ...
--mw-color-surface: ...

For example, for radius and shadow this still means looking directly at Radix and copying/adapting the actual (numeric) values. So for example we are not inventing random shadow or any other values from scratch. We are basically doing an adapted port into a manywidgets-owned contract. We can add a small source comment/notice (Radix is MIT licensed).

I like this because it gives the project a community ref point and a mature/stable token vocabulary w/o making the exact variable names from Radix our public API. Users would theme manywidgets through --mw-*, Theme(...) or per-widget style={...} and internally we can still say the defaults are Radix-derived.

Also, I think this gives us some room to make the defaults feel native in JupyterLab/MyST by falling back to their theme variables or dark-mode selectors where available.. For example --mw-color-text could fall back to a JupyterLab --jp-* variable when available, then to a Radix-derived value, then maybe to a hardcoded fallback. Same idea should work for MyST/static pages.

I think this addresses a lot of the concerns in #1/#7 like common tokens, consistent widget styling, layout-level inheritance and granular overrides. It also keeps the styling API stable even if we later tweak where the default values come from.

The part I think that still feels a bit awkward is third-party libs like Chart.js (or anything really thats canvas or WebGL-based) because the CSS vars will probably not always flow into those automatically. I think your PR already sketches the right kind of pattern with chart_palette and the chart’s palette trait. Maybe that becomes the rule? each non-DOM library gets a small theme adapter that turns the manywidgets theme into explicit library config.

Other options

I also looked at a few other paths:

• Open Props: https://open-props.style/ / https://github.com/argyleink/open-props. It has a lot of useful CSS variables but I’m not sure about the maintenance of the project and how strong it is compared to Radix for this use case
• Hand-roll our own token names, scales and values from scratch. This feels like more work and probably needs a designer. We would also have to assess color contrast/accessibility ourselves (Radix already gives us a mature set of accessible-ish values and scales to start from)

[dzole0311]

I think option 2 should also address issue developmentseed/manywidgets-playground#7. So manywidgets keeps its own --mw-* tokens but defines their defaults so they can respond to the host theme.

So in MyST, we can do something like:

.manywidgets-root {
  --mw-color-surface: var(--mw-gray-1);
  --mw-color-text: var(--mw-gray-12);
}

.dark .manywidgets-root {
  --mw-color-surface: var(--mw-gray-1-dark);
  --mw-color-text: var(--mw-gray-12-dark);
}

Then when MyST toggles dark mode, the browser recalculates the CSS variables and the widgets update.

[wrynearson]

Thanks for these thoughts @dzole0311! I like that you're trying to balance customization and using existing design systems.

A few thoughts below on the Montandon / humanitarian context (which I acknowledge should not be the only motivation for manywidgets development:

I think we have sensible/opinionated defaults as often as possible, and require users to set their own designs as seldomly as possible. I.e., it should be as easy as possible for an author to add a widget that looks good by default.

This is because, we assume, authors of notebooks within the Montandon/humanitarian context will not have any frontend/css/design capabilities.

allow setting of themes to widgets

We imagine that a certain organization might host a collection of notebooks with widgets, and that the organization might want to control the default theme globally.

[batpad]

We have basic theming now! Closing this, we can open separate issues as needed.