コードブロックUIシステム は何をしますか？
目的
コードブロックUIシステムは、ソースコードスニペット、APIリクエスト/レスポンスペイロード、複数ファイルコード例、ターミナルコマンドライン、コード差分比較を表示するための、標準化されたアクセシブルで可読性の高いレイアウトフレームワークを提供します。コードブロックは、技術文書、開発ツールマーケティングサイト、APIポータル、エンジニアリングブログ、SaaSプラットフォームにおいて重要なインタラクションコンポーネントです。
効果的なコードインターフェースを設計するには、モノスペースタイポグラフィの可読性、ライトテーマとダークテーマでの高コントラストな構文トークンハイライト、スティッキーヘッダーアクションツールバー（言語バッジ、タブ付きファイルナビゲーション、コピー・トゥ・クリップボードトリガー）、行番号、行レベルのハイライト/フォーカス、折り返しと水平スクロールの動作、アクセシブルなスクリーンリーダー体験のバランスを取る必要があります。このスキルは、コードUIプレゼンテーションのための空間ルール、トークンカラーコントラスト基準、インタラクションメカニクス、WCAG AA準拠ガイドラインを確立します。
ユースケース
- 開発者向けドキュメント & APIリファレンスポータル: 複数言語のSDK例（例：cURL、Node.js、Python、Go、Rust）とAPIレスポンスを表示する。
- 開発ツールランディングページ: ヒーローコードスニペット、CLIインストールコマンド、インタラクティブなプロダクトデモブロックを紹介する。
- エンジニアリングブログ & チュートリアル: 特定の行のコールアウト、ステップバイステップのコードハイライト、インライン注釈を含むインラインおよびブロックコード例をレンダリングする。
- バージョン管理 & コードレビューインターフェース: コード差分（
+追加、-削除）、インラインコメント、コミットスニペットを表示する。 - コードプレイグラウンド & スニペット共有ツール: 複数タブのファイルエディタ、プレビューペイン、埋め込み可能なスニペットカードを構造化する。
使用すべきでないケース
- フルブラウザ内コードエディター（IDE）: キャンバスレンダリング、仮想化ASTツリー、マルチカーソル編集、言語サーバープロトコル（LSP）統合を必要とする複雑なインタラクティブWeb IDE（例：Monaco Editor、CodeMirror）には、専用のエディター実装を使用してください。
- 一般的なフォームテキスト入力: シンタックスハイライトや行番号のない複数行プレーンテキストフィールドには、
form-design-systemを使用してください。 - インラインテキストコードバッジ: 散文段落内の短い単一単語のコード参照（例：
npm install）には、article-layout-system内でインライン<code>スタイルを使用してください。 - 構造化データテーブル: 行と列としてフォーマットされた表形式のキー値データやデータベースクエリには、
data-table-ui-systemまたはproperty-and-attribute-systemを使用してください。
入力
- コード内容 & 構文タイプ: 言語の分類（例：TypeScript、JSON、Bash、YAML、GraphQL、SQL）と構造的特徴（単一ファイル、複数ファイルタブ、差分）。
- テーマコンテキスト: ライトモードおよびダークモードにおける、サーフェス背景、ボーダー、構文トークンに対するアクティブなカラーパレットトークン（
accessible-color-systemおよびdark-theme-design-systemより）。 - モノスペースタイポグラフィトークン: 推奨フォントスタック（例：
ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace）、フォントサイズ、行の高さ（fluid-typography-systemより）。 - アクショントリガー: ブロックごとに必要な特定のインタラクティブ機能（例：1クリックコピーボタン、行番号トグル、ワードラップトグル、全画面表示、外部サンドボックスリンク）。
出力
- コードコンテナ & ヘッダーツールバー仕様: コードブロックコンテナ、スティッキーヘッダーバー、言語インジケーター、ファイルパスタブ、アクションボタングループのための空間レイアウト。
- アクセシブルな構文トークンカラーパレット: ライトテーマとダークテーマにおける、キーワード、文字列、関数、変数、コメント、演算子、型に対するWCAG AA（最小4.5:1コントラスト比）トークンカラーマッピング。
- 行レベルの階層 & 注釈システム: 行番号、行ハイライト/フォーカスオーバーレイ、差分インジケーター（
+/-）、行レベルのアンカーリンクのための設計図。 - アクセシブルなスクリーンリーダー & キーボードナビゲーションモデル: ARIAロール属性、キーボードフォーカルート、行番号マスキング（
aria-hidden="true"）、aria-liveコピーステータス通知。 - レスポンシブオーバーフロー & スクロール戦略: 水平スクロールバー、スティッキーアクションツールバー、ワードラッピングトグル、モバイルビューポート適応のためのルール。
ワークフロー
1. コードブロックシェル & ヘッダーバーの構造化
コンテナとヘッダーアクションバーを統一されたまとまりのあるユニットとして設計します。
- コンテナアーキテクチャ: 角丸のコンテナを設定します（
border-radius: 8px; border: 1px solid var(--border-subtle); overflow: hidden; background: var(--surface-code);）。明確なサーフェス背景を使用します（通常デフォルトではダークモード、またはテーマサーフェスに一致）。 - ヘッダーツールバーレイアウト: スティッキーな上部ヘッダーバーをレンダリングします（
display: flex; align-items: center; justify-content: space-between; padding: 8px 16px; background: var(--surface-code-header); border-bottom: 1px solid var(--border-subtle);）。 - ヘッダー左セクション（タブ & メタデータ）:
- 単一ファイル: ファイルパス/名前（例：
src/auth/jwt.ts）を控えめなファイルタイプアイコンと共に、または大文字の言語バッジ（例：TYPESCRIPT）を表示します。 - 複数ファイル / 複数言語: タブ付きボタンをレンダリングします（
role="tablist"）。アクティブなタブは、ハイコントラストなテキストと下部ボーダー/ピルインジケーター（border-bottom: 2px solid var(--brand-primary)）を備えます。
- 単一ファイル: ファイルパス/名前（例：
- ヘッダー右セクション（アクション）: ユーティリティアクショントリガーをグループ化します。
- コピーボタン: 32x32pxのアイコンボタン（
aria-label="コードをクリップボードにコピー"）で、明確なコピーアイコンと、より広いビューポートではラベルを備えます。 - 折り返し / スクロールトグル（オプション）: ソフトラッピング（
white-space: pre-wrap）と水平スクロール（white-space: pre）を切り替えるアイコンボタン。 - 展開 / サンドボックスリンク（オプション）: StackBlitz、CodeSandbox、または全画面でスニペットを開くトリガー。
- コピーボタン: 32x32pxのアイコンボタン（
2. モノスペースタイポグラフィ & レイアウトグリッドの確立
技術的な読み取りとコードスキャンに最適な可読性を確保します。
- フォントスタック: クリーンで可読性の高いモノスペースフォントスタックを定義します。
ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace。フォント機能設定により、0（ゼロ）とO（大文字オー）、および1（イチ）、l（小文字エル）、I（大文字アイ）の明確な区別を確保します。 - フォントサイズ & 行高:
font-size: 0.875rem（14px）と、余裕のある行高（line-height: 1.6/ 22.4px）を設定します。コードの括弧や演算子が衝突する原因となる、タイトな行高は避けます。 - コード本文コンテナ:
<pre class="code-block"><code class="language-typescript">をdisplay: block; overflow-x: auto; padding: 16px 0; margin: 0; font-family: var(--font-mono);と共に使用します。
3. 行番号、行ハイライト、差分の設計
コピー＆ペーストやスクリーンリーダーの動作を損なわずに行レベルの要素を構造化します。
- 行構造: 各行を個別のブロックコンテナとしてフォーマットします（
display: table-row;またはdisplay: flex; width: 100%;）。 - 行番号: 行番号を左側のガターにレンダリングします（
display: table-cell; text-align: right; width: 40px; padding-right: 16px; user-select: none; color: var(--text-code-muted);）。- アクセシビリティルール: 行番号を
<span aria-hidden="true">で囲むか、CSSカウンターコンテンツ（content: counter(line)）を使用して、テキスト選択時に行番号がコピーされず、スクリーンリーダーがコードステートメント間で読み上げないようにします。
- アクセシビリティルール: 行番号を
- ハイライト / フォーカス行: チュートリアルや差分でキーとなる行に注目を集めるには。
- 明示的な行ハイライト背景を適用します（
background: var(--surface-code-highlight); border-left: 3px solid var(--brand-primary);）。 - ハイライトオーバーレイがコードコンテナのスクロール可能な幅全体に及ぶことを確認します（
min-width: 100%）。
- 明示的な行ハイライト背景を適用します（
- 差分ビュー行（
+追加 /-削除）:- 追加行: 微妙な緑色の背景（
background: rgba(34, 197, 94, 0.15); border-left: 3px solid var(--color-success);）。ガターに+記号を、スクリーンリーダー用に<span class="sr-only">追加:</span>で囲んで表示します。 - 削除行: 微妙な赤色の背景（
background: rgba(239, 68, 68, 0.15); border-left: 3px solid var(--color-danger);）。ガターに-記号を、スクリーンリーダー用に<span class="sr-only">削除:</span>で囲んで表示します。
- 追加行: 微妙な緑色の背景（
4. アクセシブルな構文トークンカラーパレットの作成
構文トークンは、コードブロックの背景（var(--surface-code)）に対してWCAG AAのコントラスト比（最小 4.5:1）を満たす必要があります。
- ベーステキスト / 変数: ニュートラルライト（例：
#0F172A背景上で#E2E8F0、比率 ~12.5:1）。 - キーワード（
const、import、return、async）: 鮮やかなパープル/マゼンタ（例：#C084FC、比率 ~7.2:1）。 - 関数 & メソッド（
fetchData、useState）: 明るいブルー/シアン（例：#38BDF8、比率 ~8.5:1）。 - 文字列（
"https://api.example.com"）: 柔らかなグリーン/エメラルド（例：#4ADE80、比率 ~9.1:1）。 - 数字 & ブーリアン（
404、true）: 暖かいオレンジ/アンバー（例：#FB923C、比率 ~7.8:1）。 - コメント（
// トークンレスポンスを処理）: WCAG AA準拠の落ち着いたクールグレー（例：#94A3B8、比率 ~5.1:1）。コメントに低コントラストのグレー（例：2:1）は決して使用しないでください。 - 演算子 & 句読点（
=>、{、}、;）: ミディアムニュートラル（例：#CBD5E1、比率 ~10.2:1）。
5. コピー・トゥ・クリップボード & アクションフィードバック状態の構築
コピーアクションに即時フィードバックを提供することで、重複クリックやユーザーの不満を防ぎます。
- デフォルト状態: コピーアイコン（重なり合う2つの長方形）とオプションのラベル（「コピー」）を備えたアイコンボタンを表示します。
- ホバー / フォーカス状態: 隆起したサーフェス背景またはボーダーハイライト（
background: var(--surface-hover); outline: 2px solid var(--focus-ring)）。 - アクティブ / 成功状態: クリックすると、アイコンをチェックマークアイコンに変更し、ボタンラベルを「コピーしました！」に更新し、成功色のティントを適用します（
color: var(--color-success)）。 - スクリーンリーダー通知: 不可視の
aria-live="polite"リージョンを介して、コピーステータスを動的に通知します：「コードをクリップボードにコピーしました」。 - タイムアウトリセット: 2000ms後にボタンをデフォルト状態にリセットします。
6. モバイル & レスポンシブ適応
長いコードスニペットが小さなビューポートでも機能し続けることを保証します。
- 水平スクロールコンテインメント: モバイルで長い行に対し、ページレベルの水平スクロールバーオーバーフローを引き起こさずに、水平スクロール（
overflow-x: auto）を許可します。 - スティッキーヘッダーツールバー: ヘッダーツールバーを固定（
position: sticky; top: 0; z-index: 10;）して、100行以上のコードをスクロールする場合でも、コピーボタンとアクティブなファイルタブがアクセス可能な状態を維持します。 - モバイルタップターゲット: コピーボタン、折り返しトグル、複数ファイルタブが、タッチデバイスで最小 44x44px のタップターゲットを満たすことを確認します。
決定ルール
構文トークンコントラスト & テーマモード
| 構文カテゴリ | 推奨トークンロール | ライトテーマカラー（#F8FAFC 上） | ダークテーマカラー（#0F172A 上） | 最小コントラスト比 |
|---|---|---|---|---|
| キーワード | --token-keyword | ディープバイオレット（#6B21A8） | ブライトバイオレット（#C084FC） | ≥ 4.5:1 |
| 関数 | --token-function | ダークシアン（#0369A1） | スカイブルー（#38BDF8） | ≥ 4.5:1 |
| 文字列 | --token-string | フォレストグリーン（#15803D） | ブライトエメラルド（#4ADE80） | ≥ 4.5:1 |
| 数字 / ブーリアン | --token-number | ダークアンバー（#C2410C） | ブライトアンバー（#FB923C） | ≥ 4.5:1 |
| コメント | --token-comment | ミュートスレート（#475569） | ソフトスレート（#94A3B8） | ≥ 4.5:1 |
| ベース / 変数 | --token-base | チャコール（#0F172A） | クリスプライト（#F8FAFC） | ≥ 7.0:1 |
折り返し vs. 水平スクロール戦略
- 水平スクロール（
white-space: pre）（デフォルト推奨）: コードレイアウトの完全性、インデントの整列、複数行のフォーマットを保持します。インデントが意味構造を伝えるPython、YAML、コード差分に不可欠です。 - ソフトワードラップ（
white-space: pre-wrap）（オプションモード）: 長いターミナル出力文字列、コマンドラインの例、または水平スクロールが読書の流れを妨げる狭いサイドバーウィジェットに推奨されます。
制約事項
- アクセシビリティ（WCAG 2.1 AA）:
- SC 1.4.3 コントラスト（最小）: すべてのシンタックスハイライトトークンカラーとコメントは、コード背景に対して最小コントラスト比 4.5:1 を達成する必要があります。
- SC 2.1.1 キーボード: ユーザーは
TabキーとSpace/Enterキーを使用して、コードブロックヘッダーボタン（タブ、コピーボタン）にナビゲートし、アクティブ化できる必要があります。 - SC 4.1.3 ステータスメッセージ: コピーボタンのフィードバックは、
aria-live="polite"リージョンを介して支援技術に通知する必要があります。 - SC 1.3.1 情報と関係: 行番号は、読み取り中に数字が散在するのを避けるために、スクリーンリーダーから隠す必要があります（
aria-hidden="true"またはCSSカウンター）。
- テキスト選択 & コピー: コードブロック内のテキストを選択しても、行番号や差分マーカー（
+/-）がクリップボードバッファに選択されることは決してあってはなりません。 - レイアウトシフトの防止: 複数ファイルタブの展開や行の折り返しの切り替えは、累積レイアウトシフト（CLS）を防ぐために、固定行高またはコンテナ境界を指定する必要があります。
一般的な障害パターン
- 読み取り不能な低コントラストコメント: コメントは重要ではないと仮定して、薄いグレーのテキスト（例：
#1A202C上で#4A5568、2.8:1コントラスト）を使用し、WCAG AAガイドラインに違反する。 - 行番号のコピー: 行番号を
<pre>内の生のテキストとしてレンダリングし、コピー＆ペースト時に1 2 3 4が先頭に付いた無効なコードスニペットが生成される。 - 通知されないコピーアクション:
aria-labelを更新したりaria-live通知を送信したりせずにコピーボタンの視覚的アイコンを変更し、スクリーンリーダーユーザーにアクションが成功したかどうかを不明確なままにする。 - ページレベルオーバーフロースピル:
<pre>にmax-width: 100%とoverflow-x: autoを設定せず、120文字のコード行がモバイル画面でページレイアウトをはみ出してしまう。 - 水平スクロール内のアクセスできないフォーカストラップ: スクロール可能なコードブロックに
tabindex="0"を設定するが、明確なキーボード視覚的輪郭インジケーターがなく、キーボードユーザーが長いコードブロック内に閉じ込められてしまう。
検証基準
- コードブロックは、言語、ファイルパス、およびコピー/ラップアクションを表示するスティッキーヘッダーツールバーを備えた構造化コンテナを備えている。
- すべての構文ハイライトトークンとコメントは、コード背景に対して4.5:1以上のコントラスト比を持っている。
- 行番号はテキスト選択から除外され、スクリーンリーダーに公開されない。
- コピーボタンは、ARIAライブリージョンを介して成功/失敗の視覚的およびスクリーンリーダーフィードバックを提供する。
- コードブロックはモバイルで水平スクロールを許可し、ページレイアウトからはみ出さない。
- コードブロック内のすべてのインタラクティブ要素は、キーボードでフォーカス可能でアクティブ化可能である。
- 差分マーカー（
+/-）はコピーバッファから除外される。 - タブ切り替えにより、コードコンテンツがCLSなしで置き換えられる。
- マルチファイルタブとコピーボタンは、モバイルで44x44pxの最小タップターゲットを満たしている。