Getting started
Contributing
How the repository is laid out, how to add a component or a docs page, how tokens come in from Penpot and how a release happens.
The repository is statix/web/design-system on GitLab. AGENTS.md in the root holds the design rules and code conventions. Read it
before your first merge request. Coding agents read it too.
Repository layout
A pnpm workspace with two packages:
packages/ui/ @statix/ui, the published package
tokens/statix.tokens.json Penpot token export. Source of truth.
scripts/build-tokens.js tokens -> src/lib/styles/tokens.css
src/lib/styles/theme.css semantic variables + Tailwind @theme
src/lib/utils.ts cn, tv and helper types
src/lib/components/<name>/ one folder per component -> @statix/ui/<name>
apps/docs/ this site (SvelteKit, adapter-node)
src/lib/docs/<slug>/ one folder per component page
src/routes/ guides and foundations pages
.gitlab-ci.yml check, test, build, release (statix/ci-templates)Setup
You need Node 22.17 or later and pnpm 11 (Corepack picks the version from package.json).
git clone git@gitlab.statix.dev:statix/web/design-system.git
cd design-system
pnpm install
pnpm dev # docs on http://localhost:5173The docs read @statix/ui from source through Vite aliases, so edits in packages/ui show up without a rebuild. Before you push:
pnpm check # svelte-check, all packages
pnpm lint # prettier + eslint
pnpm test # vitest browser tests (Chromium)
pnpm --filter @statix/ui vitest --run src/lib/components/button
pnpm build # package, then docsCI runs the same commands on every merge request.
Adding a component
- Generate it. Run the shadcn-svelte CLI inside
packages/ui.components.jsonthere points the output atsrc/lib/componentsand the imports at#lib/....
cd packages/ui
pnpm dlx shadcn-svelte@latest add hover-card- Restyle it. Replace shadcn's neutral classes with the Statix utilities from
the foundations. Find the component in the Penpot
file "Commerce-and-dashboard" first and match it. Keep the shadcn variant names (
default,outline,ghost, ...) working and add Statix names on top. - Follow the conventions. Use
button/as the reference: runes,classmerged throughcn,refbindable, variants viatvexported as<name>Variants,data-sloton every part, anindex.tswith parts and aliases. - Test it. Add
<name>.svelte.test.tsnext to the component. Cover rendering, the main interaction (keyboard where relevant), theclassoverride andexpectNoA11yViolationsfromsrc/test/axe.ts. - Document it. Add a folder under
apps/docs/src/lib/docs/. The page at/components/<slug>and the sidebar entry appear on their own. - Write a Conventional Commit, for example
feat: add HoverCard. See Releases.
apps/docs/src/lib/docs/hover-card/
meta.ts defineDoc({ title, description, group, examples, api, ... })
playground.ts optional, definePlayground({ component, controls })
examples/basic.svelte one self-contained example per fileimport { defineDoc } from '../types';
export default defineDoc({
title: 'Hover card',
description: 'Shows a preview of a link target on hover, for example a website summary.',
section: 'components',
group: 'Overlays',
imports: ["import * as HoverCard from '@statix/ui/hover-card';"],
upstream: { shadcn: 'hover-card', bits: 'link-preview' },
examples: [{ file: 'basic', title: 'Basic' }],
api: [
{
name: 'HoverCard.Content',
props: [{ name: 'side', type: "'top' | 'bottom'", default: "'bottom'", description: 'Preferred side.' }]
}
]
});Each example file is self-contained, because its source is the code shown on the page. Use real
copy from the customer area: "yoga-berger.de", "Restore website", "Last backup today at 03:10".
List every public prop in api and add keyboard and ARIA notes to accessibility.
Adding a guide page
Guides live in apps/docs/src/routes/docs/<name>/+page.svelte. Start with PageHeader and wrap the text in the docs-prose utility. For
highlighted code, return snippets from a +page.server.ts with snippets() from #lib/server/snippets.js and render them with Snippet. Then add the
page to guideNav:
// apps/docs/src/lib/nav.ts
{ title: 'Forms and validation', href: '/docs/forms' },Write in English, in short sentences and active voice. No em dashes and no marketing words. Name the command, the file or the number.
Updating tokens from Penpot
Penpot is the source of truth for colours, radii, spacing and type sizes. Code never changes a token value directly.
- A designer changes the tokens in Penpot, in the set
statix. - Export the tokens as JSON (Tokens Studio format) to
packages/ui/tokens/statix.tokens.json. - Run
pnpm tokens. It rewritespackages/ui/src/lib/styles/tokens.css. - Review the diff and the Foundations pages. They read the token files, so they show the new values.
- Commit both files, for example as
feat(tokens): add tone-sand.
# 1. Save the Penpot export over the old file
cp ~/Downloads/tokens.json packages/ui/tokens/statix.tokens.json
# 2. Regenerate tokens.css
pnpm tokens
# 3. Check the result
git diff packages/ui/src/lib/styles/tokens.css
pnpm dev # open /foundations/colors, /typography, /spacingA new token needs one more step: map it to a semantic variable in theme.css and, if
it should be a utility, add it to @theme inline. If its utility shares a prefix
with Tailwind (text-, shadow-, rounded-), register it in mergeConfig in utils.ts.
Releases
Releases follow Conventional Commits and use the group's statix/ci-templates. Commitlint checks every commit and the
merge request title. The commit type decides the next version:
fix(select): keep the trigger height at 44px
feat: add HoverCard
feat(button)!: rename variant "dark" to "ink"fix:makes a patch releasefeat:makes a minor releasefeat!:or aBREAKING CHANGE:footer makes a major release. Use it for renamed or removed props, variants or exports.docs:,chore:,test:andrefactor:release nothing
After a merge to main, semantic-release creates the tag and a GitLab release with
the notes. The tag pipeline publishes @statix/ui with that version to this project's
npm registry and pushes the docs image.
Docs deployment
Each release tag pushes the image registry.statix.dev/statix/web/design-system/docs with the version and latest. It runs the Node server (adapter-node, every page
prerendered) on port 3000. The site has no login, so deploy it on an internal network or behind
basic auth.
docker login registry.statix.dev
docker run -p 3000:3000 registry.statix.dev/statix/web/design-system/docs:latest
# or build it locally from the repository root
docker build -f apps/docs/Dockerfile -t statix-docs .