brand-yml

brand.yml 技能

创建并使用 _brand.yml 文件，在 Shiny 应用和 Quarto 文档中保持品牌风格一致。

什么是 brand.yml？

brand.yml 是一种基于 YAML 的格式，可将品牌指南转换为机器可读的文件，供 Shiny 和 Quarto 使用。单个 _brand.yml 文件可定义：

• 颜色 - 调色板和语义颜色（主要颜色、成功、警告等）
• 排版 - 字体、字号、字重、行高
• 徽标 - 多种尺寸以及浅色/深色变体
• 元数据 - 公司名称、链接、身份信息

文件命名约定

• 标准名称：_brand.yml（Shiny 和 Quarto 会自动发现）
• 自定义名称：任意名称，例如 company-brand.yml（需要显式指定路径）
• 位置：通常位于项目根目录，或 _brand/、brand/ 子目录中

决策树

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

1. 要创建新的 _brand.yml 文件？ → 遵循“创建 brand.yml 文件”
2. 要在 Shiny for R 中使用 brand.yml？ → 阅读 references/shiny-r.md
3. 要在 Shiny for Python 中使用 brand.yml？ → 阅读 references/shiny-python.md
4. 要在 Quarto 中使用 brand.yml？ → 阅读 references/quarto.md
5. 要在 R 中通用地使用 brand.yml？ → 阅读 references/brand-yml-in-r.md（R Markdown、主题设置函数、程序化访问）
6. 要修改现有的 _brand.yml？ → 遵循“修改现有文件”
7. 要排查集成问题？ → 遵循“故障排除”

创建 brand.yml 文件

根据品牌指南创建 _brand.yml 文件时：

步骤 1：收集信息

收集品牌信息：

• 颜色：主要颜色、次要颜色、强调色及其十六进制值
• 字体：字体系列及其来源（Google Fonts、本地文件等）
• 徽标：不同尺寸的徽标文件路径或 URL
• 公司信息：名称、网站、社交链接（可选）

步骤 2：阅读规范

加载 references/brand-yml-spec.md，了解完整的 brand.yml 结构、字段选项和语法。

步骤 3：逐步构建文件

先添加必要部分，再添加可选元素：

最小可用的 _brand.yml：

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

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

按需添加颜色：

color:
  palette:
    brand-blue: "#0066cc"
    brand-orange: "#ff6600"
    brand-gray: "#666666"
  primary: brand-blue
  secondary: brand-gray
  warning: brand-orange
  foreground: "#333333"
  background: "#ffffff"

添加排版详情：

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

添加徽标：

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

添加元数据信息：

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

步骤 4：遵循最佳实践

遵循 references/brand-yml-spec.md 中的规则：

• 所有字段均为可选项，只包含所需内容
• 使用十六进制颜色格式："#0066cc"
• 尽可能使用简单语法（字符串优先于对象）
• 使用小写名称并以连字符分隔：brand-blue、success-green
• 所有 URL 都包含 https://
• 在引用颜色/字体之前先定义它们
• 对于颜色范围（深浅变化），选择中间色

步骤 5：验证结构

检查以下内容：

• YAML 语法有效（缩进正确，十六进制颜色使用引号）
• 颜色引用与调色板名称一致
• 字体系列在使用前已定义
• 文件路径相对于 _brand.yml 所在位置
• 所有 URL 都包含协议（https://）

修改现有文件

修改现有的 _brand.yml 文件时：

1. 读取当前文件，了解现有结构
2. 查阅 brand-yml-spec.md，了解有效的字段选项
3. 保持一致性，遵循现有的命名模式
4. 保留引用关系 - 如果其他颜色/元素引用了某个名称，请一致地更新
5. 测试集成 - 确认更改在 Shiny/Quarto 中正确生效

常见修改：

• 添加颜色：添加到 color.palette，然后在语义颜色中引用
• 更改字体：在 typography.fonts 中更新，并确保所需字重/样式可用
• 添加徽标变体：使用 light/dark 结构来定义多个变体
• 浅色/深色模式：为颜色添加 light 和 dark 变体

与 Shiny for R 搭配使用

当用户希望将 brand.yml 应用于 Shiny for R 应用时：

1. 阅读 references/shiny-r.md，了解完整的集成指南
2. 关键函数：bs_theme(brand = TRUE) 或 bs_theme(brand = "path")
3. 自动发现：将 _brand.yml 放在应用根目录
4. 页面函数：适用于 page_fluid()、page_sidebar() 等函数

