decisiondecided

コードブロックUIポリシー

背景

引き継ぎ書で「コードブロックにコピー、ダウンロード、全体表示ボタンを 付ける」という要求があった。しかし業界標準 (VitePress, Docusaurus, GitHub, MDN, Stripe Docs, Zenn) を調査した結果、標準的に実装されて いるのは「コピーボタン」のみであり、ダウンロード・全体表示は 特殊実装の部類に入る。

Parlourite の設計原則「シンプルで手堅い実装パターンを採用する。 可能な限り独自なパターンは実装しない」に照らし、これらの機能を どこまで採用するかを明示的に決定する必要がある。

決定

1. 実装するボタンはコピーのみ

astro-expressive-code (ADR 2026-09-22-rich-content-stack で採用) の 標準コピー機能を利用する。追加実装はしない。

2. ダウンロードボタンは実装しない

以下の理由で不採用:

  • 業界標準のドキュメントサイト・技術ブログでほぼ実装例がない
  • ダウンロード時のファイル名を機械的に決定できない (コードブロックに ファイル名メタ情報がある場合のみ意味を持つが、記述強制はしない方針)
  • ユーザは必要ならコピー → 手元エディタで保存できる

3. 全体表示 (展開) ボタンは実装しない

代わりに max-height によるスクロール制御を採用:

  • コードブロックに max-height: 480px; overflow: auto; を適用
  • 480px を超える長文コードは縦スクロールで参照
  • 展開/折りたたみのトグル UI は不要

4. コードブロックの視覚仕様

astro-expressive-code の標準仕様に準拠:

  • ホバー時に右上にコピーボタン表示
  • コピー成功時のフィードバック (アイコン変化) は標準挙動を使用
  • ファイル名注釈がある場合はフレーム上部にタイトルバー表示
  • 言語ラベルは表示する (右上、コピーボタンの隣)

5. モバイル対応

  • モバイル (<768px) ではコピーボタンを常時表示 (ホバーが機能しないため)
  • 横スクロール: overflow-x: auto (expressive-code 標準)
  • 縦スクロール: max-height: 480px を維持

6. テーマ連動

astro-expressive-code のテーマ設定を Parlourite のパレット (Champagne Silk) に合わせる。具体的なテーマ名は実装時に選定 (github-light / min-light 等が候補)。

理由

  • 業界標準への追従: 「一般があればそれに従う。特殊な実装はしない」 という設計原則の明示的な適用
  • 保守負荷の最小化: ダウンロード・全体表示ボタンの自作は、 ボタン UI、状態管理、a11y 対応、テスト全てで独自コードを増やす
  • UX 上の合理性: コピー機能があれば手元エディタでの操作が可能。 ダウンロード・全体表示の必要性はコピーで代替可能
  • max-height 方式: トグルボタンより実装が単純で、ユーザの スクロール操作は既に習熟した挙動

影響

  • コードブロックの CSS に max-height: 480px; overflow: auto; を追加
  • モバイル用にコピーボタン常時表示のスタイル調整
  • astro-expressive-code のテーマ設定を astro.config.mjs に記述
  • ダウンロード・全体表示ボタンは実装しない (引き継ぎ書の該当要求は 本 ADR で却下として文書化)

代替案(却下)

  • ダウンロードボタン実装: 上記理由で不採用
  • 全体表示トグルボタン: max-height スクロールで十分
  • コピー機能の自作: astro-expressive-code 標準機能で完結
  • max-height なしの全表示: 数百行のコードブロックが縦に伸び、 記事のスクロール性を著しく損なう
  • max-height をより小さく (例: 240px): ADR のコード例など 50-80行程度のブロックが常時スクロール状態になり不便