Theming Made Easy: Introducing brand.yml (Garrick Aden-Buie, Posit) | posit::conf(2025)
Theming Made Easy: Introducing brand.yml Speaker(s): Garrick Aden-Buie Abstract: brand.yml is an exciting new project from Posit that radically simplifies theming. Every data science tool supports some form of theme and appearance customization, but each app framework, output format, or visualization tool requires its own special syntax for theming. The goal of brand.yml is to create a portable and unified interface for brand-related theming that can be used anywhere that data science artifacts are produced. As a collaboration between the Shiny and Quarto teams, brand.yml provides a single interface to setting baseline themes in reports and apps across the R and Python ecosystems. In this talk, I’ll introduce brand.yml and showcase the many ways that brand.yml can bring consistent styles to your data science outputs. Materials - https://github.com/gadenbuie/brand-yml-posit-conf-2025 Slides - https://pkg.garrickadenbuie.com/brand-yml-posit-conf-2025 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.
All right, hello everyone. So I'm gonna be talking about Theming Made Easy, I'm gonna introduce brand-yml to you.
But before I do that, I wanna take you back to a time, I wanna take you back to a time a long time ago, in a galaxy very far away. Actually, in 2019, in Austin, Texas, I was an audience member at a conference very much like this, it was called RStudioConf instead of PositConf, but I was sitting in the audience for the first time at an RStudioConf, and just really soaking in all of this new knowledge and all of these people who are using R and doing really, really, really cool things, and just really loving it.
And there's one talk in particular that really sticks out to me when I think back to that conference, because it really changed the course of my career, it validated where I was in a way that really resonated with me. This talk was called Push Straight to Prod by Jacqueline Nolis and Heather Nolis, and they were talking about how they had used R in production at T-Mobile. That was the first very validating thing, that I was learning and using a programming language that we could actually put this into production, we could be proud of being R people, and we can use Shiny in production.
But there was another, there were two other ideas that were personally very validating for me, and that have stuck with me since then, and I wanna just quote directly from them. I'm not going to pretend to do their voices, but pretend that this is them talking about their app. So, in the middle of the presentation they said, we built this model, and we were really excited about it. But we'd go into these business meetings and be like, guys, look at these ROC curves, they're amazing. And everyone would be like, okay, whatever.
So, 10 minutes before one of these meetings, we're like, hey, let's just make a Shiny demo. And they made a Shiny demo. They made a little, it's not a complicated app, right? It's got a little, it's got some inputs, it has one plot, but it's interactive. And in their words, this changed the game. Right, now they, as they said, our nice Shiny demo got us, and I am not exaggerating, millions of dollars of funding and multiple new hires, this Shiny app, right? But the fact that it was interactive, that it helped communicate the idea, speaking to James's presentation about disposable Shiny apps, they could probably throw this away afterwards, but it served its purpose. It let them communicate an idea and interact with it in the meeting and make something real in front of very important people who make very important decisions. And it worked.
and I am not exaggerating, millions of dollars of funding and multiple new hires, this Shiny app, right?
And I love this part. This was the one other validating thing. I now work on the Shiny team, and I think Shiny's awesome, so that was definitely validating for me. But there's one more little detail that they kind of just slipped in there. What they said is, we actually, we spent an extra day making the HTML look nicer to give us that polished professional look.
So if you remember this app, well, this is the same app. It probably doesn't look like the same app. It doesn't feel like the same app anymore. But it's basically the same Shiny code. This is what a basic Shiny app, especially in 2019, would have looked like, right? But they took the extra day to style it and to make it look good and to make it kind of fit in with the other stuff that T-Mobile does and builds. And they specifically credited that also. It's not just that they made a Shiny app. They took a little bit of extra time to make it polished. As they said, it took one extra day, and you had a polished app. How beautiful.
The value of polish
Yeah, so if you've done this kind of thing before, you're probably starting to be, you're like, yes, this is awesome. It's really nice that it's polished. I don't know if I believe you about that one day comment. And this reminds me of an interaction on old rstats Twitter. I shared some slides and someone said, that looks really awesome. Miles McBain came up with this term, slide crafting. And I was like, immediately I latched onto that idea. Like, the way my brain works is, yes, I'm going to spend four hours tweaking CSS and changing colors just because that's how my brain works and that's what I want to do with my time. But there's a part of you that's like, should I be doing this? And slide crafting, calling it slide crafting, gave me the cover to say like, this is important. This is okay for me to be doing.
So, I put it on my LinkedIn profile. I'm a professional slide crafter and aestheticist. I like these things. I like making things beautiful. I like making things look polished. I like spending that extra bit of time. I think that's awesome.
So, this is a recurring theme. Also, RStudioConf being a place of level-upping my career is a theme as well. This is my first R package. It was a little package called ggpomological. I saw a talk the year before online at RStudioConf and I thought, that was really cool. Wouldn't it be neat if that was a ggplot theme? And I spent a bunch of time making a little package. This is like, I got to learn how to make packages.
2019 was also the year that everybody started using Sharingan to make slides. So, we started making slides in HTML, which was really, really cool. And they looked kind of like this, and I thought, that's okay, but they could look better. And I made a little package that you could just give it a couple colors and you'd have a nice Sharingan theme. Oh, and you could pick fonts and that kind of stuff and it'd be pretty neat.
Before Sharingan was around, we used Beamer and I was a graduate student and I was like, if I'm going to present something, I would rather spend a lot of time figuring out how to program in LaTeX and get Beamer to look good. So, I made a theme for USF, the school that I was at.
Every place that I have worked, basically, I have at some point said, you know what we need? We need a package that makes our plots look like our colors and we need a template for our markdown so we can have these really cool, so it looks like the other stuff that we're making. So, this is, I worked at Moffitt Cancer Center and this is a theme, a little package that had themes for Moffitt and document templates. And when RStudio, when we changed from RStudio to Posit, I also made another little package called Posit Themes that we could use to make plots in these themes.
So, this is a recurring theme. I think, personally, I think polish matters. And last year at PositConf, David Keyes gave a really cool talk where he kind of, in the middle of it, he said, basically, yes, there's a reason for this. We take things that look good more seriously. People take us more seriously when our stuff looks good. And especially if you're in a culture where all of the materials look similar and we're making, yeah, if you can make your outputs look like everything else, you are taken more seriously.
I, personally, am very comfortable with tinkering. Tinkering is something I love to do in my life and that is why I work on Shiny and these kinds of things now. But much more important is presenting, right? So, also, yes, I love tinkering, but I've also really liked packaging it up in a way so that other people could get those benefits without having to spend as much time as I spent tinkering. And I also really like this idea of writing something down one time and then getting to reuse it over and over and over again. And the things that we've seen so far sort of do that, but sort of in just one little place. And wouldn't it be nice if, instead, we had an easy way where we could take our brand guidelines and apply them to our documents? And that is the idea behind brand-yml.
Introducing brand-yml
So, brand-yml is basically a new project that we've been working on in the last year where you can take brand guidelines and turn it into YAML. So, YAML is like a structured language. It's a nice sort of like human-computer interface where it's flexible, it's easy to use as a human, and also it is structured data that we can give to a machine. We're gonna see it in action throughout the rest of this.
But first, we're going to join a company that I just invented called Pulse Mobile. Okay, Pulse Mobile is like a new cell phone provider. They are really gearing for like the 18 to 30-year-olds that wanna be hip, right? So, this is Pulse Mobile. And we're gonna pretend like we are on a team of data scientists there.
And Pulse Mobile had this genius idea. Everybody else is putting AI into stuff. We're gonna make a Pulse AI assistant. And it can, it's an AI-powered concierge that's going to solve your problems before you even notice them. Okay, as the data science team, we are tasked to figure out how much should we charge for this? So, we spend a lot of time doing, you know, running models, writing reports, doing stats, really figuring this out.
And we, but we've seen that talk from Heather and Jacqueline from RStudioConf in 2019. And so, we make a little Shiny app. So, in 2025, this is what a basic Shiny app looks like. And it's nice because, you know, we have some more features, right? It isn't, you know, there's these value boxes and there's some icons. It is a little bit more pizzazz, right? But this, the Shiny app works because people can interact with it. And they can kind of explore. And now, we're gonna let the stakeholders kind of come to their own conclusion, which is the one that we have sort of planted here, which is we should charge $15 a month for this. Something like that, right?
But, we've also seen that talk. And we know it should look more like something like, something that Pulse Mobile would create. So, what we would do if you're, you know, on that data science team is you'd go into your intranet and you'd find the brand guidelines, right? There's somebody somewhere on a marketing team has made a document that like sets out what colors and fonts and that kind of thing. And if you scroll past the marketing speak, eventually, you get to sections about logos. And you can see examples of logos, lots of logos. You can see a section on typography. It tells you what kinds of fonts you should be using. There's a section on color. And this kind of lays out all of the colors that are associated with the Pulse Mobile brand and a little bit of description about where you should be using them.
Building a brand.yml file
So, you open this up. And this is where brand-yml is going to partner with you. Okay, the idea with brand-yml is that you have, basically, in your YAML file, you're going to have four key sections that cover that same information that is in the brand guidelines. Basically, every brand guidelines PDF is going to have these four things. And we're gonna walk through them specifically. We have metadata about the company, what the logos that you should be using, typography, fonts, that kind of thing, and the colors. So, we'll go one by one.
First of all, metadata's pretty easy. So, what you're gonna do is you're gonna create an underscore brand.yaml file. And you start with meta. And now I'm gonna say the name of the company here, or the brand, is Pulse Mobile. And there's a link to the homepage. What's nice about brand-yml is it is also kind of flexible. So, if you wanna spend a little bit more time and say, in places where we can fit the name, where there's not much space, we need a short name, we'll call it Pulse Mobile. And the full legal name is Pulse Mobile Telecommunications. Something like that. And that same idea applies to link. So, if you have just one link, you can just give the link. Or, if you have multiple links, you can then start to be more specific and say, here's the link to the homepage. And here's the link to our Blue Sky profile. And none of those are real, by the way.
Okay, so now we're done. We've done metadata. That was probably the easiest one. We actually probably didn't even need to open the brand guidelines to get there, right? So, our next step is color. I think color is nice. We're doing this out of order because it's more fun this way.
Yeah, the easy stuff first, right? So, brand guidelines, again, skipping past the marketing stuff. We're gonna get to the section on colors. And here we have a list of colors. So, we'll move that over to the side, maybe have that open in a window, and you have your YAML file in the other window. And here you're gonna use color. And color lets you define a palette, which is basically like read all of the colors in the brand guidelines and just tell me what they are. So, there's a Pulse Purple. There's an Electric Blue. There's a Mint Green. Yeah, they all have these fun names, right? And there's a bunch more.
If you wanted to have regular names too, there's a cool little feature in brand-yml where you can have aliases. So, I can have Purple be an alias to Pulse Purple. But my recommendation in general if you're doing this is to skip the marketing speak names and just use regular primary colors, right? Purple, Blue, Yellow. And actually, there's good reasons for doing that. It ties into how Bootstrap thinks about color and it'll just work nicely in a bunch of different places.
Okay, so I've gone through, I've picked out all the colors and I've brought them in here. But now I need to tell brand-yml where I'm going to use those colors, right? So, at the same level as palette, there are, you can think of them like semantic colors or theme colors. So, for primary, I want primary colors, primary accents to be purple. I want secondary accents to be blue and I want anything that looks like a warning should be yellow. And it's going to use, you can see I'm saying yellow, but brand-yml is going to go find yellow in the palette and use that color specifically.
All right, if you're feeling like, I want to get this done really quickly, you can also just define those theme colors directly. You don't have to go all the way. Okay, so we've finished color. Let's go to typography. We have the typography section. We've got some fonts, okay? And it's the same process. You're first going to just list the things that are in the brand guidelines. So, we're going to list fonts. Here, we're using Montserrat, Montserrat Alternates and Space Mono.
What's really nice, though, about brand-yml is you actually can say where you're going to get these from. So, this could be Google Fonts. You could use Bunny Fonts, which is a funny name, but it's a GDPR-compliant version of Google Fonts. And also, if you have a proprietary font, you can store them locally and then use those files. Once you've picked your fonts, you're going to say where to use them. So, the base font will be Montserrat. We'll use Montserrat Alternates for headings and Space Mono for a monospace font. And you can see how these match, yeah.
Again, you can also do a more complicated version if you're going to spend a little bit more time working on this. Headings are going to use Montserrat Alternates, but also, they'll be the color purple. Wouldn't that be nice? Okay, and that will actually go back up to color palette, find that purple color, and that's what we're going to use.
All right, we're close. We're almost done. The last one is logo. We have a lot of logos. We're going to download all the logos. Then, in our brand.yaml, we say logo, images, and we're just going to list them all out. And I'm going to cut out some of those so we can just see. So, here we have, you give them a name, and then you give it a path. And those logos are right next to your brand.yaml file. And then you're going to pick where you're going to use them. So, this pattern repeats. You take some information from the brand guidelines, and then you tell brand.yaml where to use those things. So, our small logo, we'll use the icon. For medium, we have two choices. So, we'll use the color version for light mode, and we'll use the white version for dark mode. And we'll do the same for large icons.
brand-yml in action
And now, our app looks like this. So, we just take brand.yaml, drop it in next to our Shiny app file, and automatically, we get a nicer looking app. But what's really cool about brand.yaml is it's also data. Like, we have just taken our brand guidelines, turned it into a YAML structure, and we have packages in both Python and R that you can use to pull out that data. And you can do something like style your plots and a few other things really nicely, and now you have an even better looking app.
So, if you're working on a brand.yaml for your company, you might want to try this. It's the BS Lib brand.yaml app, where it gives you a little editor. You can edit live and see the changes and see your colors in like a working Shiny app and see how that looks.
And, yeah, in the end, as a company, we did great. We won, it's awesome, things are good. We go back to work. I just want to show you really quickly, though, that this also works for Quarto. So, you just, just by dropping these files, there we go, dropping the brand.yaml into the same area where you have a report, you'll end, you can make really nice looking reports. So, it works for Shiny and Quarto. This brand.yaml was a collaboration between the Quarto and Shiny teams, working really hard to make this work for us. And we hope that it works for you, too.
So, here's a bunch of links if you want to learn more about brand.yaml and use this in your own projects. And hopefully, it saves you a whole bunch of tinkering, but brings a lot of polish to your reports and apps. Thank you.
And hopefully, it saves you a whole bunch of tinkering, but brings a lot of polish to your reports and apps.
Q&A
Thank you, Garrick. It looks like we have a lot of questions. I think we only have time for one. So, please, if you did not get your question asked here, find Garrick, I'm sure he'll be around the hall, available. But, other than brand.yaml, what is your favorite trick to not make Shiny apps look like a 2019 Shiny app?
Yeah, my favorite trick is to use BSLib. So, or Shiny for Python. But, yeah, BSLib is where all of the new, fun stuff is happening for Shiny. And automatically, just by using some functions from BSLib, you just get nicer looking apps out of the box. So, BSLib and brand.yaml together, it's a great pair and I highly recommend it.
