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:
@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/uibits-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:
@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-monoImport them in the same stylesheet:
@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:
<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.
<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/mcpOther 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 --latestThe 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.