Company Branding Workflow Demo Live Q&A - February 26th

Before we dive in here to the Q&A, I just wanted to go around the room and do some quick introductions. So if I haven't met anybody, I'm Rachel Dempsey, I lead Customer Marketing at Posit, and I'm always looking for ways to bring the community and customers together to be able to share different use cases and just get to connect with each other.

Sarah, I know you introduced yourself in the beginning, but do you want to do it again now? Hi, I'm Sarah Altman, and I'm on the Developer Relations team at Posit. And Garek? Hi, everyone, I'm Garek, I'm a developer with the Shiny team at Posit. Hi, everyone, I'm Carlos, I'm a developer in the Quarto team at Posit.

Well, thank you all for joining us here. I saw some great questions asked into the chat during the demo, but we also have Slido where you can ask questions anonymously, too. So let me jump into some of the questions from during the demo.

Pronunciation of brand.yml

So one that was asked, well, actually, let me first ask a fun question here. How has everyone been saying brand YAML? Because I want to make sure I'm saying it right. Some people say brand.yaml, brand.yaml. What's the right way?

Well, I think we're very open to lots of different pronunciations, but I also say brand.yaml. Maybe I will, you know, refer to a file as a brand.yaml file, but in general, I call the project brand.yaml just because it's easier. I keep saying brand.yaml, but I agree that brand.yaml is easier to say.

But I think we do not pronounce, we do not say underscore in front of it, even though the file has it. I think it's the main thing, just because that would be a mouthful. So we all end up saying brand.yaml or brand.yaml.

Recent updates to brand.yml

So I know brand.yaml is so new, but what are some of the recent updates to brand.yaml? I think the biggest is that we've brought brand.yaml to Shiny for R and the R ecosystem, which is relatively recently. We launched brand.yaml with support in Quarto and Shiny for Python and followed up pretty quickly with support for Shiny for R.

So I see John Harmon had asked a question or I asked in the chat if people had a chance to play around with brand.yaml yet, and John had mentioned not realizing it needed a certain Quarto version. So I thought it might be good to talk about that a little bit. Which version of Quarto is needed for brand.yaml?

So we shipped the brand.yaml support in 1.6, and the latest version of Quarto 1.6, that's the stable version, is 1.6.42, I believe, that came out yesterday. And so that is what you would get if you just go on GitHub and install it. If you use Quarto on PyPI, that's the version that you get as well, and also on package managers like Chocolaty and Winget, which are the ones that we control, and so we can push changes. If you grab it from any other place, then it would depend on which version you get it. But all 1.6 versions have brand.yaml support and should work.

Light and dark themes

So I see Trang had asked a question during the demo, and it was, if I have two themes, dark and light, would I need to use two brand.yaml files?

Well, I was going to say, this is a great question, and it also depends a little bit on how each... the tool that you're using, how it implements light and dark themes. So there's a different answer for Shiny and for Quarto, and I'll let Carlos talk first about how Quarto works with this.

So let me just start by saying that I think Quarto's light and dark mode support leaves quite a bit to be improved that we are working on 1.7, and so I'll give you the answer for 1.6, and things might change a little bit and become more convenient when we release 1.7. Brand.yaml promises we're still actively working on it, but we expect there to be improvements. So for Quarto, it is probably easier for you to just use two themes, one for dark and one separate brand.yaml file for dark, and one separate brand.yaml file for light. They work kind of like actual themes, if you're doing, like, theme configuration on Quarto, so you can just use those, and that's easier to do. The brand.yaml specification, if you go on the documentation, does include support for light and dark mode, but Quarto currently doesn't work with that. So the easiest way to do it is to just use two brand.yaml files.

So Shiny has a bit of a different approach to light and dark themes. This is also relatively recent in the sense that Bootstrap 5.3, which is the thing that the web framework and CSS sort of styling framework that Shiny uses, came out with a feature for native dark mode. So the way that Shiny approaches dark themes, or themes in general, is that you create one theme. That theme typically works best if you create the light theme, the light sort of variant of the theme, and then Bootstrap will automatically make a dark theme for you out of the colors that you've picked. So in Shiny, you can use a regular brand.yaml file. If you target brand.yaml towards a light theme, then you can add the dark mode switch component into your app and get a dark mode theme for free.

