brand.yml

Unified branding with a simple YAML file

Create reports, apps, dashboards, plots and more that match your company’s brand guidelines with a single _brand.yml file.

Introducing brand.yml

brand.yml is a simple, portable YAML file that codifies your company’s brand guidelines into a format that can be used by Quarto, Python and R tooling to create branded outputs. Our goal is to support unified, branded theming for all of Posit’s open source tools—from web applications to printed reports to dashboards and presentations—with a consistent look and feel.

With a single _brand.yml file you can collect brand logos, colors, fonts and typographic choices, typically found in your company’s brand guidelines. This _brand.yml can be used by Quarto and Shiny for Python ¹ to quickly create basic themes that match the brand guidelines.

_brand.yml

meta:
  name: brand.yml
  link: https://posit-dev.github.io/brand-yml

logo: logos/icon/brand-yml-icon-color.svg

color:
  palette:
    black: "#1A1A1A"
    white: "#F9F9F9"
    orange: "#FF6F20"
    pink: "#FF3D7F"
  foreground: black
  background: white
  primary: orange
  danger: pink

typography:
  fonts:
    - family: Open Sans
      source: google
    - family: Rubik
      source: google
    - family: IBM Plex Mono
      source: google

  base: Open Sans
  headings:
    family: Rubik
    weight: 400
  monospace: IBM Plex Mono

Learn more

Jump to Structure to learn about the brand.yml syntax and how to write a _brand.yml file.

You can explore some inspiring examples of brand guidelines found in the wild.

If you’re a Python developer or are interested in using _brand.yml to adapt a Python package to use brand.yml for theming, check out the brand_yml Python package documentation to get started.

We’d love to hear from you

brand.yml is a new project and we’d love to hear from you to decide how the project will evolve. Some fields may change as we learn what works and what doesn’t.

Please reach out to us on the discussion forum with any questions, thoughts, or feedback!

Support

brand.yml is currently supported in Shiny for Python and Quarto websites, presentations, dashboards, and Typst documents, as well as via the brand_yml Python package.

We plan to support brand.yml throughout the suite of open source projects maintained by Posit, in particular the projects included in the diagram below.

---
config:
  look: handDrawn
  theme: neutral
---
flowchart LR
    by{brand.yml}
    by-->quarto[Quarto]
    quarto-->quarto-html
    quarto-->quarto-pdf
    quarto-html-->quarto-websites[Websites]
    quarto-html-->quarto-presentations[Presentations]
    quarto-html-->quarto-dashboards[Dashboards]
    quarto-html-->quarto-emails[Emails]
    quarto-pdf-->quarto-typst[Typst]

    by-->R
    R-->r-bslib["{bslib}"]
    R-->r-thematic["{thematic}"]
    r-bslib-->r-shiny["Shiny for R"]
    r-bslib-->r-rmd["R Markdown"]
    r-thematic-->r-ggplot2["{ggplot2}"]
    r-thematic-->r-plot["{plot}"]

    by-->Python
    Python-->py-brand_yml["brand_yml"]
    py-brand_yml-->py-shiny[Shiny for Python]
    py-brand_yml-->py-seaborn[seaborn, matplotlib, etc.]

    classDef implemented fill:#8CE3A0,stroke:#0A2911,color:#0A2911;
    class quarto-websites,quarto-presentations,quarto-dashboards,quarto-typst,py-brand_yml implemented;
    classDef in-progress fill:#B3D7FF,stroke:#00254D,color:#00254D;
    class py-shiny implemented;
    classDef highlighted fill:#FFE8DB,stroke:#612200,color:#612200;
    class by highlighted;

    click quarto href "https://prerelease.quarto.org/docs/authoring/brand.html"
    click quarto-typst href "https://quarto.org/docs/output-formats/typst.html" "Typst in Quarto"
    click quarto-presentations href "https://quarto.org/docs/presentations/revealjs/" "Reveal.js in Quarto"
    click quarto-dashboards href "https://quarto.org/docs/dashboards/" "Dashboards in Quarto"
    click r-shiny href "https://shiny.posit.co/"
    click r-bslib href "https://rstudio.github.io/bslib/"
    click r-thematic href "https://rstudio.github.io/thematic/"
    click r-ggplot2 href "https://ggplot2.tidyverse.org/"
    click r-rmd href "https://rmarkdown.rstudio.com/"
    click py-shiny href "https://shiny.posit.co/py/"
    click py-brand_yml href "pkg/py/"

