Brand your Quarto projects with

b

r

a

n

d

.

y

m

l

R-Ladies Philly

March 12, 2025 @ 11am CT

Introduction

ivelasq

ivelasq3

ivelasq3

ivelasq.rbind.io

You may notice I’m using the default Quarto theme—that’s on purpose! We’ll come back to that later.

Background

I’m going to start with a true story. Quarto is a scientific technical publishing system. But it’s not so new anymore, it was announced July 28, 2022 at rstudio conf. If you are here, I hope you have some familiarity with Quarto. Essentially, executable code and text to create a variety of docs (websites, presentations, books) from a single source. It’s inherently multilingual, supporting R, Python, Julia, Observable, and designed to handle more in the future. And it aims to have a consistent syntax across tools (vs R Markdown’s bookdown, xaringan, etc.). Back to the story, Quarto was announced and not quite two months later, on September 19th…

Background

Background

Why did this come up? Once the initial excitement of Quarto wears off, you start thinking about how to use it practically.

I got to hear Garrick Aden-Buie, developer on the Shiny team and one of the creators of brand.yml, talk about the motivation behind brand.yml. I want to mention Garrick is an amazing speaker, his talks are approachable, thoughtful, and insightful. He will be talking about brand.yml at Shiny Conf in April. Shiny Conf is a free and virtual conference hosted by Appsilon. If you have the opportunity, I really encourage you to join and watch Garrick’s talk to hear about brand.yml from the eyes of a developer and also to hear how it applies to Shiny, since this talk is mostly about Quarto. Anyway. At posit::conf(2024), David Keyes gave a talk about Quarto’s default styles. The defaults work well, but his company focuses on creating reports that are not just functional but also more effective, more accessible by visually appealing.

David Keyes | Report Design in R: Small Tweaks that Make a Big Difference | posit::conf(2024)

Aesthetic
Usability
Effect

Does this actually matter? The answer is yes. David discusses the aesthetic usability effect—the idea that people perceive visually appealing designs as more intuitive and easier to use. Making things look better isn’t just about style; it helps ensure your work is more effective in reaching your audience. So, it is in your best interest to do this.

At RStudio::conf(2019), Heather and Jacqueline Nolis gave a talk about prototyping a Shiny app to present to stakeholders and gain their buy-in. Their goal wasn’t just to deliver information in the right format—like a web app—but also to present it in a way stakeholders would find familiar and engaging. They shared that they spent an extra day theming the app to match T-Mobile’s brand style, which turned out to be a crucial step in securing stakeholder approval. It made a difference.

Heather & Jacqueline Nolis | Push straight to prod: API development with R and Tensorflow | rstudio::conf(2019)

This isn’t a new idea—it’s why marketing teams invest time and resources into developing brand guidelines. But branding isn’t just for marketers; developers also need to consider it to make their work more effective and engaging. Take data visualizations, for example. When you see a certain style, you instantly recognize it as The Economist’s. Their design is so distinct and standardized that it even has its own ggplot2 theme.

library("ggplot2")
library("ggthemes")

ggplot(mtcars) +
  geom_point(aes(x = wt, y = mpg, colour = factor(gear))) +
  facet_wrap( ~ am) +
  scale_y_continuous(position = "right") +
  theme_economist() +
  scale_colour_economist()

Source

Challenges with branding

• Excessive manual effort
• Difficult to update
• Team consistency

Excessive manual effort: Applying colors, fonts, and logos across reports, apps, and dashboards takes time and is prone to errors. Difficult to update: When brand guidelines change, it’s difficult to update all products consistently. Team consistency: Ensuring all contributors follow branding guidelines across reports, dashboards, and apps can be challenging to manage.

That’s why the release of brand.yml was so exciting—it provided another option for people looking to create beautifully themed documents with ease.