Local fonts

There was a kind of follow-on question to this one too, and it was, what about local fonts? How can I point brand.yaml to the local font files?

So again, the answer will be a little bit different from Quarto and Shiny, but in Quarto, we sort of, if you go on the brand.yaml documentation, there's three ways, two and a half ways, let's call it, of doing fonts, and the default one is an online font foundry is the name of it, like the website, and we use Google Fonts by default, but you can use a different CDN that's more privacy friendly, or you can also use local fonts. In Quarto, those, when you point them, they need to be inside the project, like all the other resources in Quarto, so that if you put them on GitHub and things stay reproducible, but you can definitely use local font files in that way. So there are actually two, you can have system fonts, or ones that are installed on your system just anywhere on your system, and there's also local, which is, we intend to be, essentially, you go get the font files and you're going to put them next to your brand.yaml file, and then we'll use those files. So it is possible to use local fonts, and the brand.yaml website is a good reference for how to get that set up.

What was most surprising about using brand.yml

But Sarah, in going through the process of writing the blog and giving this demo, I'm curious, like, what was most surprising to you about using brand.yaml?

I think it, it does sometimes sort of work like magic, I think, like you were saying earlier, Garrick, like it, which is really cool. So as long as you have that file, you know, next to, in the project directory of your Quarto document, and you just render it, like, it sort of seems magical, which is cool. I also just, I don't know if this was surprising, but it really is nice to be able to have one place where you can put, you know, all of your desired theming, and then move that file to other locations that you want to theme. I think, like, that is a real improvement over the previous way of doing things, which is, like, you adjust stuff in your Quarto document, and then you have to also do it in your Shiny app, but in a different way, and then things look sort of different.

I also just, I don't know if this was surprising, but it really is nice to be able to have one place where you can put, you know, all of your desired theming, and then move that file to other locations that you want to theme.

Using brand.yml with ggplot

Somebody said, I often generate lots of PNG images to import into Google Slides for accessibility for others. Is there a way to use brand.yaml for ggplot?

This is an excellent question. So it gives me a little bit of a chance to explain the relationship between brand.yaml files and the other projects. So brand.yaml is not a feature of a specific software. It's kind of like a specification that Garek and I developed was sort of how we think these other applications should understand in order to do their theming, right? So someone somewhere needs to teach ggplot about how to do these. We are working on it. I don't want to give a promise for when these things are going to be sort of ready, but this is something we're definitely working in 2025, and we have prototypes, and we're trying to understand sort of like how to make that really nice. But the hope is very much so that, you know, if it's not ggplot directly, it's some other downstream library like thematic in the case of ggplot, for example, that knows how to configure a lot of different graphics for themes and teach thematic how to do brand.yaml configuration.

I do want to follow up and say, though, that thematic is amazing, and it was one of my favourite parts of working on the R side of things was realising that if we taught bslib how to use brand.yaml, thematic already knows how to hook into the theming things that bslib does, and so if you were using thematic in an R markdown document or in a Shiny app, you basically can have your plots themed, your ggplot plots themed to match your brand.yaml just by turning on thematic, which is pretty awesome. And the Shiny for R app in the repository that I showed in the demo does use thematic, so you can take a look at that.

Sharing brand.yml across an organisation

Brittany asks a great question. How do you recommend sharing brand.yaml files across an organisation?

Again, the answer will be a little different depending on if you want to use it for Shiny and for Quarto, which are the two systems that use brand.yaml right now. There's a way to share a brand.yaml file through a Quarto extension, right? And so there's a way for you to create an extension that packages the brand.yaml file. So if someone wants to use a brand.yaml file, they can just Quarto add an extension and then extension will pick up the brand.yaml configuration in Quarto projects. We haven't given a concrete example out there, like in our blog or something, so you have to know the trick to do it, but it's possible to do today. We're soon going to post something on like a blog or documentation on how to do that because it's a very important, very common question.

