Brand YML and Dark Mode in Quarto (Gordon Woodhull, Posit) | posit::conf(2025)
Brand YML and Dark Mode in Quarto Speaker(s): Gordon Woodhull Abstract: Brand YML is a specification to provide consistent color themes, typography, and logos across all applications and packages that support it. Quarto currently implements Brand YML for its HTML and Typst formats. This talk will introduce Brand YML and get into a few of the interesting technical details about how we implemented Brand YML in Quarto. Specifically, I'll talk about the layering of SCSS styles in our HTML format, and the Typst CSS layer which translates CSS properties into Typst properties. Time and progress permitting, I'll also talk about applying Dark Mode to your documents by specifying both light and dark brands. Materials - https://gordonwoodhull.github.io/brand-yml-lightning-talk/#/title-slide posit::conf(2025) Subscribe to posit::conf updates: https://posit.co/about/subscription-management/
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Thank you. I'd like to start out with a quick survey. Could I get a show of hands for who prefers Dark Mode on their desktop or laptop computer?
And could I get a show of hands for who prefers Light Mode on their desktop or laptop computer? And who switches between the two or doesn't care? Yeah. So there's really a wide range of opinions on this. And the thing to remember is, you know, whichever one you prefer, there's a lot of people who like it the other way. So we really should be designing for both Light and Dark Mode. So we're going to see how Quarto makes that easier.
Introducing brand-yml
But first, let's take a look at brand-yml. Brand-yml is a simple and easy configuration language for doing the basics of brand. Just the most important parts of it, which are the color, typography, and logo.
No matter what kind of organization you work for, brand-yml provides a way for you to easily share and get everybody having the same look between their different work. And also, brand-yml is compatible with both Shiny and most of Quarto's HTML, all the HTML formats and the types format.
Dark mode in brand-yml
So how do we do Dark Mode in brand-yml? Well, we could simply just plug in a bunch of dark colors and a dark logo, and this totally works. But as we were saying, you really want to design for both Light and Dark Mode. So in Quarto 1.8, we support both having light and dark colors and light and dark logo.
And when you enable that, this gets you the toggle, but nobody wants to use that, right? Everybody just wants to see it the way they want to see it. So in Quarto 1.7, we introduced respect user color scheme. This just follows the system scheme, and it's dynamic for people who change between the two.
So in Quarto 1.7, we introduced respect user color scheme. This just follows the system scheme, and it's dynamic for people who change between the two.
Light and dark plot rendering
If you've been watching closely, you notice that this plot, which is a map plot lib of a spiral, has been faithfully following the background and foreground colors, even when we switch between Light and Dark Mode. So let's look at how that works. We're not going to get too much in the code, don't worry.
So we have first renderings, light, dark. It's a cell option that just says we're going to render first in Light Mode and second in Dark Mode. And you can see there's this light style and dark style, which enables Light Mode and then Dark Mode. Map plot lib is very imperative style, so you really just have to do it all again.
Other plotting libraries and table libraries that are more declarative, you can share more of the code. And here you just define the plot once and then output it once in Light Mode and once in Dark Mode. Similar for plot 9, for Altair, Plotly.
And I'm not showing just a little bit of the glue code that makes this all happen, but there's glue code in the Quarto-R and Quarto-Python packages and the brand-yml package that makes this all possible. There's just a little bit of syntax that we haven't quite finalized yet, so watch out for that in the next couple of weeks. And there's a whole bunch of links here with all kinds of documentation and examples. Please check it out. Thank you.
