A Python package that provides the brand.yml definition for applying UNDP-branded styling in Shiny and Quarto projects. The project is based on the corporate guidelines from UNDP Brand, UNDP Design System and UNDP data viz library.
Note
This package uses _brand.yml file from the brand extension in extensions-for-quarto project. As of the time of writing, that extension is still under development. Before the release of version 1.0.0 of the extension, this package should be considered experimental. Consult the resources above for the detailed guidance on corporate branding. For ideas and feedback, feel free to open an issue.
This package is distributed via GitHub only. You can install it with pip:
# latest (unstable) version
pip install git+https://github.com/undp-data/undp-brand-yml
# specific release version
pip install git+https://github.com/undp-data/undp-brand-yml.git@0.2.0
# specific release version with extras
pip install undp-brand-yml[plotting] @ git+https://github.com/undp-data/undp-brand-yml.git@0.2.0Similarly, you can add it to your requirements.txt:
# specific release version (recommended)
undp-brand-yml @ git+https://github.com/undp-data/undp-brand-yml.git@0.2.0See VCS Support in pip documenation for more details.
Tip
It is strongly recommended to install the package in a virtual environment. Refer to Creating virtual environments section in the Python documentation to learn more about venv.
The package is designed to provide "ground truth" definitions for some of the core corporate design aspects, including logos, colours, and fonts. It is mainly intended to be used as a dependency in other packages and projects. But you can also use it directly to get definitions of interest.
Quarto provides built-in multiformat support for _brand.yml. To have the branding applied, the brand file must be present in the project directory. You can easily add it to your project by running the following command in your terminal:
python -m undp_brand_ymlAlternatively, you can modify your _quarto.yml to include a pre-render command:
project:
title: "Project Title"
pre-render: python -m undp_brand_ymlThis will ensure the corporate _brand.yml is added to your project every time you render your document(s). By default, the command will do nothing if _brand.yml file already exists in the project. So, if you have modified the file, your changes will not be overwritten.
Important
Quarto 1.8.20 introduced support for brand extensions, which are now the recommended way to distribute _brand.yml and related files. You should consider using the brand extension instead of using this Python package. Refer to extensions-for-quarto project to learn more.
Like in Quarto projects, Shiny for Python applications require a _brand.yml file to be present in your project's directory. However, unlike Quarto, Shiny for Python has no support for brand extensions. You must therefore manually add the file by running the following command in your terminal:
python -m undp_brand_ymlYou will also need to modify your app.py file to enable branding:
from shiny import ui
app_ui = ui.page_fluid(
# App UI code...
theme=ui.Theme.from_brand(__file__)
)Tip
Refer to Branded theming for Shiny for Python apps to learn more about _brand.yml support in Shiny for Python.
For more advanced use cases, you may want to programmatically access the specifications from _brand.yml. Here is an example of how you can do so:
from undp_brand_yml import brand
# get the official full name and recommended description
print(brand.meta.name.full)
print(brand.meta.description)
# get official links to webpages and social media accounts
print(brand.meta.link.home)
print(brand.meta.link.linkedin)
# get hex colour values from the official palette, e.g. UNDP Blue
print(brand.color.palette["blue-600"])
# list all the colour names
print(list(brand.color.palette))
# get colour scheme definitions for plotting
print(brand.defaults["categorical"])
print(brand.defaults["sequential_neutral"])Important
You must have plotting extra installed to make use of the functionality descrived in this section. Refer to Installation section above for details.
If your project includes a data visualisation component, consider using the plotly library, whose figures can be easily styled using this package:
import plotly.express as px
from undp_brand_yml.plotting import set_plotly_theme
# set the default theme to UNDP branding
set_plotly_theme()
df = px.data.iris()
fig = px.scatter(data_frame=df, x="petal_length", y="petal_width", color="species")
fig.update_layout(xaxis={"rangemode": "tozero"}, yaxis={"rangemode": "tozero"})
fig.show()Tip
For JavaScript projects, consider using UNDP data viz library.
The package ships the _brand.yml file based on the corporate guidelines. Its main purpose is to be a dependency for other packages and projects. Its features include:
- Comprehensiveness: the package provides metadata, logo, colour and typography definitions, all in just one file.
- Consistency: the specifications are in line with the UNDP Design System and UNDP data viz library.
- Versatility: the package can be used in Quarto or Shiny for Python applications alike. It can also style
plotlyfigures usingplottingextras. - Minimalism: a single required dependency (
brand-yml).
Important
_brand.yml provides just a starting point for styling projects and by no means replaces the corporate guidelines. Adding the file to your project alone will often not suffice to fully align its design with the guidelines. You might need to complement it with custom CSS or templates to improve the look and feel of your outputs.
All contributions must follow Conventional Commits. The codebase is formatted with black and isort. Use the provided Makefile for these routine operations.
- Clone or fork the repository
- Create a new branch (
git checkout -b feature-branch) - Make your changes
- Ensure your code is properly formatted (
make format) - Commit your changes (
git commit -m 'Add some feature') - Push to the branch (
git push origin feature-branch) - Open a pull request
This project is licensed under the BSD 3-Clause License. However, entities or individuals not affiliated with UNDP are strictly prohibited from using this package or any of its components to create, share, publish, or distribute works that resemble, claim affiliation with, or imply endorsement by UNDP.
UNDP’s name, emblem and its abbreviation are the exclusive property of UNDP and are protected under international law. Their unauthorized use is prohibited, and they may not be reproduced or used in any manner without UNDP’s prior written permission.
This project is part of Data Futures Exchange (DFx) at UNDP. If you are facing any issues or would like to make some suggestions, feel free to open an issue. For enquiries about DFx, visit Contact Us.