Skip to content
Statix Design System

Getting started

Installation

Add @statix/ui to a SvelteKit app in four steps: registry access, install, one CSS import and the fonts.

Requirements

  • SvelteKit 2.57 or later, or SvelteKit 3
  • Svelte 5.40 or later (runes)
  • Tailwind CSS 4.1 or later with @tailwindcss/vite
  • pnpm. npm and Bun work too, the commands just differ.

1. Registry access

@statix/ui is private. It lives in the npm registry of the Statix group on GitLab. Point the @statix scope at it in the app's .npmrc:

.npmrc
@statix:registry=https://gitlab.statix.dev/api/v4/groups/statix/-/packages/npm/
//gitlab.statix.dev/:_authToken=${GITLAB_NPM_TOKEN}

Commit this file. The token stays out of the repository: pnpm reads GITLAB_NPM_TOKEN from the environment. Create a personal access token on gitlab.statix.dev with the read_api scope and export it in your shell:

# ~/.zshrc or ~/.bashrc
export GITLAB_NPM_TOKEN=glpat-...

In GitLab CI, set GITLAB_NPM_TOKEN: $CI_JOB_TOKEN in the job. The design system project must allow job tokens from your project (Settings, CI/CD, Job token permissions).

2. Install

pnpm add @statix/ui

bits-ui, Lucide icons, tailwind-variants and the other runtime dependencies come with it. Svelte and Tailwind are peer dependencies, so the app's versions are used.

3. Import the theme

Add the theme right after Tailwind in the app stylesheet:

src/app.css
@import 'tailwindcss';
@import '@statix/ui/theme.css';

That is all the configuration. The theme file does three things:

  • loads the Statix tokens and maps them to semantic variables such as --primary
  • registers the Tailwind utilities (bg-primary, text-title, rounded-card, h-control-md ...)
  • adds @source '../components', so Tailwind in your app scans the package and generates every class the components use

It also sets the page background, text colour and the 15px body size on body, and a visible focus outline.

4. Fonts

The theme uses Geist and Geist Mono but does not bundle them. Install the variable fonts from Fontsource:

pnpm add @fontsource-variable/geist @fontsource-variable/geist-mono

Import them in the same stylesheet:

src/app.css
@import 'tailwindcss';
@import '@statix/ui/theme.css';
@import '@fontsource-variable/geist';
@import '@fontsource-variable/geist-mono';

You can import them in the root layout with import '@fontsource-variable/geist' instead. Either way, load the stylesheet once in src/routes/+layout.svelte:

src/routes/+layout.svelte
<script lang="ts">
	import '../app.css';

	let { children } = $props();
</script>

{@render children()}

Use a component

Every component has its own import path. Compound components export their parts as a namespace.

src/routes/+page.svelte
<script lang="ts">
	import { Button } from '@statix/ui/button';
	import * as Card from '@statix/ui/card';
</script>

<Card.Root>
	<Card.Header>
		<Card.Title>yoga-berger.de</Card.Title>
		<Card.Description>Last backup today at 03:10</Card.Description>
	</Card.Header>
	<Card.Footer>
		<Button>Restore website</Button>
	</Card.Footer>
</Card.Root>

The import paths follow one pattern:

import { Button, buttonVariants } from '@statix/ui/button';
import * as Dialog from '@statix/ui/dialog';
import { cn, tv } from '@statix/ui/utils';

Per-component paths keep the bundle small and match the shadcn-svelte structure. Code copied from shadcn-svelte works after you replace $lib/components/ui/button with @statix/ui/button. The component list shows what exists.

AI agents (MCP)

The docs site runs an MCP server at /mcp. It has one tool, ui, that returns the styling rules, a component's API and its examples as plain text. Add it to Claude Code:

claude mcp add --transport http statix-ui https://statix-design-system.fly.dev/mcp

Other clients take the same URL as a Streamable HTTP server. There is no login, and the server keeps no state.

Dark mode

Not designed yet. The .dark class and the dark: variant are wired, but there are no dark tokens. Ship light only for now. Theming explains how dark tokens will arrive.

Updating

pnpm up @statix/ui --latest

The package follows semver. Read CHANGELOG.md in the package before a minor update while the version is below 1.0, because minors can contain breaking changes until then.