Contents

Components

Theme toggle

One button that flips between dark and light, remembers the choice and never flashes the wrong theme.

import { ThemeToggle } from "@sideby/ui/theme-toggle";

<ThemeToggle />

It is the same toggle as the one in the header. Press either and the whole site changes, including this page.

What it does

ThemeToggle is an outline icon Button. In dark it shows a sun and in light a moon, and its aria-label names the theme it switches to: Switch to light theme or Switch to dark theme. It names the action, not the current state, so a screen reader user hears what pressing it will do.

The choice is stored in localStorage under sideby-theme and follows the visitor to every sideby app on the same origin. When storage is blocked, the theme still changes for the page; it just is not remembered.

Dark is the default

sideby is dark first (Dark by default). A first visit always paints dark, and light is a choice someone makes. There is no “follow the system” mode, so a phone set to light still opens sideby in the dark, which is where the video looks right.

The theme API

Everything lives in @sideby/ui/theme:

  • theme.current: the current theme, "dark" or "light". It is reactive, so components can read it.
  • initTheme(): syncs theme.current with the class the page loaded with. Call it once from onMount in the root layout.
  • setTheme(name): switches to "dark" or "light", updates the class on html and stores the choice.
  • toggleTheme(): switches to the other one. This is what the toggle calls.
<script lang="ts">
	import { initTheme } from "@sideby/ui/theme";
	import { onMount } from "svelte";

	onMount(() => initTheme());
</script>

No flash of the wrong theme

The theme is decided before the first paint, by three pieces every app wires the same way:

  1. The page ships dark. app.html has class="dark" on html, so the prerendered page is dark before any script runs.
  2. A tiny inline script switches to light early. app.html holds a %sideby.themeScript% marker inside a script tag in the head. hooks.server.ts replaces it with themeScript from @sideby/ui/theme-script. The script reads sideby-theme and swaps the class to light only when the visitor chose light. It runs before the body renders, so there is nothing to flash.
  3. The CSP allows exactly that script. The script is inline, so the content security policy lists its sha256 hash. Compute the hash from the same themeScript string in vite.config.ts, so the hash and the inlined bytes can never drift apart. Every app inlines identical bytes, so the hash is the same everywhere.
<html lang="en" class="dark">
	<head>
		<script>%sideby.themeScript%</script>
		%sveltekit.head%
	</head>
</html>
// hooks.server.ts
import { themeScript } from "@sideby/ui/theme-script";
import type { Handle } from "@sveltejs/kit/hooks";

export const handle: Handle = ({ event, resolve }) =>
	resolve(event, {
		transformPageChunk: ({ html }) => html.replace("%sideby.themeScript%", themeScript),
	});

Accessibility

  • It is a native button: Tab reaches it, Enter or Space presses it, and the ring outline shows on keyboard focus.
  • The icons are hidden from assistive technology; the aria-label is the name, and it changes with the theme.
  • It sits at the default 40px control height. In a phone header with nothing else around it, that is comfortably above the 28px minimum.

Copy

Leave the built-in labels alone. If a product needs a visible label next to it, keep it plain: Theme. The joke, if there is one, goes elsewhere.