Getting Started

Install the package

pnpm add @hyzer-labs/ui

• Svelte 5.32 or newer.
• Node 22.18 or newer. You need it for the hyzer CLI in step 3.
• TypeScript is optional. Types ship with the package.
• SvelteKit is optional. The library imports nothing from Kit.

1. Import the styles and use a component

Import the token sheet that ships with the package, and the reference theme. Do this once, in your global stylesheet. Then use the components. Every page on this site runs this exact setup.

@import '@hyzer-labs/ui/tokens.css';
@import '@hyzer-labs/ui/theme';
@import '@hyzer-labs/ui/utilities.css'; /* optional, see Utilities */

svelte +page.svelte Copy

<script>
	import { Card, Badge, Button, Image } from '@hyzer-labs/ui';
	import cover from './cover.jpg';
</script>

<Card horizontal>
	{#snippet media()}
		<Image src={cover} alt="" aspectRatio="16/9" rounded="md" />
	{/snippet}

	<Badge intent="info">Technique</Badge>
	<h3>Shaping a backhand roller</h3>
	<p>Why nose angle matters more than arm speed, and how to feel it.</p>

	{#snippet actions()}
		<Button variant="ghost" intent="neutral">Read more</Button>
	{/snippet}
</Card>

Technique

Shaping a backhand roller

Why nose angle matters more than arm speed, and how to feel it.

Read more

The theme is optional. Skip it and the components stay headless: you keep the behavior and the accessibility. The browser's own defaults decide how everything looks.

2. Override tokens in CSS

Every visual decision resolves through a --hz-* custom property, also called a design token. Redefine any of them in your own stylesheet: palette, roles, intents, radius, density. There is no build step.

Dark mode runs on the same hook the library uses internally: the data-theme attribute. The tokens you set in :root are the default, which is what a page gets when nothing sets that attribute. A named theme like dark then overrides the default. The attribute works on any element, so one section can carry its own theme. Set it nowhere and the page follows the reader's system preference, with no script involved.

:root {
	--hz-palette-primary: #0f766e; /* your brand */
	--hz-radius-md: 0.625rem;
}

[data-theme='dark'] {
	--hz-palette-primary: #2dd4bf; /* the same token, for dark */
}

More override recipes live in Theming → Tokens & Overrides. Contrast & Accessibility shows how to check a new palette.

3. Generate your own tokens (optional)

This step moves your choices into the build. Describe your system in hyzer.config.ts and let the hyzer CLI generate the sheet. The CLI merges your settings over the base schema. Every run prints a WCAG contrast report to your console. Add --strict and any AA miss fails the run.

import { defineConfig } from '@hyzer-labs/ui/config';

export default defineConfig({
	output: 'src/styles/tokens.css',

	// The default theme: the :root block a page gets with no data-theme set.
	tokens: {
		palette: {
			primary: '#0f766e',
			brandRed: { 500: '#ef4444', 900: '#7f1d1d' } // ramps welcome
		},
		intent: { fairway: 'var(--hz-palette-brand-red-900)' } // new intents too
	},

	// Named variants that override the default, keyed by data-theme.
	themes: { dark: { palette: { primary: '#2dd4bf' } } }
});

{
	"scripts": {
		"generate": "hyzer generate"
	}
}

/* import YOUR generated sheet instead of ours */
@import './styles/tokens.css';
@import '@hyzer-labs/ui/theme';
@import './styles/hyzer-utilities.css'; /* only if you generated it */

hyzer generate --mode overrides writes a patch sheet to import after ours instead of replacing it. See Config & CLI for every option and how to choose a mode.

Add utilities: true to the config (or run with --utilities) and the CLI also writes hyzer-utilities.css, the opt-in single-property helper classes. See Utilities.

Where to go next