Installation

One command

Zyncat UI installs through its CLI, not a bare package install. Run this in the root of a React project:

pnpm dlx zyncat-ui init

That is the whole setup. The CLI installs @zyncat/ui (and React 19, if the project does not have it yet), imports the base stylesheet at your app root, writes a theme file beside it, installs the agent skill and registers the MCP server - then tells you exactly what it wrote.

What init does

Five steps, six under Tailwind v4, each printed as it lands. Nothing is hidden and nothing else is touched.

1. 1

   Installs the package

   Adds @zyncat/ui with your package manager - detected from the lockfile, the packageManager field or the runner you invoked it with. If react is missing it installs React 19 alongside; if React 18 is installed it asks before upgrading. Under pnpm the progress bar tracks the real download - resolved and fetched packages, with live byte counts on the tarballs.

2. 2

   Imports the stylesheet

   Finds your app entry (app/layout.tsx, src/main.tsx, app/root.tsx, ...) and adds import '@zyncat/ui/styles.css'; as the first import, so stylesheets you load later keep winning the cascade. If the import already exists, the file is untouched; if no entry is found, it prints the one line to add yourself.

3. 3

   Writes the theme file

   Writes zyncat.theme.css beside that entry and imports it right after the stylesheet. It holds the eight decisions the whole system derives from - the four hues, the gray ramp's hue, the radius, the two faces - at their defaults, so a retheme is editing a value there. A file you already have is kept.

4. 4

   Installs the agent skill

   Copies the zyncat-ui skill into .claude/skills/ - the component map, picker tables, recipes and theming guide an AI coding agent should hold in context while writing your UI.

5. 5

   Registers the MCP server

   Merges the zyncat-ui entry into .mcp.json, pointing at the server bundled with the installed package - so an agent's answers about props and tokens always match the version your project runs. Existing servers in the file are preserved.

6. 6

   Bridges Tailwind, when it is there

   With Tailwind v4 installed, finds the stylesheet that imports tailwindcss and puts @import '@zyncat/ui/tailwind.css'; on the line above it. From then on the token vocabulary is a set of utilities - bg-surface, text-muted, rounded-md, ease-standard - that Tailwind IntelliSense completes. The theming guide has the full map.

After init

Restart your agent session so it picks up the skill and the MCP server, then prove the wiring with any component:

1import { Button } from '@zyncat/ui/button';
2import { toast } from '@zyncat/ui/toast-store';
3 
4export function Hello() {
5  return (
6    <Button variant="primary" onClick={() => toast.success('Wired', { description: 'Zyncat UI is ready.' })}>
7      Say hello
8    </Button>
9  );
10}

Two things stay in your hands, because they are places in your JSX:

1// app/layout.tsx - already imports the stylesheet after init
2import { Toaster } from '@zyncat/ui/toast';
3 
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5  return (
6    <html lang="en">
7      <body>
8        {children}
9        <Toaster />
10      </body>
11    </html>
12  );
13}

From here: retheme through the scaffolded theme file on the Theming & Overrides page, or see what the agent tooling can answer on the MCP Server page.

Requirements & CI

• React 19 - react and react-dom ^19. The CLI installs or offers the upgrade itself.
• Node.js 18+ for the CLI and the MCP server.
• Modern browsers - Chrome 123+, Safari 17.5+, Firefox 128+, Edge 123+ (relative colour syntax, light-dark() and WAAPI).
• Icons are bundled. There is no icon peer to install - components render their own glyphs, and any prop that takes an icon accepts your own ReactNode.

In CI or any non-interactive shell the CLI prints plain sequential logs and never prompts. Pass --yes to accept every default and --pm to pin the package manager:

npx zyncat-ui init --yes --pm pnpm

Re-run init any time - after upgrading @zyncat/ui it refreshes the skill and theme types to match the new version. Once the package is installed, pnpm exec zyncat-ui init (or plain npx zyncat-ui init) runs the local, version-matched copy.