Fuz is a Svelte UI library that builds on my CSS framework Moss. It's in early alpha and there will be many breaking changes. I'm making it to support Zzz and my other projects that focus on end-users, so it'll continue to grow slowly as I find the time and usecases.

The goal is to make a fully-featured Svelte UI library, but it'll take extra time to get there. That lets us prioritize patterns like APIs above features, making it an interesting project for learning and experimentation. If you're interested in using Fuz, helping out, or just following along, see contributing.md.

These docs are a work in progress - for an overview see the readme.

Fuz bases its theme support on my CSS framework Moss, which is based on CSS custom properties. For usage docs see Themed.

Browse the full api docs.

Fuz supports SvelteKit's config for Content Security Policies with the create_csp_directives helper. Fuz also provides related helpers, types, and CSP data.

The goal is to provide a simple trust modeling system that balances safety+security+privacy with ergonomics, helping users maintain secure policies without unhelpful burden or restriction. It's restrictive by default and easy to set granular overrides, and there's tiered grants for convenience.

Example usage:

import {create_csp_directives, type Csp_Source_Spec} from '@ryanatkn/fuz/csp.js';

// Create the default CSP with no trusted sources except 'self' and some sensible fallbacks.
// This tries to balance security and privacy with usability,
// helping nonexperts write secure policies while still supporting advanced users.
// More later on the details of the defaults.
const csp = create_csp_directives();
// Use in svelte.config.js:
// export default {kit: {csp}}

// Create a CSP with some trusted sources, using Fuz's CSP default trust levels:
export const my_csp_trusted_sources: Array<Csp_Source_Spec> = [
	// Trust in yourself:
	{source: 'https://my.domain/', trust: 'high'},
	// No scripting allowed on these subdomains:
	{source: 'https://*.my.domain/', trust: 'medium'}, 
	// Low but allow scripting:
	{source: 'https://me.github.io/', trust: 'low', directives: ['script-src-elem']},
];
const csp = create_csp_directives({
  trusted_sources: my_csp_trusted_sources,
});

// Create a CSP that opts out of using Fuz's trust abstraction:
create_csp_directives({
	directives: {
		'img-src': ['self', 'https://*.my.domain/'],
		// ...your explicit directives
	},
	// Simply omit `trusted_sources`,
	// but note the above directives extend the base defaults.
});

// Create a CSP with no hidden base defaults,
// so it's fully declarative and explicit,
// like not using Fuz's CSP helpers at all:
const precise_csp = create_csp_directives({
	value_defaults_base: null,
	required_trust_defaults_base: null,
	value_defaults: {
		'img-src': ['self', 'https://my.domain/'],
		'connect-src': ['self', 'https://my.domain/'],
	},
});
// assert.deepEqual(precise_csp, {
// 	'img-src': ['self', 'https://my.domain/'],
// 	'connect-src': ['self', 'https://my.domain/'],
// });

// Transform/extend directives by passing a function:
const custom_csp = create_csp_directives({
  trusted_sources: my_csp_trusted_sources,
  directives: {
    // Add additional domains to existing values:
    'img-src': (v) => [...v, 'trusted.domain'], // extend trusted sources

     // Or completely replace values:
    'connect-src': ['self', 'trusted.domain'], // no base trusted sources!
    'connect-src': () => ['self', 'trusted.domain'], // equivalent

    // Example opt-in to eval:
    'script-src-elem': (v) => [...v, 'unsafe-eval', 'wasm-unsafe-eval'], // alert alert

		// Returning `undefined` or `null` removes the directive,
		// all other values are passed through to SvelteKit.
  },
});

Auditability and transparency are key concerns for the API, but some features are designed to help you to trade away some directness for ergonomics, with the idea that we make it easy for nonexpert users to safely configure basic scenarios, and advanced users can opt into using the API with full declarative transparency (and more verbosity and information load).

Fuz defines an optional system with three levels of trust/risk/sensitivity (low/medium/high, Csp_Trust_Level) that can be configured for each trusted source to give blanket permissions at a specified tier. Granular overrides are straightforward and declarative.

I'm trying to design for full customizability with clear, intuitive boundaries with escalating security and privacy implications. Fuz includes a debatable set of defaults, and input is appreciated to help tune the tradeoffs.

Fuz provides an optional CSP abstraction with three trust levels (of type Csp_Trust_Level) with tiers of escalating risk and implied permission. Sources can opt-in to blanket permissions at a specific level:

