基礎

ライブラリ全体に共通する概念です。下の 2 つの表がメンタルモデルの すべてで、どのコンポーネントページもこれを前提にしています。

HC の仕組み(6 つの規約)

規約	テンプレートでの意味
セマンティッククラス — hc-<block>__<part>、バリアントは data-variant / data-size	サーバーから意味のあるクラス名を出力します。組み合わせるユーティリティクラスはありません。
状態は HTML 属性に住む — aria-*、data-*、ネイティブの disabled / invalid	属性を変えて再レンダーすれば見た目が追随します。クライアント状態の同期は不要です。
htmx 属性は data-hx-* 形式(hx-* ではなく)	data- 属性を要求するバリデータやテンプレートツールと衝突しません。実行時はどちらの綴りも動きます。
ビヘイビアはネットワークを持たない — htmx が持つ	URL・ルーティング・レスポンスはサーバーコードに残ります。installX() は冪等でアンインストーラを返し、ゼロ設定の /behaviors バンドルが自動インストールします(一覧)。
トークンが見た目の唯一の情報源 — DTCG JSON → 生成される --hc-* カスタムプロパティ	テーマは変数の上書き(またはテーマビルダー)で行い、コンポーネント CSS は編集しません。
文字列は翻訳可能 — ビヘイビアは 1 つのメッセージカタログを読む	setMessages({ 'confirm.cancel': '…' }) で、ビヘイビアが注入する全文字列をカバーします(i18n)。

5 つのランタイム軸

5 つとも <html> の属性です。コンポーネントはライブに再解決します — リビルドも JavaScript も不要です。

軸	値	担当
data-theme	light(デフォルト)/ dark	サーフェス・テキスト・ボーダーの色。
data-color	アクセント名(例: indigo)	プライマリコントロールのアクセント。
data-neutral	グレーランプ名	ニュートラルグレーのファミリー。
data-density	comfortable(デフォルト)/ compact / dense	コントロールの高さ・パディング・ギャップ。
dir	ltr(デフォルト)/ rtl	書字方向 — 全コンポーネントが論理プロパティを使用。

コア概念 — まずこれを読む

ドキュメントの他のすべてのページが前提とする内容を、読み順で:

• 命名規則 — クラス、data 属性、カスタムプロパティ、イベント。
• トークン — あらゆる --hc-* 値の背後にある DTCG トークンレイヤー。
• レイアウトユーティリティ — 本質的にレスポンシブなレイアウトプリミティブ。
• レスポンシブデザイン — コンテナファースト戦略と各ツールの使いどころ。
• 国際化(i18n) — ビヘイビアが注入する文字列を 1 つのメッセージカタログで翻訳。
• アクセシビリティ — CSS システムカラーによる Forced Colors / Windows ハイコントラスト対応。

掘り下げ — トピックが出てきたときに読む

• 印刷 — オプトインの印刷スタイルシート: 紙はレコードを見せ、データはページをまたいで生き残り、インクは正直であり続ける。
• エラーと復旧 — ステータスコードマップ、共有の beforeSwap 許可、二重送信の衛生。
• 監査証跡 — コミットされたすべての変更の背後にある追記専用の「誰が・何を・いつ」契約と、hc-timeline の読み取り側。
• UI コピーの書き方 — アプリが描画する文字列のボイス & トーン: エラー、トースト、確認、空状態。
• モーション — 3 段階のモーションスケール、イージング、そして「そもそも動かすか」のルール。
• アイコン — インライン SVG の方針とサイズ規約。
• アンカー配置 — メニュー・ポップオーバー・ツールチップが共有する配置機構(内部機構。配置のデバッグ時に有用)。
• ブラウザサポート — kit の床(Popover API)を一度だけ明記し、新しい機能のうちスクリプトによるフォールバックを持つもの、見た目だけ劣化するもの、避けているものを整理。

インタラクティブなコンポーネントは小さな JS ビヘイビアに依存します — 全一覧はビヘイビアリファレンス、 インストール方法と冪等性の理由は インストール → ビヘイビアを 参照してください。