考え方

Plumeria を使う理由

スタイルの順番を管理し、書き間違いをビルド時に見つけられます。

間違った値は見つけやすくても、正しい値が上書きされた原因は見つけにくいものです。コンポーネントを別のファイルに移す、あるチャンクが先に読み込まれる、呼び出し元がスタイルを追加する。それだけで今まで効いていた指定が負けることがあります。エラーも差分の異常もないのに、触っていないページの見た目が変わります。リファクタリングのたびに起こり得る問題で、AI が次々とコードを移す場合は目で追い切れません。

Plumeria はビルド時にスタイルを重ねます。同じプロパティは配列の右側が優先され、上書きされたクラスは要素に付きません。CSS の読み込み順に左右されず、書き間違いがあればビルドが止まります。ブラウザーに届くのはクラス名と CSS です。

配列の右側を優先する

チャンクの読み込み順が変わっても、最後に渡したスタイルが効く

次のコンポーネントは、自分のスタイルを先に、受け取ったスタイルを最後に適用します。二つのスタイルは別のモジュールにあり、どちらも color を指定しています。

Badge.tsx
import * as css from '@plumeria/core';
import type { ReactNode } from 'react';

const styles = css.create({
  badge: {
    padding: 4,
    color: 'gray',
  },
});

type BadgeProps = {
  sx?: css.Style;
  children: ReactNode;
};

export const Badge = ({ sx, children }: BadgeProps) => (
  <span sx={[styles.badge, sx]}>{children}</span>
);
accent.ts
import * as css from '@plumeria/core';

export const accent = css.create({
  text: {
    color: 'teal',
  },
});
Page.tsx
import { accent } from './accent';
import { Badge } from './Badge';

export const Page = () => <Badge sx={accent.text}>New</Badge>;

要素に付くクラスは、各プロパティにつき一つです。

Output
<span class="x8ti24uy xxcejlqg">New</span>
Generated CSS
.xxcejlqg { color: teal; }
.x8ti24uy { padding: 4px; }
.xuifcaas { color: gray; }

灰色のルールは CSS に残ります。上書きのない Badge が使うためです。灰色のルールは青緑色より後にありますが、この要素には灰色のクラスが付かないので影響しません。コンパイラはプロジェクトが Badge に渡すスタイルを調べ、組み合わせごとの結果を表にします。

Badge.tsx (output)
<span
  className={
    "x8ti24uy" + " " + ({"x672n4nd":"xxcejlqg"}[sx] || "xuifcaas")
  }
>
  {children}
</span>

Page.tsx の import の順番を入れ替えても、accent を同じファイルに移しても、要素に付くクラスは同じです。両方の順番を実際のブラウザーでテストしています。

個別指定は一括指定より優先されます。margin と marginTop はどちらを先に書いても、上の余白には marginTop が効きます。条件付きの指定や入れ子のセレクターは基本の指定より優先されます。そのため @media の条件に当てはまれば、CSS 内の位置に関係なく、同じプロパティの基本値を上書きできます。

スタイルを重ねる規則では、この動きを数式でも説明しています。スタイルの優先順位では、どの指定が優先されるかと、自動では順位を付けられない四つの組み合わせの扱いを説明します。

スタイルを書く場所も出力に影響しません。クラス名はプロパティと値で決まるので、スタイルを別のモジュールに移しても、同じクラスと CSS が生成されます。

プレイグラウンドで上書きの順番を試す

問題をビルド時に見つける

next build は、コンパイルと並行して oxlint で Plumeria の ESLint ルールを実行します。追加設定は不要です。エラーや警告があればビルドは止まります。unplugin も同じですが、esbuild と Bun では @plumeria/init がビルドコマンドの前に plumeria-lint -- を付けます。

components/Menu.tsx
import * as css from '@plumeria/core';

const styles = css.create({
  menu: {
    position: 'fixd',
    top: 0,
    padding: 8,
  },
});

