The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Cronus UI listing page.
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.
| You want… | Install | Docs |
|---|---|---|
| Ready-made Cronus components | @cronus-ui/ui (+ tokens + theme) | packages/ui |
| Runtime theming — switch theme/mode, override tokens | @cronus-ui/theme (+ tokens) | packages/theme |
| Just the design tokens / Tailwind preset | @cronus-ui/tokens | packages/tokens |
| Stack Builder core artifacts | @cronus-ui/stack | packages/stack |
| AI assistant doctrine, skills, and rules | @cronus-ui/ai-kit | packages/ai-kit |
| To own the component source (copy-in, shadcn-style) | npx cronus-ui add <component> | packages/cli |
| To scaffold a new app | npx create-cronus-app my-app --template saas | packages/create-cronus-app |
| To scaffold a runnable default stack + KICKOFF | bun create cronus-stack@latest my-app | packages/create-cronus-stack |
| To expose the registry through MCP | npx cronus-ui-mcp | packages/mcp |
Most apps install all three library packages — @cronus-ui/ui renders against the
@cronus-ui/tokens bridge and the @cronus-ui/theme provider.
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):
Then wire up styling. Tailwind v4 and v3 are configured differently — pick the one your app uses.
In your global stylesheet (e.g. app/globals.css / src/index.css):
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.
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:
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 skipsnode_modulesunless you opt in. Without this line the markup is correct but no styles are generated.
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.
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.
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.
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).
Wave 3 — data & display: Table · DataTable (TanStack) · Pagination · Avatar · Progress · ScrollArea · Calendar · DatePicker · Chart (Recharts) · Empty · Metric · Kbd · Breadcrumb.
Wave 4 — premium & brand: GlassCard · GradientBorder · GradientText · SpotlightCard · AuroraBackground · Shimmer · AnimatedButton (motion) · Reveal · LogoCarousel · motion presets. The premium Aurora layer (glass, gradients, springs, scroll reveals, rotating brand surfaces).
See CONTRACT.md — semantic tokens (no palette scales, no raw hex), CVA
variants, forwarded ref, data-slot, focus-visible rings. This is what
keeps the library re-themeable.
Waves 0–4 (foundation through premium/brand) are done. The CLI, registry, public npm packages, and compose generator have shipped.
Shipped: compose as the default path (create-cronus-app defaults to saas,
ADR 0007), add-page, 3-way upgrade of components and composed pages, agent kit
Still not this quarter: inflating component count.
A live Cursor/Claude 20-prompt eval is for a human — no score claimed here.
Proprietary. All rights reserved. See LICENSE.
You may use official npm packages and CLI output in your own apps. You may not copy, fork, rebrand, or republish this repository or the Cronus UI design system as your own.