fukuemon.dev のデザインシステム¶

この文書は、fukuemon.dev の画面とコンポーネントのコードを書く人が、書く前に読む規則である。
値は fukuemon.dev が決め、アクセシビリティ、タイポグラフィ、配色、レイアウトの指標と参考に、デジタル庁デザインシステム（DADS）を使う。
構成の判断は Design Doc と、ADR-0021、ADR-0022、ADR-0024、ADR-0028、ADR-0062、ADR-0075 にある。

• 出典: デジタル庁デザインシステム
• ADR-0021: packages/ui に Base と Case の React のコンポーネントを置き、packages/ui の Storybook をカタログにする
• ADR-0024: トークンを、fukuemon.dev の値のプリミティブトークン、セマンティックトークン、テーマ変数の 3 つの層にし、生成りの地と旧サイトの差し色で、角丸と影を使わない版面にする
• ADR-0062: コードを動かす画面だけ、文字を 12px と 13px まで、押せる領域を 24×24 CSS px まで小さくする

カタログは https://design.fukuemon.dev で開ける。
ローカルでは、リポジトリのルートで pnpm --filter @fukuemon/ui storybook を流し、http://localhost:6106 を開く。

話題ごとの文書¶

デザインシステムの文書は、この文書と、次の 3 つの文書でできている。
画面とコンポーネントのコードを書く前に、この文書と 3 つの文書を全て読む。 この文書だけを読むと、トークンの使う場面と、コンポーネントの使い方と状態を知らないまま書くことになる。

知りたいことごとの参照先¶

デザインシステムの文書には、使い方の規則だけを書き、値と振る舞いはコードを参照先にする。

元にしたデザインシステムとの関係¶

DADS から外れる規則は、この表に並べず、外れる規則の隣に、DADS が求めることと外れる理由を書いている。

個性として残すもの¶

運営者は、旧サイトの和の感じを残すと決めた（ADR-0024、ADR-0026、ADR-0028、ADR-0075）。
規則の本文は、右の列の文書にある。
残すものと使う場所は次のとおり。

画面を作るときの原則¶

• COLOR-TOKEN: 色、文字、動きは、テーマ変数のユーティリティだけで書く。色の値とプリミティブトークンの名前を、画面のコードに直に書かない。
  • 確認: 色の値とプリミティブトークンの名前は、チェック（pnpm run check:raw-values）で見る。文字、動きの時間と遅れの値は、レビューで見る。アニメーションと緩急の任意値は、MOTION-TOKEN のチェックで見る。
• STATE-NOT-COLOR-ONLY: 状態を色だけで伝えない。エラーと注意には、文と印を色と一緒に出す。
  • 確認: レビューで、色を見分けられない人がエラーの場所と内容を読み取れるかを見る。
• TEXT-MIN-SIZE: 14px より小さい文字を使わない。本文と操作の文字は 16px にし、14px は補足だけに使う。
  • 例外: コードを動かす画面のコンポーネントは、コンソールの値と補足を 12px まで小さくしてよい。コードと操作のラベル、ファイルの木の行、入力欄の値、表のセル、メニューの項目、開閉の中身、空の状態の文、注意の枠の本文、読み込み中の文は 13px まで小さくしてよい。SQL の結果の文（影響した行の数、ページの番号、実行計画のツリーと時間）も 13px まで小さくしてよい。DevTools とコードエディタに近い密度で、多くの行を見渡すためである（ADR-0062、ADR-0067）。
    • 使うトークンは、text-compact、text-label-compact、text-body-compact、text-code-compact の 4 つである。
    • ADR-0062: コードを動かす画面だけ、文字を 12px と 13px まで、押せる領域を 24×24 CSS px まで小さくする
    • ADR-0067: コードを動かす画面の詰めたペインの文字のトークンを 4 つにし、13px の等幅の行高に DADS に無い値を使う
  • 確認: pnpm run check:utilities。4 つのトークンをコードを動かす画面の外で使っていないかは、レビューで見る。