brand.yml’s tagline is unified branding with a simple YAML file. The idea is simple: every company has brand guidelines, and brand.yml helps translate them into a YAML file that can style slides, websites, Shiny apps, and more. This approach ensures that branding is consistent across different projects. The goal is to structure the YAML file in a way that makes sense both to those referencing it for brand consistency and to developers using it to theme their work.

posit-dev.github.io/brand-yml

brand.yml

1. Define branding in a single _brand.yml file.
2. Instantly apply branding across Quarto documents, Shiny apps, and more.

The idea is to take your brand guidelines and translate them into structured YAML.You create a single, structured YAML file that Quarto and Shiny will pick up, ensuring consistent branding across your outputs. You don’t HAVE to use different systems to change the appearance of your documents. Do you need CSS? Will you need to learn bslib? Maybe. brand.yml offers “Good Enough” theming. It might not match your company’s guidelines perfectly, but it will get you very close. To specify a brand, create a _brand.yml file in the root directory of your project (next to _quarto.yml). Quarto will automatically detect the _brand.yml file and apply the branding to all supported document formats in the project. Another advantage is that you can use brand.yml in conjunction with other theming files, like you need additional tweaking with CSS.

Where does it work?

• Quarto v1.6
  • html, dashboard, revealjs, typst
• Shiny for Python v1.2
• R Markdown (with bslib v0.9.0)
• Shiny for R (with bslib v0.9.0)

Support documentation

brand.yml elements

• meta: Identifying information, name of the company, URLs, etc.
• logo: Files or links to the brand’s logos.
• color: Colors in the brand’s color palette.
• typography: Fonts for different elements.
• defaults: Additional context-specific settings.

_brand.yml structure

_brand.yml

meta: 
  name: Example Company
  link: 
    github: https://github.com/example-company

logo: 
  medium: logos/logo.png

color:
  palette:
    black: "#1C2826"
    blue: "#0C0A3E" 
    neutral: "#F9F7F1" 
    red: "#BA274A"
    violet: "#4D6CFA"
  background: neutral
  foreground: black
  primary: blue
  secondary: violet
  danger: red

typography:
  fonts:
    - family: Nunito Sans
      source: google
    - family: Montserrat
      source: google
    - family: Fira Code
      source: google

  base: Nunito Sans
  headings:
    family: Montserrat
    weight: 700
    color: primary
  monospace: Fira Code
  link:
    color: danger
    decoration: underline

You might be wondering, What is YAML? YAML stands for “YAML Ain’t Markup Language.” It’s a simple data serialization format that uses key-value pairs to represent data in a readable way. Let’s take a look at a file—the _brand.yml file. This would be in your project and typically include the elements mentioned earlier. Everything is optional, so you can add as much or as little as needed. Whether you want a simple or more complex file, it’s all up to you.

Metadata

Metadata

meta:
  name: Acme Corporation
  link: https://www.acmecorp.com

The first thing to include in the _brand.yml file is your key identity information—such as the company name, links to your brand guidelines, and more. Under the meta section, you’ll find the company name and a link to your website. Here’s a minimal example of your metadata. Quarto doesn’t do anything with the meta values—they’re just for reference.

brand.yml metadata documentation

Metadata

meta:
  name: Acme Corporation
  link: 
    home: https://www.acmecorp.com
    github: https://github.com/acmecorp

You can also include a range of names or social media handles.

brand.yml metadata documentation

Metadata

meta:
  name:
    full: Acme Corporation International
    short: Acme
  link:
    home: https://www.acmecorp.com
    docs: https://docs.acmecorp.com
    github: https://github.com/acmecorp
    bluesky: https://bsky.app/profile/acmecorp.bsky.social
    twitter: https://twitter.com/acmecorp
    linkedin: https://www.linkedin.com/company/acmecorp
    facebook: https://www.facebook.com/acmecorp
  description: |
    Acme Corporation is a leading provider of innovative solutions for cartoon
    characters worldwide.
  founded: 1952

brand.yml metadata documentation

Logo

Logo

logo: logo.png

