Getting started with cascivo — The fastest path is the prebuilt package. In any React 18+ app built with a bundler (Vite, Next.js, webpack):
Upgrading cascivo — cascivo has two consumption paths, so it has two upgrade stories: npm packages (@cascivo/react, @cascivo/core, …) upgrade with a version bump, and copied components (installed via cascivo add) upgrade with a merge. This page covers both, plus where changes are recorded.
Theming & branding cascivo — cascivo is a token-driven design system: every component reads CSS custom properties (--cascivo-*), and a theme is just a set of those properties scoped to a data-theme value. You match a brand by overriding tokens — never by forking components. This page is the end-to-end recipe.
Headless primitives (@cascivo/core) — cascade is CSS-native, but the interactive behavior — focus, dismissal, keyboard navigation, aria wiring — lives in a small, reusable headless layer in @cascivo/core. You do not roll your own aria-* toggles or keyboard handlers for menus, dialogs, and popovers: compose these primitives instead. They are unstyled, signal-driven (no useState/useEffect), and SSR-safe.
Compatibility & support matrix — What cascivo runs on, which package versions go together, and the build-tooling baseline. If an integration surprises you, start here.
cascivo Design Tokens — Every value cascivo exposes as a --cascivo-* CSS custom property. Values shown are the light theme's; theme-scoped tokens (colors, shadows) differ per [data-theme]. A machine-readable manifest is published at @cascivo/tokens/tokens.json, and a CascivoToken union for editor autocomplete at @cascivo/tokens/tokens.
Recipe: building a console/dashboard page — You're building something like Vercel's project dashboard, a Datadog-style usage console, or an admin panel — a sidebar or topbar, a project/workspace switcher, a grid of cards with row actions, KPI tiles, and usage sparklines or time-series charts. Every part below already ships in cascivo. This page maps the need to the exact component, in one place, so you don't reach for custom SVG or a separate headless library.
Recipe: transactional email — Render cascivo-themed email with @cascivo/email. Your product UI and the mail it sends share one design system: the same twelve themes, the same tokens, resolved for clients that have never heard of oklch().
Recipe: payments, billing and email on Cloudflare — Take money and send mail from a cascivo app on Cloudflare Workers, with no Stripe SDK, no AWS SDK and no nodejs_compat. Everything here is in @cascivo/app: plain fetch against Stripe's and SES's APIs, and WebCrypto for the signatures.
Recipe: sign-in, connected accounts and social posting on Cloudflare — Let people sign in with an account they already have, connect their social accounts, and post to them now or later from a Worker. Everything here is in @cascivo/app and runs on Workers with plain fetch and WebCrypto: no provider SDKs and no nodejs_compat.
Email primitives — Every component @cascivo/email exports, with its props and a worked example. Live previews of all 22, rendered as real email documents, are at [https://cascivo.com/docs/email/components](https://cascivo.com/docs/email/components). The full set of 12 themes is demonstrated on complete templates at [https://cascivo.com/docs/email](https://cascivo.com/docs/email).
Email client support — What @cascivo/email can and cannot use, derived from the [Can I email](https://www.caniemail.com) support matrix rather than asserted by hand. This page and the conformance lint read the same data, so they cannot disagree.
Migrating from shadcn/ui to cascivo — cascivo's component and prop API is close to shadcn/ui, so most JSX ports over with small renames. The two real differences are variant names and the CSS setup (cascade layers + a theme, instead of Tailwind utility classes). This page maps the deltas the way a migrator hits them.
cascivo compared to StyleX — StyleX is Meta's styling system: JavaScript style objects compiled to atomic CSS at build time, shipped as the default at Facebook, Instagram, WhatsApp and Threads, and adopted in 2026 by Linear (from styled-components, over 1,000+ PRs) and Cursor (from Tailwind). It is the most credible new answer to "how should a large app be styled", and it is worth understanding before you pick either.
Enterprise readiness: frictions → shipped primitives — This guide answers an "enterprise-readiness" report that proposed six architectural additions after a Vercel-style dashboard dry run. The valuable part of that report is the list of frictions — the recurring pain points an enterprise team (or an LLM generating their code) hits. The proposed *code*, however, was written against a generic React/Tailwind mental model, not against cascivo: it reached for useState, useEffect, useContext, Tailwind utility classes, a data-cascivo-theme attribute, a @cascivo/theme package, and dot-notation tokens like color.background.primary — none of which exist here, and most of which this project's [component rules](../CLAUDE.md) ban outright.
AI rules for building with cascivo — Drop this into your AI agent's system prompt, Cursor rules (.cursor/rules), or AGENTS.md / CLAUDE.md so it generates CSS that keeps cascivo's cascade intact. cascivo create scaffolds an AGENTS.md with the same contract automatically; this page is for existing projects.
Machine mode — Render a cascivo UI as a Markdown document — no CSS, no hydration, no interactivity. One package, @cascivo/text, with three entry points depending on where the UI is.
Troubleshooting cascivo — The failures adopters actually hit, in FAQ form. Each entry: symptom → cause → fix.
Testing cascivo components — How to test UIs built with cascivo using Vitest + Testing Library. cascivo's own component suite (199 components, packages/components/src/*/[name].test.tsx) uses exactly this stack; the patterns below are lifted from it.
Using cascivo with a router (TanStack Router, React Router, Next.js) — Every dashboard has a router, and cascivo links come in two kinds that are wired differently. Getting one of them wrong is the single most-reported friction in adopter reports, so this page is the one owner of the answer.
Using cascivo with Next.js (App Router / RSC) — cascivo works in Next.js App Router projects out of the box: components ship with 'use client' preserved in the published bundle, so React Server Components treat them as client components without any wrapper on your side. This page covers the wiring and how the server/client split falls out.
Using cascivo with Vite SSR (TanStack Start, vite-ssr, Remix, workerd) — As of @cascivo/react 0.10, SSR works with zero Vite config. The package ships a CSS-free server build selected by the node export condition, so a bare server-side ESM loader — Node's native loader, or a workerd/Cloudflare runtime — imports it cleanly. You just install, import a theme once, and render.
Using cascivo with Tailwind v4 — Short version: they coexist. cascivo ships real stylesheets and themes via CSS @layer + a data-theme attribute; Tailwind v4 ships utilities + its own tokens. The only friction is that, left alone, the two use different dark-mode mechanisms (data-theme="dark" vs a .dark class) and two unrelated token namespaces (--cascivo-* vs Tailwind's --color-*). This page — and the opt-in @cascivo/themes/tailwind.css bridge — removes both, without changing either token system.
Using cascivo with Preact — Short version: it works on Vite CSR. @cascivo/react runs inside a Preact app via the standard react → preact/compat alias — components render, signals update, interactions fire, with zero runtime errors. Two production migrations (a Vite + Tailwind v4 studio and a Preact 10 PWA) verified this firsthand. cascivo's bundle is ~75 KB JS under compat with no JS warnings; the signals runtime does not fight Preact.
Using cascivo with Astro — Status: supported as of @cascivo/react 1.0.1, with one required line of config. Every client directive — client:load, client:visible, client:only — then server-renders and styles correctly, and page content rendered with no directive at all ships as static HTML with zero JS.
Using cascivo with Ghost — Status: tokens and themes only. cascivo's design tokens and the twelve themes are plain CSS and work in a Ghost theme. The components do not — and cannot, without changing what a Ghost theme is. Read the next section before planning around them.
Styling a component's internals — cascivo components ship CSS Modules, so their inner elements carry hashed class names (_navWrapper_1r5fv_83). Those hashes change on every build — they are not a selector you can target.
Motion (@cascivo/tokens/motion.css) — cascivo's motion layer is a closed set: thirteen shared keyframes, a fixed duration scale, six easings, and five semantic pairs. A component picks from it. It does not author its own.
CSS @layer Pitfall in Example Apps — cascivo ships one authoritative layer order, declared in [@cascivo/tokens/layers.css](../packages/tokens/src/layers.css) and emitted first by every entry path. Ordered lowest-priority → highest:
Taming third-party CSS — You want to drop a legacy library into a cascivo app — a heavy charting widget, a drag-and-drop kanban board, a rich-text editor — and it ships its own global stylesheet. This page is the one-recipe answer.