
# トークンと参照

**トークン**は独自の値です。ブランドカラー、バナーの高さ、タグのリストなどです。Material のテーマには居場所がないため、`tokens` の下に置いて Dart で読みます。**参照** (`$colors.primary`) は、ある値に別の値を使わせるため、デザインシステムを一度書けば済みます。

```yaml
spring:
  flutter:
    theme:
      colors:
        primary: '#F5E000'
      tokens:
        brand:
          accent: $colors.primary
          accent-soft: { color: $brand.accent, alpha: 16% }
          banner-height: 96
          fade: 250ms
          tag:
            radius: 14
            labels: [New, Staff pick, Sale]
            colors: [$brand.accent, '#00E5FF', white]
          hero:
            source: https://cdn.example.com/hero.png
            refresh: 1d
      themes:
        sepia:
          tokens:
            brand:
              accent: '#8B4513'      # accent-soft は accent を参照するので追従する
```

## トークン

`tokens.<group>.<key>` は好きなだけ深くできます。グループとは、他のキーを持つ任意のキーです。テーマは `tokens` の下の名前について何もチェックしません。それらはあなたのものです。他のすべての値と同じく、トークンはテーマごとに異なる値にできます。

### 値の型の決まり方

トークンには宣言された型がありません。見た目によって型が決まります。前後の空白を取り除いた後、最初に一致したルールが優先されます。

| 順序 | 種類 | 見た目 | 例 | Dart では |
|---|---|---|---|---|
| 1 | 数値 | 省略可能な符号、小数部、指数を持つ数字。または大文字小文字を問わない `Infinity` | `12`、`-3`、`+5`、`.5`、`2.`、`1.5`、`1e3`、`-2.5e-2`、`Infinity` | `double` |
| 2 | 期間 | 数値 (小数も可)、省略可能な空白、そして大文字小文字を問わない `ms`、`s`、`m`、`h`、`d` | `250ms`、`250 ms`、`4s`、`1.5s`、`.5s`、`2m`、`1h`、`0.5d` | `Duration` |
| 3 | 余白 | カンマで区切った二つまたは四つの数値 (または一つ、二つ、四つの数値の YAML のリスト) | `12, 6`、`8, 4, 8, 4` | [スタイル](styles-and-states.md) でだけ。トークンではテキスト |
| 4 | 色 | 16 進数のコードか `Colors` の名前。または `color` を持つマップ (色のオブジェクト) | `#F00`、`deepPurple.shade200`、`{ color: '#F00', alpha: 12% }`、`{ color: '#F00', mix: { with: white, amount: 50% }, alpha: 80% }` | `Color` |
| 5 | テキスト | それ以外すべて | `hello`、`ease-out`、`bold`、`12px`、`https://example.com/a.png` | `String` |

`color` を持つマップであるトークンやスタイルの値は色です。`color` の隣には `mix` と `alpha` を持てますが、それ以外は持てません。それ以外のキーはエラーです (`color` トークンを他のものと並べて持つトークンのグループは色ではないので、そのトークンには別の名前を付けてください)。同じ期間の構文は、時間を読むすべての場所で使えます: モーション、アニメーション、スタイル、トークン、`transition`、`refresh`、`timeout`。

期待とは異なり、テキストになるもの:

- `Red` と `WHITE` (色の名前は大文字小文字を区別します)、`#ABCD` と `#FF00` (桁数が誤り)、`0x10` と `0xFF0000` (`0x` の色はありません)、`red.shade999`、`primary` と `on-surface` (ロールは `$colors.primary`)
- `#F00 alpha 12%`、`#F00 mix white 14%`、`primary@38%` (一行の色の式はなくなりました。変更を加えた色はオブジェクトです)
- `12px`、`-5s` (負の期間はありません)、`250 sec`、`NaN`
- `1,5,` と `12, red` (数値のリストは数値だけを持ちます)

余白を読む場所 (スタイル) では、カンマ区切りのリストの三つや五つの数値はエラーです。

### リスト

リストは YAML のリスト、または一つのカンマ区切りの値です。その型は項目から来ます。すべて色なら `List<Color>`、すべて数値なら `List<double>`、それ以外は `List<String>` です。後の層 (テーマ、またはそれが継承するテーマ) のリストは、リスト全体を置き換えます。

```yaml
spring:
  flutter:
    theme:
      tokens:
        chart:
          series: [$colors.primary, $colors.tertiary, '#FF6B00']   # List<Color>
          steps: [4, 8, 16]                                       # List<double>
          names: [Mon, Tue, Wed]                                  # List<String>
```

リストは YAML のリストとして書いてください。`12, 6` のようなスカラーは、トークンではテキストです。

### 期間

期間のトークンは単位付きの数値です: `250ms`、`1.5s`、`2m`、`1h`。単なる `250` は期間ではなく数値です。同じ形式が [モーション](motion-and-animations.md) と [スタイル](styles-and-states.md) で使われます。

### 画像

`source` を持ち、他のキーが `refresh`、`source-sha256`、`headers`、`timeout`、`fallback`、`allow-http` だけであるマップのトークンは**画像**です。[背景の画像](images.md) と同じくダウンロード、キャッシュ、更新されます。`source` の隣に他のキーを持つマップは、画像ではなくトークンのグループです。画像は少なくとも二つのグループの深さになければなりません: `tokens.<group>.<key>`。

