Company-branded reports, apps, and dashboards made easier with brand.yml & Posit

Hi, I'm Sarah Altman and I'm on the Developer Relations team at Posit.

Today I'm going to talk to you about brand.yml, a really exciting new project from the Shiny and Quarto team. Brand.yml allows you to easily apply branding across reports, dashboards, apps, and more with a single yml file. There will be a live Q&A after this presentation where we'll be joined by Gareth Aiden-Bouy and Carlo Scheidegger, two of the software engineers who created brand.yml. We're all really excited about this project and are looking forward to your question.

So today I'm going to show you how to transform your unbranded Quarto documents and Shiny apps that might look something like this into consistent branded products like this, all with a single yml file. We'll talk about why you might want to use brand.yml, the structure of a brand.yml file, how to apply brand.yml to Quarto documents and Shiny apps, and how to create a brand.yml with the help of an LLM.

Why use brand.yml

So why use brand.yml? Let's say you're a data person in an organization and as part of your job you create reports, apps, plots, dashboards, and other things. All these artifacts that people at your organization and maybe even people outside of your organization use. And your company has particular branding, it has colors, logos, fonts that it uses in its materials. That branding might even be immediately recognizable to people outside of your company. So you as a diligent data professional try to apply your company's branding across all your plots and dashboards and apps.

But you run into a couple of hurdles. First, you know how to change the color of your plots and you know how to adapt the theme of your Quarto dashboards. But to really get your company's branding right, you need to play around with CSS and other things that are mostly outside of your toolbox. Second, you can get some of the branding right but at the same time your co-workers are also trying to apply the same branding guidelines and you're all kind of getting it right but in different ways. And so your work as a team doesn't really feel right.

It doesn't feel consistent. And then maybe you've amassed all this code that brands your outputs and it looks really nice, but then the company decides to change its brand. And so now you have to comb back through your code and update everything manually. A frustrating and time-intensive task.

Consistent branding across not only your own work but across your teams ensures your work looks professional and polished. Branding can be a subtle but really powerful way to make your work shine. And your organization might also require you to follow brand guidelines.

So you need branding but branding consistently can be difficult. Your brand guidelines might include detailed requirements and applying various colors, fonts, and logos across tools and programming languages requires a lot of manual effort that can be prone to error.

It can also be really difficult to update branding consistently when brand guidelines change. Think about all the files you might need to update with traditional approaches.

Finally, ensuring team consistency can be hard. You want to make sure all contributors follow brand guidelines in a similar way across all their reports and dashboards and apps, which can definitely be challenging. So addressing these problems is exactly why the team behind brand.yml created it. With brand.yml you can define your organization's branding in a single yaml file and apply that branding across reports, dashboards, and apps pretty much instantly.

With brand.yml you can define your organization's branding in a single yaml file and apply that branding across reports, dashboards, and apps pretty much instantly.

So what does this mean? It means we write a single yaml file that specifies colors, logos, fonts, and typographic choices. You're going to often see this named underscore brand.yaml.

Then you can instantly apply branding from that yaml file across Quarto documents, Shiny apps, and more.

Structure of a brand.yml file

So at this point you might have a couple of questions. How do we structure this yaml file? And after we've created the yaml file, how do we actually apply it to our outputs to brand them? So let's look at the yaml file structure first.

So I'm going to give you an overview of the file structure and explain how you'd go about building up your own brand.yaml file. But if this seems like a lot of manual work, know that towards the end of this presentation I'll show you how to create a brand.yaml with the help of an LLM.

So yaml is a language often used to represent structured data in a human-readable format. You often see yaml used for things like configuration files. You don't need to know a lot about yaml to get started creating yaml files like brand.yaml.

One thing to know is that yaml uses key-value pairs. So the key in this case right here is meta and then this whole thing is the value. And we have another key-value pair within that.

And that's all you really need to know about how yaml works. So now let's talk about the specifics of a brand.yaml file. Brand.yaml files require a particular format to brand your outputs like Shiny apps and Quarto documents. There are four main components. Meta, which contains identity information like the name of your company. Logo, which is where you specify files or links to your brand's logo at various sizes. Color, which is where you define the colors in your brand's color palette and how those colors are used. And typography, which is where you define fonts and other typographic choices.

So again a brand.yaml file will need meta, logo, color, typography. You can also specify defaults, which is where you can add additional context-specific settings that might be options used by like Bootstrap in Quarto or Shiny.

So let's take a closer look at the color and typography sections. So first, color. So the color section in brand.yaml consists of two main parts. There's palette, which is a set of named colors specific to your brand. So in this case, the key value pairs are a name of a color, which this could be anything you want, and then the hex code for that color.

So this brand defines a black, blue, neutral, red, and violet. The second part is the theme colors. And this is where you assign those specific colors to various UI elements. So here we're saying we want to use our neutral color for background. So if you were building up this file from scratch, you would first want to define the colors in your palette by taking a look at your brand guidelines and figure out what colors are in your brand's color palette to define those colors and then map those brand colors to particular UI elements. How do you want those colors to be used? Where do you want them to appear?

