ADR-0022: コードの色を、セマンティックトークンから生成したテーマで、コードブロック、エディタ、端末に配る¶
Status¶
承認
Context¶
シンタックスハイライトと端末の色を、トークンからどう作るかを決める必要がある。
- コードの色は、記事のコードブロック（Expressive Code と Shiki）、エディタ、端末の 3 つで使う。
- DADS は、シンタックスハイライトの色を決めていない。
- トークンはテーマごとにセマンティックトークンの参照先を替える。
- Shiki はビルドのときに色を解決する。xterm.js と Monaco Editor のテーマは、色の値を受け取り、CSS の変数を読まない。
- 今のサイトは、
tokens.cssの--color-c-*と同じ値をcode-theme.tsに手で写している。
Decision¶
コードの色を、セマンティックトークンのコードの種類に置き、テーマごとに参照先を替える。
生成のスクリプトが、セマンティックトークンをテーマごとに色の値まで解決し、packages/ui/src/tokens/code-theme.gen.json に書き出す。
- Expressive Code、エディタ、端末のテーマは、この JSON から作る。
- CSS の変数を読める描画は、CSS の変数を直に使う。
- 生成物を同じコミットに入れ、CI が
--checkで元のトークンとのずれを見つける。 - 字句の種類は、面と 7 つの字句と、端末の 16 色にする。どの色も、コードの面に対して 4.5:1 以上にし、コントラストのチェックの組に入れる。
- コメントに斜体を、キーワードに太字を重ね、色だけで種類を分けない。
Considered Options¶
| 選択肢 | 強み | 弱み |
|---|---|---|
| 採用: セマンティックトークンから、テーマごとの色の値を JSON に生成する | 値の元が 1 つになる。色の値を求めるエンジンにも渡せる | 生成のスクリプトと、生成物のずれのチェックを持つ |
| 全ての描画で CSS の変数を読む（Shiki の css-variables のテーマ） | 生成物が要らない | xterm.js と Monaco Editor は CSS の変数を読まない。Expressive Code で動くかは未確認 |
| エンジンごとにテーマを手で書く | 仕組みが要らない | 同じ値を 2 か所以上に持ち、片方が古くなっても気づけない |
Consequences¶
Positive¶
- コードの色を変えるときは、セマンティックトークンだけを直せばよい。
- 記事とエディタと端末で、同じ字句が同じ色になる。
Negative¶
- エディタと端末のエンジンを決めたら、JSON から各エンジンのテーマを作る小さな変換を書く。