CONCEPTS

Why Plumeria

The style on the right wins, not the one imported or loaded last, and the build stops when something is wrong.

A wrong value is easy to spot. The harder bug is a right value that loses: a component moves to another file, a chunk loads first, a caller passes an override, and a rule that was winning stops winning. Nothing errors, the diff looks fine, and a page nobody touched changes. Every refactor risks it, and coding agents move code faster than anyone can check the result by eye.

Plumeria takes that decision away from stylesheet order. The compiler merges styles at build time, so the style on the right wins and an overridden property never reaches the element. A mistake stops the build, and what ships is class names and CSS.

The right side wins

Whichever order the chunks load in, the style passed in last wins on the element

A component applies its own style first and the one it receives last. Here the two live in different modules, and both set 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>;

The element receives one class per property:

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

Gray is still in the stylesheet, because a Badge with no override needs it, and it even comes after teal. It makes no difference, since its class never reaches this element. The compiler knows every style the project passes to Badge, and it writes the merge as a lookup:

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

Swap the imports in Page.tsx or move accent into the same file, and the element is the same. That is tested in a real browser, with the imports in both orders.

The rest of the model is just as short. A longhand beats its shorthand, so marginTop survives margin in either order. A condition or a nested selector beats its base, so an @media block overrides the declaration it shares a property with, wherever its rule lands in the stylesheet.

Composition laws states the merge formally. Specificity shows how each pair is ranked, including the four pairs nothing can rank and what to do about them.

Where a style is written does not reach the output either. A class name comes from the property and the value alone, so moving a style into a module compiles to the same classes and the same CSS.

Playground · Last style wins

The build stops

next build runs @plumeria/eslint-plugin through oxlint alongside the compile, with nothing to configure, and stops on any error or warning. The unplugin does the same on every bundler except esbuild and Bun, where @plumeria/init prefixes the build script with 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'.
  Valid values: static, relative, absolute, fixed, sticky
   ╭─[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...

A failure says what is wrong and, where it can, points at the code. A few more of the checks:

You writeThe build says
colr: 'red'Unknown CSS property 'colr'.
A key nothing readsThe key 'stale' is defined but never referenced anywhere.
'> a': { ... }Combinator ">" is not allowed unless inside functional pseudo-classes.
className beside 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 inside a componentDo not use css.create inside functions
A style prop handed on instead of applied'headerStyle' is never applied here. Apply it to sx or css.use() on an element this component renders.

Some carry the whole fix. Two states that can match at once have nothing to rank them, so the message says how to decide:

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',
   ╰────

A component sets its own limits

A component can refuse styles at its boundary. WithoutProperties names what a caller may not set, and StyleProps names the only things it may:

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>
  </>
);

The check reaches into pseudo-classes and at-rules, so position cannot slip in behind :hover.

Nothing falls back to the browser

Every entry point of @plumeria/core is a .d.ts file, so the library has no code to run in the browser and no style can wait until then.

The compiler reads your source with the oxc parser and never runs it, so a style cannot depend on what a module does when it executes. It follows a const, and a value it would have to run the code to know is an error rather than a guess:

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) => ({ ... }) }).

What passes leaves no library behind, so a React Server Component keeps its styles with no 'use client' boundary to add. Measured on identical Next.js apps with the lint off, the step adds about 0.4 seconds to a CSS Modules build. See the side-by-side benchmark.

When an agent writes the code

An agent cannot see the page, so a style that quietly loses is the failure it is least able to catch. Here, moving code does not change what renders, and what it gets wrong comes back as build output it can act on.

The same failure reads differently under a coding agent. oxlint recognizes Claude Code, Cursor, Codex and others, and drops the frame, so each failure arrives on one line with its position, its rule and what to change:

next build, run by a coding agent
components/Menu.tsx:5:15: warning @plumeria(validate-values): 'position' has an invalid value 'fixd'. Valid values: static, relative, absolute, fixed, sticky

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

The agent corrects its own change and builds again until it compiles.

It needs no person to get started either. npx @plumeria/init --yes sets up a project and asks nothing, every page here is plain Markdown at its URL plus .md, and AI Agent Resources has the prompt to start from and the Claude Code plugin.

Written as CSS

Properties are CSS names in camelCase, values are CSS values, and pseudo-classes, attribute selectors and at-rules are spelled the way CSS spells them. There is no utility vocabulary to learn. The types and the property list the linter checks are generated from MDN's data.

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 is the state assistive technology reads and the state the style matches, so the two cannot disagree. The repeated :not(#\#) is how the compiler ranks a rule without depending on its position in the stylesheet.

A selector never names a path through the DOM. Combinators are rejected, and a descendant reacts to a parent's state through css.marker and 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>
);

Move the button anywhere inside the card and the rule still holds, because nothing in it spells out the markup.

Themes are variables. createTheme takes the selector or the query that switches them, so components contain no dark-mode branch and no provider:

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',
  },
});

Plumeria or StyleX

StyleX is the closest relative, and the shared ground is real: both compile styles to atomic CSS at build time, both are type-safe, in both the last style applied wins, and Plumeria's API deliberately inherits StyleX's design philosophy. If those were the only criteria, there would be nothing to choose. The differences are in where the merge happens, what the call site looks like, and what checks run by default.

StyleXPlumeria
MergingAt runtimeAt build time
Call sitesx={[]} or stylex.props()sx={[]} or css.use
ThemesdefineVars + createThemecreateTheme
CompilerBabelRust (oxc)
ChecksESLint pluginBuilt into the build
Fallbackstylex.props() at runtimeNone; resolved where possible, otherwise an error

Two of these rows decide most projects.

Nothing to merge with at runtime is a constraint before it is a feature. Because no merger ships, the compiler has to settle every composition it can see — across files and across a prop boundary — and refuse the ones it cannot, such as a style relayed through a chain of wrappers. StyleX makes the opposite trade: the small runtime merger means a style can be passed around and applied wherever it lands. Which trade is right depends on whether your components apply the styles they receive, or mostly forward them. If they forward them, TypedCSS is the same authoring API with StyleX's side of this trade, and the dual model page is the comparison that matters.

Themes are a selector, not an application step. In StyleX a theme takes effect where props() applies it. In Plumeria the switch is part of the theme:

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>

When StyleX is the better choice: you already run it, your codebase depends on its recipes and theming patterns, or you want the runtime merge rather than a build that refuses what it cannot see. Plumeria asks for the stricter model, and in return the result of every composition is fixed before anything ships — that, and not the API shape the two share, is the reason to switch.

Coming from another styling system

Most styles move with a small rewrite: the APIs keep StyleX's names, and CSS spelling stays as it is.

Next steps

Edit on GitHub