基礎
ライブラリ全体に共通する概念です。下の 2 つの表がメンタルモデルの すべてで、どのコンポーネントページもこれを前提にしています。
HC の仕組み(6 つの規約)
Section titled “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 つのランタイム軸
Section titled “5 つのランタイム軸”5 つとも <html> の属性です。コンポーネントはライブに再解決します —
リビルドも JavaScript も不要です。
| 軸 | 値 | 担当 |
|---|---|---|
data-theme | light(デフォルト)/ dark | サーフェス・テキスト・ボーダーの色。 |
data-color | アクセント名(例: indigo) | プライマリコントロールのアクセント。 |
data-neutral | グレーランプ名 | ニュートラルグレーのファミリー。 |
data-density | comfortable(デフォルト)/ compact / dense | コントロールの高さ・パディング・ギャップ。 |
dir | ltr(デフォルト)/ rtl | 書字方向 — 全コンポーネントが論理プロパティを使用。 |
コア概念 — まずこれを読む
Section titled “コア概念 — まずこれを読む”ドキュメントの他のすべてのページが前提とする内容を、読み順で:
- 命名規則 — クラス、data 属性、カスタムプロパティ、イベント。
- トークン — あらゆる
--hc-*値の背後にある DTCG トークンレイヤー。 - レイアウトユーティリティ — 本質的にレスポンシブなレイアウトプリミティブ。
- レスポンシブデザイン — コンテナファースト戦略と各ツールの使いどころ。
- 国際化(i18n) — ビヘイビアが注入する文字列を 1 つのメッセージカタログで翻訳。
- アクセシビリティ — CSS システムカラーによる Forced Colors / Windows ハイコントラスト対応。
掘り下げ — トピックが出てきたときに読む
Section titled “掘り下げ — トピックが出てきたときに読む”- 印刷 — オプトインの印刷スタイルシート: 紙はレコードを見せ、データはページをまたいで生き残り、インクは正直であり続ける。
- エラーと復旧 — ステータスコードマップ、共有の beforeSwap 許可、二重送信の衛生。
- 監査証跡 — コミットされたすべての変更の背後にある追記専用の「誰が・何を・いつ」契約と、hc-timeline の読み取り側。
- UI コピーの書き方 — アプリが描画する文字列のボイス & トーン: エラー、トースト、確認、空状態。
- モーション — 3 段階のモーションスケール、イージング、そして「そもそも動かすか」のルール。
- アイコン — インライン SVG の方針とサイズ規約。
- アンカー配置 — メニュー・ポップオーバー・ツールチップが共有する配置機構(内部機構。配置のデバッグ時に有用)。
インタラクティブなコンポーネントは小さな JS ビヘイビアに依存します — 全一覧はビヘイビアリファレンス、 インストール方法と冪等性の理由は インストール → ビヘイビアを 参照してください。