Styling architecture

Two styles, one component API

A component is published twice: once as css-modules source, once as Tailwind source. The props, behaviour, and accessibility contract are identical, so moving between styles never changes the code that calls a component.

The registry stores them under styles.tailwind and styles["coloxo-css"]. The CLI resolves the list at install time and writes that style's files to their declared targets.

97 components ship in Coloxo CSS, 61 in Tailwind, and 61 ship in both. The tables below are generated from the registry, so they match what the installer will actually do.

Choosing a style

Pass --style to init or add. init saves the choice to coloxo.json as style; every later add reads it from there. Passing --style to a single add overrides it for that run only.

When you skip --style, the CLI decides from your project. No tailwindcss dependency means Coloxo CSS, with no prompt at all. If Tailwind is present, init asks once and defaults the answer to Tailwind.

In non-interactive --yes runs it takes the detected default instead of asking. An unknown --style value fails immediately rather than mid-install.

1npx coloxo init --style tailwind2npx coloxo add button34# or override for a single add5npx coloxo add card --style coloxo-css

Coloxo CSS

Components import a co-located .module.css file. Class names are hashed, and every value reads a --cx-* custom property.

This is the original distribution and the default for projects without Tailwind. It has no styling peer beyond the token sheet you import once.

1/* your app imports the token sheet once */2@import "@coloxo/ui/styles.css";34/* then override any semantic token on a host element */5.brand-scope {6  --cx-color-bg-brand-solid: #2348ff;7}

Tailwind

The Tailwind style is flat, self-contained TSX: the classes are written into the file, so there is no CSS module to import and nothing to add to your Tailwind config.

Because the class strings live in the component, you can edit them directly after copying the source. That is the same copy-source ownership model the CSS Modules style gives you.

Tailwind never becomes a dependency of the library itself. Only installs that choose this style expect Tailwind in the host project.

1// installed at components/ui/button.tsx2import { cx } from "@/lib/utils";34const CX: Record<string, string> = {5  base: "inline-flex items-center justify-center rounded-lg font-medium",6  "size-md": "h-10 px-4 text-sm",7};89export function Button({ size = "md", className, ...props }) {10  return <button className={cx(CX.base, CX[`size-${size}`], className)} {...props} />;11}

Style coverage

Coverage grows as components are ported. A component that offers only one style rejects the other with an explicit error instead of installing the wrong shape.

Visuals are the exception. They ship only as Coloxo CSS, and coloxo add still installs them in a Tailwind project. The command also adds @coloxo/ui to package.json so the stylesheet is in node_modules. Init does not install any visual; each slug is optional.

This table is generated from registry.json, so it reflects what `coloxo add` will accept today.

1$ npx coloxo add alert --style tailwind2"alert" is not available for style "tailwind". Available styles: coloxo-css.

Switching styles

Styles are alternatives, not layers, and each style installs to its own target path. A Tailwind button lands at components/ui/button.tsx while the Coloxo CSS version lands at components/ui/button/button.tsx plus its module and barrel file.

That means adding the other style does not overwrite your existing files — you get a second copy. Pick one style per component and delete the copy you no longer want.

Changing style in coloxo.json affects later installs only; it does not rewrite anything already in your tree.

Host applications

A consumer using Tailwind, vanilla CSS, or another system can host either style without collisions on internals.

The Coloxo CSS style keeps your own Tailwind setup intact, and the Tailwind style does not require you to adopt our spacing or colour scales.