
# テーマの色

テーマのパレットは、デザインのスターターを持つアプリでは一つの**シードカラー**から作られ、それ以外では Flutter の Material 3 のベースラインです。その後、Material 3 の 46 の**色のロール**のどれでも手で変えられます。色は、名前、16 進数のコード、他の色への参照、または不透明度を変えたり二つの色を混ぜたりするオブジェクトとして書きます。

```yaml
spring:
  flutter:
    theme:
      seed-color: '#0057B8'
      scheme-variant: vibrant
      contrast: 0.5
      colors:
        secondary: '#FFD700'
        error: '#B3261E'
        surface: '#FAFAFA'
        surface-container-low: grey.shade100
        outline-variant: { color: $colors.outline, alpha: 40% }
      themes:
        dark:
          seed-color: deepPurple.shade200
          colors:
            surface: '#121212'
```

## デザインライブラリがあるとき、ないとき

シードにはデザインのスターターが必要です。`seed-color`、`scheme-variant`、`contrast` は Material 3 のパレットを作り、そのアルゴリズムはデザインのスターターにあります。`colors.*` のロールはすべてのアプリで動きます。

| アプリ | パレット |
|---|---|
| デザインライブラリなし (種類 `widgets`) | Flutter の Material 3 のベースライン (`SpringColorScheme.baseline`) の上に `colors.*` のロール。シード、変種、コントラストは起動を止める |
| [spring_boot_starter_flutter_material](../../spring-boot-starter-flutter-material/index.md) あり | Material の `ColorScheme.fromSeed` でシードから作り、次に `colors.*` |
| [spring_boot_starter_flutter_cupertino](../../spring-boot-starter-flutter-cupertino/index.md) あり | 同じパレットを、Material なしに `material_color_utilities` で計算する。そのシードから Material のアプリが持つのと同じ色 |

上の例は、デザインのスターターを持つアプリのためのものです。スターターがなければ、何をすべきかを述べるメッセージとともに起動が失敗します。

```text
a design starter in the dependencies: seed-color, scheme-variant and contrast make a Material 3 palette, which spring_boot_starter_flutter_material (or spring_boot_starter_flutter_cupertino) calculates. Without one, set the roles under colors
```

デザインライブラリのないアプリのためのテーマは、ロールを書き出します。

```yaml
spring:
  flutter:
    theme:
      colors:
        primary: '#0057B8'
        on-primary: '#FFFFFF'
        primary-container: '#D6E3FF'
        on-primary-container: '#001B3D'
        surface: '#FAFAFA'
```

## シード、変種、コントラスト

デザインのスターターがあれば、三つのプロパティが Flutter のベースラインの代わりにパレットを作ります。`seed-color` は 46 のロールすべての元になる一つの色、`scheme-variant` はそれらを作る Material 3 の九つのアルゴリズムのどれか (`tonalSpot`、`fidelity`、`vibrant`、...)、`contrast` は `-1` から `1` です。Material と Cupertino のスターターは、これらから同じ色を作ります。すべての変種、コントラストのレベル、例は、Material のスターターの[シードからのパレット](../../spring-boot-starter-flutter-material/palette.md) (と [Cupertino のスターターのもの](../../spring-boot-starter-flutter-cupertino/palette.md)) にあります。