• PRIMARY-ACTION-ONE: 主のボタンは、1 つの画面かダイアログに 1 つまでにする。
  • 確認: レビューで、画面の主の操作が 1 つに決まるかを見る。
• FOCUS-ONE: フォーカスの表示は 1 つのユーティリティ（墨の 2px の 1 重の輪）だけを使い、コンポーネントごとに色や太さを変えない。例外の理由は DesignDoc の「フォーカスの表示」に書いた。
  • 例外: 検索の欄（TextField の appearance="underline"）の緑の罫。
  • 例外: コードを動かす画面の詰めたペインの中の行と、FileTree の名前の欄の、内側に引く輪（focus-ring-inset）。
  • 例外: ペインの全体を占めるスクロールする領域の、外側の要素の ::after に引く内側の輪（focus-ring-frame）。
    • ADR-0066: コードを動かす画面の詰めたペインで、フォーカスの輪を要素の内側に引く
    • ADR-0074: 詰めた木の行の中の名前の欄に内側の輪を引き、欄の行には輪を引かない
  • DADS は、黄色の輪と黒の枠の 2 重の表示を求める。墨の輪にする理由は、DesignDoc の「フォーカスの表示」にある。
  • 確認: pnpm run check:utilities。focus-ring-inset と focus-ring-frame を詰めたペインの外で使っていないかは、レビューで見る。
• TARGET-SIZE: 押せる領域は 44×44 CSS px 以上にする。WCAG 2.2 の AA（2.5.8）の 24×24 より厳しい、AAA（2.5.5）の値を選んでいる。見た目を小さくするときは、見た目の外に押せる領域を広げる。
  • 例外: Link は対象にせず、WCAG 2.2 の AA（2.5.8）の 24×24 CSS px 以上にする。本文の中の文字のリンクを 44×44 CSS px にすると、行の高さが崩れるためである。
    • 文中に置かないリンクのうち、行の中身がリンクの文字だけの一覧のリンクは、isLargeTarget で 44×44 CSS px 以上にする。プレイグラウンドの一覧の、ツールを開くリンクが当たる。
  • 例外: コードを動かす画面のコンポーネントは、WCAG 2.2 の AA（2.5.8）の 24×24 CSS px 以上にする。木の行と開閉の要約（Disclosure）は 24px、ボタン、入力欄、タブは 28〜32px にする（ADR-0062）。
    • ADR-0062: コードを動かす画面だけ、文字を 12px と 13px まで、押せる領域を 24×24 CSS px まで小さくする
    • 触る端末（pointer: coarse）では、コードを動かす画面のコンポーネントも 44×44 CSS px 以上にする。
    • ADR-0071: 触る端末では、コードを動かす画面の押せる領域を 44px にし、iOS と iPadOS の入力時の拡大を viewport の指定で止める
  • 例外: マウスで押す端末の SplitPane の仕切りは、押せる幅を 8px にする。キーボードの矢印のキーで同じ操作ができる。
    • ADR-0073: コードを動かす画面を、地の上に角の丸い紙の面を重ねる見た目にし、面の角を 6〜14px で丸める
  • 確認: pnpm run test:ui の component の project で、コンポーネントごとの、名前に「44 px」を含むテストが見る。コードを動かす画面の例外のコンポーネントでは、名前に「24 px」か「28 px」、仕切りでは「8 px」を含むテストが見る。例は、src/base/Button/Button.test.tsx の「S のボタンは、見た目の外まで 44×44 px 以上を押せる」である。カタログのアクセシビリティの自動チェックは、押せる領域の大きさを確認しない。
• SPACING-SCALE: 余白は、トークンの文書の「レイアウト、区切り、重なり、動き」の表の余白の段のユーティリティだけで書く。任意値（p-[13px] のような書き方）を書かない。
  • 確認: pnpm run check:utilities
  • 入力欄と、その見出し、補足の文、誤りの文の間は、gap-2（8px）以上にする。フォーカスの表示（focus-ring）は、欄の外へ 4px 広がる。狭いと、フォーカスの表示が近くの文字に重なる。
    • 確認: レビューで、欄と近くの文字の間が、その段以上かを見る。
