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:

1. Creating a new _brand.yml file? → Follow "Creating brand.yml Files"
2. Using brand.yml in Shiny for R? → Read

   references/shiny-r.md

3. Using brand.yml in Shiny for Python? → Read

   references/shiny-python.md

4. Using brand.yml in Quarto? → Read

   references/quarto.md

5. Using brand.yml in R (general)? → Read

   references/brand-yml-in-r.md

   (R Markdown, theming functions, programmatic access)
6. Modifying existing _brand.yml? → Follow "Modifying Existing Files"
7. 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:

1. Read the current file to understand existing structure
2. Consult brand-yml-spec.md for valid field options
3. Maintain consistency with existing naming patterns
4. Preserve references - if other colors/elements reference a name, update consistently
5. 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:

1. Read

   references/shiny-r.md

   for complete integration guide
2. Key function:

   bs_theme(brand = TRUE)

   or

   bs_theme(brand = "path")

3. Automatic discovery: Place

   _brand.yml

   at app root
4. 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:

1. Read

   references/shiny-python.md

   for complete integration guide
2. Key function:

   ui.Theme.from_brand(__file__)

3. Automatic discovery: Place

   _brand.yml

   at app root
4. 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:

1. Read

   references/quarto.md

   for complete integration guide
2. Automatic discovery: Place

   _brand.yml

   at project root with

   _quarto.yml

3. Supported formats: HTML, dashboards, RevealJS, Typst PDFs
4. 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)