brand-yml

What this skill does

# 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:**

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

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:

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

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

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

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