# Building Your Brand Identity

## Introduction

Your documents tell a story through their visual presentation. Consistent branding makes your work recognizable, professional, and polished.

The `brand_settings()` function helps you create and manage a unified visual identity for all your Quarto projects. Whether you’re a research lab, data science team, or individual consultant, `brand_settings()` ensures your documents maintain consistent colors, logos, and typography.

## What Is Quarto Branding?

Quarto 1.6+ supports branding through `_brand.yml` files, allowing you to centralize:

- Project/organization name: Used in document headers
- Colors: Primary brand colors and extended palettes
- Logos: Large and small logo variants
- Typography: Font families, sizes, and styles
- Additional styling: Links, code, headings

## Flexible Brand Configuration: Two Approaches

`froggeR` offers two complementary ways to configure your brand, balancing ease-of-use with comprehensive customization. This ensures you can quickly set up core branding elements while retaining full control over advanced options.

### Core Elements (Interactive)

The most impactful branding elements are configured through an interactive prompt:

- Project/organization name: What appears in document headers
- Primary color: Your main brand color (hex format)
- Logo - large: Full-size logo for headers
- Logo - small: Icon/favicon for compact displays

### Advanced Options (Template)

For specialized or advanced branding needs, `froggeR` provides access to the complete `_brand.yml` template (`gists/brand.yml` within the package). This allows direct editing of all available options, including:

- Typography: Font families, sizes, weights, styles
- Color palette: Secondary, tertiary, and extended colors
- Links: Custom link colors and hover effects
- Code styling: Monospace fonts and inline code appearance
- Headings: Individual heading level customization
- Logo metadata: Alt text, links, and sizing parameters

This full template is based on the `gists/brand.yml` file used internally by `write_brand()`. A snippet of the template looks like this:

    # Example of the full _brand.yml template (gists/brand.yml)
    meta:
      name: ""
      # ... other meta options ...
    color:
      palette:
        primary: ""
        # ... other color options ...
    logo:
      large: ""
      small: ""
      # ... other logo options ...
    typography:
      font-family-sans: ""
      # ... other typography options ...
    # ... and so on for links, code, headings

To customize these, select ‘Edit the full template for advanced options’ above.

## The Interactive Workflow

### First-Time Setup with Dr. Rachel Kim

Rachel runs `brand_settings()` for the first time:

    > froggeR::brand_settings()

    froggeR Brand Configuration
    ✖ No project-level branding
    ✖ No global branding

    What would you like to do?

    1: Create or update branding
    2: View current branding
    3: Exit

    Selection: 1

froggeR proceeds to Core Elements (Interactive):

    Configure your branding (Core Elements - Interactive)

    Project or organization name
      Used in document headers and branding
      : Kim Lab

    Primary brand color
      Hex format (e.g., #0066cc, #FF5733). See: https://www.color-hex.com/
      : #1E3A8A

    Logo path - large
      Path to large logo (e.g., logos/logo-large.png)
      : logos/kim-lab-logo.png

    Logo path - small
      Path to small/icon logo (e.g., logos/logo-icon.png)
      : logos/kim-lab-icon.png

After entering Core Elements fields, froggeR shows a preview:

    Your branding configuration (Core Elements):

    ---
    meta:
      name: Kim Lab

    logo:
      large: logos/kim-lab-logo.png
      small: logos/kim-lab-icon.png

    color:
      palette:
        primary: #1E3A8A
    ---

Next, froggeR shows available Advanced Options (Template):

    Available for advanced customization (Advanced Options - Template):

    * Typography: fonts, families, sizes, styles
    * Colors: additional color palette options
    * Links: custom link colors and styling
    * Code: monospace font and inline code styling
    * Headings: custom heading colors and styles
    * Logo meta: alt text, links, sizing

    To customize these, select 'Edit the full template' above.

Rachel saves with the basics:

    What would you like to do?

    1: Save with these basics
    2: Edit the full template for advanced options
    3: Cancel (discard changes)

    Selection: 1

    Where would you like to save this branding?

    1: Save to this project only
    2: Save globally (reuse in all future projects)
    3: Save to both locations
    4: Cancel (discard changes)

    Selection: 2

    ✔ Saved to global: /home/rachel/.config/froggeR/_brand.yml

    ✔ froggeR branding configured successfully!

    ℹ Your branding will automatically be used in future froggeR projects.

## Input Validation: Hex Color Format

froggeR validates color inputs for proper hex format:

    Primary brand color
      Hex format (e.g., #0066cc, #FF5733). See: https://www.color-hex.com/
      : 1E3A8A

      Color must be in hex format: #RRGGBB (e.g., #0066cc) or #RGB (e.g., #06c)

    Primary brand color
      Hex format (e.g., #0066cc, #FF5733). See: https://www.color-hex.com/
      : #1E3A8A

    ✔

The validator accepts both 6-digit (`#RRGGBB`) and 3-digit (`#RGB`) hex formats.

## Project-Specific Branding

For specific projects needing different branding:

    > froggeR::brand_settings()

    # ... navigate to ...

    Selection: 1

    Branding already exists. What would you like to do?

    1: Update existing branding
    2: Start fresh

    Selection: 2

Choose “Start fresh” to create project-specific branding that doesn’t affect your global settings.

## Advanced Customization

For high-profile publications needing custom typography and colors:

    Selection: 2
    # "Edit the full template for advanced options"

    ℹ A branding template will open in your editor for advanced customization.
    Configure additional options, then save.

Your editor opens with the complete `_brand.yml` file including your Core Elements (Interactive) values plus all Advanced Options (Template) available for customization.

## Viewing Your Current Branding

At any time, view your configuration:

    > froggeR::brand_settings()

    froggeR Brand Configuration
    ✔ Project-level branding found
    ✔ Global branding found (reuses across projects)

    What would you like to do?

    1: Create or update branding
    2: View current branding
    3: Exit

    Selection: 2

    ✔ Project-level branding:

    meta:
      name: Sleep Consortium
    ...

    ✔ Global branding (used by default in new projects):

    meta:
      name: Kim Lab
    ...

## Where Is Branding Stored?

froggeR stores branding in two locations:

1. Project-level: `_brand.yml` in your project directory
   - Used by current project only
   - Takes precedence over global branding
   - Committed to version control
2. Global: Platform-specific configuration directory
   - Linux/macOS: `~/.config/froggeR/_brand.yml`
   - Windows: `C:\Users\<username>\AppData\Local\froggeR\_brand.yml`
   - Used as default for all new projects

## Next Steps

Now that you understand branding with `brand_settings()`, explore:

- Your Metadata, Your Way - Learn about `settings()`
- Set Once, Use Everywhere - Understand global configuration philosophy
- From Zero to Project in Seconds - See how `quarto_project()` uses your branding

## Summary

The `brand_settings()` function provides a flexible approach to branding:

- Core Elements (Interactive): Quick setup of essential elements—name, primary color, logos
- Advanced Options (Template): Advanced customization when you need fine-grained control
- Validates input with helpful error messages
- Stores globally for reuse across all projects
- Allows project-specific overrides when needed
- Shows clear previews before saving
- Provides flexible save options to match your workflow

By configuring branding once with `brand_settings()`, you create a consistent visual identity across all Quarto projects.