brand.yml Skill

Create and use

_brand.yml

files for consistent branding across Shiny applications and Quarto documents.

What is brand.yml?

brand.yml is a YAML-based format that translates brand guidelines into a machine-readable file usable across Shiny and Quarto. A single

_brand.yml

file defines:

Colors

- Palette and semantic colors (primary, success, warning, etc.)

Typography

- Fonts, sizes, weights, line heights

Logos

- Multiple sizes and light/dark variants

Meta

- Company name, links, identity information

File Naming Convention

Standard name

:

_brand.yml

(auto-discovered by Shiny and Quarto)

Custom names

Any name like

company-brand.yml

(requires explicit paths)

Location

Typically at project root, or in

_brand/

or

brand/

subdirectories

Decision Tree

Determine the user's goal and follow the appropriate workflow:

Creating a new _brand.yml file?

→ Follow "Creating brand.yml Files"

Using brand.yml in Shiny for R?

→ Read

references/shiny-r.md

Using brand.yml in Shiny for Python?

→ Read

references/shiny-python.md

Using brand.yml in Quarto?

→ Read

references/quarto.md

Using brand.yml in R (general)?

→ Read

references/brand-yml-in-r.md

(R Markdown, theming functions, programmatic access)

Modifying existing _brand.yml?

→ Follow "Modifying Existing Files"

Troubleshooting integration?

→ Follow "Troubleshooting"

Creating brand.yml Files

When creating

_brand.yml

files from brand guidelines:

Step 1: Gather Information

Collect brand information:

Colors

Primary, secondary, accent colors with hex values

Fonts

Font families and where they're sourced (Google Fonts, local files, etc.)

Logos

Logo file paths or URLs for different sizes

Company info

Name, website, social links (optional)

Step 2: Read the Specification

Load

references/brand-yml-spec.md

to understand the complete brand.yml structure, field options, and syntax.

Step 3: Build the File Incrementally

Start with the essential sections and add optional elements:

Minimum viable _brand.yml:

color

:

palette

:

brand-blue

:

"#0066cc"

primary

:

brand

-

blue

background

:

"#ffffff"

typography

:

fonts

:

-

family

:

Inter

source

:

google

weight

:

[

400

,

600

]

base

:

Inter

Add colors as needed:

color

:

palette

:

brand-blue

:

"#0066cc"

brand-orange

:

"#ff6600"

brand-gray

:

"#666666"

primary

:

brand

-

blue

secondary

:

brand

-

gray

warning

:

brand

-

orange

foreground

:

"#333333"

background

:

"#ffffff"

Add typography details:

typography

:

fonts

:

-

family

:

Inter

source

:

google

weight

:

[

400

,

600

,

700

]

style

:

[

normal

,

italic

]

-

family

:

Fira Code

source

:

google

weight

:

[

400

,

500

]

base

:

family

:

Inter

size

:

16px

line-height

:

1.5

headings

:

family

:

Inter

weight

:

600

monospace

:

Fira Code

Add logos:

logo

:

small

:

logos/icon.png

medium

:

logos/header.png

large

:

logos/full.svg

Add meta information:

meta

:

name

:

Company Name

link

:

https

:

//example.com

Step 4: Apply Best Practices

Follow these rules from

references/brand-yml-spec.md

:

All fields are optional - only include what's needed

Use hex color format:

"#0066cc"

Prefer simple syntax (strings over objects) when possible

Use lowercase names with hyphens:

brand-blue

,

success-green

Include

https://

in all URLs

Define colors/fonts before referencing them

For color ranges (shades/tints), choose the midpoint color

Step 5: Validate Structure

Check that:

YAML syntax is valid (proper indentation, quotes on hex colors)

Color references match palette names

Font families are defined before use

File paths are relative to

_brand.yml

location

All URLs include protocol (

https://

)

Modifying Existing Files

When modifying existing

_brand.yml

files:

Read the current file

to understand existing structure

Consult brand-yml-spec.md

for valid field options

Maintain consistency

with existing naming patterns

Preserve references

- if other colors/elements reference a name, update consistently

Test integration

- verify changes apply correctly in Shiny/Quarto

Common modifications:

Adding colors

Add to

color.palette

, then reference in semantic colors

Changing fonts

Update in

typography.fonts

, ensure weights/styles are available

Adding logo variants

Use

light

/

dark

structure for multiple variants

Light/dark mode

Add

light

and

dark

variants to colors

Using with Shiny for R

When the user wants to apply brand.yml to a Shiny for R app:

Read

references/shiny-r.md

for complete integration guide

Key function

:

bs_theme(brand = TRUE)

or

bs_theme(brand = "path")

Automatic discovery

Place

_brand.yml

at app root

Page functions

Works with page_fluid() , page_sidebar() , etc. Quick example: library ( shiny ) library ( bslib ) ui <- page_fluid ( theme = bs_theme ( brand = TRUE ) ,

... UI elements

)

Using with Shiny for Python

