Skip to content
bref / ui

A Svelte-first, human-first, agent-first UI library.

Star

Use the package

Set up semantic palettes, native styles, surfaces, glass and icon fonts at the app root.

Installation

Bash
npm install bref-ui

Import components from bref-ui and types from bref-ui/types . Render Theme once at the application root for palette tokens, the global reset and Material Symbols. Components do not load Theme automatically.

Svelte
<script>
	import { Theme, Button } from 'bref-ui';
</script>

<Theme>
	<Button label="Save" variant="filled" color="primary" />
</Theme>

Usage

Current mode: light. This control and the navbar control share the same mode.

check_circle
Svelte
<script lang="ts">
	import { Select, Theme, ThemeModeToggle } from 'bref-ui';
	import type { ThemeMode, ThemeProps, Palette, Color } from 'bref-ui/types';
	let mode = $state<ThemeMode>('auto');
	const modes = [
		{ id: 'auto', label: 'System' },
		{ id: 'light', label: 'Light' },
		{ id: 'dark', label: 'Dark' }
	];
</script>

<Theme>
	<ThemeModeToggle {mode} />
	<label for="theme-mode">Theme</label>
	<Select
		id="theme-mode"
		items={modes}
		bind:value={() => mode, (next) => (mode = next as ThemeMode)}
	/>
</Theme>

Render Theme once at the app root to install semantic color tokens, surfaces, glass, fonts and native styles. Supply a partial palette of hex colors or separate light/dark palettes. Children are optional. ThemeModeToggle sets color-scheme metadata; mode is a controlled prop, not a binding. Override CSS tokens explicitly when customizing.

Prebuilt Theme components from bref-ui-themes/new-paris, bref-ui-themes/glassy, bref-ui-themes/crystal-code and bref-ui-themes/vscode accept the same ThemeProps. They reuse the palette serializer and mode styles from core Theme. Their palette overrides merge per mode with their own defaults and stay scoped to each wrapper, including nested instances. Use ThemeModeToggle for light/dark/system selection or a local data-theme="light", "dark" or "auto" container; the nearest container wins. Without a mode selection, Crystal Code follows the system, New Paris and Glassy stay light, and VS Code stays dark. Theme-specific material and typography tokens remain unchanged.

ThemeModeToggle

Svelte
<script lang="ts">
	import { ThemeModeToggle } from 'bref-ui';
	import type { ThemeMode } from 'bref-ui/types';
	let mode = $state<ThemeMode>('auto');
</script>

<ThemeModeToggle {mode} />
<label
	>Appearance
	<select bind:value={mode}>
		<option value="auto">System</option>
		<option value="light">Light</option>
		<option value="dark">Dark</option>
	</select>
</label>

Render once at the app root. This component emits color-scheme metadata and has no visible control. Pass a reactive mode prop; auto allows the system preference, light and dark force a scheme. Build a labeled native control to update mode. The mode prop is not bindable.

ThemeModeToggle props
PropTypeRequiredDefaultDescription
mode'light' | 'dark' | 'auto'Noautolight, dark or auto; controls color-scheme metadata.

Playground

Try a shared palette or separate light and dark colors. Changes apply to the documentation while this page is open.

Live preview

check_circle

Readable text and semantic colors follow the shared theme.

Contrast — light: text 15.76:1, primary filled 5.78:1; dark: text 15.13:1, primary filled 8.22:1. Ratios cover normal text and the primary filled button at rest; check other variants and interaction states separately.

Settings

Theme mode
Palette
View generated code
Svelte
<script>
	import { Theme, ThemeModeToggle, Icon, Button } from 'bref-ui';
</script>

<Theme>
	<ThemeModeToggle mode="light" />
	<Icon name="check_circle" color="success" label="Complete" size="large" />
	<Button variant="neutral" color="primary" label="neutral" />
	<Button variant="soft" color="primary" label="soft" />
	<Button variant="filled" color="primary" label="filled" />
	<p>Readable text and semantic colors follow the shared theme.</p>
</Theme>

Props

Component props
PropTypeRequiredDefaultDescription
palettePalette | { dark: Palette; light: Palette }No{}Optional semantic hex colors; a shared palette applies to both modes. Invalid hex values throw.
childrenSnippetNo—Optional application content.

Choosing a mode

Use the navbar theme control to test every example in light, dark or system mode. System follows the browser preference.

ThemeModeToggle renders color-scheme metadata and has no visible control. Pass a reactive mode from an application Select or Button. Theme accepts a children snippet; neither theme component forwards native attributes or exposes an element binding.

Applications can also set data-theme="light" , data-theme="dark" or data-theme="auto" on a container to select its palette.

Palette

The active palette includes foreground and background colors, accents and semantic status colors.

--color-primary
--color-secondary
--color-foreground
--color-background
--color-muted
--color-info
--color-success
--color-warning
--color-error

Customization

Pass palette to the application-root Theme. Omitted roles retain defaults. Existing CSS overrides still apply; verify contrast for custom colors.

Svelte
<Theme palette={{ primary: '#875000' }} />
<Theme palette={{ light: { primary: '#875000' }, dark: { primary: '#e8bb75' } }} />

Override light and dark variables such as --color-primary-light and --color-primary-dark on :root or a themed container, or override an active color alias on a specific component. Verify final foreground/background contrast.

Theme applies a global reset and loads Material Symbols. Components do not import it automatically.

Body text uses the --font-sans system sans fallback without loading a text font. Set --font-text to use your own font, as this gallery does, or customize --font-sans . Theme does not set font weight or smoothing.

Theme composes internal colors, surfaces, fonts and styles components. Surface and Button share the surface paint recipe. Use the typed helper from bref-ui on native HTML; copied sources include it at theme/surface.ts .

Svelte
<Button color="primary" label="Default primary" onClick={save} />
<Button
	color="primary"
	label="Local color override"
	onClick={save}
	style="--color-primary: var(--color-secondary);"
/>