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:

yaml

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:

yaml

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:

yaml

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:

yaml

logo:
  small: logos/icon.png
  medium: logos/header.png
  large: logos/full.svg

Add meta information:

yaml

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)

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):

python

from shiny.express import ui

ui.page_opts(theme=ui.Theme.from_brand(__file__))

Quick example (Shiny Core):

python

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):

yaml

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

Quick example (project in

_quarto.yml

yaml

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")

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

yaml

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

yaml

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

yaml

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

yaml

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)

brand-yml

NPX Install

Tags

SKILL.md Content

brand.yml Skill

What is brand.yml?

File Naming Convention

Decision Tree

Creating brand.yml Files

Step 1: Gather Information

Step 2: Read the Specification

Step 3: Build the File Incrementally

Step 4: Apply Best Practices

Step 5: Validate Structure

Modifying Existing Files

Using with Shiny for R

Using with Shiny for Python

Using with Quarto

Troubleshooting

Brand Not Applying

Colors Not Matching

Fonts Not Loading

YAML Syntax Errors

Reference Documentation

Key Principles

Common Patterns

Light/Dark Mode Colors

Logo Variants

Multiple Font Weights

Color Aliases

Tips