Okay, so now typography. Like color, typography has two sections. First, you define the fonts used by your brand. And you can specify either local or online font sources. So this brand.yaml uses Google fonts.

Then you take those fonts and define how they are used by different typographic elements. So in this case, we're using this font as the base font. And then for headings, we're using Montserrat with a particular weight and also assigning a color. Great. So, so far, we've talked about why you might want to use brand.yaml, how to structure a brand file.

Applying brand.yml to Quarto and Shiny

And now let's see it in action. I'm going to show you how to use brand.yaml with Quarto and Shiny.

Okay, so now I'm in Positron. And over here on the left hand side, you can see all of my files. I have a Python Shiny app, Shiny for R app, and a Quarto document that creates a Quarto site.

So I'm going to show you how to apply brand.yaml to the Shiny for Python app, Shiny for R app, and the Quarto document. So I have the Python app open, but we're actually going to talk about Quarto first.

Okay. So here's my Quarto document. Let's just render it and see what it looks like without any branding. So I'm clicking the preview button to render and preview this Quarto site.

Okay. Great. So that's just the default Quarto theme. We haven't applied any branding at all.

For Quarto documents, to apply brand.yaml, all we need to do is add an underscore brand.yaml to the same parent directory. Quarto will then automatically apply the branding. So let's add a brand.yaml file. I'm going to create a new file.

And I already have all the yaml that I want over here, so I'm just going to paste it in.

Okay. This is the brand.yaml file that we saw earlier that defines a brand for an example company. It has a color palette, some fonts, a logo. Okay. I'm going to save this as underscore brand.yaml. And now I didn't change anything in the original Quarto document, so let's just rerun it and see what happens. Great. So without changing any code in the actual Quarto document, we applied the branding from brand.yaml. Quarto found our underscore brand.yaml file and applied the branding. So now we have a different colored nav bar, a logo, a different background, different fonts. And we got all of this from a single yaml file.

If we wanted to use a brand yaml file from a different directory, you can supply the path to that brand.yaml to brand in the Quarto.yaml header. So if we had it in a directory brand.brandfile.examplecode.yaml, we could specify that there. You can also specify the brand file in the Quarto.yaml file if you're using a Quarto project. If you have a brand.yaml file in a directory with multiple Quarto documents and you want to turn off the branding for one of those documents, you can set brand to false. And that will make it so that the branding is not applied.

I'm going to remove this and let's rerender. Okay. So you'll notice that the plots aren't branded. They didn't change. The goal is for Python and R plotting libraries to support brand.yaml in the future. But for right now, we're going to do a little bit of extra work to get the plot styled correctly. So for now, one way to do this is to take advantage of the brand.yaml Python package. With this package, we can easily read in the brand.yaml file into Python and then access specific elements of this. So we're going to use this to write a function that builds a matplotlib style sheet, essentially just something that's styling our matplotlib plots. And then in that style sheet, we'll use the colors from our brand.yaml.

So I'm not really going to talk too much about this, but the code is in the GitHub repository and feel free to ask questions about it during the Q&A. Let's just quickly take a look at that Python script. So again, we're using the brand.yaml Python package. And if you take away something from all this matplotlib talk, I would take away this. There is a brand.yaml Python package that helps you use brand.yaml in Python. So here we create a function that defines that matplotlib style sheet using the brand.yaml Python package to read in our brand and then access specific elements of it.

Okay. So now I'm going to go back to the Quarto document and uncomment these lines which are importing that function and then running it. Great. And now our plots follow the branding defined in the brand.yaml file.

So next, let's talk about Shiny for Python. With Shiny for Python version 1.2, using brand.yaml to theme your Shiny app is pretty straightforward. To get started, you'll want to make sure you've installed the latest version of Shiny with the theme extra. And you can do that like this. So I'm just going to the terminal.

So pip install Shiny bracket theme. I'm not going to run this because I already have it installed. And that will get you the latest version of Shiny with the theme extra.

Great. I'm going to close these and now open up our Shiny for Python app.

Let's run this. And remember, we have that brand file in the directory. So you might have expected it to automatically brand just like the Quarto document that we rendered. But this is just the default Shiny theme. So for Shiny for Python, we're going to need to do one more step to apply our branding from the brand.yaml file. And to do so, we're going to use the function UI theme from brand to define a custom theme from our brand.yaml file.

So this is UI.page. This is defining page options for the entire page. So here we have a title and we're just setting fillable to true. But now I'm going to add the theme argument. And create a theme using UI.theme from brand. And this is setting the theme of the page to a theme that we're creating from brand. But now we still need to supply it with information about where our brand.yaml file is. So now I can either pass it the path to a brand.yaml file or because brand.yaml is in the same directory, I can use double underscore file to refer to the current file path and then theme from brand will find the correct brand.yaml file.

Okay. So now I'm going to run this app again and see what happens.

Great. So now our app uses the branding from brand.yaml.

This is a little hard to see because it's small, but you'll see it in full screen in a little bit.

So we still need to style the plots. I'm going to do the same thing as I did for the Quarto document. Import that style sheet function and then run it.

Okay. Now the plot is themed correctly.