• BODY-WIDTH: 文字の列（記事の本文、シリーズの説明、トップの Profile）の幅は、テーマ変数の --container-body（40rem）のユーティリティの max-w-body で抑える。max-w-prose を書かない。
  • max-w-prose は Tailwind の 65ch で、幅が本文の書体の「0」の幅で決まる。本文は端末に入っている書体で描くので、1 行の字数が端末ごとにずれる。
  • max-w-prose はテーマ変数を読まず、65ch に固定されている。
  • 確認: pnpm run check:utilities
• LAYOUT-OVERFLOW: レイアウトのブレークポイントの幅ごとに、ページの横方向のオーバーフローを出さない。長い文字とデータの多い状態でも出さない。
  • 確認: ページの全体の幅は、pnpm run test:ui の src/screens/Playground.test.tsx の、名前に LAYOUT-OVERFLOW を含むテストで見る。320px、767px、768px、1280px の幅を見る。内側の領域で切れた文字とボタンは、撮った画像をレビューで見る。
• MOTION-TOKEN: アニメーションと緩急は、トークンの文書の「レイアウト、区切り、重なり、動き」の表の動きのユーティリティだけで書く。任意値（animate-[ping_1s_infinite] のような書き方）を書かない。アニメーションの任意値はテーマ変数を通らないので、MOTION-REDUCE の止め方では止まらない。
  • 確認: pnpm run check:utilities
• MOTION-REDUCE: 利用者が OS で動きを減らす設定（prefers-reduced-motion: reduce）にしたときは、位置、大きさ、回転を動かすアニメーションと遷移、スクロールに合わせた動きを止める。残すのは、状態の変化を伝える短い透明度の変化と、機能に欠かせない動きだけにする。今の止め方は、透明度の変化を含めて、時間で進むアニメーションと遷移を全て止める。WCAG 2.2 の AA に無い、AAA（2.3.3）の基準を選んでいる。止め方はテーマ変数のファイル（src/tokens/theme.css）の末尾の 1 か所に置き、画面のコードに設定ごとの条件を書かない。
  • 例外: スクロールに合わせた動きのうち、scroll-fade-end だけは残す。scroll-fade-end は右に続きがあることを知らせる印で、途中の濃さを出さず、右端まで送ったときに一度に消える。
  • 確認: レビューで、テーマ変数のファイルの止め方を見る。
  • 確認: 動きを減らす設定で描画した画面を調べるテストは、packages/e2e/tests/specs/articles/scroll-box-fade.e2e.ts だけである。この spec は記事のページの検証用の原稿を開くので、原稿を消すときは、開く記事を差し替える。
• PLAYGROUND-ONLY: コードを動かす画面だけの面、角丸、高さの条件を、コードを動かす画面と、そのコンポーネントの外で使わない。対象は、surface-ground、surface-pane、surface-pane-subtle、rounded-pane、rounded-sheet、rounded-control-compact、short: である。packages/ui の Base では、density="compact" か size="XS" のときだけ使う。例外として、コードを動かす画面だけで使う PageLoading は、density と size によらず、覆いの面に surface-pane を使う。同じく、コードを動かす画面だけで使う Select は、density によらず、欄の面に surface-pane を使う。
  • ADR-0072: コードを動かす画面を、幅が 48rem 未満か高さが 500px 未満のときに狭い配置にし、高さが 500px 未満ではペインを左の縦のタブで切り替える
  • ADR-0073: コードを動かす画面を、地の上に角の丸い紙の面を重ねる見た目にし、面の角を 6〜14px で丸める
  • 確認: pnpm run check:utilities。使ってよい置き場は、チェックのスクリプトの PLAYGROUND_PATHS に列挙する。Base の中で compact の分岐の外に書いていないかは、レビューで見る。