快速示例：

library(shiny)
library(bslib)

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

与 Shiny for Python 搭配使用

当用户希望将 brand.yml 应用于 Shiny for Python 应用时：

1. 阅读 references/shiny-python.md，了解完整的集成指南
2. 关键函数：ui.Theme.from_brand(__file__)
3. 自动发现：将 _brand.yml 放在应用根目录
4. 安装：需要运行 pip install "shiny[theme]"

快速示例（Shiny Express）：

from shiny.express import ui

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

快速示例（Shiny Core）：

from shiny import App, ui

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

与 Quarto 搭配使用

当用户希望将 brand.yml 应用于 Quarto 文档时：

1. 阅读 references/quarto.md，了解完整的集成指南
2. 自动发现：将 _brand.yml 与 _quarto.yml 一起放在项目根目录
3. 支持的格式：HTML、仪表板、RevealJS、Typst PDF
4. 主题叠加：使用 brand 关键字控制优先级

快速示例（文档）：

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

快速示例（_quarto.yml 中的项目）：

project:
  brand: _brand.yml

format:
  html:
    theme: default

故障排除

品牌未生效

Shiny：

• 确认文件名为 _brand.yml（带下划线）
• 检查文件位置（应用目录或父目录）
• 尝试指定路径：bs_theme(brand = "path/to/_brand.yml") 或 ui.Theme.from_brand("path")
• 对于 Python：确保已安装 libsass

Quarto：

• 确认 _brand.yml 位于项目根目录
• 确保项目级品牌设置存在 _quarto.yml
• 尝试在文档前置元数据中指定路径
• 如果使用自定义主题，请检查主题叠加顺序

颜色不匹配

• 确保十六进制颜色值带引号："#0066cc"，而不是 #0066cc
• 确认颜色名称与调色板定义完全一致
• 检查语义颜色（primary、success 等）是否引用了有效的调色板名称
• 确保先定义调色板，再定义语义颜色

字体未加载

• 确认 Google Fonts 的拼写正确且字体可用
• 检查网络连接（Google Fonts 需要联网）
• 确保指定了 source: google 或 source: bunny
• 确认排版元素中的字体系列名称完全一致
• 对于 Typst：使用 quarto typst fonts 检查字体缓存

YAML 语法错误

• 检查缩进（使用空格，不要使用制表符）
• 确保十六进制颜色值带引号："#447099"
• 确保冒号后有空格：primary: blue
• 检查列表项是否带有连字符：- family: Inter
• 如果语法问题仍未解决，请使用 YAML 验证器

参考文档

根据需要加载以下文档，了解详细信息：

• 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：R 的常规用法，包括 R Markdown 集成、主题设置函数（ggplot2、gt、flextable、plotly、thematic）以及以编程方式访问品牌设置

关键原则

• 从简单开始：先使用颜色和一种字体系列
• 保持简洁：仅包含与品牌直接相关的字段
• 优先使用标准名称：尽可能使用 Bootstrap 颜色名称（blue、green、red 等）
• 使用自动发现：将文件命名为 _brand.yml，以便自动检测
• 在不同目标中测试：确认品牌设置在所有预期格式中均正确生效
• 版本控制：将 _brand.yml 纳入 git 仓库

常见模式

浅色／深色模式颜色

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

Quarto 1.8 版本新增了浅色／深色颜色模式，目前 R 或 Python 的 brand.yml 包尚不支持。

Logo 变体

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

多种字体粗细

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

尽可能包含 Bootstrap 颜色名称，可直接定义，也可用作别名：blue、indigo、purple、pink、red、orange、yellow、green、teal、cyan、white、black。这有助于保持一致性，而且使用 brand.yml 的工具会自动识别这些颜色。

提示

• 先阅读规范：创建或修改文件时，务必查阅 brand-yml-spec.md
• 针对框架的指南：加载相应的参考文档（shiny-r.md、shiny-python.md、quarto.md），了解集成详情
• 逐步验证：从最简结构开始，测试后再逐步增加复杂度
• 使用引用：在调色板中定义颜色，再在语义颜色中按名称引用
• 标准文件名：使用 _brand.yml，以便自动发现
• 显式路径：仅在必要时（共享品牌、多个变体）使用自定义文件名