Use the logo field to specify your brand’s logo at various sizes. You can provide a local file path (relative to the location of _brand.yml) or a URL. This flexible system supports different logo sizes, light/dark variants, and the ability to store multiple image resources for various use cases.

brand.yml logo documentation

Logo

logo:
  small: logos/icon.png
  medium: logos/header-logo.png
  large: logos/full-logo.svg

The small attribute defines the logo used for small display contexts, such as favicons or mobile app icons. The medium attribute specifies the logo for medium-sized display contexts, typically used in website headers or navigation bars. The large attribute defines the logo for large display contexts, such as title slides or marketing materials.

brand.yml logo documentation

Logo

logo:
  small: logos/icon.png
  medium:
    light: logos/header-logo.png
    dark: logos/header-logo-white.png
  large: logos/full-logo.svg

You can specify different logos for light and dark backgrounds by giving the small, medium, and large attributes a nested mapping with light and dark child elements. “light” means for use on light background (or in a light color mode), and “dark” means for use on dark background (or in a dark color mode).

brand.yml logo documentation

Logo

logo:
  images:
    icon: logos/icon.png
    header: logos/header-logo.png
    header-white: logos/header-logo-white.png
    full: logos/full-logo.svg
  small: icon
  medium:
    light: header
    dark: header-white
  large: full

Use images as a nested mapping to define multiple logo resources with meaningful names. Then, you can directly reference these resources by name in the small, medium, and large attributes.

brand.yml logo documentation

Logo

logo:
  images:
    icon:
      path: logos/icon.png
      alt: "Company icon with abstract shapes"
    header:
      path: logos/header-logo.png
      alt: "Company name with logo"
    header-white:
      path: logos/header-logo-white.png
      alt: "Company name with logo in white"
    full:
      path: logos/full-logo.svg
      alt: "Full company logo with tagline"
  small: icon
  medium:
    light: header
    dark: header-white
  large: full

Logo images can have associated alternative text for accessibility purposes. This can be specified as an alt property in the image object as the alt text is directly associated with each image.

brand.yml logo documentation

Colors

Colors

color:
  palette:
    black: "#1C2826"
    blue: "#0C0A3E" 
    neutral: "#F9F7F1" 
    red: "#BA274A"
    violet: "#4D6CFA"

Next, let’s define your brand’s colors in structured YAML. The color section in _brand.yml consists of two main parts, palette, aset of named colors specific to the brand, and theme colors, semantic color assignments for various UI elements. Use the color field to set your brand’s color palette, mapping each color to its semantic role. Load your colors mapped to their hex codes (this is recommended). Define the palette with special names, so you can refer to them easily.

brand.yml color documentation

Colors

color:
  . . .
  
  foreground: black # Main text color
  background: white # Main background color
  primary: blue # Primary accent color, used for hyperlinks, etc.
  secondary: "#707073" # Secondary accent color, often used for lighter text
  tertiary: "#C2C2C4" # Tertiary accent color
  success: green # Color used for positive or successful actions
  info: teal # Color used for neutral or informational actions
  warning: orange # Color used for warning or cautionary actions
  danger: burgundy # Color used for errors, dangerous actions
  light: white # Bright color, used as a high-contrast foreground color
  dark: "#404041" # Dark color, used as a high-contrast foreground color

Then, map the brand colors to theme colors in the color section. Assign colors to specific properties, and Quarto will apply them in the output. You can also reuse these colors throughout the _brand.yml file, like in the typography section.

brand.yml color documentation

Colors

color:
  palette:
    white: "#FFFFFF"
    black: "#151515"
    blue: "#447099"
    orange: "#EE6331"
    green: "#72994E"
    teal: "#419599"
    burgundy: "#9A4665"

  foreground: black
  background: white
  primary: blue
  secondary: "#707073"
  tertiary: "#C2C2C4"
  success: green
  info: teal
  warning: orange
  danger: burgundy
  light: white
  dark: "#404041"

This would be the full section with both the palette and the themes. Colors defined in the palette can be referenced by name in other parts of the color section.

