フロントエンドトークンの定義

Liferay DXP/Portal 7.3以降

スタイルブックの視覚的なルールは、カテゴリーごとにグループ化された選択肢で構成されています。 例えば、「ボタン」カテゴリには「背景色」というオプションがある場合があります。

スタイルブック の各オプションはトークンで定義されます。 テーマ用に定義されたすべてのトークンのコレクションは、 フロントエンドトークン定義 です。 フロントエンドのトークン定義は、テーマのCSSクライアント拡張機能によって提供されるJSONファイル、または以前のリリースではテーマ自体によって提供されるファイルです。

注

Liferay DXP 2024.Q2/Portal GA120 以降では、フロントエンドのトークン定義を テーマ CSS クライアント拡張機能 で指定し、それを サイトのすべてのページ に適用することができます。 以前のバージョンではテーマモジュールが必要でした。

スタイルブックのトークン定義

フロントエンドトークンの定義は、テーマのCSSクライアント拡張機能（またはテーマ）に関連付けられているため、各フロントエンドトークンは、提供されたCSSのCSS変数に対応している必要があります。 frontend-token-definition.json ファイルでフロントエンドトークンを指定します。

• テーマ CSS クライアント拡張機能: フロントエンドトークン定義をクライアント拡張機能プロジェクトに配置し、パスを client-extension.yaml で定義します。 例:

  frontendTokenDefinitionJSON: src/frontend-token-definition.json
  

• テーマ: フロントエンドトークン定義ファイルをテーマモジュールの src/WEB-INF/ フォルダに配置し、 frontend-token-definition.json という名前を付けます。

フロントエンドトークンのカテゴリ

スタイルブックの設定オプションを定義するフロントエンドトークンは、カテゴリごとにグループ化されています。 スタイルブックを編集する際、各カテゴリはドロップダウンメニューに表示されます。

テーマのsrc/WEB-INF/frontend-token-definition.jsonファイルに、frontendTokenCategoriesフィールドを使用して、これらの各カテゴリを定義します：

{
 "frontendTokenCategories": [
  {
   "frontendTokenSets": [],
   "label": "buttons",
   "name": "buttons"
  }
 ]
}

フロントエンドトークンの各カテゴリに対して、 ラベル と 名前 を定義します。 label値は言語キーとして解釈され、カテゴリのドロップダウンメニューのオプションとして表示されます。

フロントエンドトークンセット

各カテゴリはさらに フロントエンドトークンセット に整理され、スタイルブックを編集する際に表示される折りたたみ可能なオプショングループに対応します。

例えば、デフォルトのクラシックテーマを使用する場合、ボタンプライマリーフロントエンドトークンセット（ボタンカテゴリ内）には、標準ボタンカラーオプションのすべてのフロントエンドトークンが含まれます。

カテゴリの frontendTokenSets フィールド内で、各フロントエンドトークンセットを定義します。

{
 "frontendTokenCategories": [
  {
   "frontendTokenSets": [
    {
     "frontendTokens": [],
     "label": "primary-buttons",
     "name": "primaryButtons"
    }
   ],
   "label": "buttons",
   "name": "buttons"
  }
 ]
}

各カテゴリと同様に、各フロントエンドトークンセットに対して、 ラベル と 名前 を定義します。

フロントエンドトークンの定義

各トークンセットの frontendTokens フィールド内でフロントエンドトークンを定義します。 フロントエンドトークンに使用できるプロパティの一覧は以下のとおりです。

プロパティ	Description
defaultValue	このオプションに表示されるデフォルト値。 このフィールドは、CSSで使用されるデフォルト値と一致する必要があります。
editorType	このフィールドにカラーピッカーエディタを使用する場合は、このフィールドを使用してください。 サポートされている値は、 ColorPicker、 、および Length、 です。 値が設定されていない場合は、テキスト入力が使用されます。 選択入力が必要な場合は、代わりに validValues プロパティを使用してください（これら 2 つのプロパティは同時に使用できません）。
mappings	フロントエンドトークン定義名と対応するCSS変数名とのマッピング（ネストされたフィールドとして 型 と 値 を含む必要があります）。 cssVariable を 型 として使用し、 値を として CSS 変数名を定義します。
label	スタイルブックを編集する際に、そのオプションに表示される言語キー。
name	フロントエンドトークンの名前。
type	フロントエンドトークンが表示するデータの種類。 整数、 数値、または 文字列 を使用して、これらの型の値を保持するテキスト フィールドを表示します。 チェックボックスを表示するには、 またはブール値 を使用します。
validValues	UI上でユーザーが利用できるオプションを一覧表示するオプションのプロパティ。 このフィールドには、labelとvalueのペアのネストされたリストが含まれている必要があります（valueは、CSSでのフィールドの値です）。 このプロパティは、editorTypeと一緒に使用することはできません。 validValuesに値を定義すると、入力タイプが自動的に選択入力になります。

フロントエンドトークン定義のJSONスキーマは、 Liferayのリポジトリで公開されています。

以下は、フロントエンドトークンセット内のフロントエンドトークンの例です。

"frontendTokens": [
    {
        "defaultValue": "#0B5FFF",
        "editorType": "ColorPicker",
        "label": "primary",
        "mappings": [
            {
                "type": "cssVariable",
                "value": "primary"
            }
        ],
        "name": "primaryColor",
        "type": "String"
    },
    {
        "defaultValue": "sans-serif",
        "label": "font-family",
        "mappings": [
            {
                "type": "cssVariable",
                "value": "fontFamily"
            }
        ],
        "name": "fontFamily",
        "type": "String",
        "validValues": [
            {
                "label": "sans-serif",
                "value": "sans-serif"
            },
            {
                "label": "monospace",
                "value": "Courier New"
            }
        ]
    }
]

CSS変数をスタイルブックトークンに一致させる

フロントエンドトークン定義で定義されているすべてのフロントエンドトークンは、テーマのCSSクライアント拡張機能またはテーマのCSSにおけるスタイル（色、間隔、フォントなど）を表す必要があります。

フロントエンドトークンが表すスタイルは、CSS変数としてコード化されます。 フロントエンドのトークン定義が適用されているページであれば、どのページでも対応するCSS変数を参照できます。

注

Liferay DXP 2026.Q2+ では、 プライマリカラーとセカンダリカラー (およびその明るい色と暗い色のバリエーション) に Clay の CSS 変数名を テーマ CSS クライアント拡張機能 だけでなく、従来のテーマでも使用できます。

以前のバージョンでは、これらの名前を使用しても、値はテーマにのみ伝播されました。

例えば、このトークンはフォントを設定するオプションを提供します。

{
 "defaultValue": "sans-serif",
 "label": "font-family-base",
 "mappings": [
  {
   "type": "cssVariable",
   "value": "font-family-base"
  }
 ],
 "name": "fontFamilyBase",
 "type": "String"
}

このトークンは、CSS変数として参照することでCSS内でアクセスできます（ var(--token-name) 構文を使用）。

body {
 font-family: var(--font-family-base);
}

フロントエンドトークン定義の マッピング (font-family-base) の値は、CSS の変数名と一致します。 CSS変数名の前に2つのハイフンを使用します（この例では、--font-family-base）。

関連トピック

• スタイルブックを使用してサイトの外観を標準化する
• テーマCSSクライアント拡張機能の使用