Install — one css entry, zero engine tooling

Adding jixoai-ui items owes exactly one thing: a css entry that imports what the items ship. Compiled-payload items (the atom-authored migration) compile on our side — you import plain css and plain class strings, and never install a styling engine for OUR components. Running one for your own markup is your choice.

one css entry zero @stylexjs/* owed engine tooling optional your utilities always win

prerequisite

The prerequisite is a css entry

Whatever your stack, the wiring is the same shape the jixoai theme sheet has always used: import the css your items ship. Nothing to configure, nothing to compile.

the whole prerequisite

/* src/app.css — the WHOLE prerequisite (compiled-payload items) */
@import '$lib/jixoai.css';   /* the token sheet (rides @jixoai/jixoai-theme) */
@import '$lib/ui/popover/popover.css';  /* a migrated item's css — plain css, zero tooling */

the compiled contract

Compiled payload items: import the css, use the classes

Kernel paint is authored as StyleX atoms on our side and compiled by our build. What ships is a class-constant module (plain strings) plus the item's css — the F11 contract. Your bundler never sees the engine.

a compiled-payload item in use

<script lang="ts">
  import Popover from '$lib/ui/popover';        /* the components */
  import '$lib/ui/popover/popover.css';         /* the item's css — or your entry imports it */
</script>

<!-- the compiled atoms are plain class strings: no engine, no plugin -->
<Popover>schedule</Popover>

Key	Action
`class constants`	Plain string modules — import them, put them on class, nothing else
`item css`	Plain css with the canonical layer statement first — one import per item (or one fan-in entry)
`@stylexjs/*`	Absent from your lockfile: the engine rides the jixoai-ui build, never yours
`your own engine`	Optional and unrelated — Tailwind, StyleX, anything, for YOUR markup

transition

The transitional state: legacy items still want Tailwind v4

Not every family has migrated yet. Utility-authored items (the standing registry) keep their documented prerequisite — tailwindcss v4 with @tailwindcss/vite and the jixoai sheet imported after it — until their family's migration lands. The migration is staged; this page's compiled-payload lane grows as it advances.

the legacy entry (utility-authored items)

/* the standing TW4 prerequisite — legacy utility-authored items */
@import 'tailwindcss';        /* tailwind v4 (tailwindcss + @tailwindcss/vite) */
@import '$lib/jixoai.css';    /* the jixoai token sheet, AFTER tailwind */

guarantee

Your utilities always beat kernel paint

Every kernel stylesheet — compiled atoms included — opens with the same canonical layer statement, so consumer utilities sort after the kernel tiers no matter which side imports first. Restyling an installed component is a class away, never a specificity fight.

the canonical layer order (baked, never hand-written)

@layer properties, theme, base, components,
  components.stylex.priority1, …, components.stylex.priorityN, utilities;
/*              ↑ kernel atom paint (nested in components)   ↑ your utilities — always last */

installation

Verify your install

The registry ships a prerequisite checker for the legacy lane; the compiled lane needs none (an import that resolves IS the proof). Both run from your project root.

install + verify

npx jixoai-ui add popover          # install an item (compiled or legacy)

# legacy utility-authored items only — the TW4 prerequisite check
# (scripts/check-tw4-prereq.mjs; copy it or run it from a checkout):
node check-tw4-prereq.mjs src/app.css