
# シードからのパレット

`seed-color` を持つテーマは、その色の Material 3 のパレットを持ちます。テーマの明るさに対する 46 の色のロール (`primary`、`on-primary`、`surface-container`、`outline-variant`、...) で、Material 自身のアルゴリズム `ColorScheme.fromSeed` が作ります。`scheme-variant` はシードがどのようにロールになるかを、`contrast` は色とその上の色がどれだけ離れるかを選び、`colors.*` の下に書いたロールは作られたものより優先されます。

## 使う理由

二つの明るさの 46 のロールは、選んで揃え続けなければならない 92 の色です。シードがあれば、一つのブランドカラーがそのすべてを、どのサーフェスの上でもテキストが読めるトーンで与え、ダークのテーマは同じシードに `brightness: dark` を付けたものになります。ブランドが正確に必要とするいくつかのロール (エラーの赤、サーフェス) は、その上に手で設定します。

## 例

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      seed-color: '#0057B8'
      scheme-variant: tonal-spot
      colors:
        error: '#B3261E'          # 手で設定: シードのものより優先される
      themes:
        dark:
          brightness: dark        # 同じシード、ダークのトーン
        neon:
          seed-color: '#F5E000'
          scheme-variant: fidelity
        high-contrast:
          extends: light
          seed-color: '#000000'
          contrast: 1
```

```properties
spring.flutter.theme.seed-color=#0057B8
spring.flutter.theme.scheme-variant=tonal-spot
spring.flutter.theme.colors.error=#B3261E
spring.flutter.theme.themes.dark.brightness=dark
spring.flutter.theme.themes.neon.seed-color=#F5E000
spring.flutter.theme.themes.neon.scheme-variant=fidelity
spring.flutter.theme.themes.high-contrast.extends=light
spring.flutter.theme.themes.high-contrast.seed-color=#000000
spring.flutter.theme.themes.high-contrast.contrast=1
```

## プロパティ

| キー | 値 | デフォルト | 働き |
|---|---|---|---|
| `spring.flutter.theme.seed-color` | 色: `'#RRGGBB'`、`Colors` の名前 (`teal`、`deepPurple.shade200`)、色のオブジェクト | なし | パレットを作る元の色 |
| `spring.flutter.theme.scheme-variant` | `tonalSpot`、`fidelity`、`content`、`vibrant`、`expressive`、`monochrome`、`neutral`、`rainbow`、`fruitSalad`。どの書き方でも可 (`tonal-spot`、`fruit_salad`) | `tonalSpot` | Material 3 のどのアルゴリズムでパレットを作るか |
| `spring.flutter.theme.contrast` | `-1` から `1` の数値 | `0` | ロール間のコントラスト: `0` は Material の標準、`1` が最も高く、`-1` が最も低い |
| `spring.flutter.theme.colors.<role>` | 色 | シードから作られる | 作られたパレットの上に、手で設定する一つのロール |

どれも名前付きのテーマの中にも書けます (`themes.<name>.seed-color`)。`seed-color` なしの変種やコントラストは、Material 3 のベースラインのシード `#6750A4` を使います。三つのどれも持たないテーマは、Flutter のベースラインのパレット、つまり `ThemeData()` のものを持ちます。`#6750A4` のパレットに近いですが、同じではありません。

シードは他と同じ色なので、参照 (トークンへの `seed-color: $brand.blue`) やオブジェクト (`{ color: teal, mix: { with: white, amount: 20% } }`) でも書けます。

## スキームの変種

変種は、シードがどのように primary、secondary、tertiary、そしてサーフェスの中立的なトーンになるかを決めます。それぞれが Material Color Utilities のスキーム (`DynamicSchemeVariant`) の一つです。

| 変種 | 働き | 使う場面 |
|---|---|---|
| `tonalSpot` | Material 3 のデフォルト。落ち着いた中程度の強さの色。secondary と tertiary はシードのより柔らかい親類で、サーフェスはほぼグレー | ほとんどのアプリ |
| `fidelity` | primary は、強いシードであっても、トーンが許す限りシードに近く保たれる。コンテナはその色相と強さを保つ。tertiary はシードの補色の色相 | シードが、そのまま表示されなければならないブランドカラーのとき |
| `content` | `fidelity` に似ているが、tertiary は補色ではなくシードの隣の色相。画像の主な色のような、コンテンツから取ったシードのために作られている | アルバムのジャケットや写真からのパレット |
| `vibrant` | primary はシードの色相を最も高い強さで保つ。secondary と tertiary は隣の色相に回され、サーフェスはより色づく | 遊び心のあるカラフルなアプリ |
| `expressive` | primary の色相はシードのものから離され、secondary と tertiary はさらに離される。意外な組み合わせ | 忠実さより個性的な見た目 |
| `monochrome` | グレーだけ: どのロールも色相を持たない | 白黒のデザイン、印刷や電子ペーパーのような見た目 |
| `neutral` | ほぼグレーで、すべてのロールにシードの気配がある | 落ち着いたツール、読書のアプリ |
| `rainbow` | 色相のないグレーのサーフェス。primary はシードの色相で、tertiary はそこから大きく離される | はっきりと互いに異なる必要のあるアクセント |
| `fruitSalad` | カラフル: primary と secondary はシードの色相から離され、tertiary はシードの色相 | ゲーム、子ども向けのアプリ |

未知の変種は起動を失敗させ、この九つを列挙します。

## コントラスト

`contrast` は、ロールのすべての組 (色とその上に表示される色: `primary` と `on-primary`、`surface` と `on-surface`) を、より離したり、より近づけたりします。

