WP Ambient CSS

日本語 | English

Ambient CSS の陰影表現を、WordPress ブロックエディタの設定項目として使えるようにするプラグインです。

Ambient CSS は、1つの光源パラメータから影・ハイライト・面のグラデーションを決定論的に導出する CSS フレームワークです。個々の box-shadow を手で調整する代わりに、光源の向きと強度を決めれば、それに整合した陰影がすべての要素で自動的に生成されます。本プラグインは、その指定をインスペクターの GUI から行えるようにします。

テーマの改修も追加 CSS も不要です。

必要環境

ブラウザは目安として Chrome/Edge 125+、Safari 16.4+、Firefox 128+ です（Chromium 以外は未検証）。未対応環境では影と面の色が出ないだけで、border-radius は効き、レイアウトは崩れません。

インストール

1. Releases から wp-ambientcss-x.y.z.zip をダウンロード
2. 「プラグイン」→「新規追加」→「プラグインのアップロード」からインストール
3. 有効化

使い方

ブロックを選択し、インスペクターの「Ambient」パネルを開きます。「Ambient を有効にする」をオンにすると各項目が使えるようになります。

基本設定

詳細設定

面の色（albedo）、反射率、キーライト、フィルライト、光の色相・彩度、光源 X / Y、グレイン量、曲面の強さ、バウンスアニメーション。

ポインタ追従

ブロック毎に、光源を訪問者のポインタに追従させられます。

両モードは同一ページで混在できます。ポインタが離れると、光源は最後の位置で止まります（自動で戻らないので、視界の中で勝手に動くものがありません）。

追従を有効にしたブロックでは、光源の向きプリセットと光源 X / Y は無効になります。光源をスクリプトが制御するためです。

サイト全体の既定値

「設定」→「Ambient CSS」で、サイト全体の光源・面の色・グレイン量の既定値を設定できます。空欄の項目は Ambient CSS の既定値がそのまま使われます。

同じ画面で、スタイルシートを常に読み込むか、Ambient を使うページだけに読み込むかを選べます。

読み込みと性能

• フロントエンドの JavaScript は既定でゼロです。 ポインタ追従を使うブロックがあるページでのみ、依存のない約 1.1KB のスクリプトを読み込みます
• スタイルシートは約 26KB（Ambient CSS 本体）
• 追従時の描画コスト（Chromium 実測）: ページ全体モードは 200 要素で約 2.0ms/更新、ブロック単位モードは 50 要素で約 1.2ms/フレーム。いずれも 60fps の予算内です
• (hover: hover) でない端末、および prefers-reduced-motion: reduce を設定した環境では、追従スクリプトは何もしません

対象ブロック

カスタムクラス名を受け付けるすべてのブロックが対象です。ただし次のブロックは、マークアップを持たない・クラス付与が破壊的、などの理由で除外しています。

core/freeform  core/html      core/shortcode  core/missing
core/nextpage  core/more      core/block      core/pattern
core/legacy-widget            core/widget-area
core/template-part

拡張

PHP フィルタ

JavaScript フィルタ（wp.hooks）

開発

セットアップ

npm install
composer install

Node 24.18 以上が必要です（wp-env が依存する @php-wasm パッケージの要求）。

ビルド

npm run build     # 本番ビルド（翻訳 JSON の生成を含む）
npm start         # 監視ビルド

build/ はコミット対象です。ビルドを通さずにプラグインが動くようにするためで、CI は build/ が最新かどうかを検証します。

テスト

npm run env:start     # wp-env 起動（Docker が必要）
npm run test:e2e      # Playwright による E2E テスト
npm run test:e2e:ui   # UI モードでデバッグ

静的解析

npm run lint:js       # ESLint（@wordpress/recommended）
composer run lint     # phpcs（WordPress Coding Standards）

Ambient CSS の更新

npm run update:ambient   # node_modules から assets/vendor/ へ同期

同梱している CSS のクラス名・カスタムプロパティは SPEC.md の対応表が正としています。上流を更新したら、対応表を再検証してください。

翻訳

npm run i18n:pot   # .pot を生成
npm run i18n:mo    # .po から .mo を生成
npm run i18n:json  # エディタ用の JSON を生成

リリース

0.0.0 形式のタグを push すると、GitHub Actions がプラグイン zip を作成して Release に添付します。タグとプラグインヘッダ・readme.txt の Stable tag・WP_AMBIENTCSS_VERSION が一致しない場合は失敗します。

git tag 0.2.0
git push origin 0.2.0

設計

実装仕様は SPEC.md（日本語）にまとめています。ブロック属性のスキーマ、属性からクラス名・カスタムプロパティへの変換表、静的ブロックと動的ブロックの出力経路、セキュリティ上の判断などを記載しています。

ライセンス

本プラグインは GPL-2.0-or-later です。全文は LICENSE を参照してください。

assets/vendor/ambient.css は Ambient CSS（@ambientcss/css v3.1.0）の無改変コピーで、MIT License / Copyright (c) 2026 Ramakrishnan Veeraragavan のもとで配布されています。ライセンス全文は assets/vendor/LICENSE-ambientcss.txt に同梱しています。

MIT は GPL と互換であるため、GPL-2.0-or-later のプラグインに同梱して配布できます。