コードブロック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行程度のブロックが常時スクロール状態になり不便