gh-posit-dev-skills-quarto/skills/brand-yml/references/brand-yml-spec.md

brand.yml Specification

Complete specification for creating valid _brand.yml files for the brand.yml project.

File Naming Convention

• Conventional name: _brand.yml (auto-discovered by Shiny and Quarto)
• Custom names: Any .yml file (e.g., my-brand.yml) requires explicit paths
• Location: Typically at project root or in _brand/ or brand/ subdirectories

File Structure

All fields are optional. Only include fields directly relevant to the brand.

meta:           # Company/project identity information
logo:           # Logo files and variants
color:          # Color palette and semantic colors
typography:     # Fonts and text styling
defaults:       # Framework-specific customizations

Meta Section

Company or project metadata.

Simple Format

meta:
  name: Acme
  link: https://acmecorp.com

Extended Format

meta:
  name:
    short: Acme
    full: Acme Corporation International
  link:
    home: https://www.acmecorp.com
    docs: https://docs.acmecorp.com
    github: https://github.com/acmecorp
    bluesky: https://bsky.app/profile/acmecorp.bsky.social
    mastodon: https://mastodon.social/@acmecorp
    linkedin: https://www.linkedin.com/company/acmecorp
    facebook: https://www.facebook.com/acmecorp
    twitter: https://twitter.com/acmecorp

Requirements:

• All links must include https:// prefix
• Additional custom fields are allowed

Logo Section

Logo files for different contexts and sizes.

Structure

logo:
  images:           # Named logo resources (optional)
    name: path      # Map names to file paths or URLs
  small: path       # Icon-sized logo (favicons, mobile)
  medium: path      # Standard logo (headers, navigation)
  large: path       # Large logo (hero, title slides)

File Paths

• Local files: Relative paths from _brand.yml location (e.g., logos/logo.png)
• Remote files: Full URLs with http:// or https://

Light/Dark Variants

logo:
  medium:
    light: logo-dark.png      # For light backgrounds
    dark: logo-white.png      # For dark backgrounds

With Alt Text

logo:
  images:
    header:
      path: logos/header.svg
      alt: Company logo
  medium: header

Complete Example

logo:
  images:
    header: logos/header-logo.png
    header-white: logos/header-logo-white.png
    icon: logos/icon.png
    full:
      path: logos/full-logo.svg
      alt: Acme Corporation logo
  small: icon
  medium:
    light: header
    dark: header-white
  large: full

Color Section

Brand color palette and semantic color assignments.

Structure

color:
  palette:        # Named brand colors
    name: "#hex"  # Flat list of color names and hex values
  # Semantic theme colors (all optional)
  foreground: "#color"    # Main text color
  background: "#color"    # Main background color
  primary: "#color"       # Links, buttons, primary actions
  secondary: "#color"     # Lighter text, disabled states
  tertiary: "#color"      # Hover states, accents
  success: "#color"       # Positive actions
  info: "#color"          # Neutral information
  warning: "#color"       # Cautions
  danger: "#color"        # Errors, negative actions
  light: "#color"         # High contrast on dark
  dark: "#color"          # High contrast on light

Color Palette Best Practices

• Use hex color values: "#447099"
• Use descriptive names following Sass conventions: blue, brand-orange, success-green
• Create aliases by referencing other palette colors: purple: burgundy
• Include Bootstrap color names when possible: blue, indigo, purple, pink, red, orange, yellow, green, teal, cyan, white, black
• When brands define ranges of shades, choose the midpoint as the primary color

Referencing Colors

Theme colors can reference palette names:

color:
  palette:
    brand-blue: "#447099"
    brand-orange: "#EE6331"
  primary: brand-blue      # References palette
  warning: brand-orange    # References palette

Complete Example

color:
  palette:
    white: "#FFFFFF"
    black: "#151515"
    blue: "#447099"
    orange: "#EE6331"
    green: "#72994E"
    teal: "#419599"
    burgundy: "#9A4665"
  foreground: black
  background: white
  primary: blue
  success: green
  info: teal
  warning: orange
  danger: burgundy

Typography Section

Font definitions and text element styling.

Structure

typography:
  fonts:              # Font definitions
    - family: Name
      source: type    # file, google, bunny, or system
      # Additional source-specific fields
  base:               # Body text (optional)
  headings:           # Heading text (optional)
  monospace:          # Code text (optional)
  monospace-inline:   # Inline code (optional)
  monospace-block:    # Code blocks (optional)
  link:               # Hyperlinks (optional)

