Resources
Feb 27, 2025 |
34 min
|
518 views
|

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

Hi, there!
If you started here first, please refer back to the Demo: https://youtu.be/U48y0_yzEPY

This Q&A Session followed a workflow demo on "how to apply consistent company branding across reports, dashboards, and apps"

Key Links:
1. GitHub Repo for Example: https://github.com/skaltman/brand-yml-demo
2. brand.yml GitHub repo: https://posit-dev.github.io/brand-yml/
3. Follow-along blog post: https://posit.co/blog/unified-branding-across-posit-tools-with-brand-yml/

Additional Resources Mentioned in Q&A:
1. Quarto specific page on brand: https://quarto.org/docs/authoring/brand.html
2. Typography: https://posit-dev.github.io/brand-yml/brand/typography.html
3. brand.yml + pkgdown: https://github.com/rstudio/bslib/tree/main/pkgdown
4. LLM brand.yml prompt: https://posit-dev.github.io/brand-yml/articles/llm-brand-yml-prompt/
5. Inspiration/gallery: https://posit-dev.github.io/brand-yml/inspiration/

Please note, the main demo will be here: https://youtu.be/U48y0_yzEPY?feature=shared

If you'd like to ask questions anonymously, you can use: https://pos.it/demo-questions

image: thumbnail.jpg

Transcript#

This transcript was generated automatically and may contain errors.

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? Yeah. Hi, I'm Sarah Altman, and I'm on the Developer Relations team at Posit. Thank you, Sarah. And Garek? Hi, everyone. I'm Garek. I'm a developer with the Shiny team at Posit. Awesome. Hi, everyone. I'm Carlos. I'm a developer in the Quarto team at Posit.

Great. 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.

Pronunciation of brand.yml

So let me jump into some of the questions from during the demo. 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?

Garek? Well, I think we're very open to lots of different pronunciations, but I also say brand.yaml. Yeah. 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. Yeah. I keep saying brand.yaml, but I agree that brand.yaml is easier to say. So I'll try to teach myself to say it like that.

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. Okay. Before I ask a bunch of questions here, I want to make sure I was saying it right.

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.

A large glass thing just shattered in my background. I'm trying to keep my cat from eating it. Oh, no, you can go take care of that. It just fell off the shelf spontaneously and shattered. I think it's okay now, but she keeps trying to eat the pieces of glass. Sorry about that. I think you should go take care of the cat. I'll be back in like one second. Yeah. I'm trying to. Okay. No worries. Awesome.

Quarto version requirement

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? Right. 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. So that's what you need to use.

Light and dark themes

Okay. Thank you. Thank you. 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? So... Garak? 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.

Right. 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. But like Jarek will say, the answer for Shiny is a little bit different, so I'll let you answer that.

Yeah. 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, and that was in Bootstrap 5.3, so that's a relatively recent thing that we've added in Shiny, and it came after Quarto had implemented their version of light and dark. 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.

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.

Using local fonts

Thank you. 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, and so if you just search for fonts and search for the word source, that's where you get the fonts from, and then you can point to the local font files. 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, and if they are OTF files, they will even work in Typst, for example, so you can use that as a system font for your PDF documents using Typst, so you can definitely do that, it's just the font specification needs to say that it's a local font, it's a system font, I think is how we call them, and then you just give the path to it, so you have to have the files.

So there are actually two, you can have system fonts, or ones that are installed on your system just anywhere on your system, you know, like if you, you know, you download a font and then install it, like through either Windows or through macOS or whatever, 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 there are, so it is possible to use local fonts, and the brand.yaml website is a good reference for how to get that set up. Awesome, thank you.

Reflections on using brand.yml

So I had linked this in the original YouTube demo video, but I wanted to make sure everyone also saw, Sarah wrote a great blog post on brand.yaml as well, which helps walk through it, and I think the combination of the demo video and the blog post together is really helpful. 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?

It's a good question. 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. So yeah, I think it's, like, and then on the developer relations team, like, we're trying to develop a team-wide style, and I think for that use case, like, brand.yaml is really great. Awesome. Yeah, I'm not sure about surprising, but. Well, yeah, but no, that was perfect. Thank you. Cool.

Using brand.yml with ggplot

I want to make sure I get to some of the Slido questions as well, so as a reminder, you can ask questions anonymously, too, and I'll put that link in the chat in just a second, but 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. If you go sort of, you know, and use Python tooling, this would be like someone needs to teach Matplotlib how to understand brand.yaml and those, and that hasn't been done yet. 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, and then you can very easily go from this one file and configure your document and configure your plotting libraries. So that is not ready for sort of like public consumption, but we are actively working on it. It will come out sooner rather than later, like just I don't want to give a promise of a date that might be pushed back, but we're on it.

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. I did have to do a slight bit of extra tweaking, but it mostly just themed it correctly right off the bat.

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.

Sharing brand.yml across an organisation

Awesome. So I think that then answers Mike's question in the chat. So, yes, it works with ggplot theming. Brittany asks a great question. How do you recommend sharing brand.yaml files across an organisation? This is a really good question. 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?

So someone else just asked an extension question, so I'll follow up on that too. 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. So that's as far as Quarto is concerned.

So before, sorry, Jarek, just to answer the question of whether this will replace the extension folder, Quarto extensions are used for more things than just brand, right? So you can create filters, you can create article formats, you can create a lot of other things. So it's not that it will replace an extension format, it's that you can create an extension in Quarto that will bring in the brand and then it will just work. It will have the branding for that.

And on the Shiny side, we have definitely, so 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. And at that point, it could be anywhere as far as Shiny or R Markdown is concerned.

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 I'd probably just put that all in a small repo. 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.