brand.yml color documentation

Colors

color:
  foreground: "#151515"
  background: "#FFFFFF"
  primary: "#447099"
  secondary: "#707073"
  tertiary: "#C2C2C4"
  success: "#72994E"
  info: "#419599"
  warning: "#EE6331"
  danger: "#9A4665"
  light: "#FFFFFF"
  dark: "#404041"

Of course, you can also skip creating a brand color palette and pick theme colors directly.

brand.yml color documentation

Typography

Typography

typography:
  base: Open Sans
  headings: Roboto Slab
  monospace: Fira Code

The typography element lets you specify fonts and their styles. Use the fonts field to list the fonts for your brand—this can be simple or more detailed. First, specify the fonts used by your brand. You can then refer to these fonts by family in other typography options and define the fonts and styles used by different typographic elements. You can use fonts from public sources like Google Fonts, or list custom font files using a relative path or URL. At its most minimal, you can directly set the font families for base text, headings, and monospace text.

brand.yml typography documentation

Typography

typography:
  base:
    family: Open Sans
  headings:
    family: Roboto Slab
  monospace:
    family: Fira Code

This saves a bit of typing and is equivalent to the following.

brand.yml typography documentation

Typography

typography:
  fonts:
    - family: Open Sans
      source: google
    - family: Roboto Slab
      source: google
    - family: Fira Code
      source: google

Currently, Quarto and Shiny assume that a font family mentioned in the typography section is available on the user’s system. To use fonts from Google Fonts or Bunny Fonts (a GDPR-compliant Google Fonts replacement), define the font sources in fonts.

brand.yml typography documentation

Typography

typography:
  fonts:
    - family: Open Sans
      source: bunny
    - family: Roboto Slab
      source: bunny
    - family: Fira Code
      source: bunny

brand.yml typography documentation

Typography

typography:
  fonts:
    # Local files
    - family: Open Sans
      source: file
      files:
        - path: fonts/open-sans/OpenSans-Variable.ttf
        - path: fonts/open-sans/OpenSans-Variable-Italic.ttf
          style: italic
    # Online files
    - family: Closed Sans
      source: file
      files:
        - path: https://example.com/Closed-Sans-Bold.woff2
          weight: bold
        - path: https://example.com/Closed-Sans-Italic.woff2
          style: italic

You can also add local fonts, so those not from the internet. Local fonts are specified using source: file and typically consist of multiple files, each representing a different weight and style. To use local fonts, list each file under the files section, providing a path attribute and optionally specifying the weight and style for each file.

brand.yml typography documentation

Typography

typography:
  fonts:
    - family: Open Sans
      source: google
    - family: Roboto Slab
      source: google
    - family: Fira Code
      source: google
  base: Open Sans #  Font and appearance settings for the base (body) text
  headings: Roboto Slab #  Font and appearance settings for heading text
  monospace: Fira Code # Font and appearance settings for monospaced text 
  link: Fira Code   #Font and appearance settings for hyperlink text

You can then specify how the fonts are applied and styled.

brand.yml typography documentation

Typography

. . .
  base:
    family: Open Sans
    line-height: 1.25
    size: 1rem
  headings:
    family: Roboto Slab
    color: primary
    weight: 600
  monospace:
    family: Fira Code
    size: 0.9em

brand.yml typography documentation

Defaults

Defaults

defaults:
  bootstrap:
    defaults:
      enable-rounded: false
      link-decoration: none

These are additional, context-specific settings beyond basic brand colors and typography. For example, they could be options used by Bootstrap in Quarto or Shiny. They might also be integrated into existing Quarto YAML fields like format or website, or added as new fields for other contexts, such as Shiny.

brand.yml defaults documentation

brand.yml inspiration

The brand.yml inspiration page features examples of companies and their themes. It’s a great resource for inspiration and reference. Plus, the team would love to add your company’s theme to the inspiration page!

brand.yml inspiration page

Let’s try it out!

