brand-yml

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

brand.yml Skill

brand.yml 使用指南

Create and use

_brand.yml

files for consistent branding across Shiny applications and Quarto documents.

创建并使用

_brand.yml

文件，在Shiny应用和Quarto文档中实现一致的品牌风格。

What is brand.yml?

什么是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

brand.yml是一种基于YAML的格式，可将品牌规范转换为可在Shiny和Quarto中通用的机器可读文件。单个

_brand.yml

文件可定义：

颜色 - 调色板和语义颜色（主色、成功色、警告色等）
排版 - 字体、字号、字重、行高
徽标 - 多种尺寸和亮/暗模式变体
元信息 - 公司名称、链接、标识信息

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

标准名称：
```
_brand.yml
```
（Shiny和Quarto可自动识别）
自定义名称：可使用任意名称，如
```
company-brand.yml
```
（需指定明确路径）
存放位置：通常在项目根目录，或
```
_brand/
```
、
```
brand/
```
子目录中

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"

确定用户目标后，遵循相应的工作流程：

创建新的_brand.yml文件？ → 遵循「创建brand.yml文件」步骤
在Shiny for R中使用brand.yml？ → 阅读
```
references/shiny-r.md
```
在Shiny for Python中使用brand.yml？ → 阅读
```
references/shiny-python.md
```
在Quarto中使用brand.yml？ → 阅读
```
references/quarto.md
```
在R（通用场景）中使用brand.yml？ → 阅读
```
references/brand-yml-in-r.md
```
（R Markdown、主题函数、程序化访问）
修改现有的_brand.yml文件？ → 遵循「修改现有文件」步骤
排查集成问题？ → 遵循「故障排查」步骤

Creating brand.yml Files

创建brand.yml文件

When creating

_brand.yml

files from brand guidelines:

根据品牌规范创建

_brand.yml

文件时：

Step 1: Gather Information

步骤1：收集信息

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)

收集品牌相关信息：

颜色：主色、辅助色、强调色及对应的十六进制值
字体：字体家族及其来源（Google Fonts、本地文件等）
徽标：不同尺寸的徽标文件路径或URL
公司信息：名称、官网、社交链接（可选）

Step 2: Read the Specification

步骤2：阅读规范文档

Load

references/brand-yml-spec.md

to understand the complete brand.yml structure, field options, and syntax.

查看

references/brand-yml-spec.md

，了解brand.yml的完整结构、字段选项和语法规则。

Step 3: Build the File Incrementally

步骤3：逐步构建文件

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

从核心部分开始，逐步添加可选元素：

最简_brand.yml示例：

yaml

color:
  palette:
    brand-blue: "#0066cc"
  primary: brand-blue
  background: "#ffffff"

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

按需添加颜色：

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"

添加排版细节：

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

添加徽标：

yaml

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

添加元信息：

yaml

meta:
  name: Company Name
  link: https://example.com

Step 4: Apply Best Practices

步骤4：遵循最佳实践

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

遵循

references/brand-yml-spec.md

中的规则：

所有字段均为可选，仅添加需要的内容
使用十六进制颜色格式：
```
"#0066cc"
```
尽可能使用简单语法（优先使用字符串而非对象）
使用小写名称并以连字符分隔：
```
brand-blue
```
、
```
success-green
```
所有URL需包含
```
https://
```
先定义颜色/字体，再引用它们
对于颜色范围（深浅色调），选择中间值

Step 5: Validate Structure

步骤5：验证结构

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

检查以下内容：

