fuz

design system for CSS, Svelte, and SvelteKit

npm i -D @fuz.dev/fuz

theme

Themed adds global support for both the browser's color-scheme and custom themes based on CSS variables. Themed is a singleton component that's mounted at the top-level of the page:

import Themed from
	'@fuz.dev/fuz/Themed.svelte';

<!-- +layout.svelte -->
<Themed>
	<slot />
</Themed>

why the singleton?

why nest the slot?

Themed is designed to wrap every page at the top level so it can provide the selected theme and color scheme in the Svelte context. It works without a slot, but get_theme and get_color_scheme will fail unless you call set_theme and set_color_scheme yourself.

These context helpers provide the writable stores to your code, and they also reduce boilerplate in the helper components documented below.

If you set stores in context manually, they must be the same references as the Themed props:

<script>
	const theme = writable(...);
	const color_scheme = writable(...);
	set_theme(theme);
	set_color_scheme(color_scheme);
</script>
<Themed
	selected_theme={theme}
	selected_color_scheme={color_scheme}
/>
<!-- sibling content... -->

color scheme

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

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

<Color_Scheme_Input />

Pass a prop to override the default:

<Color_Scheme_Input
	selected_color_scheme={writable(null)}
/>

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

more about Color_Scheme_Input

themes

A theme is a simple JSON collection of variables that can be transformed into CSS that set CSS variables. Each variable can have values for light and/or dark color schemes.

scoped themes

⚠️ scoped themes are a work in progress

Scope a theme to one branch of the DOM tree with Themed_Scope:

import Themed_Scope from
	'@fuz.dev/fuz/Themed_Scope.svelte';

<Themed_Scope {selected_theme}>
		...
</Themed_Scope>

the base theme

the low contrast theme

the high contrast theme

the base theme

the low contrast theme

the high contrast theme

theme usage

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

To use fuz's base theme:

<!-- +layout.svelte -->
<script>
	import '@fuz.dev/fuz/style.css';
	import '@fuz.dev/fuz/theme.css';
	import Themed from '@fuz.dev/fuz/Themed.svelte';
<script>

<!-- enable theme and color-scheme support -->
<Themed>
	<slot />
</Themed>

Themed can be customized with the nonreactive, bindable, writable store props selected_theme and selected_color_scheme:

<Themed {selected_theme} {selected_color_scheme}>
	<slot />
</Themed>

Themed sets the writable stores selected_theme and selected_color_scheme in the Svelte context:

// get values from the Svelte context provided by
// the nearest `Themed` or `Themed_Scope` ancestor:

import {get_theme} from '@fuz.dev/fuz/theme.js';
const selected_theme = get_theme();
$selected_theme.name; // 'base'

import {get_color_scheme} from '@fuz.dev/fuz/theme.js';
const selected_color_scheme = get_color_scheme();
$selected_color_scheme; // 'null'

more about Themed

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, scoped or global, or imported at buildtime or runtime. It also allows runtime access to the data if you want to pay the performance costs.

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.

elements

styles for HTML elements

👆 `blockquote`

👇 `hr` 👈 `code`

`details` and `summary`

Click me, a summary, to see the rest of the details

so many details

<details>
	<summary>
		Click me, a <code>summary</code>,
		to see the rest of the <code>details</code>
	</summary>
	<Code code={'...'} />
</details>

`table`

this is unfinished and will change

<table>
	<thead>
		<th>th</th>
		<th>th</th>
		<th>th</th>
	</thead>
	<tbody>
		<tr><td>td</td><td>td</td><td>td</td></tr>
		<tr><td>td</td><td>td</td><td>td</td></tr>
		<tr><td>td</td><td>td</td><td>td</td></tr>
	</tbody>
</table>

th	th	th
td	td	td
td	td	td
td	td	td

<table class="width_full">
	...
</table>

th	th	th
td	td	td
td	td	td
td	td	td

`aside`

the aside looks like this

<aside>
	<aside>
		<aside>nested asides</aside>
	</aside>
</aside>

forms

<form>
	<fieldset>
		<legend>
			a <code>legend</code>
			in a <code>fieldset</code>
		</legend>
		<label>
			<div class="title">
				username
			</div>
			<input
				bind:value={username}
				placeholder=">"
			/>
		</label>
		...
	</fieldset>
	...
</form>

`form` with range input

`form` with checkboxes

The above are wrapped with:

<label class="row">

with the .disabled class as needed:

<label class="row disabled">

`form` with radio buttons

disabled button

<button disabled>
	:|
</button>

<button disabled>
	a bigger disabled button
</button>

`button` with CSS class `.selected`

