posit-dev/brand-yml

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)