We are bursting to announce that Shiny for Python now supports brand.yml, a simple, unified theming experience through a single YAML file.
What is brand.yml?
brand.yml simplifies brand management by consolidating your visual identity—colors, typography, and styling—into a single, easy-to-maintain YAML file.
For you: it’s a centralized source of truth for your brand or company’s visual identity. For the tools you use: it’s simple, structured data to coordinate theming of any output.
Here’s an example _brand.yml
file that includes metadata about the company, its logos, color palette, theme, and the fonts and typographic settings used by the brand.
_brand.yml
meta:
name: brand.yml
link: https://posit-dev.github.io/brand-yml
logo:
small: brand-yml-icon.svg
medium: brand-yml-tall.svg
large: brand-yml-wide.svg
color:
palette:
orange: "#FF6F20"
pink: "#FF3D7F"
primary: orange
danger: pink
typography:
fonts:
- family: Open Sans
source: google
base: Open Sans
A core goal of brand.yml is to introduce a common syntax for theming across various data science outputs created with open-source tools. With brand.yml you won’t need to write multiple CSS files to maintain a consistent look across your apps, websites, and presentations.
And because all fields are optional, brand.yml also serves as a simple interface to theming across many outputs. For example, you could use brand.yml to set the base font to Roboto and use orange as the primary accent color.
A minimal _brand.yml
color:
primary: "#F96302"
typography:
fonts:
- family: Roboto
source: google
base: Roboto
This same file can be used for your Shiny apps as well as your Quarto projects. We’re starting with Posit-sponsored projects like Shiny, Quarto, and R Markdown, but we’re hoping to see brand.yml adopted more widely in the open-source community. To encourage this, we’ve published the brand-yml Python package, which you can use to integrate brand.yml into your project or other packages.
We know that writing YAML isn’t everyone’s cup of tea! If you want to enlist the help of a friendly large language model (LLM), we’ve written up a guide to using LLMs to write brand.yml.
The article includes a prompt you can copy and use to teach an LLM about the brand.yml syntax, as well as a few tips and follow-up prompts you can use to get the best results.
Getting Started
With Shiny for Python v1.2.0, using brand.yml to theme your Shiny app is straightforward. To get started, make sure you’ve installed the latest version of shiny with the theme
extra:
pip install shiny[theme]
Then, create a _brand.yml
file in your project directory (either alongside your app.py
or in a parent folder). Finally, use the new ui.Theme.from_brand()
function to set your page theme
.
app.py
from shiny.express import input, render, ui
=ui.Theme.from_brand(__file__)) ui.page_opts(theme
app.py
from shiny import ui
= ui.page_fluid(
app_ui # App UI code...
=ui.Theme.from_brand(__file__)
theme )
We’ve added a complete branded theming example to shinylive.io that you can run directly in your browser. Use it to explore brand.yml features or to preview your own company’s _brand.yml
look in Shiny.
Looking Forward
We’re excited to see how the community uses this feature and look forward to your feedback! You can learn more about brand.yml and its features at the official brand.yml website. Or read more about branded and custom theming in Shiny for Python.
For Python developers, we encourage you to check out the brand_yml Python package, which provides an easy-to-use interface for parsing and making use of brand.yml files.
For R and Shiny for R developers, hang tight! Shiny for R support is next on our roadmap, followed by additional tooling to support reading and using brand.yml files.