shiny-bslib-theming

bslib で Shiny アプリをテーマ設定する

bslib の Bootstrap 5 テーマ設定システムを使って、Shiny アプリの外観をカスタマイズします。手軽に使える Bootswatch テーマから、高度な Sass カスタマイズ、動的なカラーモード切り替えまで対応します。

クイックスタート

「shiny」プリセット（推奨の開始点）：

page_sidebar(
  theme = bs_theme(),  # "shiny" preset by default — polished, not plain Bootstrap
  ...
)

Bootswatch テーマ（異なるビジュアルスタイルにする場合）：

page_sidebar(
  theme = bs_theme(preset = "zephyr"),  # or "cosmo", "minty", "darkly", etc.
  ...
)

カスタムカラーとフォント：

page_sidebar(
  theme = bs_theme(
    version = 5,
    bg = "#FFFFFF",
    fg = "#333333",
    primary = "#2c3e50",
    base_font = font_google("Lato"),
    heading_font = font_google("Montserrat")
  ),
  ...
)

_brand.yml から自動でブランド設定を適用： アプリまたはプロジェクトのディレクトリに _brand.yml ファイルがある場合、bs_theme() が自動的に検出して適用します。コードを変更する必要はありません。brand.yml R パッケージが必要です。

bs_theme(brand = FALSE)    # Disable auto-discovery
bs_theme(brand = TRUE)     # Require _brand.yml (error if not found)
bs_theme(brand = "path/to/brand.yml")  # Explicit path

テーマ設定のワークフロー

1. "shiny" プリセット（デフォルト）または希望する外観に近い Bootswatch テーマから始めます
2. メインカラー（bg、fg、primary）をカスタマイズします
3. font_google() やその他のフォントヘルパーでフォントを調整します
4. ... または bs_add_variables() で Bootstrap Sass 変数を微調整します
5. 必要に応じて bs_add_rules() でカスタム Sass ルールを追加します
6. プロットをテーマに合わせるため、thematic::thematic_shiny() を有効にします
7. 開発中は bs_themer() を使ってインタラクティブにプレビューします

例：

