Use the package
Set up semantic palettes, native styles, surfaces, glass and icon fonts at the app root.
Installation
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.
<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.
<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
<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.
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
mode | 'light' | 'dark' | 'auto' | No | auto | light, 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
Readable text and semantic colors follow the shared theme.
Settings
View generated code
<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
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
palette | Palette | { dark: Palette; light: Palette } | No | {} | Optional semantic hex colors; a shared palette applies to both modes. Invalid hex values throw. |
children | Snippet | No | — | 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-errorCustomization
Pass palette to the application-root Theme. Omitted roles retain defaults. Existing CSS overrides still apply; verify contrast for custom colors.
<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 .
<Button color="primary" label="Default primary" onClick={save} />
<Button
color="primary"
label="Local color override"
onClick={save}
style="--color-primary: var(--color-secondary);"
/>