トークンと参照
トークンは独自の値です。ブランドカラー、バナーの高さ、タグのリストなどです。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。
期待とは異なり、テキストになるもの:
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、NaN1,5,と12, red(数値のリストは数値だけを持ちます)
余白を読む場所 (スタイル) では、カンマ区切りのリストの三つや五つの数値はエラーです。
リスト
リストは 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 としてしか到達できません。
ルール:
- 参照は値のテキストを表します。 色のオブジェクトはそれが作る色として参照されるため、
{ 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は、$$も含めて書いたとおりに残されます。プレースホルダーから届くシークレットは$を含むことがあります。
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 は、参照を含む任意の色の値で使えます。色 を参照してください。