theme <- bs_theme(preset = "minty") |>
  bs_theme_update(
    primary = "#1a9a7f",
    base_font = font_google("Lato")
  ) |>
  bs_add_rules("
    .card { box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
  ")

bs_theme()

Bootstrap テーマを作成するための中心的な関数です。sass::sass_bundle() オブジェクトを返します。

bs_theme(
  version = version_default(),
  preset = NULL,        # "shiny" (default for BS5+), "bootstrap", or Bootswatch name
  ...,                  # Bootstrap Sass variable overrides
  brand = NULL,         # brand.yml: NULL (auto), TRUE (require), FALSE (disable), or path
  bg = NULL, fg = NULL,
  primary = NULL, secondary = NULL,
  success = NULL, info = NULL, warning = NULL, danger = NULL,
  base_font = NULL, code_font = NULL, heading_font = NULL,
  font_scale = NULL,    # Scalar multiplier for base font size (e.g., 1.5 = 150%)
  bootswatch = NULL     # Alias for preset
)

既存のテーマを変更するには bs_theme_update(theme, ...) を使います。オブジェクトがテーマかどうかをテストするには is_bs_theme(x) を使います。

プリセットと Bootswatch

「shiny」プリセット（推奨）： bs_theme() は Bootstrap 5 以降でデフォルトとして preset = "shiny" を使います。これは Shiny アプリ専用に設計された、洗練されたテーマです。標準の Bootstrap ではありません。 カード、サイドバー、値ボックス、その他の bslib コンポーネントに、適切に選ばれたデフォルト設定とプロフェッショナルなスタイルを提供します。まずはこれを使い、Bootswatch テーマを選ぶ前に色とフォントをカスタマイズしてください。

バニラ Bootstrap： preset = "bootstrap" を使うと、「shiny」プリセットが解除され、変更されていない Bootstrap 5 のスタイルになります。

組み込みプリセット： builtin_themes() で bslib 独自のプリセットを一覧表示できます。

Bootswatch テーマ： bootswatch_themes() で利用可能な Bootswatch テーマをすべて一覧表示できます。アプリの目的と対象ユーザーに合ったものを選んでください。デフォルトで適用する必要はありません。

よく使われるオプション："zephyr"（明るくモダン）、"cosmo"（すっきり）、"minty"（爽やかなグリーン）、"flatly"（フラットデザイン）、"litera"（明快）、"darkly"（ダーク）、"cyborg"（ダーク）、"simplex"（ミニマリスト）、"sketchy"（手描き風）。

メインカラー

影響の大きいカラーです。これらを変更すると、変数のカスケードによって 数百もの CSS ルールに影響します。

パラメーター	説明
bg	背景色
fg	前景（テキスト）色
primary	ブランドのメインカラー（リンク、ナビゲーションのアクティブ状態、入力欄のフォーカス）
secondary	アクションボタンのデフォルト
success	肯定／成功状態（通常は緑）
info	情報コンテンツ（通常は青緑）
warning	警告（通常は黄色）
danger	エラー／破壊的な操作（通常は赤）

bs_theme(
  bg = "#202123", fg = "#B8BCC2",
  primary = "#EA80FC", secondary = "#48DAC6"
)

色のヒント：

• bg／fg：色相を近づけ、輝度差を大きくします（読みやすさのためにコントラストを確保します）
• primary：bg と fg の両方に対してコントラストを持たせます。ハイパーリンク、ナビゲーション、入力欄のフォーカスに使われます
• 色は htmltools::parseCssColors() が認識できる任意の形式を使えます

タイポグラフィ

フォント引数は base_font、heading_font、code_font の 3 つです。font_scale を使うとすべてのフォントサイズを均一に拡大・縮小できます（例：1.5 で 150%）。

各引数には、単一のフォント、font_collection()、またはフォント名の文字ベクトルを指定できます。

font_google()

Google Fonts をダウンロードしてローカルにキャッシュします（デフォルトで local = TRUE）。インターネット接続が必要なのは初回のダウンロード時のみです。

bs_theme(
  base_font = font_google("Roboto"),
  heading_font = font_google("Montserrat"),
  code_font = font_google("Fira Code")
)

可変ウェイトを指定する場合：font_google("Crimson Pro", wght = "200..900")

特定のウェイトを指定する場合：font_google("Raleway", wght = c(300, 400, 700))

遅い接続で不可視テキストの表示（FOIT）が発生しないよう、フォールバックを設定することをおすすめします：

bs_theme(
  base_font = font_collection(
    font_google("Lato", local = FALSE),
    "Helvetica Neue", "Arial", "sans-serif"
  )
)

フォントの組み合わせに関するリソース：fontpair.co

font_link()

カスタムフォント URL 用の CSS Web フォントインターフェースです：

font_link("Crimson Pro",
  href = "https://fonts.googleapis.com/css2?family=Crimson+Pro:[email protected]")

font_face()

完全な @font-face 制御を備えたローカルホスト型のフォントファイルの場合:

font_face(
  family = "Crimson Pro",
  style = "normal",
  weight = "200 900",
  src = "url(fonts/crimson-pro.woff2) format('woff2')"
)

font_collection()

複数のフォントをフォールバック順で組み合わせます:

font_collection(font_google("Lato"), "Helvetica Neue", "Arial", "sans-serif")

低レベルテーマ設定関数

bs_theme() の名前付きパラメータを超えたカスタマイズ向けです。これらは Bootstrap の Sass レイヤーを直接操作します。

bs_add_variables()

Bootstrap Sass 変数のデフォルト値を追加または上書きします:

theme <- bs_add_variables(
  bs_theme(preset = "sketchy", primary = "orange"),
  "body-bg" = "#EEEEEE",
  "font-family-base" = "monospace",
  "font-size-base" = "1.4rem",
  "btn-padding-y" = ".16rem"
)

.where パラメータは Sass コンパイル順序における配置を制御します:

.where	使用する場面
"defaults" (デフォルト)	!default フラグを付けて変数のデフォルト値を設定します。Bootstrap 自身のデフォルトの前に配置されます。
"declarations"	他の Bootstrap 変数 (例: $secondary) を参照します。Bootstrap のデフォルトの後に配置されます。
"rules"	すべてのルールの後に配置されます。必要な場面はほとんどありません。

Bootstrap 変数の参照:

# This fails in bs_theme() because $secondary isn't defined yet:
# bs_theme("progress-bar-bg" = "$secondary")

# Use bs_add_variables with .where = "declarations" instead:
bs_theme() |>
  bs_add_variables("progress-bar-bg" = "$secondary", .where = "declarations")

bs_add_rules()

Bootstrap の変数やミックスインを参照できるカスタム Sass/CSS ルールを追加します:

theme <- bs_theme(primary = "#007bff") |>
  bs_add_rules("
    .custom-card {
      background: mix($bg, $primary, 95%);
      border: 1px solid $primary;
      padding: $spacer;

      @include media-breakpoint-up(md) {
        padding: $spacer * 2;
      }
    }
  ")

外部ファイルから: bs_add_rules(sass::sass_file("www/custom.scss"))

利用可能な Sass 関数: lighten()、darken()、mix()、rgba()、color-contrast()。 利用可能な Bootstrap ミックスイン: @include media-breakpoint-up()、@include box-shadow()、@include border-radius()。

bs_add_functions() と bs_add_mixins()

カスタム Sass 関数やミックスインをテーマバンドルに追加します:

theme |>
  bs_add_functions("@function my-tint($color) { @return mix(white, $color, 20%); }") |>
  bs_add_rules(".highlight { background: my-tint($primary); }")

bs_bundle()

sass::sass_bundle() オブジェクトをテーマに追加します (再利用可能なテーマ拡張をパッケージ化するため):

my_extension <- sass::sass_layer(
  defaults = list("my-var" = "red !default"),
  rules = ".my-class { color: $my-var; }"
)
theme <- bs_theme() |> bs_bundle(my_extension)

Bootstrap Sass 変数

任意の Bootstrap 5 Sass 変数を bs_theme(...) または bs_add_variables() を通じて渡せます。

変数名の探し方: https://rstudio.github.io/bslib/articles/bs5-variables/

よく使う変数:

bs_theme(
  "border-radius" = "0.5rem",
  "card-border-radius" = "1rem",
  "card-bg" = "lighten($bg, 5%)",
  "navbar-bg" = "$primary",
  "link-color" = "$primary",
  "font-size-base" = "1rem",
  "spacer" = "1rem",
  "btn-padding-y" = ".5rem",
  "btn-padding-x" = "1rem",
  "input-border-color" = "#dee2e6"
)

値には、変数・関数・数式を参照する Sass 式を使用できます。

Bootstrap CSS カスタムプロパティ

詳細は sass-and-css-variables.md を参照してください:

• Sass 変数がどのように --bs-* CSS カスタムプロパティへコンパイルされるか
• ランタイム変数レイヤーとコンパイル時変数レイヤー
• Bootstrap 5.3 のカラーモードがどのように CSS 変数の上書きを利用するか
• data-bs-theme による要素単位のテーマ設定
• 単発のスタイリング向けの CSS ユーティリティクラス

ダークモードとカラーモード

詳細は dark-mode.md を参照してください:

• Bootstrap 5.3 のクライアントサイドカラーモードシステム (data-bs-theme 属性)
• ユーザーが切り替えを制御できる input_dark_mode() と toggle_dark_mode()
• session$setCurrentTheme() によるサーバーサイドのテーマ切り替え
• ライトモード・ダークモードの両方で動作するカスタム Sass の書き方
• コンポーネントの互換性 (テーマ設定に反応するもの、しないもの)

R プロットのテーマ設定

bs_theme() は CSS にのみ影響します。R のプロット出力 (サーバーサイドで画像としてレンダリングされる) は自動的に一致しません。thematic パッケージを使用してください:

library(thematic)
thematic_shiny(font = "auto")  # Call before shinyApp()
shinyApp(ui, server)

• base R、ggplot2、lattice で動作します
• CSS の色を R のプロットのデフォルト値に変換します
• font = "auto" は bs_theme() のフォントにも一致します
• リアルタイムプレビュー用の bs_themer() を補完します

さらなる一貫性のために、ggplot2 のグローバルテーマを設定します:

library(ggplot2)
theme_set(theme_minimal())

ダッシュボードの背景スタイリング

bslib-page-dashboard CSS クラスは、メインコンテンツ領域の背後に薄いグレーの背景を追加し、ダッシュボードスタイルのアプリに、カードが背景から際立つ洗練された外観を与えます。これはテーマ設定の詳細であり、レイアウトの挙動は変えず、視覚的な処理だけを変更します。

page_sidebar() ダッシュボードの場合:

page_sidebar(
  class = "bslib-page-dashboard",
  title = "My Dashboard",
  sidebar = sidebar(...),
  ...
)

ダッシュボードに特化したページを持つ page_navbar() の場合: ダッシュボード指向のページだけがグレーの背景を得るように、個々の nav_panel() コンテナにクラスを適用します (page_navbar() 自体ではありません):

page_navbar(
  title = "Analytics",
  nav_panel("Dashboard", class = "bslib-page-dashboard",
    layout_column_wrap(...)
  ),
  nav_panel("Report",
    # No dashboard class — standard white background for prose/reports
    ...
  )
)

インタラクティブなテーマ設定ツール

bs_theme_preview()

多数のサンプル UI コンポーネントを使ってテーマをプレビューするためのスタンドアロンのデモアプリ:

bslib::bs_theme_preview()                        # Default theme
bslib::bs_theme_preview(bs_theme(preset = "darkly"))  # Custom theme

デフォルトでテーマ設定 UI を含みます (with_themer = TRUE)。

run_with_themer()

既存の Shiny アプリをテーマエディタのオーバーレイ付きで実行します (shiny::runApp() の代わりに):

run_with_themer(shinyApp(ui, server))
run_with_themer("path/to/app")

bs_themer()

独自アプリのサーバー関数にテーマエディターを追加します：

server <- function(input, output, session) {
  bs_themer()  # Add during development, remove for production
  # ...
}

3つのツールはいずれも、コピーして貼り付けやすいように、生成された bs_theme() コードを R コンソールに出力します。制限事項： Bootstrap 5 以降のみ、Shiny アプリと runtime: shiny の R Markdown のみが対象です。bs_dependency_defer() を使用しないサードパーティー製ウィジェットには影響しません。

テーマの確認

計算済みの Sass 変数の値を取得します：

vars <- c("body-bg", "body-color", "primary", "border-radius")
bs_get_variables(bs_theme(), varnames = vars)
bs_get_variables(bs_theme(preset = "darkly"), varnames = vars)

コントラストを確認します（アクセシビリティ向け）：

bs_get_contrast(bs_theme(), c("primary", "dark", "light"))

WCAG AA 準拠を目指してください。通常のテキストは 4.5:1、大きなテキストは 3:1 です。

ベストプラクティス

1. カスタム CSS より bs_theme() を優先します — 変数が関連するすべてのコンポーネントに自動的に反映されます
2. Bootstrap のバージョンを固定します： bs_theme(version = 5) を指定すると、デフォルト値の変更による不具合を防げます
3. font_collection() でフォールバックフォントを指定します — 接続が遅いときの FOIT を防げます
4. コンポーネントごとにテストします： 入力欄、ボタン、カード、ナビゲーション、プロット、テーブル、モーダル、トースト、モバイル
5. bs_get_contrast() とブラウザーの開発者ツールでアクセシビリティを確認します
6. 一度限りのスタイル設定には、カスタム CSS ではなく CSS ユーティリティクラスを使用します（sass-and-css-variables.md を参照）
7. 複雑なテーマは別の theme.R にまとめます：

# theme.R
app_theme <- function() {
  bs_theme(
    version = 5,
    primary = "#2c3e50",
    base_font = font_google("Lato"),
    heading_font = font_google("Montserrat", wght = c(400, 700))
  ) |>
    bs_add_rules(sass::sass_file("www/custom.scss"))
}

参考ファイル

• sass-and-css-variables.md — Bootstrap の 2 層構成の変数システム、CSS カスタムプロパティ、ユーティリティクラス
• dark-mode.md — カラーモード、ダークモード、動的なテーマ設定、コンポーネントの互換性