Mike pointed out a question about using, use this for that, right? Sort of like just use branding and then you point at a file or you point to the repository or something. So that is something we could we could do. We haven't done yet, but that's very naturally a thing that makes sense to do.

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. And so it's sort of like it wouldn't be exactly use branding. It would be like, you know, use Shiny branding or use Quarto branding or something of that sort, because these details might make a difference. So we want to be a little careful on how to do these general use this. 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. So I expect that kind of thing to come up, Mike. It's a very good question, but it will not be in the immediate future. We still need to sort of understand a little better how the community is going to use brand.yaml.

Sharing brand.yaml across projects

Thank you. See, 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 or or, yeah, 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. That's sort of the standard way to do that. 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. And that makes it really hard for you to track down and maintain it sort of, you know, it's very convenient for like five projects, but it's really, really complicated and hard when you get to like 25 or 30 projects. Right. So we just take the conservative approach and ask you to put things inside the directory.

Compatibility with other tools

Thank you. Another question. And people are testing my pronunciation with packages, but is brand.yml compatible with a sharing gun or can it also be used with Quarto documents in shiny apps? I think presentations.

Yeah, I love I love sharing and I happen to also maintain a package called sharing in femur and the which is designed to create full sharing themes. And I appreciate the nudge. I feel like brand.yml would be a great fit for that. And it would totally work. And it could be a new feature in the sharing and femur package. But 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.yml 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.yml file and read it and pull out the fields that you need and pass them to sharing and femur. And just about anywhere that brand.yml doesn't currently work by magic, it can be made to work using normal theming ideas. So there's always the escape hatch of just taking the stuff that's in your brand.yml file and passing it to the appropriate theming functions or or finding something that can help you do that.

So there's always the escape hatch of just taking the stuff that's in your brand.yml file and passing it to the appropriate theming functions or or finding something that can help you do that.

Thank you, and I want to make sure I share the GitHub remote repo for brand.yml in the chat here as well. Thank you, Carlos, for reminding me about that. So that's the like, Eric said, that's the specification documentation, right? So that's sort of like what he and I worked on that explains how to organize the information on these files so that Quarto and Shiny and in the future, Zaring and thematic and ggplot can all get the information from this. Right. But generally speaking, different packages, different systems, different libraries will need to learn to speak brand.yml. So to speak, right. Like that's not something that happens automatically. That's something that needs support to be added explicitly. Awesome, thank you.

So while we're sharing a few links, I also saw an inspiration page where we built a few examples like I know Dell and Home Depot and their brands are on there. So I'm just going to add if you wanted to see your company in the gallery, we are open to pull requests there. But let me share this inspiration page in the chat.

pkgdown and bslib support

Awesome. 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.yml.

So if you're looking for a concrete example, you can go to the website and you can find So if you're looking for a concrete example, you can go check out bslib and I'll make sure a link shows up in the chat in a second. 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.yml styling your pkgdown websites as well.

It's a very simple example, but I will also note that the brand.yml website uses brand.yml for its steaming. So Derek did that very early on. And so right off the top of the page on the introducing brand.yml sort of section, there's an example that brand.yml example is actually the example that we are using for brand.yml. 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.

So I just wanted to take a quick break here to say I am maybe missing links that you all want me to share with everybody while I'm trying to gather questions and copy and paste from Slido. So Quarto, there was a Quarto page that you wanted me to share. Sarah, can you just remind me what that was in reference to?

Yeah, so earlier you shared that like brand.yml website. There's also documentation on specifically how to use brand.yml with Quarto on the Quarto website. And that's that quarto.org link. Yeah, perfect. Just share that one. And then Garrick, you just shared one with me that I'll put in the chat too. And that's brand.yml and pkgdown.

Sass variables and theming details

Okay, perfect. Let me go try and grab a few more questions over from Slido. One was, I'm not sure how SAS variables defined in the SAS file would be treated when providing that file to bslib 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.yml 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.yml website and clicking on report an issue. And I'm happy to help you figure out what the best approach is here.

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.

HTML widgets and third-party library support

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. Thank you. 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 in the same way that you would do like we did for Quarto and for Shiny. We just added that feature. So, 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.

Yeah. 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.

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.

Sharing brand.yml across an organization

Okay. I know we are quickly approaching the end of our time here. But I thought it might be good to ask this question in a slightly different variation of something we discussed before. 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 like, you would essentially 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. And then, you know, worry about how you would pull in changes through that kind of thing.

Awesome. Thank you so much.

I know we're at the top of the hour. So, if you do have to run to another call, that is okay. I just saw there were like two or so other questions.

Oh, you have to run? Okay. I'll gather any questions that we didn't get a chance to answer. And maybe we can do a follow-up blog post with some of those questions as well or share them with the recording of the demo too.

Carlos. Okay. Carlos says you have five minutes. Sarah has two minutes. Okay. Never mind. I'm going to keep going.

I see Sam had asked a question a little bit earlier and I had missed it. So, I'm just going to try and find that real quick. But it was, I noticed an email in the brand YAML feature flowchart. What are you envisioning for that?

Email feature in brand.yml

I can take 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. So, we have to be a little bit more careful on, like, what we are allowed because you can't use all of the features that are available. 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. So, it's, we are working on that.

Closing remarks

Thank you all so much. I just put into the chat, if I had missed anybody's questions, feel free to repost. I didn't see any come up there yet. 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.

But thank you so much for taking the time to join us. I hope to see you at the next one, too.

Any last words of advice or anything you all want to share with everybody?

Just say, I think, like, try out brand.yml, 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. I don't know why cats want to eat glass.

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