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)