Manual installation

Add Systhema by hand to an existing Next.js, Payload or plain Tailwind project. For framework-specific walk-throughs, see Install in a Next.js app and Install in a Payload project. To start a new project instead, use the Quick start.

PrerequisitesLink to this section

• Node.js 20.9 or newer for project packages, and Node.js 22 or newer for the systhema CLI.
• pnpm 10.
• Registry access to the private @systhemaui/* packages. See Registry access.

StepsLink to this section

For an existing Payload app, follow Install in a Payload project before using init --payload, which also generates Payload files and cleans defaults. The steps below describe the shared token and Tailwind setup.

1. Install the packagesLink to this section

# Always required.
pnpm add @systhemaui/core

# If you want React components.
pnpm add @systhemaui/react

# For Next.js, also add its adapters.
pnpm add @systhemaui/next

# If you want PayloadCMS integration.
pnpm add @systhemaui/payload
pnpm add @payloadcms/plugin-import-export
pnpm add -D @payloadcms/next \
  @payloadcms/plugin-nested-docs @payloadcms/plugin-redirects \
  @payloadcms/plugin-seo @payloadcms/richtext-lexical @payloadcms/ui

2. Install Tailwind CSS v4Link to this section

pnpm add tailwindcss @tailwindcss/postcss postcss

If your build needs a postcss.config.js, add the plugin:

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

3. Initialize Systhema in the projectLink to this section

The project-local helper is systhema-core (shipped by @systhemaui/core). Use the init command to create config files:

# Plain CSS / React projects:
pnpm systhema-core init

# Or with the global CLI proxying to systhema-core:
systhema init

# PayloadCMS projects (auto-enables --ts, --react, --postcss):
pnpm systhema-core init --payload

Common flags for init:

• --ts, emit TypeScript versions of the config files.
• --src, place the Systhema config inside src/ instead of the project root.
• --react, set packages.react = true so the React/Next safelists are emitted.
• --payload, full Payload setup (implies --ts --react --postcss).
• --tw-legacy, also create a tailwind.config.{js,ts} (only if you need the legacy v3-style config).
• --postcss, also create a PostCSS config.
• --o: overwrite existing core config files without prompting.

The command produces systhema.config.{js|ts} and, depending on flags, tailwind.config.* and/or postcss.config.*.

4. Wire Tailwind to SysthemaLink to this section

In your global stylesheet (typically src/app/globals.css for Next.js, or your main entry CSS file):

/* Replace `@import 'tailwindcss';` with: */
@import '@systhemaui/core/tailwind';

This single import pulls in Tailwind v4 plus all of Systhema's utilities, components, and design-token-derived classes.

If you're stuck with a legacy tailwind.config.js, wrap it with withSysthema():

const { withSysthema } = require('@systhemaui/core')

/** @type {import('tailwindcss').Config} */
const config = {
  content: ['./src/app/**/*.{js,ts,jsx,tsx,mdx}'],
  theme: { extend: {} },
  plugins: [],
}

module.exports = withSysthema(config)

Reference it from src/app/globals.css with the @config directive:

@import 'tailwindcss' source(none);
@config '../../../tailwind.config.js';

5. Add your design tokensLink to this section

Place exported token JSON files in src/tokens/ (or another path; keep systhema.config.* pointing at the right manifest.json). Token files come out of the Figma plugin or Systhema Design, they should not be hand-edited.

Reference the manifest in your config:

import type { SysthemaConfig } from '@systhemaui/core'
import manifest from './src/tokens/manifest.json'

const config: SysthemaConfig = {
  manifest,
  packages: {
    react: true,
    // payload: true,
  },
}

export default config

6. Sync token artifactsLink to this section

Every time tokens change, the Systhema config changes, the @systhemaui/core package is updated, or you freshly install dependencies:

pnpm systhema-core sync

This generates token artifacts, types, the safelist and TOON references, then refreshes core's token cache. For Payload projects, use the Payload commands directly if your project has no generation scripts:

pnpm exec payload generate:types
pnpm exec payload generate:importmap

7. Start buildingLink to this section

Import Systhema components and types directly:

import { Article, Section, Button, Heading, Paragraph } from '@systhemaui/next'

export default function Home() {
  return (
    <main id="main-content">
      <Article theme="default" layoutBackground="main">
        <Section>
          <Heading.h1>Hello world</Heading.h1>
          <Paragraph type="lead">A paragraph.</Paragraph>
          <Paragraph>
            <Button.a href="/about" variant="primary">
              About us
            </Button.a>
          </Paragraph>
        </Section>
      </Article>
    </main>
  )
}

For Next.js, also mount the provider shown in Install in a Next.js app. For React without Next.js, import the components and provider from @systhemaui/react.