Font Sources

Local/Remote Files

fonts:
  - family: Open Sans
    source: file
    files:
      - path: fonts/OpenSans-Regular.ttf
        weight: 400
        style: normal
      - path: fonts/OpenSans-Bold.ttf
        weight: 700
        style: normal
      - path: https://example.com/fonts/OpenSans-Italic.ttf
        weight: 400
        style: italic

Proprietary fonts, should be downloaded and stored adjacent to the brand.yml file and referenced via relative paths in the path field.

Google Fonts

fonts:
  - family: Roboto
    source: google
    weight: [400, 700]        # Optional: specific weights
    style: [normal, italic]   # Optional: specific styles
    display: block            # Optional: font-display property

Weight options:

• Array of numbers: [400, 700]
• Range (variable fonts): 400..900
• Named weights: [thin, normal, bold]

Bunny Fonts (GDPR-compliant alternative)

fonts:
  - family: Inter
    source: bunny
    weight: [400, 600]
    style: [normal, italic]

Same syntax as Google Fonts.

Typographic Elements

All elements support these fields:

• family: Font family name (must match a defined font)
• weight: 100-900 or thin, normal, bold, etc.
• style: normal or italic
• size: CSS units (16px, 1rem, 0.9em)
• line-height: Number or CSS unit
• color: Hex value or reference to color name
• background-color: Hex value or reference to color name

Simple Format (String)

typography:
  base: Open Sans
  headings: Roboto
  monospace: Fira Code

Extended Format (Object)

typography:
  base:
    family: Open Sans
    weight: 400
    size: 16px
    line-height: 1.5
  headings:
    family: Roboto
    weight: 600
    style: normal
    line-height: 1.2
    color: "#333333"
  monospace:
    family: Fira Code
    weight: 400
    size: 0.9em
  monospace-inline:
    color: "#7d12ba"
    background-color: "#f8f9fa"
  monospace-block:
    color: foreground
    background-color: background
    line-height: 1.4
  link:
    weight: 600
    color: primary
    decoration: underline

Note: Base text color uses color.foreground by default. Do not specify color in base unless overriding.

Complete Example

typography:
  fonts:
    - family: Open Sans
      source: google
      weight: [400, 600, 700]
      style: [normal, italic]
    - family: Roboto Slab
      source: google
      weight: [600, 900]
    - family: Fira Code
      source: bunny
      weight: [400, 500]
  base:
    family: Open Sans
    size: 16px
    line-height: 1.5
  headings:
    family: Roboto Slab
    weight: 600
  monospace: Fira Code
  link:
    color: primary
    weight: 600

Defaults Section

Framework-specific customizations. Use sparingly - only when brand requirements cannot be met through the standard sections above.

Structure

defaults:
  bootstrap:      # Bootstrap/bslib customizations
    functions:    # SCSS function declarations (string)
    defaults:     # Bootstrap variable overrides (mapping)
    mixins:       # SCSS mixins (string)
    rules:        # Additional SCSS rules (string)
  quarto:         # Quarto-specific settings
    format:       # Format-specific options
  shiny:          # Shiny-specific settings
    theme:
      defaults:   # Bootstrap variables
      rules:      # Additional SCSS rules

Example

defaults:
  bootstrap:
    defaults:
      navbar-bg: $brand-orange
    rules: |
      .btn-primary {
        border-radius: 0.5rem;
      }
  shiny:
    theme:
      defaults:
        navbar-padding-y: 1rem

Note: Colors from color.palette are available as Sass variables: $brand-{color_name}

Validation Rules

When creating _brand.yml files:

1. All fields are optional - only include what's needed
2. Prefer hex colors - use "#447099" format
3. Prefer simple syntax - use strings instead of objects when possible
4. Follow Sass naming - color/font names use lowercase and hyphens
5. Include URLs with protocol - always use https://
6. Reference before use - define colors/fonts before referencing them
7. Keep it concise - simpler is better

Complete Minimal Example

color:
  palette:
    blue: "#0066cc"
    gray: "#666666"
  primary: blue
  foreground: gray
  background: "#ffffff"

typography:
  fonts:
    - family: Inter
      source: google
      weight: [400, 600]
  base: Inter
  headings:
    weight: 600

Complete Comprehensive Example

See the example in the document provided to you (brand-yml.prompt.txt) for a full-featured _brand.yml with all options demonstrated.