原則と確認の方法の対応¶

画面を作るときの手順¶

順¶

1. 参照先の表、トークンの文書、コンポーネントの文書、カタログから、使うパターン、コンポーネント、トークンを探す。合うものがなければ、画面のコードで作らず、デザインシステムに足すかを尋ねる。
2. テーマ変数のユーティリティと、このデザインシステムのコンポーネントだけで書く。
3. 使ったコンポーネントの状態のうち、画面で起きるものを作る。
4. 下の「流すコマンド」を、表の順に流す。
5. 描画した画面を、トークンの文書のブレークポイントの幅ごとと、テーマごとに撮り、横方向のオーバーフローを確認する。撮った画像はレビューで見る。
6. チェックが通らなければ直し、手順 4 から流し直す。チェックの出力を見て自分で直すのは、2 回までにする。
   • 2 回直しても通らないか、違反の数が減らないときは、直すのをやめて止まる。最後に全てのチェックが通ったコミットに、通らない変更を混ぜない。通らない変更は、コミットせずに差分として報告に添える。
   • 全てのチェックが通ったコミットが無いときは、作業を始めたときのコミットを代わりにし、そのときに既に通らなかった原則の ID を報告に書く。
7. 下の「報告の形」で報告する。止まったときは、最後に通ったコミットの SHA と、通らないまま残った原則の ID を書く。

流すコマンド¶

受け入れ条件¶

• [ ] 「流すコマンド」が全て終了コード 0 で終わった
• [ ] 「確認の方法」がレビューの原則を、描画した画面で見た
• [ ] 幅とテーマごとに撮った画像を、レビューで見た
• [ ] 使ったコンポーネントの状態が、コンポーネントの文書のそのコンポーネントのセクションと合っている
• [ ] 報告に、5 つの状態のどれでもない原則がない
• [ ] 報告に、対象のコミット、コミットしていない変更の有無、デザインシステムの文書のバージョンがある

報告の形¶

アクセシビリティ¶

ハイコントラスト¶

Windows のハイコントラスト（forced-colors: active）では、ブラウザが背景の色と影（ring を含む）を消し、色をシステムの色に置き換える。 背景の色と ring だけで境界と状態を表す要素は、見分けられなくなる。

直し方は、src/tokens/theme.css の forced-* のユーティリティを、その要素に足すことである。 通常の表示には何も変わらない。

ユーティリティの一覧と使い方は design/tokens.md にある。 システムの色（CanvasText、GrayText、SelectedItem など）は、ブラウザが決める値で、テーマごとに変わらない。そのため、プリミティブトークンを通さず、theme.css の forced-* に直に書く。

• フォーカスの輪は outline なので、ハイコントラストでも残る。focus-ring のユーティリティだけで書く。
• 状態を背景の色か ring だけで表すコンポーネントを足すときは、forced-* を足す。
• 状態の違いは、各コンポーネントの *.forced-colors.test.tsx が、Chromium を forced-colors: active にして確認する。見た目は、Chromium の DevTools の Rendering で forced-colors: active を再現して、カタログの story を開いて見る。

決まっていない選択¶

• カタログのアクセシビリティの自動チェックを、テーマごとに動かすか: 今はデフォルトのテーマ（OS の設定。テストのブラウザではライト）だけで動く。案は、pnpm run test:ui の storybook の project を、ライトとダークの 2 つの条件で流すこと。ダークの組み合わせは pnpm run check:contrast が見ているが、描画した story の違反は見ていないためである。
• LAYOUT-OVERFLOW のテストを、記事の画面とダークのテーマに広げるか: 今は、コードを動かす画面をライトで見るだけである。案は、記事の画面の story にも同じ幅のテストを足すこと。
• 動きを減らす設定で、状態の変化を伝える短い透明度の変化を残すか: MOTION-REDUCE は残してよいとしているが、今の止め方は透明度の変化も止める。案は、今のまま全てを止めること。残したい動きが出たときに、止め方の例外として足す。