Design

User stories

Jordan Ellis and Sofia Torres are data scientists at Genewise Therapeutics, a biotech company that uses AI to create tailored treatment plans based on personal genetic makeup and biomarkers.

Jordan Ellis

Jordan Ellis is a data scientist with a strong academic background in bioinformatics, in particular biology, genetics and statistical analysis. They frequently collaborate with bioligists and chemists to analyze data and present results in a clear an digestible format.

Jordan uses both R and Python and has recently started using Quarto to create their reports, which they share with non-scientific stakeholders. They noticed that their reports garnered more attention when they started using Quarto, but they suspect that their reports would be even more impactful if they matched the look and feel of the company’s branded reports.

On the other hand, Jordan doesn’t want to spend too much time having to rely on design teams for their reports, which often need to be re-created when data changes. Once, they tried to learn CSS but found it too complex and intimidating to learn in a few hours, so they settled on a Bootswatch theme that’s “close enough” to Genewise’s brand.

Sofia Torres

Sofia Torres leads a team of data scientists, including Jordan, at Genewise. She’s noticed that Jordan isn’t the only person on their small team who could benefit from branded reporting. She has been considering talking to a designer she knows on the marketing department, but it’s been hard to coordinate a time to meet and the designer sounded confused when he heard about Quarto.

Today, Sofia was copied on emails from two of her reports who each used Quarto to create attached reports. But when she opened the reports, she was a little embarrassed that her team had sent out two reports with wildly different styles.

Sofia wants to get everyone on her team on the same page. She started collected snippets of code and settings in a page on her department’s Confluence space, but she can tell that very few people have even seen it, let alone have been using it.

Users like Jordan and Sofia will interact with brand.yml in three primary ways:

Creating a _brand.yml file. Jordan has found Genewise’s internal branding guidelines. As they’re reading through these guidelines, they notice that the guidelines recommend a specific set of colors and fonts. They also find copies of their company’s logo, along with several pages of do this not that examples.

At this stage, Jordan wants to codify the best practices mentioned in the brand guidelines into a simple, human readable format. They’re excited that they only need to do this once, but they do make a note of the link to brand guidelines, just in case.

While they have the brand guidelines open, they download the logo files and store them next in the same folder as the _brand.yml file they’re working on.
Using and sharing the _brand.yml file. When Jordan shared their new report style with their manager, Sofia was thrilled. Immediately, she asked everyone on her team to start using the new branded styles. Thanks to Quarto’s simple interface, everyone on the team could run a single command to bring the brand assets into their projects and documents, including the logos that Jordan downloaded.

The next time two members of her team sent out reports on the same day, both attachments looked coherent and professional. She’s just as thrilled when she opens up the experiment-tracking Shiny dashboard her team built for a biology group and the Shiny app looks custom-built for Genewise.
Updating branding tweaks and format settings. After a few weeks of using the branded theme for her reports, Sofia needs to present to the C suite. She uses the new brand files to create her presentation, but it’s just a little off. Thankfully she’s able to grab some time with the designer, who gives her a small CSS file that really brings the design home.

Knowing that the rest of her team would like to use the same slide styles, she saves the CSS file in their brand.yml repository. She also realizes that everyone else would likely also want to use her settings for slide-number and title-slide-attributes, so she updates the _brand.yml with these new values for the revealjs format.

Guiding principles

brand.yml was designed with the following considerations in mind:

It needs to be easy to translate brand guidelines into the structured format of a _brand.yml file.
We aim for Good Enough theming. A _brand.yml is a great place to start and for most people will be all they need.
A YAML file alone isn’t enough. Brands have additional assets, like logos and font files.
Users will want to create new documents, projects or apps with the _brand.yml and related assets.
Users will want to incorporate the branded theme into existing documents, projects and apps.
Using brand.yml should not impede localized customizations.
Because brand.yml is by design incomplete for any given output format, it needs to fit into a workflow that makes specific outputs formats shareable and reproducible.
1. This could mean that brand.yml tooling is flexible enough to store format-specific options, e.g. to encompass additional assets used in Shiny apps or Quarto websites, or format-specific options for Quarto PDF documents, etc.
2. Alternatively, brand.yml tooling could fit into larger, existing tools for sharing settings and formats, like R packages, Quarto custom formats, or a Shiny html_dependency().

Footnotes

Support for Shiny for R is expected to arrive in the very near future.↩︎