```yaml
spring:
  flutter:
    theme:
      tokens:
        brand:
          hero: { source: https://cdn.example.com/hero.png, refresh: 1d, fallback: assets/hero.png }
```

### Dart でトークンを読む

```dart
final theme = SpringTheme.of(context);
theme.tokenColor('brand.accent');          // Color?
theme.tokenNumber('brand.banner-height');  // double?
theme.tokenDuration('brand.fade');         // Duration?
theme.token('brand.badge-text');           // String?
theme.tokenTexts('brand.tag.labels');      // List<String>?
theme.tokenColors('brand.tag.colors');     // List<Color>?
theme.tokenNumbers('chart.steps');         // List<double>?
theme.tokenImage('brand.hero');            // ThemeImage?
```

それぞれ、トークンがない場合やその種類でない場合は `null` を返します。ジェネレーターがあれば型は固定され、各グループは小さなクラスになります。

```dart
final tag = context.theme.tokens.brand.tag;
tag.radius;      // double
tag.labels;      // List<String>
tag.colors;      // List<Color>
context.theme.tokens.brand.hero;   // ThemeImage
context.theme.tokens.brand.fade;   // Duration
```

トークンはすべてのテーマで一つの型を持たなければなりません。あるテーマでは色で、別のテーマでは数値であるトークンは、両方の場所を示してビルドを失敗させます。

## 参照

参照は、`$` とそのパスで、同じテーマの別の値を指定します。

| 形式 | 意味 |
|---|---|
| `$colors.primary` | `colors.primary` の値 |
| `$spacing.m` | `spacing.m` の値 |
| `$motion.durations.fast` | `motion.durations.fast` の値 |
| `$tokens.brand.accent` | 完全な形のトークン |
| `$brand.accent` | 短い形のトークン: 最初のセグメントがテーマのセクションの名前でなければ `tokens.` を省ける |
| `$colors.outline` | 書いていない Material の色のロール: テーマの `seed-color`、`brightness`、`scheme-variant`、`contrast` が作るパレットのロール (デザインのスターターがあるとき)、またはその明るさの Flutter のベースラインのロール (ないとき) |
| `$shape.extra-small` | 書いていない Material 3 の角の半径 |
| `$$` | 文字どおりの `$` |

パスを始めるセクションは、ちょうど次のものです: `brightness`、`seed-color`、`scheme-variant`、`contrast`、`colors`、`typography`、`shape`、`elevation`、`spacing`、`visual-density`、`tap-target-size`、`splash`、`motion`、`components`、`tokens`、`cupertino`、`styles`、`animations`、`background`。これらの名前の一つを持つトークンのグループ (`colors` という名前のグループ) には、`$tokens.colors.x` としてしか到達できません。

ルール:

- **参照は値のテキストを表します。** 色のオブジェクトはそれが作る色として参照されるため、`{ color: $brand.accent, alpha: 12% }` は、それ自体がオブジェクトであるトークンの上に置けます。リストは、その項目をカンマでつないだものとして参照されます。参照は値の中のどこにでも置けます: `transition: $motion.durations.fast ease-out`。
- **宣言された値が優先されます。** `colors` に書いたロールは書いたとおりに使われます。書いていないロールは、`colors` の変更を除いたパレットから来るため、`$colors.outline` は安定しています。
- **テーマごと、`extends` の後。** 参照はテーマが組み合わされるときに解決されます。`colors.primary` を変えるダークテーマは、それを参照するすべてのものを変えます。
- **パスの綴り。** パスは通常のキーのルールに従います。大文字小文字、`-`、`_` の違いは問いません。末尾のドットやダッシュ (文の終わりのような `$colors.primary.`) はパスの一部ではありません。
- **`$` と文字以外はテキストです。** `$5` は `$5` のままです。
- **循環や未知のパスは起動を止めます。** メッセージは参照の連鎖、または最も近い既知のパス (「did you mean」) を示します。
- **解決されない値もあります。** `headers` の下のすべてと、画像のキー `source`、`fallback`、`source-sha256` は、`$$` も含めて書いたとおりに残されます。プレースホルダーから届くシークレットは `$` を含むことがあります。

```yaml
spring:
  flutter:
    theme:
      seed-color: $brand.seed        # デザインのスターターが必要
      colors:
        primary-container: { color: $brand.accent, alpha: 18% }
        outline-variant: { color: $colors.outline, alpha: 40% }
      shape:
        small: 6
      styles:
        chip:
          radius: $shape.small
          padding: $spacing.s
      tokens:
        brand:
          seed: '#0057B8'
          accent: '#FF6B00'
```

### なぜ `${...}` ではないのか

`${cdn.token}` は Spring のプレースホルダーです。アプリケーションの `Environment` の任意のプロパティ (ファイル、環境変数、`--dart-define`) を読み、テーマの中でも、例えば画像の `headers` で引き続き動きます。テーマの参照は、テーマのルートからのパスで*同じテーマ*の別の値を指し、`extends` の後にテーマごとに解決しなければなりません。独自の記号を持つ短い形が二つを区別します: `${...}` はアプリケーションのもの、`$path` はテーマのものです。

## 色の式

`alpha` と `mix` は、参照を含む任意の色の値で使えます。[色](colors.md#不透明度と混色-色のオブジェクト) を参照してください。

## 関連項目

- [色](colors.md)
- [スタイルと状態](styles-and-states.md): `styles` の中の参照
- [画像](images.md): 画像のトークン
- [概要](index.md#型付きのキー-contexttheme): 生成される `context.theme.tokens`
