brand-yml

brand.yml スキル

Shiny アプリケーションと Quarto ドキュメントで一貫したブランディングを実現するために、_brand.yml ファイルを作成して使用します。

brand.yml とは？

brand.yml は、ブランドガイドラインを Shiny と Quarto 全体で使用できる機械可読ファイルに変換する YAML ベースの形式です。1 つの _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：情報を収集する

ブランド情報を収集します。

• カラー：プライマリ、セカンダリ、アクセントカラーとその 16 進数値
• フォント：フォントファミリーとその入手元（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 に記載されている以下のルールに従います。

• すべてのフィールドは任意です。必要なものだけを含めてください
• 16 進数のカラー形式を使用します："#0066cc"
• 可能な場合は、シンプルな構文（オブジェクトより文字列）を優先します
• 小文字とハイフンを使った名前にします：brand-blue、success-green
• すべての URL に https:// を含めます
• 参照する前にカラーとフォントを定義します
• カラーレンジ（シェード／ティント）では、中間の色を選びます

ステップ 5：構造を検証する

以下を確認します。

• YAML 構文が有効である（インデントが適切で、16 進数カラーが引用符で囲まれている）
• カラー参照がパレット名と一致している
• フォントファミリーが使用前に定義されている
• ファイルパスが _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 での使用

ユーザーが Shiny for R アプリに brand.yml を適用する場合：

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 での使用

ユーザーが Shiny for Python アプリに brand.yml を適用する場合：

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 での使用

ユーザーが Quarto ドキュメントに brand.yml を適用する場合：

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 が存在することを確認します
• ドキュメントのフロントマターで明示的なパスを指定してみます
• カスタムテーマを使用している場合は、テーマのレイヤー化の順序を確認します

色が一致しない

• 16 進カラーコードが引用符で囲まれていることを確認します："#0066cc"（#0066cc ではありません）
• 色名がパレットの定義と完全に一致することを確認します
• セマンティックカラー（primary、success など）が有効なパレット名を参照していることを確認します
• セマンティックカラーより前にパレットが定義されていることを確認します

フォントが読み込まれない

• Google Fonts のスペルと利用可能状況を確認します
• インターネット接続を確認します（Google Fonts に必要です）
• source: google または source: bunny が指定されていることを確認します
• タイポグラフィ要素でフォントファミリー名が完全に一致することを確認します
• Typst の場合：quarto typst fonts でフォントキャッシュを確認します

YAML 構文エラー

• インデントを確認します（タブではなくスペースを使用してください）
• 16 進カラーコードが引用符で囲まれていることを確認します："#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 Markdown との統合、テーマ設定関数（ggplot2、gt、flextable、plotly、thematic）、プログラムによるブランドへのアクセスなど、R での一般的な使い方

主な原則

• シンプルに始める：まず色と 1 つのフォントファミリーを設定します
• 簡潔に保つ：ブランドに直接関係するフィールドのみを含めます
• 標準的な名前を優先する：可能な場合は 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:
  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 を使用してください
• 明示的なパス：カスタムファイル名は必要な場合（共有ブランディング、複数のバリアント）にのみ使用してください