And on the Shiny side, there's sort of like the easy case, which is you just put your brand.yaml file inside, like in the same place as your app and then it just works sort of like Quarto does as well. But there are also, you know, all of the functions that sort of bring in brand.yaml files take a path as an argument or let you specify where the brand.yaml file lives. Personally, if I were in charge of maintaining a brand.yaml, I would probably create a small repo that has just the brand.yaml file and the extra assets. You know, you end up with some logos and some other, maybe some, you know, fonts next to the brand.yaml. And in the future, I can see us adding tooling that makes it easier to go grab all of those things from a repo or from somewhere.

The part that, again, needs a little bit of care is that Quarto uses brand.yaml configuration, Shiny uses brand.yaml configuration, and we hope other systems and libraries will use this in the future. So each one of these might have a slightly different way of like pulling in that information. So we'll probably take a little bit of time to let sort of the use patterns show up in a way that's natural. And then once we understand them well, we will put them inside use this.

Using brand.yml outside the project directory

John had asked a question during the demo as well, and it was would also be interested to know if you can use these.yaml files outside of the directory for our dashboards or apps so multiple projects can point to the same file.

Yeah, and I'll say that, yes, you totally can do this. I think ultimately you will end up running into the small problem of when you go to deploy your shiny apps, you'll likely want to have all of the files be contained in the same folder. In general, lots of deployment patterns require that. But beyond that, you know, locally, the shiny, at least on the shiny side, things are pretty flexible in the sense of, you know, we try to like nudge you towards keeping all of your app files in the same folder, but you could have a shared directory where you put your brand.yaml and you could use that.

Yeah, Quarto is a little more opinionated about this, you will need to put your brand file in the Quarto directory, your brand.yaml configuration in the Quarto project configuration. You can have subdirectors of your Quarto project that all share a single brand.yaml file that totally works. But separate projects need to have sort of separate files. That's what we use extensions for. The reason we do this is for reproducibility, right? It's sort of for deployment, like Garrick is saying, the risk of doing something outside of the directory is that you no longer control it. So if someone else changes it, now things can change in your project and you don't see it.

brand.yml with Xaringan and HTML widgets

And people are testing my pronunciation with packages, but is brand.yml compatible with Xaringan or can it also be used with Quarto documents in shiny apps?

Yeah, I love Xaringan and I happen to also maintain a package called xaringanthemer and which is designed to create full Xaringan themes. And I appreciate the nudge. I feel like brand.yaml would be a great fit for that. And it would totally work. And it could be a new feature in the xaringanthemer package. But it wasn't actually something that was on my mind until now. So thank you. That being said, you know, you can grab, you can use the idea, as Carlos had said before, is that brand.yaml is this is a first and foremost, it's a specification or structure for organizing information about your brand. So the in other words, you could use the brand.yaml file and read it and pull out the fields that you need and pass them to xaringanthemer. And just about anywhere that brand.yaml doesn't currently work by magic, it can be made to work using normal theming ideas.

OK, so while we're talking about requests, I see there was one about pkgdown websites as well. Have we said anything about this yet?

We haven't, but it is totally possible. It's entirely possible. In fact, the bslib website now uses brand.yaml. So if you're looking for a concrete example, you can go check out bslib. And it's basically a function of the fact that bslib is used in many places throughout the R ecosystem as the main provider of Bootstrap, which is pretty cool. So it's more or less just either works by magic or requires a small change to your pkgdown yaml file. And you can have brand.yaml styling your pkgdown websites as well.

It's a very simple example, but I will also note that the brand.yaml website uses brand.yaml for its theming. So Garek did that very early on. And so right off the top of the page on the introducing brand.yaml sort of section, there's an example that brand.yaml example is actually the example that we are using for brand.yaml. So you can see it's about 25 lines of a file that is enough to do that. And that will work. That would generate exactly the brand imagery that you are seeing.

SAS variables and HTML widgets

One was, I'm not sure how SAS variables defined in the SAS file would be treated when providing that file to BS add rules. Can you please explain?