| プロパティ | 型 | 値 | デフォルト | 働き |
|---|---|---|---|---|
| `seed-color` | 色 | 任意の色 | Flutter のベースラインのパレット | パレットを作る元の色。デザインのスターターが必要 |
| `scheme-variant` | 列挙 | `tonalSpot`、`fidelity`、`content`、`vibrant`、`expressive`、`monochrome`、`neutral`、`rainbow`、`fruitSalad` | `tonalSpot` | シードからパレットを作る方法。デザインのスターターが必要 |
| `contrast` | 数値 | `-1` から `1` | `0` | パレットのコントラスト。デザインのスターターが必要 |
| `brightness` | 列挙 | `light`、`dark` | テーマによる | ライトまたはダークのトーン。[プロパティ](properties.md#明るさ) を参照 |
| `colors.<role>` | 色 | 任意の色 | シードから、なければベースラインから | パレットのロールの一つを置き換える。すべてのアプリで動く |

## 色のロール

`colors.<role>` は、以下の任意のロールをケバブケース (`on-surface`) で受け取ります。書かなかったロールはシードから (シードがなければベースラインから) 来ます。書いたロールはそのロールだけを置き換え、他はシードやベースラインが作ったままです。

### Primary、secondary、tertiary

primary は主なアクセントです: ボタン、アクティブなコントロール、主要なコンポーネント。secondary は、フィルターチップのような目立ちにくいコンポーネントのためのものです。tertiary は、primary と secondary のバランスを取る対照的なアクセントのためのものです。

| ロール | 用途 |
|---|---|
| `primary` | 主なアクセント: 塗りつぶしのボタン、オンのスイッチ、フォーカスリング、リンク |
| `on-primary` | `primary` の上のテキストとアイコン |
| `primary-container` | より柔らかいアクセントのサーフェス: 目立つカード、選択されたナビゲーションのインジケーター |
| `on-primary-container` | `primary-container` の上のテキストとアイコン |
| `primary-fixed` | ライトとダークで色が変わらないアクセントのサーフェス |
| `primary-fixed-dim` | より暗い `primary-fixed`。その隣での強調に使う |
| `on-primary-fixed` | `primary-fixed` と `primary-fixed-dim` の上のテキストとアイコン |
| `on-primary-fixed-variant` | 固定の色の上の、強調の弱いテキストとアイコン |
| `secondary` | 目立ちにくいアクセント: フィルターチップ、トーナルボタン |
| `on-secondary` | `secondary` の上のテキストとアイコン |
| `secondary-container` | secondary のコンポーネントのための柔らかいサーフェス: トーナルボタン、選択されたチップ |
| `on-secondary-container` | `secondary-container` の上のテキストとアイコン |
| `secondary-fixed` | ライトとダークで同じままの secondary のサーフェス |
| `secondary-fixed-dim` | より暗い `secondary-fixed` |
| `on-secondary-fixed` | secondary の固定の色の上のテキストとアイコン |
| `on-secondary-fixed-variant` | secondary の固定の色の上の、強調の弱いテキストとアイコン |
| `tertiary` | バランスのための対照的なアクセント: バッジ、ハイライト |
| `on-tertiary` | `tertiary` の上のテキストとアイコン |
| `tertiary-container` | tertiary のコンポーネントのための柔らかいサーフェス |
| `on-tertiary-container` | `tertiary-container` の上のテキストとアイコン |
| `tertiary-fixed` | ライトとダークで同じままの tertiary のサーフェス |
| `tertiary-fixed-dim` | より暗い `tertiary-fixed` |
| `on-tertiary-fixed` | tertiary の固定の色の上のテキストとアイコン |
| `on-tertiary-fixed-variant` | tertiary の固定の色の上の、強調の弱いテキストとアイコン |

### エラー

| ロール | 用途 |
|---|---|
| `error` | エラー: 不正なフィールド、破壊的なアクション、エラーのテキスト |
| `on-error` | `error` の上のテキストとアイコン |
| `error-container` | エラーメッセージのための柔らかいサーフェス |
| `on-error-container` | `error-container` の上のテキストとアイコン |

### サーフェス

サーフェスはアプリの背景です。コンテナのロールは最も低いものから最も高いものまで五段階あるため、カードやシートをページの上に置けます。

| ロール | 用途 |
|---|---|
| `surface` | 画面、カード、シートのデフォルトの背景 |
| `on-surface` | 任意のサーフェスの上のテキストとアイコン。主なテキストの色 |
| `on-surface-variant` | サーフェスの上の、強調の弱いテキストとアイコン: ヒント、補助的なテキスト |
| `surface-dim` | 常に `surface` より暗いサーフェス |
| `surface-bright` | 常に `surface` より明るいサーフェス |
| `surface-container-lowest` | 最も低いコンテナの段階。他のものの背後の領域に使う |
| `surface-container-low` | 低いコンテナの段階: カード、シート |
| `surface-container` | 中間のコンテナの段階: ナビゲーションバー、ダイアログ |
| `surface-container-high` | 高いコンテナの段階: メニュー、日付ピッカー |
| `surface-container-highest` | 最も高いコンテナの段階: テキストフィールド、セグメントボタン |
| `surface-tint` | 一部のコンポーネントで、エレベーションを示すためにサーフェスに重ねる色 |

### 反転、アウトライン、システム

| ロール | 用途 |
|---|---|
| `inverse-surface` | テーマと反対に見えるサーフェス: スナックバー |
| `on-inverse-surface` | `inverse-surface` の上のテキストとアイコン |
| `inverse-primary` | スナックバーのアクションなど、`inverse-surface` の上に表示されるアクセント |
| `outline` | テキストフィールドとアウトラインボタンの枠線。重要な区切り線 |
| `outline-variant` | 装飾的な区切り線と、より薄い枠線 |
| `shadow` | 影の色 |
| `scrim` | モーダルのシートやダイアログの背後のページを暗くする色 |

`colors` の下のそれ以外の名前は起動を止め、有効なロールを列挙します。

## 色の書き方

色の値は次のいずれかです。

| 形式 | 例 | 注記 |
|---|---|---|
| `#RGB` | `'#F00'` | 各桁が二重になる: `#F00` は `#FF0000` |
| `#RRGGBB` | `'#FF40A0'` | 不透明 |
| `#AARRGGBB` | `'#80FF0000'` | 最初の二桁が不透明度 |
| `Colors` の名前 | `white`、`black`、`transparent`、`red`、`grey`、`deepPurple`、`black54`、`white70` | Flutter の `Colors` の名前 |
| シェード | `red.shade200`、`deepPurple.shade700`、`redAccent.shade100` | `shade50`、`shade100` ... `shade900`。アクセントのファミリーは 100、200、400、700 を持つ |
| 参照 | `$colors.primary`、`$brand.accent` | ロール、またはテーマの任意の値。[トークンと参照](tokens-and-references.md) を参照 |
| オブジェクト | `{ color: $colors.primary, alpha: 12% }` | 変更を加えた色。後述 |

変更を加えた色の形式は一つ、オブジェクトだけです。ロールの名前だけ (`primary`) や不透明度付きのロール (`primary@12%`) は色ではありません。`$colors.primary` と書いてください。

注記:

- YAML では **`#` で始まるものはすべて引用符で囲んでください**。そうしないと、行の残りがコメントになります (`{ ... }` の中でも)。
- `Colors` の名前は、キャメルケース (`deepPurple`)、ケバブケース (`deep-purple`)、スネークケース (`deep_purple`) で書けます。名前は大文字小文字を区別します: `Red` は色ではありません。
- Flutter の `Colors` のファミリーは、`red`、`pink`、`purple`、`deepPurple`、`indigo`、`blue`、`lightBlue`、`cyan`、`teal`、`green`、`lightGreen`、`lime`、`yellow`、`amber`、`orange`、`deepOrange`、`brown`、`grey`、`blueGrey` で、それぞれ `.shade50` から `.shade900` を持ちます。`brown`、`grey`、`blueGrey` を除くすべての色のファミリーは、アクセントのファミリーも持ちます: `redAccent`、`pinkAccent`、`purpleAccent`、`deepPurpleAccent`、`indigoAccent`、`blueAccent`、`lightBlueAccent`、`cyanAccent`、`tealAccent`、`greenAccent`、`lightGreenAccent`、`limeAccent`、`yellowAccent`、`amberAccent`、`orangeAccent`、`deepOrangeAccent` で、それぞれ `.shade100`、`.shade200`、`.shade400`、`.shade700` を持ちます (`pinkAccent.shade200`)。`black87`、`black54`、`black45`、`black38`、`black26`、`black12`、`white70`、`white60`、`white54`、`white38`、`white30`、`white24`、`white12`、`white10` は、その不透明度を持つ Flutter の色です。

### 不透明度と混色: 色のオブジェクト

変更を加えた色はオブジェクトです。必須なのは `color` だけです。

```yaml
badge-fill:
  color: $colors.primary
  alpha: 12%
hover-fill:
  color: $colors.primary
  mix: { with: white, amount: 14% }
```

| キー | 働き |
|---|---|
| `color` | 元にする色: 単なる色、参照、または別のオブジェクト。必須 |
| `mix` | `{ with: <color>, amount: <percent> }` は、色をその割合だけ `with` の方へ動かす |
| `alpha` | 結果の不透明度をその割合に設定する。色が持っていた不透明度を置き換える |

キーの順序にかかわらず、`mix` が先に、次に `alpha` が適用されます。割合は `0%` から `100%`、または `0` から `1` です (`12%` と `0.12` は同じです)。範囲外の割合、`color` がないこと、`color`、`mix`、`alpha` 以外のキーは起動を止め、最も近いキーを示します (`alfa` は「did you mean 'alpha'」になります)。オブジェクトは、色が使えるすべての場所で動きます: `colors.*`、`seed-color`、トークン、スタイル (状態ごとにも)、コンポーネント (状態ごとにも)、`cupertino`、`background`、グラデーションの色。`.properties` ファイルでは、オブジェクトはキーごとに書きます。

```properties
spring.flutter.theme.colors.primary-container.color=$colors.primary
spring.flutter.theme.colors.primary-container.alpha=18%
```

```yaml
spring:
  flutter:
    theme:
      colors:
        primary: '#F5E000'
        primary-container: { color: $colors.primary, alpha: 18% }
        secondary-container:
          color: $colors.primary
          mix: { with: white, amount: 80% }
      tokens:
        glass: { color: '#FFFFFF', alpha: 8% }
```


`colors` ではロールを名前で書きません。あるロールを別のロールの定義の中や、`components` と `cupertino` で使うには、参照を使います: `$colors.primary`、`$colors.surface-container-low`。[コンポーネント](../../spring-boot-starter-flutter-material/components/index.md) を参照してください。

## Dart で読む

```dart
final theme = SpringTheme.of(context);               // 任意の種類のアプリ
theme.colorScheme.secondary;                         // SpringColorScheme
theme.role('surface-container-low');                 // 名前で
final colors = Theme.of(context).colorScheme;        // Material のアプリでだけ
```

`SpringThemeData.colorScheme` は `SpringColorScheme` です。スターター独自のパレットのクラスで、Material 3 の 46 のロールを同じ名前で持ち (`primary`、`onSurface`、`surfaceContainerHigh`)、`role(name)`、`roles`、`withRoles(...)`、`SpringColorScheme.baseline(brightness)` を持ちます。Material の `ColorScheme` ではありません。Material のアプリでは、`Theme.of(context).colorScheme` が同じロールを持つ Material の `ColorScheme` です ([プロパティからのテーマ](../../spring-boot-starter-flutter-material/themes.md#テーマを読む) を参照)。これは `MaterialApp` にだけ存在します。

ジェネレーターがあれば、`colors` の下で宣言したすべてのロールが型付きになります。

```dart
context.theme.colors.surfaceContainerLow;   // Color
context.theme.colors.outline;               // Material のロールも使える
```

`context.theme.colors.<role>` は、テーマ自身の値、またはパレットのその名前の Material のロールを返します。宣言していないロールにはゲッターがありません (`SpringTheme.of(context).colorScheme` を使ってください)。

## 関連項目

- [プロパティ](properties.md): `brightness`、`seed-color`、`scheme-variant`、`contrast`
- [シードからのパレット](../../spring-boot-starter-flutter-material/palette.md): スキームの変種とコントラスト
- [トークンと参照](tokens-and-references.md): `$colors.primary` と色のオブジェクト
- [コンポーネントのテーマ](../../spring-boot-starter-flutter-material/components/index.md): Material のボタン、カード、バーの色
- [背景](background.md): 画面の背後の色とグラデーション
- [デザインライブラリ](../design-libraries.md): Material や Cupertino があるとき、ないときのパレット
