New project

Create a Next.js app with tokens, components, and agent instructions already connected:

npx create-sigil-app@latest my-sigil-app
cd my-sigil-app
npm run dev

Use the package manager selected during setup. The scaffold uses Next.js 16, which requires Node.js 20.9 or later.

Existing project

From your React project directory, run:

npx @sigil-ui/cli@latest init

Choose a preset and follow the installation prompts. To set up an existing app with dependency installation and CSS injection explicitly enabled:

npx @sigil-ui/cli@latest init --preset sigil --install --inject-css
npx @sigil-ui/cli@latest doctor

Keep your existing package manager and framework. Sigil components support React 18 and 19 and use Tailwind CSS v4 for their utility styles.

Manual setup

1. Install the packages

npm install @sigil-ui/components @sigil-ui/tokens

Use pnpm add, yarn add, or bun add if that is your project's package manager. Set up Tailwind CSS v4 for your framework before continuing.

2. Import tokens and register component styles

For a stylesheet at app/globals.css:

app/globals.css

@import "tailwindcss";
@import "@sigil-ui/tokens/css";
@import "@sigil-ui/tokens/tailwind";
@source "../node_modules/@sigil-ui/components/src";

All four lines matter. The CSS import supplies the token values. The Tailwind import maps them to theme utilities. The @source directive makes Tailwind generate the library's component classes; node_modules is excluded from automatic scanning.

Source paths are relative to the stylesheet. If yours is src/app/globals.css, use ../../node_modules/@sigil-ui/components/src. See Tailwind's source detection guide.

3. Load your global stylesheet

In Next.js, import it from the root layout:

app/layout.tsx

import "./globals.css";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return <html lang="en"><body>{children}</body></html>;
}

For Vite, import the stylesheet in src/main.tsx. For other frameworks, import it from the root entry point.

4. Render a component

app/page.tsx

import { Button, Stack } from "@sigil-ui/components";

export default function Page() {
  return (
    <Stack gap="var(--s-space-16)" align="start">
      <h1>Your first Sigil page</h1>
      <Button>Continue</Button>
      <Button variant="outline">Save for later</Button>
    </Stack>
  );
}

Interactive event handlers such as onClick belong in a client component when using Next.js App Router.

Choose a source of truth

For the CLI preset workflow, import the generated token stylesheet at the path in sigil.config.ts. Avoid importing the default package token stylesheet after it, which would override your chosen preset.

For an editable markdown spec, follow the DESIGN.md guide. Generate the file, compile it, and import its output. Recompile after editing token tables.

For small overrides, redefine tokens after the imported styles:

:root {
  --s-radius-button: 12px;
  --s-radius-card: 16px;
}

Verify the setup

npx @sigil-ui/cli@latest doctor

Unstyled components: check the Tailwind @source path and restart the development server.
Missing colors or spacing: confirm your global stylesheet imports token CSS.
Preset changes have no effect: import the generated CSS referenced by tokensPath in sigil.config.ts, and remove competing token imports.
Fonts look different: load the font families named in your preset, or override its typography tokens with fonts available in your app.

Installation