Installation
Add Syntara to a React project with npm, or by copying the files.
Syntara installs two ways: with one npm command, or by copying a component’s source files into your project (ADR-011). Both give you the same components and the same tokens. Every component page has the exact steps.
You need React 19 and a bundler that handles CSS — Next.js and Vite both do out of the box. Syntara doesn’t use Tailwind, so it works with or without it.
With npm
Run one command in your app's folder. It is the whole setup.
pnpm dlx syntara initIt does four things:
- Asks about your brand. A few questions, each with a suggestion: press Enter to take it. No brand guidelines? Pick a starting look instead. Built a theme on the Themes page? Its Use in your app command gives the same answers, so only the name is asked.
- Writes your theme.
syntara-theme.cssis a light and dark theme that passes every WCAG 2.2 AA contrast check.syntara.brand.jsonkeeps the answers it was built from. - Installs Syntara. It offers to run your project's own package manager to add the
syntarapackage. Add--no-installto skip this. - Adds it to your app. It finds your entry file (
src/main.tsxin Vite,app/layout.tsxorpages/_app.tsxin Next.js) and adds two style imports and aThemeScopearound your app that follows the computer's light or dark setting. It also adds a welcome card (syntara-welcome.tsx) that shows your brand on real components when you start the app; delete the file and its two lines when you are done, or add--no-welcometo skip it. It shows you the change and asks before it saves. Add--no-editto skip this and do it by hand.
Changed syntara.brand.json by hand? Run npx syntara build to rebuild the theme.
With an AI assistant
AI coding assistants are careful with a package they haven't seen before, and may stop to check before they run it. Paste this so yours knows where Syntara comes from and what it will change:
Set up the Syntara design system in this project.
It is on npm as "syntara", docs at https://syntara.live,
source at https://github.com/anujpatel06/syntara.
First ask me for my brand name and main colour (a hex value).
Then run, with my answers:
npx syntara init --name "<brand name>" --primary "<hex>"
It writes syntara-theme.css and syntara.brand.json, installs
the syntara package, adds two style imports and a ThemeScope
to the app's entry file, and adds a welcome card
(syntara-welcome.tsx). Show me what changed.Without a terminal to ask in, init takes the suggested answer for anything you don't pass, and saves without asking. Add --no-edit to the command to make the entry-file change yourself.
Icons come from syntara/icons and the theme engine from syntara/theme-engine.
What init added, or doing it by hand
If you used --no-edit, or want to know what changed, these are the two steps syntara init does in your entry file.
Your own font. Pick Your own font at the Fonts question, or pass it as a flag:
pnpm dlx syntara init --font ManropeAny Google font works, or your own files (--font-file fonts/acme.woff2), if it passes six checks. It must have real Regular, Medium, Semibold and Bold. It must draw every letter itself. No letter may be cut off at any size Syntara uses, and line spacing must stay within limits. Its small letters must be tall enough to read at 12px. Checking takes a minute or two (Hindi and Arabic fonts up to four) in the Chrome or Edge on your computer. A font that fails is not used: you get the reason in a sentence, and a list of Google fonts that pass. See Theming.
Import the CSS once
At your app root — app/layout.tsx in Next.js, src/main.tsx in Vite — import the one stylesheet (every built-in brand’s tokens, then the component styles), then your brand’s.
import 'syntara/styles.css';
import './syntara-theme.css';The tokens are scoped to [data-syntara-theme="<id>"], one block per brand. Skipped init? Leave out the second line and use a built-in brand, such as vela.
Wrap your app in a ThemeScope
theme is your brand's id: the one syntara init printed, also in syntara.brand.json. scheme is light (the default), dark, or auto to follow the computer's setting.
import { Button, ThemeScope } from 'syntara';
export default function App() {
return (
<ThemeScope theme="my-brand" scheme="dark">
<Button>Continue</Button>
</ThemeScope>
);
}Just want the package, without the brand setup?
pnpm add syntaraOne piece at a time
syntara is a bundle of the separate packages, which are still published on their own: @syntara/react (components),
@syntara/tokens (token CSS), @syntara/icons and @syntara/theme-engine. Install them separately when you only need
one, for example the tokens in an app that isn't React:
pnpm add @syntara/react @syntara/tokensimport '@syntara/tokens/dist/syntara.css';
import '@syntara/react/styles.css';If your app only ever shows one brand, import @syntara/tokens/dist/<id>/tokens.css instead of dist/syntara.css; it
puts that tenant on :root. Each component also has its own entry point, e.g.
import { Button } from '@syntara/react/ui/button'.
By hand
Every component page has a Manual tab with the full source of each file.
- Install the npm packages the component lists — usually
react-aria-components(44 components) and@syntara/icons(23); the two date components also need@internationalized/date. - Copy its
.tsxand.module.cssfiles into one folder, such ascomponents/ui. - Copy any Syntara components it uses into the same folder. Files import each other as
./button, so the folder can live anywhere. - Load a token file once at your app root. Take one from
@syntara/tokens, or copy the CSS export on the Themes page.
The files are yours from then on. They are CSS Modules that read --syntara-* variables, and nothing else.
Set the theme
Token CSS keys off three attributes on one element — <html> for the whole app, or a ThemeScope for part of it.
<html data-syntara-theme="vela" data-syntara-scheme="auto" data-syntara-density="compact">With a single tenant’s tokens.css, the tenant is already on :root. Put the scheme and density attributes on <html>. To give regions of a page different tenants or schemes, load syntara.css and pass theme to each ThemeScope.