コンテンツにスキップ
Hypermedia Components

テーマビルダー

ブランドカラーを 1 つ選ぶと、このビルダーが data-color アクセント セットの残り — ホバーシェード、ソフトティント、primary 上のテキスト色 — を導出し、WCAG コントラストを検査し、すぐ使えるエクスポートを生成します。

モードは 2 つ:

  • アクセント — 新しい [data-color="<name>"] 軸を追加します (オプトインで、組み込みの 5 つと並存)。変わるのはアクセントだけです。
  • フルテーマ — デフォルトの見た目をカスタマイズします: アクセント に加えて、ニュートラルランプ(gray / slate / zinc / neutral / stone。surface / text / border / secondary を駆動)、コントロールの 角丸、タイポグラフィ(body / heading / mono の font-family)を、 ライトとダークの両方にわたって。出力はテーマ適用ビルドと素のビルドの 差分として計算されるため、変わった変数だけが — それ以上は何も — 含まれます。

仕組みは、実物のトークントランスフォーマー (@hypermedia-components/core/token-transform)を実物の DTCG ソースに対してブラウザ内で実行することです。プレビュー、 Apply to this page ボタン、すべてのエクスポートは、ライブラリのビルドが 使うのと同じ buildTokensCss で生成されます — つまりカスタムテーマは 組み込みテーマとまったく同じに振る舞い(影響するすべてのコンポーネント 変数、サブツリー安全)、「DTCG ソース → 生成 CSS 変数」というモデルが 迂回されることはありません。

In OKLCH —
ActiveNeutral
Saved

Semantic status colors (success / warning / error) stay fixed — the accent doesn't touch them.

Heading sample

Body text on this ramp — press ⌘K (mono). Select me for ::selection.

Scoped to this box and rendered by the real token build. Toggle the site's light/dark switch to check both. Apply to this page themes the whole site.

Additive — keep the stock CSS and load this after it. No build.

導出の仕組み

Section titled “導出の仕組み”

すべて OKLCH で導出されます。しかもライブラリ自身のランプを生成している のと同じラダーを使うため、ここで作ったテーマは組み込みの 5 アクセントと まったく同じ組み立て方になります。

出力導出
action-primary-bg / border選んだブランドカラーそのまま(oklch() で書き直したもの)。
action-primary-hover-bg / borderブランドカラーを、色相と彩度を保ったまま Hover darkness の分だけ明度を下げたもの。デフォルトの 7 は組み込みランプの 600 と 700 の差です。
action-primary-fgAuto は明度のしきい値を適用します — 0.55 以下なら白、それ以外は gray.900。好みに応じて手動で上書きできます。
action-primary-soft-bgcolor-mix(in oklab, <brand> N%, transparent) — ライトとダークどちらの面でも正しくブレンドされる 1 つの値。
focus-ringデフォルトはブランドカラー。

以前のビルダーは sRGB のチャンネルを掛け算して暗くし、前景色はコントラスト 探索で選んでいました。どちらも廃止しました。sRGB での暗色化は暖色を寒色より 速く沈ませるため、同じ「12%」でもブランドごとに知覚的な段差が変わって しまいます。明度差ならそれが起きません。前景色も探索が不要になりました — OKLCH の明度を固定するとコントラスト比は色相にも彩度にもほとんど依存せず、 交差点が定数になるため、単なる比較で済みます。

ラダーにスナップ

Section titled “ラダーにスナップ”

In OKLCH の表示は、ブランドカラーが OKLCH のどこにあり、その色相の ラダーのステップ 600 からどれだけ離れているかを示します。Snap to ladder はそれをそのステップに置き換えます — 同じ色相に対して組み込み軸が 使うのとまったく同じ色で、構成上、白文字で AA を満たします。

スナップは任意です。通常はブランドの忠実さが優先ですし、コントラスト表示を 満たす色ならそれで問題ありません。色を「合わせる」のではなく「選ぶ」ときの ための機能です。なお Shuffle はランダムな色相をラダーに通すように なったため、シャッフルしたテーマは常に AA を満たします。

コントラスト表示は、ブランドカラーと解決されたテキスト色の間の WCAG 2.x 比です。4.5 : 1(AA)以上を目指してください。それを下回ると バッジが赤くなります。失敗する場合、ブランドカラーの明度が 0.62 付近の 「白文字も暗い文字も AA に届かない」帯に入っています。スナップするか、 明度をその帯から離せば解消します。

3 つのエクスポート

Section titled “3 つのエクスポート”

ビルダーは、あなたの色を合成 color.<name> ソースとして注入した buildTokensCss を実行し、出力を 3 つの形で渡します:

  1. テーマ CSS ブロック — このテーマの [data-color="<name>"] ブロックだけ(影響するすべてのコンポーネント変数、解決済み)。 追加的です: 素のトークン CSS を保ったままこれを後に読み込み、 data-color="<name>" を設定します。ビルド不要。これが正しい パス Aです — 7 つの semantic 変数を手で上書きするやり方は動きません (カスケードの実際の動き(重要)を参照)。

  2. DTCG トークンファイル — color.<name>.tokens.json。 packages/core/src/tokens/ 配下に保存して build-tokens.mjs に 登録すれば、テーマをビルドに同梱できます (パス B)。 外部の DTCG ツーリング(Style Dictionary、Figma)にも渡せます。

  3. 完全なトークン CSS — 完全な hc.tokens.css(すべての組み込み テーマに加えてあなたのテーマ)。ブロックを足すよりファイルごと 差し替えたい場合の、素のトークンスタイルシートのドロップイン代替です。

4 つ目のタブ Email templates は、同じ解決済みトークンをテーブル+ インラインスタイルの HTML メール断片(Thymeleaf / プレーン HTML フレーバー)に焼き込み、ライブプレビュー付きで提供します — HTML メールガイドを 参照してください。

Apply to this page は生成されたブロックを docs サイトの <html> に 注入し、あなたのテーマの下で全コンポーネントを閲覧できるようにします。 Reset で解除します。

関連

Section titled “関連”