R-Ladies Organizational Guide - Branding

Creating a brand.yml with an LLM

ou might be thinking, Extracting color values, fonts, and logos from brand guidelines can be tedious. Thankfully, large language models (LLMs) are great at processing information and can do the hard work for you!

Creating a brand.yml with an LLM

Creating a brand.yml with an LLM

• Explain brand.yml using the provided Markdown file in either a chat interface or as a system prompt
• Then, follow up with additional instructions: Create a _brand.yml for {company} using the following context from {company}'s' brand guidelines
• Test it out using the Shiny example app

Since brand.yml is a relatively new project, LLMs like OpenAI’s ChatGPT, Anthropic’s Claude, and others haven’t fully learned the syntax—yet. However, it’s easy to teach an LLM everything it needs to know about brand.yml. We’ve created a simple markdown file explaining brand.yml that you can copy and paste into a chat interface or use as a system prompt. Just copy the code block below and paste it into a chat interface or system prompt. Then, give it instructions to create the YAML file. There’s also a Shinylive app linked in the article if you want to try it out online.

Creating a brand.yml with an LLM

Using _brand.yml values

Beyond the automatic application of your brand file, you can also directly access _brand.yml values in Quarto documents via the brand shortcode.

document.qmd

{{< brand logo LOGO_NAME >}}

document.qmd

`## Slide Title {background-color='{{< brand color primary >}}'}`

You can’t currently access typography, meta, or defaults values using the brand shortcode.

Quarto multiformat branding documentation

brand.yml structure (outside of Quarto Projects)

document.qmd

---
brand:
  color:
    background: "#fff"
---

You can create a _brand.yml file outside of a Quarto project (e.g. without a _quarto.yml). In this case, _brand.yml will automatically apply to documents in the same directory.

Quarto multiformat branding documentation

Let’s try it out!

Positron is a next-generation data science IDE built by Posit PBC. An extensible, polyglot tool for writing code and exploring data. A familiar environment for reproducible authoring and publishing.

Positron

Disabling brand.yml

Disable brand for a document by setting brand to false:

document.qmd

---
brand: false
---

Theming priority

Keep in mind that _brand.yml always takes lowest priority in styles.

_quarto.yml

theme:
  - brand        # theming derived from `_brand.yml`
  - cosmo        # a predefined bootswatch theme
  - tweaks.scss  # a user-defined customization

Defined themes will override the brand settings. As a result, values set by the brand.yml file can be overridden by themes like cosmo or by tweaks.scss. While this can be useful in some cases, you may often want the brand settings to take priority. For these situations, use the following:

Theming priority

Keep in mind that _brand.yml always takes lowest priority in styles.

_quarto.yml

theme:
  - cosmo        # a predefined bootswatch theme
  - brand        # theming derived from `_brand.yml`
  - tweaks.scss  # a user-defined customization

Sharing brand.yml

• Create an extension
• Upload to a GitHub repo where it can be downloaded

Quarto extensions documentation

Summary

brand.yml allows you to collect a brand’s logos, colors, fonts, and typographic choices into a single _brand.yml file, which you can then apply instantly across Quarto reports, Shiny apps, and more.

• Consistency without effort
• Easy collaboration
• Not just for corporate branding

Ensure all your work consistently follows brand guidelines and avoid duplication by defining branding in one file that can be applied across projects. Share a single _brand.yml file across your organization to ensure everyone can easily apply the same branding, eliminating the need for contributors to recreate brand-specific designs for every project. You can also use brand.yml to create custom themes for your personal or team-specific projects. Create a _brand.yml file to match a specific journal or conference style.

Future of brand.yml

• Plots and tables
• Additional development in LLM tools

Join the discussion!

One thing in the works is adding branding support for plots and tables. Since brand.yml is a new project, we’d love your feedback to help shape its future. Some fields may change as we learn what works and what doesn’t.

T

h

a

n

k

y

o

u

!

Would love to hear if your company has a brand guide and whether you see an immediate use case.