export const my_csp_trusted_sources: Array<Csp_Source_Spec> = [
	{source: 'https://a.domain/'}, // undefined `trust` - same as null
	{source: 'https://b.domain/', trust: null}, // no trust
	{source: 'https://c.domain/', trust: 'low'}, // passive resources only
	{source: 'https://d.domain/', trust: 'medium'}, // no script execution
	{source: 'https://e.domain/', trust: 'high'}, // arbitrary code execution
];

null

'low'

'medium'

'high'

The trust system introduces opt-in abstraction and indirection, and a downside of the design is that it encourages over-permissioning at each individual tier. The maintainers currently feel that this granularity with 3 tiers offers an intuitive base that gets most of the important questions right most of the time for most users, and additional safeguards are available for those that want tighter control or less chance of error.

The CSP helpers have a convenient, declarative API for defining directives per source. These override any defaults, and unlike trust, the directives do not depend on an abstraction layer, so WYSIWYG.

export const my_csp_trusted_sources: Array<Csp_Source_Spec> = [
	{source: 'https://a.domain/'}, // No explicit directives, will use trust level if any
	{source: 'https://b.domain/', directives: null}, // Explicitly no directives
	{source: 'https://c.domain/', directives: ['img-src']}, // Only use for images
	{source: 'https://d.domain/', directives: ['connect-src', 'font-src']}, // Allow for connections and fonts
];

Explicit directives are additive with the trust system. For example, a source with trust: 'low' would normally not be allowed for connect-src, but you can explicitly permit this by including connect-src in the directives array.

// Example: explicitly allowing a source for specific directives regardless of trust
export const my_csp_trusted_sources: Array<Csp_Source_Spec> = [
	// Allow for specific directives (adds to what trust level allows):
	{source: 'https://a.domain/', trust: 'low', directives: ['connect-src']},
	
	// Trust-level provides baseline permissions, explicit directives add specific ones:
	{source: 'https://b.domain/', trust: 'medium', directives: ['script-src-elem']},
	
	// Both mechanisms work together - trust level provides baseline permissions
	// and explicit directives add specific permissions
];

The options value_defaults_base (defaults to csp_directive_value_defaults) and required_trust_defaults_base (defaults to csp_directive_required_trust_defaults) afford full control over defaults:

// Start with completely empty defaults (fully declarative):
const minimal_csp = create_csp_directives({
	// Set both base values to null or {} to reset defaults
	value_defaults_base: null, // or {} for same effect
	required_trust_defaults_base: null, // or {} for same effect
	
	// Define only what you need
	value_defaults: {
		'script-src': ['self'],
		'img-src': ['self', 'data:'],
	},
});
// The above is equivalent to not using Fuz's CSP abstraction at all:
assert.deepEqual(minimal_csp, {
	'script-src': ['self'],
	'img-src': ['self', 'data:'],
});

// Use your own custom base value defaults:
create_csp_directives({
	// Define your own value defaults base
	value_defaults_base: {
		'default-src': ['none'],
		'script-src': ['self'],
		'img-src': ['self', 'data:'],
	},
	
	// Override specific directives in the base
	value_defaults: {
		'script-src': ['self', 'https://trusted.domain/'],
	}
});

// Set custom trust requirements for directives:
create_csp_directives({
	// Define your own trust requirements base
	required_trust_defaults_base: {
		'script-src': 'high',
		'connect-src': 'medium',
		'img-src': 'low',
	},
	
	// Source will be added based on your custom trust requirements
	trusted_sources: [
		// This source gets trusted for script-src and connect-src and no other directives.
		// If the `required_trust_defaults_base` were omitted, it would have the normal defaults.
		{source: 'https://somewhat.trusted.domain/', trust: 'medium'},
	]
});

The exported csp_directive_specs has JSON data about the CSP directives. Fuz omits deprecated directives.

The intersect helper in intersect.svelte.ts creates an attachment that observes when an element enters or leaves the viewport using the Intersection Observer API.

Uses the lazy function pattern to optimize reactivity: callbacks can update without recreating the observer, preserving state.

import {intersect} from '@ryanatkn/fuz/intersect.svelte.js';

<div {@attach intersect(() => ({intersecting}) => {
  console.log(intersecting ? 'entered' : 'left');
})}>
  scroll me into view
</div>

The callback receives intersecting (boolean), intersections (number count), el, observer, and disconnect.

Triggers when the element enters the viewport by at least a pixel. Scroll to see items change state.

<div {@attach intersect(() => ({
  onintersect: ({intersecting, el}) => {
    el.classList.toggle('intersecting', intersecting);
  }
}))}>
  content
