Skill v1.0.0
currentLLM-judged scan90/100version: "1.0.0" name: choosing-charcoal-tokens description: Use before choosing any color, text style, spacing, radius or border value in code that uses @charcoal-ui, and whenever a literal is about to be written where a token exists — a hex color, a px padding or gap, a font-size, a border-radius or border-width. Charcoal has one correct token for each of these and the choice is prescribed, not a matter of taste. Also use when reviewing such code, or when deciding how dense, how loud or how bordered a screen should be.
Charcoal のトークンを選ぶ
Charcoal の値は好みで決めない。用途ごとに使うトークンが決まっている。迷ったら推測せず、 下の参照先で用途の表を引く。
原則として、hex・px の直書きをしない。 値はトークン名で書く。
どれを読むか
| 決めること | 参照 | |
|---|---|---|
| 背景・文字・アイコン・ボーダーの色、状態（hover/press）、強さ | references/color.md | |
| 本文か見出しか、Body / Caption / Heading / Paragraph の選択、字間・字幅 | references/typography.md | |
| 余白、要素間の間隔、コンポーネント内部の padding、タップ領域の大きさ | references/spacing.md | |
| 角丸の大きさ、円形にするかどうか | references/radius.md | |
| 線を引くかどうか、太さ、どの色か | references/border.md | |
| 上の各ガイドラインに無い判断、全体の方針 | references/design-philosophy.md |
読む前に外さないこと
参照を開かずに書き始める場合でも、次は守る。
- 文字色に `#000000` を使わない。 既定は
text.default。 - プライマリーカラーは重要アクションと誘導にだけ使う。 目立たせたいという理由で使わない。
- 警告色はその状態を示すときだけ使う。 強調の手段にしない。
- ボーダーは、無いと理解を妨げるときだけ引く。 まず余白か背景色の差で足りないか試す。
区切り線の既定は border.secondary。
- 余白はレイアウトトークンから選ぶ。 トークンに無い数値を作らない。迷ったら
layout.30。 - 本文の基準は Body（`body.Regular`）。 テキストスタイルは 4 種類しかない。5 種類目を作らない。
- 派手なグラデーション、過剰な線、過剰な装飾を足さない。 コンテンツより UI が目立たない。
トークン名を CSS 変数に直す
ガイドラインはトークンを layout.30 のように書く。CSS 変数の名前はそれとは違う。 推測すると --charcoal-layout-30 のような存在しない名前になり、値は当たらない。
| ガイドライン | CSS 変数 | |
|---|---|---|
layout.30 | --charcoal-space-layout-30 | |
target.m | --charcoal-space-target-m | |
space.30 | --charcoal-space-30 | |
text.default | --charcoal-color-text-default | |
container.primary.default | --charcoal-color-container-primary-default | |
radius.m | --charcoal-radius-m | |
border-width.m | --charcoal-border-width-m | |
Body | --charcoal-text-font-size-body ほか | |
heading.M | --charcoal-text-font-size-heading-m ほか | |
caption.S | --charcoal-text-font-size-caption-s ほか |
規則は --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 で名前を確かめる。無い名前は書かない。
判断の順番
- その値にトークンがあるか。あれば必ずトークンを使う。
- 用途の表で、書こうとしている部品が名指しされているか。されていなければ、近い値を理由に
割り当てない。表が名指ししている用途にだけ使う。
- 状態（hover / press / disabled）が要るか。要る状態にだけ付ける。
- 迷いが残るなら
references/design-philosophy.mdの原則で決める。