Pixel HUD UI は何をしますか？
単なるカラーテーマではなく、UIフレームワークです。3つのレイヤーがあり、良い結果を得るにはすべてを使用します：
- 基礎：4pxグリッド、12pxピクセルフェースに調整されたタイプスケール、カラーの役割（各色は1つの意味を持つ）、影の代わりとなる1pxルール、段階的モーション。
- コントロール：パネルとタイトルバー、インテントを持つキー（ボタン）、アイコンキー、タブ、セグメントコントロール、リスト行、フォームフィールド、入力、セレクト、正方形チェックボックスとラジオボタン、ランプスイッチ、ゲージスライダー、プログレスゲージ、ランプ、タグ、バッジ、キーキャップ、メニュー、ツールチップ、ダイアログ、トースト、テーブル、コードブロック、散文、ローダー、空の状態。各コントロールは固定サイズと1つの共有状態モデル（ホバー、プレス、フォーカス、選択、無効、ローディング、エラー）を持ちます。
- パレット：
--hud-*トークンにより、フレームワークは任意の色（アプリ独自のブランドカラーを含む）の上に配置できます。
ファイル
| ファイル | 説明 |
|---|---|
references/design-system.md | 仕様書。 原則、基礎、およびすべてのコントロールの構造、サイズ、状態、使用すべきタイミング、アクセシビリティ。設計前に読んでください。 |
assets/pixel-hud.css | 実装：トークン、[data-skin="pixel"] 下のライトグローバル、および hud-* コントロールクラス |
assets/palettes.css | starward（深宇宙、ダーク）、terminal（グレーグリーン、ダーク）、paper（暖かい砂色、ライト） |
assets/fonts.css | Fusion Pixel 12px（OFL）、jsDelivrに固定。または @fontsource 経由でセルフホスト |
assets/pixel-caret.js | テキストフィールド用のオプションの3pxブロックキャレット（data-pixel-caret） |
assets/demo.html | すべての状態の全コントロールとパレットスイッチャー：視覚的リファレンス |
references/integration.md | スタックごとのレシピ：アプリの色のマッピング、Tailwind、shadcn/ui、React/Next、Vue、スコーピング、フラッシュ防止トグル、セルフホストフォント |
scripts/check-contrast.mjs | 任意のパレットのWCAGチェック：node scripts/check-contrast.mjs my.css |
ワークフロー
1. 仕様書とデモを読む
references/design-system.md（少なくとも原則、基礎、およびタスクに必要なコントロール）を読み、assets/demo.html を見てください。仕様書には各コントロールがなぜそのような見た目になっているかの理由が書かれています。それに従うことが、画面を「ピクセルフォントのダークテーマ」ではなく、このフレームワークとして認識させるために重要です。
2. プロジェクトを確認する
何かをコピーする前に、以下を確認してください：
- スタックとグローバルCSSの読み込み場所（レイアウトファイル、
main.ts、index.html、Tailwindエントリ） - 現在の色の定義方法（CSSカスタムプロパティ、Tailwindテーマ、shadcnのHSL変数、コンポーネント内の16進数）
- 新しいUIかリスタイルか、アプリの唯一の見た目か切替可能なテーマか、ページ全体か一部か
これらがカラーマッピング（ステップ4）を決定し、アプリのスタイルとの競合を防ぎます。
3. キットを追加する
pixel-hud.css、fonts.css、palettes.css（バンドルされたパレットを使用する場合）、および pixel-caret.js（アプリにテキスト入力がある場合）をプロジェクトにコピーします。読み込み順序：fonts → palettes → pixel-hud.css、アプリの基本スタイルの後に配置します。
4. 色を選ぶ
- バンドルパレット：
data-hud-palette="starward" | "terminal" | "paper" - アプリ独自の色：1つのブロックで変数を
--hud-*にマッピング（references/integration.md› アプリの色のマッピング）。ブランドは維持し、フレームワークを追加します。 - 新しいパレット：仕様書の「新建一套配色」に従います。
その後、作成またはマッピングしたパレットに対して node scripts/check-contrast.mjs <file> を実行し、すべてのFAILを修正します。コントロールは、バー、テキスト、および緑色がすべてのサーフェスで読みやすいことに依存しています。
5. 有効にする
<html data-skin="pixel" data-hud-palette="starward">
切替可能なテーマの場合は、最初の描画前にこれらを設定します（references/integration.md › フラッシュ防止トグル）。1つのエリアのみにスタイルを適用するには、両方の属性をそのコンテナに設定します。
6. コントロールで構築する
グローバル設定はすでに、タイポグラフィ、正方形の角、ネイティブ入力、セレクト、レンジスライダー、チェックボックス、スクロールバー、フォーカスリング、選択、スキャンラインを処理します。各要素にクラスで役割を与え、サイズと状態の仕様に従います：
| 必要なもの | コントロール（クラス） |
|---|---|
| 関連情報のグループ化 | .hud-panel + .hud-titlebar（+ .hud-titlebar__actions）、本文 .hud-panel__body、セクション .hud-subhead |
| メインアクション | .hud-btn.is-solid（インテント：accent、go、warn、info、danger） |
| セカンダリアクション | .hud-btn |
| アイコンのみのアクション | .hud-icon-btn + aria-label |
| ビューの切り替え | .hud-tabs > .hud-tab[aria-selected] |
| 2～5個の値から1つを選択 | .hud-segmented > button[aria-pressed] |
| ナビゲーション可能なリスト | .hud-row[aria-current] |
| ラベル付き入力 | .hud-field > .hud-label + input/select + .hud-help / .hud-error |
| ドロップダウン | .hud-select > select |
| はい/いいえ、複数から1つ | .hud-check、.hud-radio（正方形のマーク） |
| 即時オン/オフ | button.hud-switch[role=switch][aria-checked] > .hud-switch__knob |
| レベル / 進捗 | .hud-gauge + --value（data-state warn/alert） |
| ステータス | .hud-lamp[data-state] |
| 値、ID、パラメータ | .hud-tag；カウント .hud-badge；キー kbd |
| メニュー、ヒント、モーダル、フィードバック | .hud-menu、.hud-tooltip、.hud-backdrop > .hud-dialog、.hud-toasts > .hud-toast |
| データ、コード、記事 | table.hud-table、.hud-code、.hud-prose |
| コマンド / チャット入力 | .hud-input + data-pixel-caret |
| 待機中、表示するものなし | .hud-loader、キーの aria-busy、.hud-empty |
クラスはコンポーネントソース（JSX、テンプレート）に配置し、コンポーネントライブラリの className/class プロップを介して渡します。フレームワーク内部に対するセレクタを記述するのではありません。リファクタリングに耐え、明確に読み取れます。
既存のアプリをリスタイルする場合は、まず既存の各コンポーネントを上記のテーブルにマッピングし（返信に短いリストを含めるとユーザーが追跡しやすくなります）、その後適用します。
7. 結果を確認する
- ページのスクリーンショットを撮る（または開く）か、
assets/demo.htmlと比較します。 - ピクセルフォントが読み込まれたことを確認します（
document.fonts、Networkタブ）。CSPがjsDelivrをブロックしている場合はセルフホストします。 - Tabキーで移動：すべてのコントロールにフォーカスが当たり、1pxの緑色のフォーカスリングが表示されることを確認します。
- 主要なコントロールで状態モデルを確認：ホバー、プレス、無効、ローディング、エラー。
- 使用中のパレットでコントラストスクリプトが合格すること。
最も重要なルール
仕様書に完全な理由が記載されています。これらは最も頻繁に破られるルールです：
- 正方形でフラット。 半径なし、ぼかし影なし、スキャンライン以外のグラデーションなし。オーバーレイのみがハードオフセットシャドウを持つ。
- 色はそれぞれの役割を守る。 バー＝構造と選択；緑＝オン、強調、フォーカス；黄色＝値；オレンジ＝注意と警告；赤＝危険。緑を装飾に使うと「オン」の意味が失われる。
- 選択＝反転。 バーの塗りつぶしに暗いテキスト；行には3pxの緑のエッジを追加。バー色の背景では、ホバーは逆方向に反転する。
- 1つのエリアに1つのソリッドメインアクション；横に並んだアクションはそれぞれ独自のインテント色を持ち、無効時もその色を維持する（フェードアウト、アウトライン化しない）。
- タイトルバーはパネルだけ。 テーブルとコードのヘッダーはソフトな色合い
--hud-bar-softを使用する。 - サイズはスケールから来る：コントロールは24/28/32px、間隔は4pxグリッド、テキストは12/14/16/24/36px。
落とし穴
- フレームワークはスコープ内で
border-radius: 0 !importantを強制します。丸いものを維持する（アバターなど）には、スキンをその要素を除外するコンテナにスコープします。 color-mix()はChrome/Edge 111、Safari 16.2、Firefox 113が必要です。古いブラウザでは--hud-bar-soft/--hud-bar-lineをプレーンな色に設定します。displayを設定するクラスはhidden要素を表示します。フレームワークはスコープ内で[hidden]を再び非表示にするため、トグルにはhidden属性を優先的に使用します。- コードからフィールドの値を設定するフレームワークは
inputイベントを発火しません。そのような変更後、キャレットをすぐに移動する必要がある場合はfield.__pixelCaret.update()を呼び出します。 - スキャンラインは非常に高いz-indexにあり、
pointer-events: noneです。邪魔になる場所（スクリーンショット、キャンバスアプリ）ではdata-hud-scanlines="off"でオフにします。