<button class="selected">...</button>

.selected buttons with the .deselectable class continue to be clickable when selected:

<button class="selected deselectable">
	...
</button>

`.plain` and `.icon_button`

<button class="plain">
	+
</button>

<button class="icon_button">
	+
</button>

<button class="plain icon_button">
	+
</button>

`disabled` variants

<button class="plain" disabled>
	+
</button>

<button class="icon_button" disabled>
	+
</button>

<button class="plain icon_button" disabled>
	+
</button>

`.selected` variants

<button class="plain selected">
	+
</button>

<button class="icon_button selected">
	+
</button>

<button class="plain icon_button selected">
	+
</button>

`.selected` and `.deselectable` variants

<button class="plain selected deselectable">
	+
</button>

<button class="icon_button selected deselectable">
	+
</button>

<button class="plain icon_button selected deselectable">
	+
</button>

`.buttonlike` CSS class

the .buttonlike class is useful when you want interactive builtin elements to be wrapped in a larger clickable area:

<label class="buttonlike">
	<input type="checkbox" />...
</label>

this entire thing is buttonlike, not just the checkbox

<label class="buttonlike disabled">...</label>

this is a .disabled buttonlike

<div class="buttonlike selected padded_md">...</div>

.buttonlike with .selected

<div class="buttonlike deselectable selected padded_md">...</div>

.buttonlike with .selected and .deselectable

TODO: add more deselectable signifiers?

icon sizes

the `--icon_size` variable's variants

unlike --size_ variables, --icon_ variables are in px not rem, so they're insensitive to browser font size

--icon_size_xs: 18px

🐢

--icon_size_sm: 32px

🐢

--icon_size_md: 48px

🐢

--icon_size_lg: 80px

🐢

--icon_size_1: 128px

🐢

--icon_size_2: 196px

🐢

--icon_size_3: 316px

🐢

--icon_size_4: 512px

🐢

prose

the .prose CSS class styles HTML elements for document-like presentation

`ul` inside `.prose`

`ul` without a `.prose` ancestor

`a` links are inline inside `.prose`

this link is inline

`a` without a `.prose` ancestor

outside of .prose links are normally blocks

headings and other elements have no margin by default:

h1

h2

h3

h4

h5

h6

small

p _sub p ^sup p

blockquote

but they do inside `.prose`:

h1

h2

h3

h4

h5

h6

small

p _sub p ^sup p

blockquote

typography

h1

h2

h3

h4

h5

h6

small

p _sub p ^sup p

--size_xs

--size_sm

--size_md

--size_lg

--size_1

--size_2

--size_3

--size_4

--size_5

--size_6

--size_7

--size_8

--size_9

`font-weight`

100

200

300

400

500

600

700

800

900

950

--size_xs

--size_sm

--size_md

--size_lg

--size_1

--size_2

--size_3

--size_4

--size_5

--size_6

--size_7

--size_8

--size_9

variables

170 theme variables

Variables are CSS custom properties that can be grouped into a theme. Each variable can have values for light and/or dark color schemes.

export interface Theme {
	// TODO probably need an `id`
	// id: string;
	name: string;
	items: Theme_Variable[];
}

export interface Theme_Variable {
	name: string;
	light?: string;
	dark?: string;
	summary?: string;
}

🕸

variables are snake_case so they're also valid js identifiers

styles

color scheme

themes

scoped themes

theme usage

theme: base

this is an h2 inside .prose

form

👆 blockquote

👇 hr 👈 code

details and summary

form with range input

form with checkboxes

form with radio buttons

disabled button

button with CSS class .selected

.plain and .icon_button

disabled variants

.selected variants

.selected and .deselectable variants

.buttonlike CSS class

the --icon_size variable's variants

ul inside .prose

ul without a .prose ancestor

a links are inline inside .prose

a without a .prose ancestor

headings and other elements have no margin by default:

h1

h2

h3

h4

h5

h6

but they do inside .prose:

h1

h2

h3

h4

h5

h6

h1

h2

h3

h4

h5

h6

this is an `h2` inside `.prose`

`form`

👆 `blockquote`

👇 `hr` 👈 `code`

`details` and `summary`

`form` with range input

`form` with checkboxes

`form` with radio buttons

`button` with CSS class `.selected`

`.plain` and `.icon_button`

`disabled` variants

`.selected` variants

`.selected` and `.deselectable` variants

`.buttonlike` CSS class

the `--icon_size` variable's variants

`ul` inside `.prose`

`ul` without a `.prose` ancestor

`a` links are inline inside `.prose`

`a` without a `.prose` ancestor

but they do inside `.prose`: