Skip to content
Statix Design System

Getting started

Customization

Five ways to change a component, from the smallest change to the largest. Start at the top and move down only when the step above can't do what you need.

  1. 1 Override CSS variables Change the look everywhere
  2. 2 Pass a class Adjust one instance
  3. 3 Extend the variants Add a reusable style
  4. 4 Compose parts Change the markup
  5. 5 Copy the source Change how it works

1. Override CSS variables

Colours, radii, shadows and fonts are CSS variables. Set them in the app stylesheet after the theme import and every component follows. Theming covers the details and scoped overrides.

src/app.css
:root {
	--radius-card: 20px;
	--shadow-card: none;
}

2. Pass a class

Every component takes a class prop. It goes through cn(), which removes conflicting Tailwind classes. Your class comes last, so it wins.

<Button class="w-full">Restore website</Button>

<!-- size="sm" sets h-control-sm px-4. The class wins: -->
<Button size="sm" class="h-10 px-6">Renew domain</Button>

cn is exported, so your own components can merge classes the same way:

import { cn } from '@statix/ui/utils';

cn('px-4 text-body text-ink', 'px-6 text-white');
// -> 'text-body px-6 text-white'
// px-6 replaces px-4, text-white replaces text-ink, text-body stays (it is a size)

cn knows the Statix theme keys. Without that, it would read text-body as a colour and drop text-white. The keys are registered in mergeConfig in packages/ui/src/lib/utils.ts. When you add a theme key to the package that shares a prefix with a Tailwind utility (text-*, shadow-*, rounded-*, h-*), add it there as well:

// packages/ui/src/lib/utils.ts
const mergeConfig = {
	extend: {
		theme: {
			text: ['display', 'section', 'heading', /* ... */ 'label', 'caption'],
			radius: ['card'],
			shadow: ['card', 'overlay', 'dock']
		}
	}
};

Apps that define their own theme keys hit the same problem, because the package's cn doesn't know them. Give app keys a prefix Tailwind doesn't use, or propose the key for the package.

3. Extend the variants

Components with variants export them: buttonVariants, badgeVariants and so on. Build on them with tv from @statix/ui/utils. It uses the same merge rules as cn.

src/lib/variants.ts
import { tv } from '@statix/ui/utils';
import { buttonVariants } from '@statix/ui/button';

export const shopButton = tv({
	extend: buttonVariants,
	variants: {
		variant: {
			success: 'bg-success text-success-foreground hover:bg-success/90'
		},
		size: {
			xl: 'h-14 px-8 text-lead'
		}
	}
});
<script lang="ts">
	import { Button } from '@statix/ui/button';
	import { shopButton } from '$lib/variants';
</script>

<Button class={shopButton({ variant: 'success', size: 'xl' })}>Order now</Button>

<!-- Or style a plain element the same way -->
<a href="/checkout" class={shopButton({ variant: 'success' })}>Go to checkout</a>

The shopButton classes come after the button's own classes, so bg-success replaces bg-primary. If a variant is useful in more than one app, add it to the package instead.

4. Compose parts

Components built on bits-ui accept a child snippet. It replaces the rendered element and hands you the props to spread, so a trigger can be any component:

<script lang="ts">
	import { Button } from '@statix/ui/button';
	import * as Dialog from '@statix/ui/dialog';
</script>

<Dialog.Root>
	<Dialog.Trigger>
		{#snippet child({ props })}
			<Button {...props} variant="outline">Change password</Button>
		{/snippet}
	</Dialog.Trigger>
	<Dialog.Content>...</Dialog.Content>
</Dialog.Root>

When the package has no matching component, use bits-ui directly and style it with the Statix utilities. Add bits-ui to the app's dependencies first.

<script lang="ts">
	import { Popover } from 'bits-ui';
	import { cn } from '@statix/ui/utils';
</script>

<Popover.Root>
	<Popover.Trigger class="h-chip rounded-full bg-secondary px-3 text-label">DNS</Popover.Trigger>
	<Popover.Content class={cn('rounded-lg bg-popover p-4 text-small shadow-overlay')}>
		A record: 194.126.80.12
	</Popover.Content>
</Popover.Root>

5. Copy the source

As a last resort, copy the component into the app and edit it there. You stop getting fixes from package updates for that component, so note where it came from.

git clone git@gitlab.statix.dev:statix/web/design-system.git /tmp/design-system
mkdir -p src/lib/components/ui
cp -r /tmp/design-system/packages/ui/src/lib/components/button src/lib/components/ui/button
rm src/lib/components/ui/button/*.test.ts

Then replace the package-internal imports:

// before (inside the package)
import { cn, tv, type VariantProps } from '#lib/utils.js';
// after (in your app)
import { cn, tv, type VariantProps } from '@statix/ui/utils';

If you copied it because the package can't do something, open an issue in the design system project. A fix there helps every app.