MISSION - Refactor bokeh's theme and styling systems

[trallard]

📌 Summary

Modernise and simplify bokeh's theming system and its accessibility.

📝 Background

Bokeh's theming system is rather rudimentary and only focuses on plots. Interactive widgets and components are controlled through CSS files, making consistent styling challenging for end-users. We plan to redesign the theming system, thus allowing for a single and consistent approach to styling plots and interactive components. This will also significantly reduce the library maintenance effort.

Such an improvement will also allow for designing and implementing consistent light/dark styling, adopting accessibility best practices, complying with WCAG, and developing high-contrast and colorblind-friendly themes and color palettes.

🚀 Tasks / Deliverables

Note

See issues labelled as: mission: theming 🪄

ℹ️ References

• Bokeh themes documentation
• Bokeh stylesheets documentation
• WCAG 2
• Starting in 3.5 - there has been some improvement made towards leveraging CSS see: Add support for CSS-based theming on the canvas bokeh/bokeh#13828
• Issue related to theming and colourblindness Improve usability with color vision deficiencies bokeh/bokeh#11481

[mattpap]

Since bokeh 3.0 when we migrated from classical CSS (global CSS stylesheets) to shadow DOM and web components, the only way to create CSS-based themes is with CSS variables. Currently have just a few common ones defined in src/less/base.less. Thus we will have to start with defining a set of CSS variables and use them across bokehjs' components. I'm not sure how many and how granular these variables should be, but we can take a hint and some inspiration from existing libraries and frameworks (Bootstrap, Fluent UI, etc.). Using them in components should be fairly straightforward, because almost all styling of bokehjs' components is applied via stylesheets. There are still some inline styles in a few places, but those are either being replaced in existing PRs or will be in near future. Many components define private CSS variables (private to a component), so it may appear that the current situation is better than it is in reality. Pretty much every component defines its own colors, borders, animations, etc.

*.less files are the primary source of styling for bokehjs' components. Another source are UI model properties, especially visual properties and mixins, e.g. Plot.background_fill_color, also known simply as "visuals". These mostly affect the canvas and in this case form a mostly CSS-detached styling system, but can also affect CSS components like layouts (LayoutDOM and its descendants). In the later case they are limited primarily to sizing (width, height, aspect, etc.) and rarely to colors, etc. Finally all properties and visual properties in particular can be affected with bokeh or bokehjs JSON-based "themes". I put themes in quotes, because this is a very generic mechanism that allows to override any value of any property of any model on a fundamental level (i.e. replacing the default value of a property; known as property overrides in bokeh's and bokehjs' type systems).