</div>

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Triggers when 50% of the element is visible.

<div {@attach intersect(() => ({
  onintersect: ({intersecting, el}) => {
    el.classList.toggle('intersecting', intersecting);
  },
  options: {threshold: 0.5}
}))}>
  content
</div>

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Triggers only when the element is fully visible.

<div {@attach intersect(() => ({
  onintersect: ({intersecting, el}) => {
    el.classList.toggle('intersecting', intersecting);
  },
  options: {threshold: 1}
}))}>
  content
</div>

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Disconnects after the first intersection cycle (enter and leave). A count of 0 disables observation. Negative or undefined never disconnects. (the default)

<div {@attach intersect(() => ({
  onintersect: ({intersecting, el}) => {
    el.classList.toggle('intersecting', intersecting);
  },
  count: 1
}))}>
  content
</div>

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Disconnects after two intersection cycles.

<div {@attach intersect(() => ({
  onintersect: ({intersecting, el}) => {
    el.classList.toggle('intersecting', intersecting);
  },
  count: 2
}))}>
  content
</div>

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Try different parameter combinations. Positive count values disconnect after N cycles. 0 disables observation. Negative or undefined never disconnects. (the default)

• item 0
• item 1
• item 2
• item 3
• item 4
• item 5
• item 6
• item 7
• item 8
• item 9
• item 10
• item 11
• item 12
• item 13
• item 14

Fuz includes a number of logos available as data that can be mounted with the Svg component. Only the ones you use are included in your bundle.

• <Svg data={zzz_logo} />

• <Svg data={moss_logo} />

• <Svg data={belt_logo} />

• <Svg data={gro_logo} />

• <Svg data={fuz_logo} />

• <Svg data={webdevladder_logo} />

• <Svg data={fuz_blog_logo} />

• <Svg data={fuz_mastodon_logo} />

• <Svg data={fuz_code_logo} />

• <Svg data={fuz_gitops_logo} />

• <Svg data={fuz_template_logo} />

• <Svg data={earbetter_logo} />

• <Svg data={spiderspace_logo} />

• <Svg data={github_logo} />

• <Svg data={mdn_logo} />

• <Svg data={chatgpt_logo} />

• <Svg data={claude_logo} />

• <Svg data={gemini_logo} />

mdz is a small markdown dialect that supports Svelte components and a subset of TSDoc. The goal is to be friendly to nontechnical users and integrate with other Fuz systems.

import Mdz from '@ryanatkn/fuz/Mdz.svelte';

Supports bold, italic, and strikethrough:

<Mdz content="**Bold** and _italic_ and ~strikethrough~ text." />

mdz preserves and renders all whitespace exactly as written, minimizing surprise for nontechnical users:

<Mdz content=" see 
  how       
   whitespace    
is preserved " />

Single newlines create line breaks:

First line.
Second line.
Third line.

Double newlines create paragraph breaks:

First paragraph.

Second paragraph.

Triple newlines create paragraphs with a blank line between:

First paragraph.


Second paragraph separated by an extra newline.

Use exactly three hyphens (---) at the start of a line to create a horizontal rule. Must be separated from other content by blank lines (paragraph breaks), except at document start/end:

Section one.

---

Section two.

Backtick code automatically links to identifiers and modules:

To parse markdown directly, use `mdz_parse` from module `mdz.ts`.

Non-identifiers become plain code elements:

This `identifier` does not exist.

Use {@link} and {@see} tags:

See {@link Alert} and {@link Card} components.

For more control, use mdz_parse directly with Mdz_Node_View:

import {mdz_parse} from '@ryanatkn/fuz/mdz.js';
import Mdz_Node_View from '@ryanatkn/fuz/Mdz_Node_View.svelte';

const nodes = mdz_parse(content);

