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 Quarto and Shiny for Python1 to instantly 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.
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.
The diagram shows brand.yml connected to Quarto, R and Python. Quarto is connected to HTML (websites, presentations, dashboards and emails) and PDF (Typst) formats. R is connected to the bslib (Shiny for R and R Markdown) and thematic (ggplot, plot) packages. Python is connected with brand_yml, which connects to Shiny for Python and seaborn and other plotting libraries.
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.
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 forslide-number
andtitle-slide-attributes
, so she updates the_brand.yml
with these new values for therevealjs
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.
- 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.
- 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.↩︎