トークンと参照

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

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 スタイル でだけ。トークンではテキスト
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。

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

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

リスト

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

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 は期間ではなく数値です。同じ形式が モーション と スタイル で使われます。

画像

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

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

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 を返します。ジェネレーターがあれば型は固定され、各グループは小さなクラスになります。

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 としてしか到達できません。

ルール:

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 は、参照を含む任意の色の値で使えます。色 を参照してください。

関連項目