Cronus UI

Cronus UI is a product UI system — the Cronus design language, a live theme runtime, and a compose path that turns validated blocks into apps. Dual distribution: install @cronus-ui/ui from npm, or copy the source in with the CLI. Canonical start: npx create-cronus-app my-app --template saas.

Aurora is the flagship theme of generated product; Neutral is the docs chrome.

v0.7.6 — OSS at aicronus.com, Cronus Pro at iacronus.com. Canonical start: npx create-cronus-app my-app --template saas. See ADR 0003.

Monorepo layout

packages/
  tokens/   @cronus-ui/tokens   — source-of-truth tokens (TS) + CSS-var bridge + Tailwind v4 @theme
  theme/    @cronus-ui/theme    — <CronusUIProvider> + useTheme (runtime theming, CSS-var only, no re-render)
  ui/       @cronus-ui/ui       — components (Radix + CVA + cn)
  stack/    @cronus-ui/stack    — Stack Builder catalog, resolver, schema, KICKOFF artifacts
  ai-kit/   @cronus-ui/ai-kit   — assistant doctrine, skills, and config templates
  cli/      cronus-ui           — copy-in installer, compose, theme, upgrade
  create-cronus-app/ create-cronus-app      — Next.js + Cronus UI app scaffold
  create-cronus-stack/ create-cronus-stack  — Stack Builder scaffold generator
  mcp/      cronus-ui-mcp       — MCP server for registry discovery
apps/
  www/      @cronus-ui/www      — OSS docs and landing (aicronus.com, :4747 locally)
  pro/      @cronus-ui/pro      — Cronus Pro origin (iacronus.com, :4748 locally)

Which package do I need?

Most apps install all three library packages — @cronus-ui/ui renders against the @cronus-ui/tokens bridge and the @cronus-ui/theme provider.

Quickstart

bun install
bun run build       # turbo: builds all packages and the docs app
bun run www         # OSS landing + docs at http://localhost:4747
bun run pro         # Cronus Pro at http://localhost:4748
bun run lint        # biome

Install (external consumer)

npx create-cronus-app my-app --template saas

That scaffolds a composed SaaS app (Aurora). The CLI default is saas (ADR 0007); pass --template default for the single-page starter.

To consume the library without the scaffolder, install the three runtime packages from public npm (published under the @cronus-ui scope — see RELEASE.md):

npm i @cronus-ui/ui @cronus-ui/tokens @cronus-ui/theme
# peers (provide what you don't already have):
npm i react react-dom

Then wire up styling. Tailwind v4 and v3 are configured differently — pick the one your app uses.

Tailwind v4 (CSS-first)

In your global stylesheet (e.g. app/globals.css / src/index.css):

@import "tailwindcss";
@import "@cronus-ui/tokens/styles.css";

/* REQUIRED. Tailwind v4 does not scan node_modules by default, so the utility
   classes baked into the shipped components (dist/**/*.js) would never be
   emitted and your components would render unstyled. This @source opts the
   published package back into content detection. Adjust the relative path so it
   resolves to your node_modules from this CSS file. */
@source "../node_modules/@cronus-ui/ui/dist/**/*.js";

That's it — no PostCSS config beyond the standard @tailwindcss/postcss (or the Vite plugin). The @import "@cronus-ui/tokens/styles.css" line brings in the Aurora theme tokens and the @theme inline bridge that maps bg-primary, rounded-lg, text-fg-secondary, shadow-glow, etc. onto the runtime --cronus-* variables.

Tailwind v3 (config JS)

Consume the @cronus-ui/tokens/preset (it maps bg-primary, rounded-lg, shadow-glow, … onto the --cronus-* variables) and add the package dist to content[] so the component classes survive purging:

// tailwind.config.js
import cronusPreset from "@cronus-ui/tokens/preset";

/** @type {import('tailwindcss').Config} */
export default {
  presets: [cronusPreset],
  content: [
    "./src/**/*.{ts,tsx}",
    // REQUIRED: keep the utilities used inside the shipped components.
    "./node_modules/@cronus-ui/ui/dist/**/*.js",
  ],
};

/* your global stylesheet */
@tailwind base;
@tailwind components;
@tailwind utilities;

v3 does not import @cronus-ui/tokens/styles.css. That file is Tailwind v4-only (it uses @theme inline / @utility, which the v3 PostCSS engine can't parse). On v3 the --cronus-* runtime variables are injected for you by <CronusUIProvider> from @cronus-ui/theme (see below) — the preset is what connects the utility classes to those variables.

Why the extra @source (v4) / content (v3) entry on both paths? The components ship as pre-compiled JS with their Tailwind class strings inline (e.g. class="inline-flex … bg-primary rounded-lg …"). Tailwind only emits CSS for classes it finds while scanning content, and it skips node_modules unless you opt in. Without this line the markup is correct but no styles are generated.

Using it in your app

// layout.tsx (or your root)
import { CronusUIProvider } from "@cronus-ui/theme";
<CronusUIProvider asRoot defaultThemeName="aurora" defaultModeName="dark">{children}</CronusUIProvider>

// anywhere
import { Button, Card, Badge } from "@cronus-ui/ui";
<Button variant="primary">Ship it</Button>

Customize everything (runtime)

const { setTheme, setMode, setOverrides } = useTheme();
setOverrides({ radius: "20px", primary: "#7c3aed", border: "..." }); // re-themes the whole subtree, no re-render

Two end-to-end consumer fixtures live under examples/: a Next.js App Router app (examples/smoke-next) and a Vite + React app (examples/smoke-vite). bun run package:smoke validates package shape, built imports, and the real release packer's internal dependency pins. SMOKE_FULL=1 bun run package:smoke also packs tarballs, installs the runtime UI packages into those fixtures, builds them, and asserts the component utility classes show up in the compiled CSS — proof that an external install renders styled.

Or copy-paste, shadcn-style (you own the code)

npx cronus-ui init
npx cronus-ui add button card dialog
npx cronus-ui compose saas --brand Acme
npx cronus-ui add-page --route /faq --blocks faq,cta --nav FAQ
npx cronus-ui theme set aurora --mode dark
npx cronus-ui upgrade --all --dry-run

The registry under registry/ is generated from the real component sources by packages/cli — see packages/cli/README.md. Both distribution modes (npm package + CLI registry) share one source of truth.

Publishing

Nine packages publish to public npm in lockstep from v0.2.0 onward: @cronus-ui/tokens, @cronus-ui/theme, @cronus-ui/ui, @cronus-ui/stack, @cronus-ui/ai-kit, cronus-ui, create-cronus-app, create-cronus-stack, and cronus-ui-mcp (all with access: public) — see RELEASE.md. Run bun run release for the default dry-run, and only run bun run release --publish when you intend to publish and tag. A real publish needs npm rights for the @cronus-ui scope and the unscoped package names.

Components

Wave 0 — foundation: Button · Input · Label · Badge · Card (+ Header/Title/ Description/Action/Content/Footer) · Separator · Skeleton · Spinner.

Wave 1 — forms: Textarea · Checkbox · Switch · RadioGroup · Select (composable) · Slider · Toggle · ToggleGroup · Field · Form (react-hook-form + zod) · InputOTP · FileDropzone.

Wave 2 — overlays & navigation: Dialog · Sheet · AlertDialog · DropdownMenu · Popover · HoverCard · Tooltip · Tabs · Accordion · Drawer (vaul) · Toast (sonner) · Command palette (cmdk, ⌘K).