Theme System

Quick Start #

bash
 
npm install @astryx-svelte/theme-neutral

svelte
 
<script lang="ts">
	import { Theme } from '@astryx-svelte/core';
	import { neutralTheme } from '@astryx-svelte/theme-neutral';
	import '@astryx-svelte/theme-neutral/theme.css';
​
	let { children } = $props();
</script>
​
<Theme theme={neutralTheme}>
	{@render children()}
</Theme>

svelte
 
<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import { Theme } from '@astryx-svelte/core';
	import { neutralTheme } from '@astryx-svelte/theme-neutral';
	import '../app.css';
​
	let { children } = $props();
</script>
​
<Theme theme={neutralTheme} mode="system">
	{@render children()}
</Theme>

Each theme ships as its own npm package. Install the one you want, import its stylesheet once, then wrap your app in <Theme>. The same pattern works for every theme; just swap the package and import name.

Published themes are pre-built: the theme object carries __built: true, so <Theme> skips runtime <style> injection and the stylesheet you imported does the work. That is what makes them SSR-safe with no flash.

Available Themes #

Install the theme package you want with npm install @astryx-svelte/theme-{name}, then import its theme object as shown below.

Every theme package publishes three entries: - @astryx-svelte/theme-{name}: the built theme object plus its icon registry — what an app imports - @astryx-svelte/theme-{name}/tokens: the same theme as plain data, with no icon registry and no imports, so plain Node can read it - @astryx-svelte/theme-{name}/theme.css: the pre-compiled stylesheet, imported once alongside the theme

Theme Props #

Creating a Custom Theme #

Scaffold one with the CLI (recommended) or create it manually with defineTheme. Only override tokens that differ from defaults; omitted tokens use the design system defaults.

bash
 
astryx-svelte theme add neutral

defineTheme #

defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values.

ts
 
import { defineTheme } from '@astryx-svelte/core/theme';
​
export const myTheme = defineTheme({
	name: 'my-theme',
	color: { accent: '#7B61FF', neutralStyle: 'cool' },
	typography: {
		scale: { base: 14, ratio: 1.2 },
		body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' }
	},
	radius: { base: 4, multiplier: 1 },
	motion: { fast: 175, medium: 410, ratio: 0.75 },
	tokens: {
		// Explicit overrides take precedence over scale-generated values
		'--color-accent': ['#7B61FF', '#9B85FF']
	},
	components: {
		button: { 'variant:primary': { color: 'white' } }
	}
});

Extending a Theme #

extends lets you derive a new theme from an existing one, inheriting its tokens, component overrides, icons, and fonts. Only specify what you want to change; everything else carries over from the base theme.

ts
 
import { defineTheme } from '@astryx-svelte/core/theme';
import { neutralTheme } from '@astryx-svelte/theme-neutral';
import { myIcons } from './icons.svelte';
​
export const brandTheme = defineTheme({
	name: 'brand',
	extends: neutralTheme,
	icons: myIcons,
	tokens: {
		'--color-accent': ['#7B61FF', '#9B85FF']
	}
});

Component Style Overrides #

The components field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use base for all instances, variant:value or stateName for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in astryx-svelte docs styling.

ts
 
components: {
	// Standard CSS properties are expanded automatically.
	// borderRadius also sets the internal radius var for concentric math.
	// padding on container components (card, section, dialog) expands to layout tokens.
	card: {
		base: { borderRadius: '20px', padding: '24px' }
	},
	button: {
		base: { borderRadius: '9999px', textTransform: 'uppercase' },
		'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },
		// Some components have public CSS vars for properties that don't map
		// to standard CSS. Set these directly.
		'--button-press-scale': 'scale(0.95)'
	}
}

Run astryx-svelte component <Name> to see a component's theming targets, public CSS variables, and which standard CSS properties are supported.

• Write standard CSS properties (borderRadius, padding); the pipeline expands them into internal vars.
• Set public CSS vars directly when no standard property equivalent exists.

• Set private CSS vars (prefixed --_) directly. Use standard CSS properties instead. astryx-svelte theme build will error.

Custom Variants #

Themes can add new prop values to any component. Any prop:value key where the value isn't a built-in gets treated as a new variant. Use astryx-svelte theme build to generate TypeScript augmentations for type safety.

ts
 
components: {
	button: {
		// Override an existing variant
		'variant:secondary': { backgroundColor: 'rgba(0,0,0,0.06)' },
		// Add a new variant — generates type augmentation on build
		'variant:primary-muted': {
			backgroundColor: 'light-dark(#F2F4F6, #28292C)',
			color: 'var(--color-text-primary)'
		}
	},
	banner: {
		// Any extensible prop axis works — not just variant
		'status:neutral': {
			backgroundColor: 'var(--color-background-muted)',
			color: 'var(--color-text-secondary)'
		}
	}
}

After building, the new values are type-safe in markup:

svelte
 
