---
title: "Building Your Brand Identity"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Building Your Brand Identity}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

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

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

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

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

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

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

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

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

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

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

```r
> 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](your-metadata-your-way.html) - Learn about `settings()`
- [Set Once, Use Everywhere](set-once-use-everywhere.html) - Understand global configuration philosophy
- [From Zero to Project in Seconds](from-zero-to-project.html) - 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.