<!-- manipulate nodes or customize the wrapper as desired -->
<div class="white_space_pre_wrap">
	{#each nodes as node (node)}
		<Mdz_Node_View {node} />
	{/each}
</div>

For example you may want white_space_pre to avoid wrapping in some circumstances.

mdz has simpler syntax than CommonMark/GFM:

• bold: **text** only
• italic: _text_ only

In CommonMark, *text* is italic. In mdz, single * has no special meaning and renders as literal text. This choice creates a clear visual distinction between bold and italics.

import Alert from '@ryanatkn/fuz/Alert.svelte';

<Alert>info</Alert>

icon can be a string prop or snippet:

<Alert icon="▷">
	icon as a string prop
</Alert>

<Alert>
	{#snippet icon(t)}{t}◡{t}{/snippet}
	icon as a snippet
</Alert>

Alerts can be buttons by including an onclick prop. This API may change because it's a bit of a mess - a separate Alert_Button may be better.

<Alert onclick={() => clicks++}>
	alerts can be buttons{'.'.repeat(clicks)}
</Alert>

clicks: 0

The status prop, which defaults to 'inform', changes the default icon and color.

// @ryanatkn/fuz/alert.js
export type Alert_Status = 'inform' | 'help' | 'error';

<Alert status="error">
	the computer is mistaken
</Alert>

<Alert status="help">
	here's how to fix it
</Alert>

<Alert status="help" color="var(--color_d_5)">
	the <code>color</code> prop overrides the status color
</Alert>

import Breadcrumb from '@ryanatkn/fuz/Breadcrumb.svelte';

<Breadcrumb />

<Breadcrumb>🏠</Breadcrumb>

<Breadcrumb>
	{#snippet separator()}.{/snippet}
</Breadcrumb>

<Breadcrumb
	path="/a/b/c/d"
	selected_path="/a/b"
	base_path={resolve('/docs/breadcrumb')}
>
	<span class="font_size_xl">🔡</span>
	{#snippet separator()}.{/snippet}
</Breadcrumb>

import Card from '@ryanatkn/fuz/Card.svelte';

<Card>
  just<br />
  a card
</Card>

<Card>
  custom<br />
  icon
  {#snippet icon()}📖{/snippet}
</Card>

<Card href="/">
  a<br />
  link
</Card>

<Card href="/docs/card">
  href is<br />
  selected
</Card>

<Card tag="button">
  custom<br />
  tag
</Card>

<Card align="right">
  align<br />
  icon right
</Card>

<Card align="above">
  align<br />
  icon above
</Card>

<Card align="below">
  align<br />
  icon below
</Card>

Fuz provides a customizable contextmenu that overrides the system contextmenu to provide helpful capabilities to users. Popular websites with similar features include Google Docs and Discord. Below are caveats about this breaking some user expectations, and a workaround for iOS Safari support. See also the contextmenu_event docs and w3 spec.

When you rightclick inside a Contextmenu_Root, or longpress on touch devices, it searches the DOM tree for behaviors defined with Contextmenu starting from the target element up to the root. If any behaviors are found, the Fuz contextmenu opens, showing all contextually available actions. If no behaviors are found, the default system contextmenu opens.

Here's a Contextmenu_Root with a Contextmenu inside another Contextmenu:

This simple hierarchical pattern gives users the full contextual actions by default -- not just the actions for the target being clicked, but all ancestor actions too. This means users don't need to hunt for specific parent elements to find the desired action, unlike many systems -- instead, all actions in the tree are available, improving UX convenience and predictability at the cost of more noisy menus. Developers can opt out of this inheritance behavior by simply not nesting Contextmenu declarations, and submenus are useful for managing complexity.

Mouse and keyboard:

• rightclick opens the Fuz contextmenu and not the system contextmenu (minus current exceptions for input/textarea/contenteditable)
• holding Shift opens the system contextmenu, bypassing the Fuz contextmenu
• keyboard navigation and activation should work similarly to the W3C APG menubar pattern

Touch devices:

• longpress opens the Fuz contextmenu and not the system contextmenu (minus current exceptions for input/textarea/contenteditable)
• tap-then-longpress opens the system contextmenu or performs other default behavior like selecting text, bypassing the Fuz contextmenu
• tap-then-longpress can't work for clickable elements like links; longpress on the first contextmenu entry for those cases (double-longpress)

All devices:

• opening the contextmenu on the contextmenu itself shows the system contextmenu, bypassing the Fuz contextmenu
• opening the contextmenu attempts haptic feedback with navigator.vibrate

Check the boxes below to disable automatic a link detection and copy text detection, and see how the contextmenu behaves.

<Contextmenu_Root>

When no behaviors are defined, the system contextmenu is shown instead.

Expected: the Fuz contextmenu will open and show:

• custom "some custom entry" entry
• "copy text" entry when text is selected
• link entry when clicking on a link

Fuz provides two versions of the contextmenu root component with different tradeoffs due to iOS Safari not supporting the contextmenu event as of October 2025, see WebKit bug #213953.

Use Contextmenu_Root by default for better performance and haptic feedback. Use Contextmenu_Root_For_Safari_Compatibility only if you need iOS Safari support.

Contextmenu_Root

• standard, default implementation
• relies on the browser's contextmenu event
• much simpler, better performance with fewer and less intrusive event handlers, fewer edge cases that can go wrong
• does not work on iOS Safari until WebKit bug #213953 is fixed

Contextmenu_Root_For_Safari_Compatibility

• opt-in for iOS
• some browsers (including mobile Chrome) block navigator.vibrate haptic feedback due to the timeout-based gesture detection (because it's not a direct user action)
• implements custom longpress detection to work around iOS Safari's lack of contextmenu event support
• works on all devices including iOS Safari
• more complex implementation with custom touch event handling and gesture detection
• a longpress is cancelled if you move the touch past a threshold before it triggers
• opt into this version only if you need iOS Safari support

The Fuz contextmenu provides powerful app-specific UX, but it breaks from normal browser behavior by replacing the system contextmenu.

To mitigate the downsides:

• The Fuz contextmenu only replaces the system contextmenu when the DOM tree has defined behaviors. Note that a links have default contextmenu behaviors unless disabled. Other interactive elements may have default behaviors added in the future.
• The Fuz contextmenu does not open on elements that allow clipboard pasting like inputs, textareas, and contenteditables -- however this may change for better app integration, or be configurable.
• To bypass on devices with a keyboard, hold Shift while rightclicking.
• To bypass on touch devices (e.g. to select text), use tap-then-longpress instead of longpress.
• Triggering the contextmenu inside the Fuz contextmenu shows the system contextmenu.

See also the contextmenu_event docs and the w3 spec.

The Details component is an alternative to the details element. By default it's lazy, and you can pass eager to render the children immediately like the base element.

Benefits of lazy children:

• children are transitioned in/out with an animation (TODO this may be doable with eager children, if so it would probably be the better default, and then the prop should be swapped to lazy)
• improved performance, can significantly improve UX in some cases

Tradeoffs:

• ctrl+f does not work to find text and auto-open the details
• you may desire some behavior caused by mounting the children

<Details>
  {#snippet summary()}summary content{/snippet}
  lazy children content
</Details>

<Details eager>
  {#snippet summary()}summary content{/snippet}
  eager children content
</Details>

<details>
  <summary>a summary element instead of a snippet</summary>
  the plain details
</details>

A modal that overlays the entire page. Uses Teleport to allow usage from any component without inheriting styles.

<button onclick={() => (opened = true)}>
	open a dialog
</button>
{#if opened}
	<Dialog onclose={() => (opened = false)}>
		{#snippet children(close)}
			<div class="box">
				<div class="pane p_xl box">
					<h1>attention</h1>
					<p>this is a dialog</p>
					<button onclick={close}>ok</button>
				</div>
			</div>
		{/snippet}
	</Dialog>
{/if}

import Hue_Input from '@ryanatkn/fuz/Hue_Input.svelte';

<Hue_Input bind:value />

<Hue_Input
	oninput={(v) => (value_from_oninput = v)}
/>

<Hue_Input>
	Some colorful hue input
</Hue_Input>

This is a component related to Gro's public packages features.

import Package_Detail from '@ryanatkn/fuz/Package_Detail.svelte';

<Package_Detail {pkg} />

This is a component related to Gro's public packages features.

import Package_Summary from '@ryanatkn/fuz/Package_Summary.svelte';

<Package_Summary {pkg} />

import Pending_Animation from '@ryanatkn/fuz/Pending_Animation.svelte';

<Pending_Animation />

The default animation has text children, so they scale with font-size.

Set size with custom properties:

<Pending_Animation --font_size="var(--font_size_xl5)" />

Set size with classes:

<Pending_Animation attrs={{class: 'font_size_xl3'}} />

Size is inherited by default:

<div class="font_size_xl4"><Pending_Animation /></div>

<Pending_Animation inline />

with inline={true} •••

<Pending_Animation --font_size="var(--font_size_xl6)">
	{🐢}
</Pending_Animation>

with children 🐢🐢🐢 * 2

<Pending_Animation>
	{#snippet children(index)}
		<div class="box">
			{🐸}
			{index}
			<span class="font_size_xl5">
				{⏳}
			</span>}
		</div>
	{/snippet}
</Pending_Animation>

with running={true}

and children

<Pending_Animation --animation_duration="var(--duration_6)" --font_size="var(--font_size_xl4)" />

Preserves a button's normal width while animating.

import Pending_Button from '@ryanatkn/fuz/Pending_Button.svelte';

toggle the pending status of the buttons below

<Pending_Button
	pending={false}
	onclick={() => (pending_1 = !pending_1)}
>
	do something async
</Pending_Button>

do something async

<Pending_Button
	pending={true}
	onclick={() => (pending_2 = !pending_2)}
>
	do another
</Pending_Button>

Adds a redirect for a page using a meta tag with the refresh header. Includes a rendered link and JS navigation fallback.

import Redirect from '@ryanatkn/fuz/Redirect.svelte';

<Redirect auto={false} />

redirect to /docs

<Redirect
	host="https://www.felt.dev"
	path="/docs"
	let:url
	auto={false}
>
	the redirect url is {url}
</Redirect>

import Svg from '@ryanatkn/fuz/Svg.svelte';

<Svg data={fuz_logo} />

Fills available space by default:

Set size: (see the Moss typography docs)

<Svg data={fuz_logo} size="var(--icon_size_xl)" />

<Svg data={fuz_logo} size="var(--icon_size_sm)" />

Set --font_size on the component or a parent:

<span style:--font_size="var(--icon_size_xl)"><Svg data={fuz_logo} /></span>

Set fill: (see the Moss colors docs)

<Svg data={fuz_logo} fill="var(--color_d_5)" />

<Svg data={fuz_logo} fill="var(--color_b_5)" />

Set --text_color on the component or a parent, for svgs that have no default fill:

<span style:--text_color="var(--color_i_5)"><Svg data={github_logo} /></span>

Relocates elements in the DOM, in the rare cases that's useful and the best solution. The Dialog uses this to mount dialogs from any component without inheriting styles.

import Teleport from '@ryanatkn/fuz/Teleport.svelte';

<Teleport to={swap ? teleport_1 : teleport_2}>
	🐰
</Teleport>
<div class="teleports">
	<div class="panel" bind:this={teleport_1} />
	<div class="panel" bind:this={teleport_2} />
</div>
<button onclick={() => (swap = !swap)}>
	teleport the bunny
</button>

Themed defaults to automatic color-scheme detection with prefers-color-scheme, and users can also set it directly:

import Color_Scheme_Input from '@ryanatkn/fuz/Color_Scheme_Input.svelte';

<Color_Scheme_Input />

Pass props to override the default:

<Color_Scheme_Input
	value={{color_scheme: 'auto'}}
	onchange={...}
/>

The builtin themes support both dark and light color schemes. Custom themes may support one or both color schemes.

A theme is a simple JSON collection of Moss style variables that can be transformed into CSS that set custom properties. Each variable can have values for light and/or dark color schemes. In other words, "dark" isn't a theme, it's a mode that any theme can implement.

Themes are plain CSS that can be sourced in a variety of ways.

To use Fuz's base theme:

<!-- +layout.svelte -->
<script>
	import '@ryanatkn/moss/style.css';
	import '@ryanatkn/moss/theme.css';
	import Themed from '@ryanatkn/fuz/Themed.svelte';
	import type {Snippet} from 'svelte';

	interface Props {
		children: Snippet;
	}
	
	const {children}: Props = $props();
</script>

<!-- enable theme and color-scheme support -->
<Themed>
	{@render children()}
</Themed>

Themed can be customized with the the nonreactive prop themer:

import {Themer} from '@ryanatkn/fuz/themer.svelte.js';
const themer = new Themer(...);

<Themed {themer}>
	{@render children()}
</Themed>

Themed sets the themer in the Svelte context:

// get values from the Svelte context provided by
// the nearest `Themed` ancestor:
import {themer_context} from '@ryanatkn/fuz/themer.svelte.js';
const themer = themer_context.get();
themer.theme.name; // 'base'
themer.color_scheme; // 'auto'

For a more complete example, see fuz_template.

Themed initializes the system's theme support. Without it, the page will not reflect the user's system color-scheme. By default, Themed applies the base theme to the root of the page via create_theme_setup_script. It uses JS to add the .dark CSS class to the :root element.

This strategy enables color scheme and theme support with minimal CSS and optimal performance for most use cases. The system supports plain CSS usage that can be static or dynamic, or imported at buildtime or runtime. It also allows runtime access to the underlying data like the style variables if you want to pay the performance costs. Scoped theming to one part of the page is planned.

The theme setup script interacts with sync_color_scheme to save the user's preference to localStorage. See also Color_Scheme_Input.

The setup script avoids flash-on-load due to color scheme, but currently themes flash in after loading. We'll try to fix this when the system stabilizes.