pixiv/charcoal/choosing-charcoal-tokens

Charcoal のトークンを選ぶ

Charcoal の値は好みで決めない。用途ごとに使うトークンが決まっている。迷ったら推測せず、 下の参照先で用途の表を引く。

原則として、hex・px の直書きをしない。 値はトークン名で書く。

どれを読むか

読む前に外さないこと

参照を開かずに書き始める場合でも、次は守る。

• 文字色に `#000000` を使わない。 既定は text.default。
• プライマリーカラーは重要アクションと誘導にだけ使う。 目立たせたいという理由で使わない。
• 警告色はその状態を示すときだけ使う。 強調の手段にしない。
• ボーダーは、無いと理解を妨げるときだけ引く。 まず余白か背景色の差で足りないか試す。

区切り線の既定は border.secondary。

• 余白はレイアウトトークンから選ぶ。 トークンに無い数値を作らない。迷ったら layout.30。
• 本文の基準は Body（`body.Regular`）。 テキストスタイルは 4 種類しかない。5 種類目を作らない。
• 派手なグラデーション、過剰な線、過剰な装飾を足さない。 コンテンツより UI が目立たない。

トークン名を CSS 変数に直す

ガイドラインはトークンを layout.30 のように書く。CSS 変数の名前はそれとは違う。 推測すると --charcoal-layout-30 のような存在しない名前になり、値は当たらない。

規則は --charcoal-<カテゴリ>-<キーを - でつないだもの>。色は color、余白は space（layout と target はその下）、角丸は radius、線の太さは border-width、 文字は text。

テキストスタイルは font-size と line-height の 2 本で指定する。 1 本で済ませない。 スタイル名は小文字にしてつなぐ（heading.M → heading-m、caption.S → caption-s）。 px は書かない。

確証がなければ node_modules/@charcoal-ui/theme/dist/css/v2/light.css で名前を確かめる。無い名前は書かない。

判断の順番

1. その値にトークンがあるか。あれば必ずトークンを使う。
2. 用途の表で、書こうとしている部品が名指しされているか。されていなければ、近い値を理由に

割り当てない。表が名指ししている用途にだけ使う。

1. 状態（hover / press / disabled）が要るか。要る状態にだけ付ける。
2. 迷いが残るなら references/design-philosophy.md の原則で決める。