When the user wants to apply brand.yml to a Shiny for Python app:

Read

references/shiny-python.md

for complete integration guide

Key function

:

ui.Theme.from_brand(file)

Automatic discovery

Place

_brand.yml

at app root

Installation

Requires pip install "shiny[theme]" Quick example (Shiny Express): from shiny . express import ui ui . page_opts ( theme = ui . Theme . from_brand ( file ) ) Quick example (Shiny Core): from shiny import App , ui app_ui = ui . page_fluid ( theme = ui . Theme . from_brand ( file ) ,

... UI elements

)

Using with Quarto

When the user wants to apply brand.yml to Quarto documents:

Read

references/quarto.md

for complete integration guide

Automatic discovery

Place

_brand.yml

at project root with

_quarto.yml

Supported formats

HTML, dashboards, RevealJS, Typst PDFs

Theme layering

Use brand keyword to control precedence Quick example (document):

title : "My Document" format : html : brand : _brand.yml

Quick example (project in _quarto.yml ): project : brand : _brand.yml format : html : theme : default Troubleshooting Brand Not Applying Shiny: Verify file is named _brand.yml (with underscore) Check file location (app directory or parent directories) Try explicit path: bs_theme(brand = "path/to/_brand.yml") or ui.Theme.from_brand("path") For Python: Ensure libsass is installed Quarto: Verify _brand.yml is at project root Ensure _quarto.yml exists for project-level branding Try explicit path in document frontmatter Check theme layering order if using custom themes Colors Not Matching Ensure hex colors have quotes: "#0066cc" not

0066cc

Verify color names match palette definitions exactly

Check semantic colors (primary, success, etc.) reference valid palette names

Ensure palette is defined before semantic colors

Fonts Not Loading

Verify Google Fonts spelling and availability

Check internet connection (required for Google Fonts)

Ensure

source: google

or

source: bunny

is specified

Verify font family names match exactly in typography elements

For Typst: Check font cache with

quarto typst fonts

YAML Syntax Errors

Check indentation (use spaces, not tabs)

Ensure hex colors have quotes:

"#447099"

Verify colons have space after them:

primary: blue

Check list items have hyphens:

- family: Inter

Use YAML validator if syntax issues persist

Reference Documentation

Load these as needed for detailed information:

references/brand-yml-spec.md

Complete brand.yml specification with all sections, fields, examples, and validation rules

references/shiny-r.md

Using brand.yml with Shiny for R via bslib (bs_theme, automatic discovery, Shiny-specific integration)

references/shiny-python.md

Using brand.yml with Shiny for Python via ui.Theme (from_brand(), installation, performance)

references/quarto.md

Using brand.yml with Quarto (formats, light/dark mode, layering, extensions, Typst)

references/brand-yml-in-r.md

General R usage including R Markdown integration, theming functions (ggplot2, gt, flextable, plotly, thematic), and programmatic brand access

Key Principles

Start simple

Begin with colors and one font family

Keep it concise

Only include fields directly relevant to the brand

Prefer standard names

Use Bootstrap color names when possible (blue, green, red, etc.)

Use automatic discovery

Name file

_brand.yml

for auto-detection

Test across targets

Verify brand applies correctly in all intended formats

Version control

Include _brand.yml in git repository Common Patterns Light/Dark Mode Colors color : primary : light : "#0066cc" dark : "#3399ff" background : light : "#ffffff" dark : "#1a1a1a" foreground : light : "#333333" dark : "#e0e0e0" Light/dark color modes were added in Quarto version 1.8 and currently are not supported in the R or Python brand.yml packages. Logo Variants logo : images : logo-dark : logos/logo - dark.svg logo-white : logos/logo - white.svg icon : logos/icon.png small : icon medium : light : logo - dark dark : logo - white Multiple Font Weights typography : fonts : - family : Inter source : google weight : [ 300 , 400 , 500 , 600 , 700 ] style : [ normal , italic ] base : family : Inter weight : 400 headings : family : Inter weight : 600 Color Aliases color : palette : navy : "#003366" ocean-blue : "#0066cc" sky-blue : "#3399ff" primary-color : ocean - blue

Alias

brand-blue : ocean - blue

Alias

blue : sky - blue

Alias for primary colors

primary

:

brand

-

blue

Include Bootstrap color names when possible, either defined directly or as aliases:

blue

,

indigo

,

purple

,

pink

,

red

,

orange

,

yellow

,

green

,

teal

,

cyan

,

white

,

black

. This is useful for consistency and these colors are picked up automatically by tools that use brand.yml.

Tips

Read specification first

Always consult

brand-yml-spec.md

when creating or modifying files

Framework-specific guides

Load the appropriate reference (shiny-r.md, shiny-python.md, quarto.md) for integration details

Validate incrementally

Start with minimal structure, test, then add complexity

Use references

Define colors in palette, then reference by name in semantic colors

Standard file name

Use

_brand.yml

for automatic discovery

Explicit paths

Use custom file names only when necessary (shared branding, multiple variants)