I can try to give a little bit more context and just say that in general, when we take brand.yaml and turn it into your theme in the CSS for your theme in Shiny or in our ecosystem, we take key parts of it and create convenient little SAS variables for you. Actually, we create SAS and CSS variables for you. So, for example, if you define a custom color, so you define your custom red under color dot palette, right? So, under the color palette, you put your own red color. We'll actually create a SAS variable that is dollar brand dash red, which means that you can then access that anywhere you want in your SAS files. And, yeah, beyond that, I think this starts to get pretty specific in terms of exactly how you layer your theme that includes brand with extra rules and things like that. In which case, it is much easier to see like an actual concrete example. And I am very happy to answer any questions in the about this, either in the bslib repo or just by going to the brand.yaml website and clicking on report an issue.

So, I will note that Quarto does the same thing for variables. So, they become brand dash the name of the thing in the palette. So, Quarto does the same process. So, then you can access them in your own SAS files if you have further configurations and CSS as well. So, you can do both of those. So, that should work on both Shiny and Quarto.

So, before we get to this question, Jeff asked the question about my Shiny apps tend to make heavy use of HTML widgets like Plotly, Leaflet, DT, et cetera. The answer is, unfortunately, these libraries need to be sort of like they need to learn to speak brand YAML in the same way that we taught Quarto and Shiny to speak brand YAML. So, support for these will come sort of gradually over time as people make pull requests into these open source libraries to add support for brand YAML. That doesn't happen automatically. That will happen over time. But that's the point of doing brand YAML is that it enables this kind of work. So, now the configuration happens in one place. And so, we expect this to become progressively better as time goes by.

And, again, brand YAML stands on the shoulders of a lot of work that has been done in the past. In particular, I'd like to call out Carson Sievert's work on getting theming to work in general in Shiny through bslib. So, there is a good chance that a lot of these widgets, when they're in a Shiny app that is themed matching brand YAML, will just pick up important theming properties from the main Shiny app. And if they don't, that's something that we would be interested in taking a look at.

Recommending brand.yml across your organisation

But let's pretend we all work at some company that wants to incorporate brand YAML. And somebody was at the event today and learned how to do it. How would you go and then recommend, like, sharing that with other people across your organization?

So, I'll say I like what is being suggested here in this question. Storing brand YAML in a shared location and kind of following Quarto's model of how extensions work, where you pull the current state of the brand YAML from the shared location into your project. Ideally, you know, I see us in the future having a way to do that, like, we have a Python package that helps you work with brand YAML. I see us also having an R package that helps you work with brand YAML. And a very good fit for both of those would be a function that helps you pull brand YAML from a shared location into your project. I personally, if I were maintaining, like I said before, if I were maintaining a brand YAML, I would put it in its own repo and then try to figure out how to get it, you know, out. So, it's like versions separately because it's sort of a separate thing that can be used across a bunch of different projects.

Email format support

I noticed an email in the brand YAML feature flowchart. What are you envisioning for that?

So, if you use some of Posit commercial, Posit Teams, something like Posit Connect, one of the really nice features you have there is that you can have scheduled documents that get emailed on, like, every Monday or, like, on, you know, sort of before, like, 5 p.m. on every day that are Quarto documents that get sent out and you get an email with the content of those. The email feature there is the, from my understanding, is sort of like Quarto's internal email feature that gets used inside, for example, Posit Connect. And so, we haven't implemented that, but it's sort of on the roadmap. It's figuring out how to make the brand YAML configuration kick in for the email format. The reason this is not just HTML is that email is a much more restrictive format on what it allows to do in terms of CSS, in terms of styling. But the hope is that sort of basic things like the foreground, background color and, like, fonts that are okay to use in email can be used for Posit Connect's email feature. We don't have a timeline to offer for that, but that's coming.

Thank you all so much. I just put into the chat, if I had missed anybody's questions, feel free to repost. But thank you all so much for joining us, too. I just want to remind everybody, we host these workflow demos the last Wednesday of every month and, of course, they are all recorded. But if you ever have suggestions for us and things that you want to see, you can let us know in the comments as well.

Any last words of advice or anything you all want to share with everybody? Just say, I think, like, try out brand.yaml, even if you want to use it for your own personal uses. I think it's really fun to play around with. And also, sorry again for all my cat and glass problems.

Well, thank you again. And if anybody has other pieces of feedback, you can always go to the GitHub repo for brand.yaml as well. But have a great rest of the day, everybody.