| 値 | 結果 |
|---|---|
| `-1` | コントラストを下げたもの: より柔らかく、装飾的なテーマのため |
| `0` | Material 3 の標準: テキストはそのサーフェスの上で WCAG の 4.5:1 を満たす |
| `0.5` | 中程度のコントラスト。Android の「中程度のコントラスト」の設定 |
| `1` | 高コントラスト。Android の「高コントラスト」の設定: ロービジョンのため |

その間のどの数値でも動きます。`-1` から `1` の外は起動を失敗させます。高コントラストの専用のテーマがあれば、ユーザーがアプリの中でそれを選べます。

```yaml
spring:
  flutter:
    theme:
      seed-color: '#3F51B5'
      themes:
        high-contrast:
          extends: light
          contrast: 1
        high-contrast-dark:
          extends: dark
          contrast: 1
```

## シードの上に手で設定するロール

`colors.*` の下に書いたロールは、そのロールだけを置き換えます。他はすべてシードが作ったままです。ロールは、設定されたものでも作られたものでも、別のロールを参照できます。

```yaml
spring:
  flutter:
    theme:
      seed-color: teal
      scheme-variant: vibrant
      colors:
        secondary: '#0277BD'
        surface-container-low: '#E6F4F1'
        primary-container: { color: $colors.primary, alpha: 18% }
      themes:
        dark:
          brightness: dark
          colors:
            surface-container-low: '#10302E'
```

テーマのパレットは次の順で作られます。

1. テーマの明るさのパレット: Flutter のベースライン、またはシード、変種、コントラストがあれば、それらから `ColorScheme.fromSeed` が作るもの。
2. その上に `colors.*` のロール。
3. 参照が解決されます: `$colors.primary` を参照するロールは、最終的な `primary` を受け取ります。

結果はテーマの `SpringThemeData.colorScheme` (`SpringColorScheme`。同じ 46 のロールを持つ Flutter のスターターのパレットのクラス) であり、`ThemeData` では同じ色を持つ Material の `ColorScheme` です。46 のロールのどれも、ケバブケースの名前で `colors.*` の下にあります。[色](../spring-boot-starter-flutter/themes/colors.md#色のロール) を参照してください。

## 作られたロールへの参照

`$colors.<role>` は、テーマのプロパティの中で、手で設定されたものもシードから作られたものも、すべてのロールに届きます。そのため、シードだけを設定すれば、コンポーネントとスタイルはパレットに従います。

```yaml
spring:
  flutter:
    theme:
      seed-color: deepPurple
      components:
        card: { color: $colors.surface-container }
        app-bar: { background-color: $colors.primary-container }
      styles:
        tag:
          fill: { color: $colors.tertiary, alpha: 12% }
```

シードを変えるテーマ (`seed-color: teal` を持つ `ocean`) は、作られたロールを参照するすべての値を変えます。Dart では次のとおりです。

```dart
final scheme = Theme.of(context).colorScheme;              // Material の ColorScheme
final same = SpringTheme.of(context).colorScheme;          // SpringColorScheme
Container(color: scheme.surfaceContainerHigh);
```

ジェネレーターの型付きのキー (`context.theme.colors.<role>`) は、`colors` の下に書いたロールに対して存在します。作られたロールはカラースキームから読みます。[型付きのキー](../spring-core-dart-generator/flutter/typed-keys.md) を参照してください。

## Web のページのローダーでの同じパレット

ジェネレーターが `web/index.html` に書き込む Web のページのローダーは、Flutter が動く前に表示されるため、Material に色を尋ねることはできません。ジェネレーターは同じアルゴリズム (Material Color Utilities) で、同じ `seed-color`、`scheme-variant`、`contrast` から自分でパレットを作ります。そのため、`color: $colors.primary` のローダーは、その少し後にアプリが表示するのと同じ色を表示します。

```yaml
spring:
  flutter:
    theme:
      seed-color: '#0057B8'
      loaders:
        dots: { kind: dots, color: $colors.primary, size: 10, count: 3 }
      splash:
        background: { color: $colors.surface-container-lowest }
        loader: dots
```

シード、変種、コントラストのないテーマは、それらが異なりうる唯一の場合です。そのときページのローダーは、Flutter のベースラインではなく `#6750A4` のパレットを使います。正確に一致させるには、シードか、ローダーが使うロールを設定してください。[ページのローダー](../spring-core-dart-generator/flutter/page-loader.md) と [ローダーとスプラッシュ](../spring-boot-starter-flutter/themes/loaders.md) を参照してください。

## エラー

色ではない値、未知の変種、`-1` から `1` の外のコントラストは起動を失敗させ、プロパティを示します。デザインのスターターがなければ、三つのどれも同じく起動を失敗させます。

```text
Invalid theme property spring.flutter.theme.seedcolor (theme light): '#0057B8'; expected 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.
```

デザインライブラリのないアプリは、代わりにロールを `colors.*` の下に書きます。設定しないものは Flutter のベースラインです。[Cupertino のスターター](../spring-boot-starter-flutter-cupertino/palette.md) は Material なしで同じパレットを作るため、Material のアプリと Cupertino のアプリが共有するテーマは、どちらでも同じ色になります。

## Spring (Java) との対応

相当するものはありません。アルゴリズムは Material 3 のもの (Material Color Utilities) で、Flutter の `ColorScheme.fromSeed` がそれを実行します。

## 関連項目

- [色](../spring-boot-starter-flutter/themes/colors.md): 46 のロールと色の書き方
- [プロパティからのテーマ](themes.md)
- [Cupertino のスターターのパレット](../spring-boot-starter-flutter-cupertino/palette.md)
- [トークンと参照](../spring-boot-starter-flutter/themes/tokens-and-references.md)
- [デザインライブラリ](../spring-boot-starter-flutter/design-libraries.md)