<!-- TypeScript knows about 'primary-muted' after astryx-svelte theme build -->
<Button variant="primary-muted" label="Save draft" />
<Banner status="neutral" title="Note" />

Custom variants only work when the theme that defines them is active. The component's variant map is extended via module augmentation, with no changes to the component source needed.

Building Themes for Production #

astryx-svelte theme build compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (SvelteKit with adapter-node, adapter-vercel, or any prerendered output) where styles must be present on first paint.

bash
 
astryx-svelte theme build ./src/lib/themes/ocean.ts

This generates the following files alongside the source:

The __built: true flag tells Theme to skip runtime <style> injection; the CSS file handles it.

svelte
 
<script lang="ts">
	import { Theme } from '@astryx-svelte/core';
	import { oceanTheme } from '$lib/themes/ocean.js';
	import '$lib/themes/ocean.css';
​
	let { children } = $props();
</script>
​
<Theme theme={oceanTheme}>
	{@render children()}
</Theme>

Runtime vs Built Themes #

Themes work in two modes. Every published @astryx-svelte/theme-* package is already built; the distinction matters for a theme you write yourself.

• Import the published theme plus its theme.css for production apps.
• Use a runtime defineTheme() theme during development for fast iteration.
• Run astryx-svelte theme build for custom themes to get the built artifacts.

• Ship a runtime theme in a server-rendered app; component overrides will flash on hydration.
• Import a built theme without its CSS file; component overrides won't apply.

Light/Dark Mode #

Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on Theme to follow OS preference.

ts
 
'--color-accent': ['#0064E0', '#2694FE'],
//                   ^light     ^dark

svelte
 
<script lang="ts">
	import { Button, Theme } from '@astryx-svelte/core';
	import { myTheme } from '$lib/themes/my-theme.js';
​
	let mode = $state<'light' | 'dark'>('light');
</script>
​
<Theme theme={myTheme} {mode}>
	<Button
		label={mode === 'light' ? 'Switch to Dark' : 'Switch to Light'}
		onclick={() => (mode = mode === 'light' ? 'dark' : 'light')}
	/>
</Theme>

Nesting Themes #

Wrap different sections in separate <Theme> providers.

svelte
 
<Theme theme={lightTheme} mode="light">
	<Layout>
		{#snippet header()}
			<LayoutHeader>...</LayoutHeader>
		{/snippet}
​
		{#snippet start()}
			<Theme theme={darkTheme} mode="dark">
				<LayoutPanel><!-- Dark sidebar --></LayoutPanel>
			</Theme>
		{/snippet}
​
		{#snippet content()}
			<LayoutContent><!-- Light content --></LayoutContent>
		{/snippet}
	</Layout>
</Theme>

Token Utilities #

Use tokenVar() when a non-StyleX styling library wants a CSS variable reference, and resolveThemeTokens() when JavaScript needs token values for a specific theme and mode without any component context. Themes are also registered by name when created with defineTheme(); call registerTheme(theme) for prebuilt or object-literal themes that need name-based SSR lookup.

ts
 
import { tokenVar, tokenVars } from '@astryx-svelte/core/theme';
​
const pandaOrEmotionTheme = {
	colors: {
		text: tokenVar('--color-text-primary'),
		surface: tokenVars['--color-background-surface']
	},
	spacing: {
		4: tokenVars['--spacing-4']
	}
};

ts
 
import { resolveThemeTokens } from '@astryx-svelte/core/theme';
import { neutralTheme } from '@astryx-svelte/theme-neutral/tokens';
​
const lightTokens = resolveThemeTokens(neutralTheme, { mode: 'light' });
const chartTheme = {
	textColor: lightTokens['--color-text-primary'],
	seriesColor: lightTokens['--color-icon-blue']
};

These helpers are server-safe and render nothing, so they work in a +page.server.ts, a build script, or a plain Node process. Import the theme itself from its /tokens subpath there: the package root pulls in an icon registry that is a .svelte module, which plain Node cannot parse.

useTheme #

useTheme() uses the same token resolution as resolveThemeTokens(), but reads the nearest Theme and effective color mode from context and media query state. Use it inside a component for SVG, canvas, charts, maps, and third-party configuration objects that need token values in JavaScript instead of var(...) references.

It returns a live object — name, mode, tokens, and a token(name) lookup — whose properties are getters, so read them inside $derived rather than destructuring them once.

svelte
 
<script lang="ts">
	import { useTheme } from '@astryx-svelte/core/theme';
​
	const theme = useTheme();
​
	const options = $derived({
		mode: theme.mode,
		textColor: theme.tokens['--color-text-primary'],
		gridColor: theme.tokens['--color-border'],
		seriesColor: theme.token('--color-icon-blue')
	});
</script>
​
<Chart {options} />

Prefer CSS variables, xstyle, or class for ordinary styling. To change the theme or mode, manage state at the app level and pass it to <Theme>.

See astryx-svelte docs styling-libraries for styling-library interop and astryx-svelte docs tokens for the full token reference.