YAML语法有效（正确缩进，十六进制颜色加引号）
颜色引用与调色板名称匹配
字体家族在使用前已定义
文件路径相对于
```
_brand.yml
```
的存放位置
所有URL包含协议头（
```
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

修改现有

_brand.yml

文件时：

阅读当前文件，了解现有结构
参考brand-yml-spec.md，确认有效的字段选项
保持一致性，遵循现有的命名模式
保留引用关系 - 如果其他颜色/元素引用了某个名称，需同步更新
测试集成效果 - 验证修改在Shiny/Quarto中正确应用

常见修改场景：

添加颜色：在
```
color.palette
```
中添加，然后在语义颜色中引用
更换字体：更新
```
typography.fonts
```
中的内容，确保字重/样式可用
添加徽标变体：使用
```
light
```
/
```
dark
```
结构定义多种变体
亮/暗模式：为颜色添加
```
light
```
和
```
dark
```
变体

Using with Shiny for R

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

当用户需要将brand.yml应用于Shiny for R应用时：

**阅读
```
references/shiny-r.md
```
**获取完整集成指南

核心函数：

bs_theme(brand = TRUE)

或

bs_theme(brand = "path")

自动识别：将
```
_brand.yml
```
放在应用根目录
页面函数：适用于
```
page_fluid()
```
、
```
page_sidebar()
```
等

快速示例：

library(shiny)
library(bslib)

ui <- page_fluid(
  theme = bs_theme(brand = TRUE),
  # ... UI元素
)

Using with Shiny for Python

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

当用户需要将brand.yml应用于Shiny for Python应用时：

**阅读
```
references/shiny-python.md
```
**获取完整集成指南
核心函数：
```
ui.Theme.from_brand(__file__)
```
自动识别：将
```
_brand.yml
```
放在应用根目录
安装依赖：需要执行
```
pip install "shiny[theme]"
```

快速示例（Shiny Express）：

python

from shiny.express import ui

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

快速示例（Shiny Core）：

python

from shiny import App, ui

app_ui = ui.page_fluid(
    theme=ui.Theme.from_brand(__file__),
    # ... UI元素
)

Using with Quarto

在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

当用户需要将brand.yml应用于Quarto文档时：

**阅读
```
references/quarto.md
```
**获取完整集成指南
自动识别：将
```
_brand.yml
```
放在项目根目录，与
```
_quarto.yml
```
同目录
支持格式：HTML、仪表板、RevealJS演示文稿、Typst PDF
主题分层：使用
```
brand
```
关键字控制优先级

快速示例（单篇文档）：

yaml

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

快速示例（项目级配置，在

_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

Shiny场景：

确认文件名为
```
_brand.yml
```
（包含下划线）
检查文件位置（应用目录或父目录）

尝试使用明确路径：

bs_theme(brand = "path/to/_brand.yml")

或

ui.Theme.from_brand("path")

Python环境：确保已安装
```
libsass
```

Quarto场景：

确认
```
_brand.yml
```
在项目根目录
项目级品牌配置需确保
```
_quarto.yml
```
存在
尝试在文档前置元数据中指定明确路径
如果使用自定义主题，检查主题分层顺序

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

确保十六进制颜色值添加了引号：
```
"#0066cc"
```
而非
```
#0066cc
```
验证颜色名称与调色板定义完全一致
检查语义颜色（primary、success等）引用了有效的调色板名称
确保调色板在语义颜色之前定义

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

验证Google Fonts的拼写和可用性
检查网络连接（加载Google Fonts需要联网）
确保指定了
```
source: google
```
或
```
source: bunny
```
验证排版元素中的字体家族名称完全匹配
Typst格式：使用
```
quarto typst fonts
```
检查字体缓存

YAML Syntax Errors

YAML语法错误

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

检查缩进（使用空格，而非制表符）
确保十六进制颜色值添加了引号：
```
"#447099"
```
验证冒号后有空格：
```
primary: blue
```
检查列表项带有连字符：
```
- family: Inter
```
如果语法问题持续，使用YAML验证工具排查

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

按需查看以下文档获取详细信息：

references/brand-yml-spec.md
：完整的brand.yml规范，包含所有章节、字段、示例和验证规则
references/shiny-r.md
：通过bslib在Shiny for R中使用brand.yml的指南（bs_theme、自动识别、Shiny专属集成）
references/shiny-python.md
：通过ui.Theme在Shiny for Python中使用brand.yml的指南（from_brand()、安装、性能）
references/quarto.md
：在Quarto中使用brand.yml的指南（支持格式、亮/暗模式、分层、扩展、Typst）
references/brand-yml-in-r.md
：brand.yml在R中的通用用法，包括R Markdown集成、主题函数（ggplot2、gt、flextable、plotly、thematic）和程序化访问

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

从规范开始：创建或修改文件时，务必先参考
```
brand-yml-spec.md
```
保持简洁：仅添加与品牌直接相关的字段
优先使用标准名称：尽可能使用Bootstrap颜色名称（blue、green、red等）
使用自动识别：将文件命名为
```
_brand.yml
```
以实现自动发现
跨目标测试：验证品牌样式在所有目标格式中正确应用
版本控制：将
```
_brand.yml
```
纳入git仓库

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.

yaml

color:
  primary:
    light: "#0066cc"
    dark: "#3399ff"
  background:
    light: "#ffffff"
    dark: "#1a1a1a"
  foreground:
    light: "#333333"
    dark: "#e0e0e0"

亮/暗颜色模式在Quarto 1.8版本中新增，目前R或Python的brand.yml包暂不支持该功能。

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

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

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.

yaml

color:
  palette:
    navy: "#003366"
    ocean-blue: "#0066cc"
    sky-blue: "#3399ff"
    primary-color: ocean-blue  # 别名
    brand-blue: ocean-blue     # 别名
    blue: sky-blue             # 主色系别名
  primary: brand-blue

尽可能包含Bootstrap颜色名称，可直接定义或作为别名：

blue

、

indigo

、

purple

、

pink

、

red

、

orange

、

yellow

、

green

、

teal

、

cyan

、

white

、

black

。这有助于保持一致性，并且使用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-spec.md
```
参考框架专属指南：查看对应的参考文档（shiny-r.md、shiny-python.md、quarto.md）获取集成细节
逐步验证：从最小结构开始，测试后再增加复杂度
使用引用：在调色板中定义颜色，然后在语义颜色中通过名称引用
使用标准文件名：使用
```
_brand.yml
```
以实现自动识别
仅必要时使用自定义名称：仅在共享品牌、多变体场景下使用自定义文件名，并指定明确路径