export const Menu = () => <nav sx={styles.menu} />;
next build
  ⚠ @plumeria(validate-values): 'position' has an invalid value 'fixd'.
  Did you mean 'fixed'?
   ╭─[components/Menu.tsx:5:15]
 4 │   menu: {
 5 │     position: 'fixd',
   ·               ──────
 6 │     top: 0,
   ╰────

Found 1 warning and 0 errors.
Finished in 119ms on 50 files with 19 rules using 2 threads.

✖ [plumeria] Linting failed. Aborting build...

メッセージには理由が表示され、箇所を特定できる場合は該当するコードも示されます。次はその例です。

書いたコードビルド時のメッセージ
colr: 'red'Unknown CSS property 'colr'.
どこからも使われていないキーThe key 'stale' is defined but never referenced anywhere.
'> a': { ... }Combinator ">" is not allowed unless inside functional pseudo-classes.
className と sx を併用"sx" handles both "className" and "style". Avoid mixing them.
sx={{ color: 'red' }}Do not pass inline objects to "sx". It only accepts compiled styles from css.create().
コンポーネント内で css.create を呼ぶMove css.create() to module scope and reference the result inside the function.
受け取ったスタイルを適用せず、別のコンポーネントに渡す'headerStyle' is never applied here. Apply it to sx or css.use() on an element this component renders.

直し方まで示すメッセージもあります。たとえば、同時に当てはまる二つの状態に優先順位を付けられないときは、その指定方法が表示されます。

next build
  ⚠ @plumeria(no-order-dependent-overlap): ':hover' and ':focus' can match at
  the same time and both set 'color', but neither outranks the other, so the
  result depends on the order they are written. Declare ':hover:focus' if the
  intersection has a value of its own, or split them into separate styles and
  compose them in the order that should win.
   ╭─[components/Button.tsx:8:5]
 7 │     },
 8 │     ':focus': {
   ·     ────────
 9 │       color: 'blue',
   ╰────

変更できる範囲を決める

コンポーネント側で受け取るスタイルを制限できます。WithoutProperties は呼び出す側が変更できないプロパティを指定し、StyleProps は変更できるプロパティだけを列挙します。

Panel.tsx
import * as css from '@plumeria/core';
import type { ReactNode } from 'react';

const styles = css.create({
  panel: {
    display: 'flex',
    padding: 8,
  },
});

type PanelProps = {
  sx?: css.WithoutProperties<'position' | 'top' | 'left'>;
  children: ReactNode;
};

export const Panel = ({ sx, children }: PanelProps) => (
  <div sx={[styles.panel, sx]}>{children}</div>
);
Page.tsx
import * as css from '@plumeria/core';
import { Panel } from './Panel';

const styles = css.create({
  tinted: {
    color: 'teal',
  },
  pinned: {
    position: 'fixed',
  },
});

export const Page = () => (
  <>
    <Panel sx={styles.tinted}>Accepted</Panel>
    <Panel sx={styles.pinned}>Type error</Panel>
  </>
);

疑似クラスやアットルールの中もチェックされます。:hover の中に書いた場合でも、禁止した position は渡せません。

ビルド時に CSS を作る

@plumeria/core の公開する入口はすべて .d.ts ファイルです。ブラウザーで動かすライブラリコードはなく、スタイルの解決を実行時まで持ち越すこともありません。

コンパイラは oxc のパーサーでソースを読み、コードを実行しません。モジュールの実行結果に依存するスタイルは作れません。const の値はたどれますが、実行しないと分からない値はエラーになります。

components/Box.tsx
import * as css from '@plumeria/core';

const SPACING = Math.max(8, 16);

const styles = css.create({
  box: {
    padding: SPACING,
  },
});

export const Box = () => <div sx={styles.box} />;
next build
Error: [plumeria] Cannot resolve the value of "padding" at build time
(SPACING). Values in css.create must be statically known; pass a runtime
value through the function form, css.create({ name: (value) => ({ ... }) }).

ビルド後にライブラリコードが残らないので、React Server Component でも 'use client' を追加せずスタイルを使えます。lint を無効にした同じ構成の Next.js アプリでは、CSS Modules のビルドに比べて約0.4秒の追加でした。計測結果の比較

AI でコードを書く

ページを見られないエージェントにとって、エラーが出ずにスタイルが上書きされる問題は特に発見しにくいものです。Plumeria ではコードを移しただけで表示は変わらず、間違いは修正に使えるビルドメッセージとして返ります。

oxlint は Claude Code、Cursor、Codex などの実行環境を認識します。エージェントにはコードの抜粋を省き、位置、ルール、直す内容を一行にまとめて返します。

next build, run by a coding agent
components/Menu.tsx:5:15: warning @plumeria(validate-values): 'position' has an invalid value 'fixd'. Did you mean 'fixed'?

✖ [plumeria] Linting failed. Aborting build...

エージェントはメッセージを見て自分の変更を直し、通るまでビルドを繰り返せます。

初期設定も自動化できます。npx @plumeria/init --yes は質問をせずに設定を進めます。英語版の各資料は URL の末尾に .md を付けると Markdown で読めます。AI に渡す資料には最初に渡すプロンプトと Claude Code プラグインがあります。

CSS との対応

プロパティは CSS の名前を camelCase で、値は CSS と同じ形で書きます。疑似クラス、属性セレクター、アットルールの書き方も CSS と同じです。独自のユーティリティ名を覚える必要はありません。型と、リンターがチェックするプロパティ一覧は、MDN のデータから生成しています。

MenuItem.tsx
import * as css from '@plumeria/core';

const styles = css.create({
  item: {
    padding: 8,
    borderRadius: 6,
    '[aria-current="page"]': {
      fontWeight: 600,
    },
    ':hover': {
      backgroundColor: '#f4f4f5',
    },
    '@media (min-width: 768px)': {
      padding: 12,
    },
  },
});

export const MenuItem = () => (
  <a href="/" aria-current="page" sx={styles.item}>
    Home
  </a>
);
Generated CSS
.xymmdeuh { padding: 8px; }
.x1b4ohri { border-radius: 6px; }
.x8nzehgc:not(#\#):not(#\#)[aria-current="page"] { font-weight: 600; }
.xzvfwjlv:not(#\#):not(#\#):hover { background-color: #f4f4f5; }
@media (min-width: 768px) {
  .xy3st0md:not(#\#) { padding: 12px; }
}

支援技術もスタイルも、同じ aria-current 属性で状態を判断します。そのため、読み上げと表示の状態がずれません。コンパイラが :not(#\#) を重ねるのは、CSS の記述順に依存せず優先順位を付けるためです。

通常のセレクターに DOM の経路を書く結合子は使えません。親の状態に応じて子孫を変える場合は css.marker と css.extended を使います。

Card.tsx
import * as css from '@plumeria/core';

const styles = css.create({
  card: {
    ...css.marker('card', ':hover'),
    padding: 16,
  },
  action: {
    opacity: 0.6,
    [css.extended('card', ':hover')]: {
      opacity: 1,
    },
  },
});

export const Card = () => (
  <article sx={styles.card}>
    <footer>
      <button sx={styles.action}>Open</button>
    </footer>
  </article>
);

カードの内側なら、ボタンをどこに移してもルールが効きます。要素までの経路を指定していないからです。

テーマは CSS 変数で表します。createTheme に切り替え用のセレクターやクエリーを渡すので、コンポーネントにダークモード用の分岐やプロバイダーを書く必要はありません。

theme.ts
import * as css from '@plumeria/core';

export const theme = css.createTheme('@media (prefers-color-scheme: dark)', {
  surface: {
    default: '#fff',
    theme: '#111',
  },
  text: {
    default: '#111',
    theme: '#eee',
  },
});

Tailwind CSS や CSS Modules との違い

CSS Modules と Tailwind CSS はどちらも一般的な選択肢です。CSS Modules では、詳細度が同じルールの勝ち負けは、アプリ全体で CSS がページに届く順番で決まります。ルートごとの分割や遅延読み込みで、コンポーネントを編集しなくても結果が変わることがあります。Tailwind CSS では、同じプロパティを変えるユーティリティの優先順位は生成された CSS の順序で決まります。クラス名を並べ替えても変わらないため、実行時に競合を解決する tailwind-merge が使われます。

CSS ModulesTailwindPlumeria
同じプロパティを指定した場合アプリ全体での CSS の読み込み順CSS 内の順番、または実行時の tailwind-mergeビルド時に配列の右側を選ぶ
スタイルの書き方CSS ファイルユーティリティクラスTypeScript の型付きオブジェクト
つづり間違いや未使用のスタイル検出しない未知のクラスには CSS を生成しないビルドエラー
実行時に決まる値CSS 変数を自分で設定任意の値、またはインラインの style関数で定義したスタイルを CSS 変数に変換
初期設定多くのバンドラーに標準搭載PostCSS またはバンドラーのプラグイン一つバンドラーに合うプラグイン一つ

次の点では、ほかの選択肢が向いています。

  • 周辺のツールと情報。 Tailwind CSS にはコンポーネント集、テンプレート、エディター向けツール、長年蓄積された質問と回答があります。Plumeria の資料は主にこのドキュメントです。
  • ビルドで許される書き方。 コンパイラが読めない値、コンポーネント内の css.create、ラッパーを何段も経由するスタイルはエラーになります。CSS Modules や Tailwind CSS には、これらのビルド時の制限がありません。
  • 慣れ。 多くの開発者や AI モデルは、すでに Tailwind CSS や通常の CSS に慣れています。Plumeria を使うには、まずルールを読む必要があります。

小さなプロジェクトや、一人がすべてのスタイルを管理する場合には、読み込み順で困ることは少なく、シンプルなツールで十分です。多くの場所から共通コンポーネントにスタイルを渡し、どのページでも同じ上書きを効かせたいときに Plumeria が役立ちます。

StyleX との違い

StyleX は Plumeria に最も近いライブラリです。どちらもビルド時にアトミック CSS を作り、型をチェックでき、最後に適用したスタイルが優先されます。Plumeria の API は意図的に StyleX の設計を受け継いでいます。選ぶ基準になる違いは、スタイルを重ねるタイミング、呼び出す側の書き方、標準で実行するチェックです。

StyleXPlumeria
スタイルを重ねるタイミング実行時ビルド時
二つの状態に同時に当てはまる場合疑似クラスの優先順位が固定右側のスタイルの詳細度を上げる
呼び出し側の書き方sx={[]} または stylex.props()sx={[]} または css.use
テーマdefineVars + createThemecreateTheme
コンパイラBabelRust(oxc)
チェックESLint プラグインビルドに組み込み
ビルド時に決まらない場合実行時に stylex.props() で処理解決できる場合はビルド時に処理し、できない場合はエラー

多くのプロジェクトでは、特に次の二点が選ぶ基準になります。

実行時にスタイルを重ねるか。 Plumeria は重ね合わせのコードを配らないため、ファイルや prop をまたぐ場合もビルド時に結果を決めます。ラッパー間で転送され続けるスタイルなど、追跡できないものはエラーになります。StyleX には実行時にスタイルを重ねる小さな処理があり、複数のコンポーネントに渡した後でも適用できます。自分のコンポーネントが受け取ったスタイルを直接適用するのか、さらに転送することが多いのかで選べます。

テーマを切り替える場所。 StyleX では props() で適用した場所にテーマが効きます。Plumeria では切り替え条件をテーマの定義に書きます。

StyleX
// tokens.stylex.ts
export const colors = stylex.defineVars({
  surface: '#fff',
  text: '#111',
});

// theme.ts
export const dark = stylex.createTheme(colors, {
  surface: '#111',
  text: '#eee',
});

// App.tsx
<div {...stylex.props(isDark && dark)}>{children}</div>

すでに StyleX を使い、そのレシピやテーマの書き方に依存している場合や、実行時の重ね合わせが必要な場合は StyleX が向いています。Plumeria は書き方を厳しくする代わりに、配布前にすべての組み合わせの結果を確定します。共通する API の形よりも、この違いが乗り換える理由になります。

ほかのライブラリから移行する

多くのスタイルは小さな変更で移せます。API には StyleX と同じ名前が多く、CSS の書き方もそのまま使えます。

始める

Edit on GitHub