Okay. So finally we're going to talk about Shiny for R. So let's open up that app.

Okay. So with the recent release of bslib 0.9, bslib and Shiny for R support brand.yaml. So to get started with brand.yaml in Shiny for R, you'll want to make sure to update bslib.

So let's run this app. So for Shiny for R, all we need to do is have that underscore brand.yaml file in our same directory. And Shiny will automatically apply the theme. You'll notice that I didn't need to do anything extra to style the plots, and that's because I'm using thematic. So right now thematic only partially supports brand.yaml, so I had to do a little bit of extra work. And the goal is for thematic to entirely support brand.yaml, so you won't have to do any extra work to style your plots inside Shiny apps.

Okay. So now we have two apps and a Quarto website styled from a single brand.yaml file. Now let's say we want to deploy one of these apps somewhere. I'm going to deploy to Posit Connect.

So in Positron, which is the IDE I'm in, or in VS Code, you can use the Posit Publisher extension to deploy to Posit Connect. So I'm going to deploy to Posit Connect, and I'm going to deploy to Publisher extension to publish to Connect. If you don't already have that extension, you can go to the extensions tab and then search for Posit Publisher, and then install. And then click on Posit Publisher and deploy your project from there.

I've already deployed this Shiny app, so I already have a deployment set up. But if you're starting from scratch, you can click this plus button to set up a new deployment, select the file that you want to deploy, create a title for it, and then select where you want to deploy it.

So I want to deploy the Shiny4R app, so I'm going to switch back to that, and then click deploy your project. Great. So this says our deployment was successful, so now I'm going to click view and then open. Okay, so here's our Shiny4R app, themed with brand.yaml and deployed to Connect. This diagram shows everywhere that the brand.yaml team hopes to deploy Shiny4R to that the brand.yaml team hopes to support brand.yaml in the future. The green boxes show where brand.yaml is already supported. This diagram is on the brand.yaml website.

Creating a brand.yml with an LLM

So if you want the most up-to-date information, you can take a look there. At this point, you might be thinking, this all sounds great, but translating my organization's brand guidelines into YAML seems kind of tedious. This is a great use case of an LLM.

Garrick wrote this very helpful article about how to create a brand.yaml with the help of an LLM. Because brand.yaml is pretty new, the LLMs like chatGPT don't really know about it yet, but you can teach it pretty easily with a prompt.

So Garrick wrote this helpful prompt that you can copy and paste into a chat interface or use as a system prompt. It teaches the LLM about brand.yaml and how to format the file.

So I can copy this and then go to chatGPT and paste in that prompt. Then at the end, ask the LLM to generate you a brand.yaml file for your organization. So let's ask it to make a brand.yaml file for Posit.

Now I need to supply it with information about Posit's brand. This can take the form of screenshots of the brand guidelines, text from the brand guidelines, or a screenshot of a page that shows a bunch of features of the brand. I'm going to supply it with a few screenshots of Posit's brand.

So now we have a brand.yaml file for Posit. Let's try it out. One good way to experiment with brand.yaml is by using this branded theming example on ShinyLive. ShinyLive is a way to run Shiny in the browser. So I'm going to try out our brand.yaml in this example.

So this ShinyLive example includes an app that uses a brand.yaml file, and the app is designed to highlight all the features of the brand. So this is using the brand.yaml that was already there, and you can see the color palette and the fonts. You can see the full palette here. So let's paste in from chatGPT and see what happens.

And I'm not going to add the logos here, so let's just remove this for now.

And rerun. Okay.

So I don't think this perfectly captures Posit's brand, but it gets pretty close, and it's reasonably good. It's a good way to play around with a brand.yaml file. The LLM might not have given us a perfect brand.yaml file, but it's a good starting point. And now if I wanted to experiment, I could edit what is already there instead of starting from scratch. This branded theming example on ShinyLive is also just a great way to get familiar with brand.yaml.

Summary and advantages

Okay. So we've covered a lot today. We've talked about how to apply brand.yaml files, how to structure those yaml files, and how to generate a brand.yaml file with the help of an LLM.

Brand.yaml is really cool, and I encourage you all to try it out for your organization or personal branding uses. And again, here are just some advantages of brand.yaml. Brand.yaml creates a common syntax for theming across different outputs. You don't need to worry about maintaining different files with different structures for different outputs.

This helps you get consistent branding without a lot of effort, ensuring your work consistently follows brand guidelines and avoids duplication by defining branding in one file.

Brand.yaml also makes it really easy to collaborate. You can share a single brand.yaml file across your organization to ensure everyone can easily apply the same branding.

Another thing is that we've been talking about using brand.yaml for use in your organization, but there are other things you might want branding for. You might want to develop a personal brand.yaml and use it across your websites and talks to create a consistent personal brand.

I use brand.yaml for these slides, so if I want to use this theme in the future, I can just use this theme in the future. I can just use that same yaml file.

Brand.yaml also makes it really easy to collaborate. You can share a single brand.yaml file across your organization to ensure everyone can easily apply the same branding.

Great, so thanks for coming to this presentation, and I am looking forward to your questions in the Q&A.