Getting started

Two ways in: scaffold a new project, or add helix-ui to an app you already have.

Every snippet on this page is the same code the create-helix-ui-app templates ship, which CI scaffolds, installs, and compiles on every commit.

Requirements

Node 20 or newer
React 18 or 19 — both are supported peer ranges
A bundler that understands ESM and CSS imports (Vite, Next.js, Remix, Parcel, webpack 5). helix-ui ships ESM only.

Option A — start a new app

npm create helix-ui-app@latest my-app
cd my-app
npm run dev

The scaffolder asks which template you want and installs with whichever package manager you invoked it with:

Template	What you get
`minimal`	One themed card and the DNA preset switcher. Start here.
`admin`	Sidebar, page header, stat cards, data table.
`marketing`	Hero, feature grid, pricing.
`agent-ui`	Chat shell with thinking blocks and tool calls.

Pick one non-interactively with --template:

npm create helix-ui-app@latest my-app -- --template admin

Option B — add to an existing app

npm install @helix-ui/core @helix-ui/tokens @helix-ui/dna @helix-ui/icons

@helix-ui/core needs @helix-ui/tokens and @helix-ui/dna, so a package manager will pull them in regardless — installing them explicitly just makes the dependency visible in your manifest. @helix-ui/icons is optional.

1. Import the stylesheet, once

At your app entry, before your own CSS:

import '@helix-ui/core/styles.css';

That’s the only import you need — styles.css already @imports @helix-ui/tokens/css, so the design tokens come with it.

Skip it and every component renders as a plain browser default: component CSS references var(--helix-ui-…) with no fallbacks, so with no stylesheet loaded those declarations are simply invalid. In development helix-ui notices and tells you in the console; in production it says nothing, so keep the import.

Importing the tokens on their own is also fine if you want the CSS variables without any components:

import '@helix-ui/tokens/css';

2. Wrap your tree in a DNA provider

import { HelixUIDNAProvider } from '@helix-ui/core';
import { wildtype } from '@helix-ui/dna';

export function App() {
  return <HelixUIDNAProvider dna={wildtype()}>{/* your app */}</HelixUIDNAProvider>;
}

wildtype() is the default genome. The provider resolves it into CSS variables on a wrapper element, so everything below re-themes through the cascade — no context reads, no re-renders.

3. Render something

import { Button, Card, Stack, Text } from '@helix-ui/core';
import { Sparkle } from '@helix-ui/icons';

<Card variant="elevated" style={{ padding: 'var(--helix-ui-space-8)' }}>
  <Stack gap={5}>
    <Stack direction="row" gap={3} align="center">
      <Sparkle />
      <Text size="2xl" weight="semibold">
        Hello, helix-ui.
      </Text>
    </Stack>
    <Button tone="brand">Ship it</Button>
  </Stack>
</Card>;

That’s the whole setup. Everything else on this site is detail.

Change the theme

Swap the genome and the tree follows. The five built-in presets:

import { PRESETS, wildtype } from '@helix-ui/dna';

<HelixUIDNAProvider dna={PRESETS.noir()}>…</HelixUIDNAProvider>;

wildtype · studio · botanic · solstice · noir.

To go further than a preset, breed one:

npx @helix-ui/dna breed studio noir --seed 42 --output shorthand

Pass the resulting mutations array to the provider. See DNA for the gene model.

Framework notes

Next.js App Router — every helix-ui component carries 'use client', so importing one from a server component works without extra wrapping. Import the stylesheets in app/layout.tsx. See React Server Components.

Tailwind — helix-ui tokens are available as a Tailwind preset, so utilities and components share one scale rather than drifting. See Tailwind.

TypeScript — every package you import from ships its own declarations (@helix-ui/core, tokens, dna, icons, document, slides); no @types/* needed. The spec.md beside each component is the same API surface the types express. The CLI-only packages (@helix-ui/mcp, @helix-ui/prompt, @helix-ui/stylelint-plugin) are plain JS — you run them, you don’t import them.

Point your AI tools at it

helix-ui is built to be read by a model as easily as by a person:

claude mcp add helix-ui -- npx -y @helix-ui/mcp

Or hand any assistant a single URL: llms.txt for the index, llms-full.txt for everything. See Integrations for Cursor, Copilot, Windsurf, and a tool-agnostic AGENTS.md.

Where to next

Components — every component’s props, tokens, and a11y contract.
Tokens overview — how the DTCG JSON becomes CSS variables.
DNA — the 22-gene theme model.
Compatibility — exact versions helix-ui is tested against.