From 7a6933cf90027101496e6647f8cfafa640323635 Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Fri, 10 Jul 2026 23:54:24 +0800
Subject: [PATCH 01/13] lazy-load heavy libraries

---
 src/lib/components/front-page/Wave.svelte     |  4 ++--
 .../comparing-scalers/Comparison.svelte       | 14 ++++++-------
 .../widget/comparing-scalers/Slices.svelte    | 15 +++++++-------
 .../bradbury/bricolage/ForceDirected.svelte   |  4 ++--
 .../(content)/getting-started/Map.svelte      | 16 +++++++++------
 .../BanditGraph.svelte                        |  6 ++++--
 .../RawPitchGraph.svelte                      |  2 +-
 .../learn/smoothing-data/MFCCSmooth.svelte    |  2 +-
 .../learn/smoothing-data/Smoothing.svelte     |  2 +-
 .../learn/time/NoisePitchShape.svelte         | 10 ++++++++--
 .../(content)/learn/time/NoiseShape.svelte    | 10 ++++++++--
 .../(content)/learn/time/PitchShape.svelte    | 10 ++++++++--
 .../reference/ampfeature/AmpFeature.svelte    |  2 +-
 .../(content)/reference/chroma/Chroma.svelte  |  2 +-
 .../(content)/reference/grid/Grid.svelte      |  9 +++++----
 .../reference/grid/GridExtent.svelte          |  9 +++++----
 .../reference/grid/GridOversample.svelte      |  9 +++++----
 .../(content)/reference/kdtree/KDTree.svelte  |  2 +-
 .../(content)/reference/kmeans/KMeans.svelte  | 20 +++++++++++++++----
 .../reference/loudness/Loudness.svelte        |  2 +-
 src/routes/(content)/reference/mds/MDS.svelte |  9 +++++----
 .../(content)/reference/mfcc/DropZero.svelte  |  2 +-
 .../noveltyfeature/NoveltyFeature.svelte      |  2 +-
 .../onsetfeature/OnsetFeature.svelte          |  2 +-
 .../reference/onsetslice/OnsetSlice.svelte    |  6 ++++--
 .../spectralshape/Spectrogram.svelte          |  6 ++++--
 .../(content)/reference/umap/UMAP.svelte      | 13 +++++++++---
 27 files changed, 121 insertions(+), 69 deletions(-)

diff --git a/src/lib/components/front-page/Wave.svelte b/src/lib/components/front-page/Wave.svelte
index fb740caa..d37fdf68 100644
--- a/src/lib/components/front-page/Wave.svelte
+++ b/src/lib/components/front-page/Wave.svelte
@@ -1,6 +1,5 @@
-<script lang="ts">
+<script>
     import { onMount } from 'svelte';
-	import { CanvasSpace, Create, Pt } from 'pts';
     let height = 100;
     let width;
     let palette = [
@@ -15,6 +14,7 @@
     let waveHeight = 1.0;
     $: speed = 0.75
     onMount(async () => {
+		const { CanvasSpace, Create, Pt } = await import('pts');
 		let space = new CanvasSpace('#canvas');
 		let form = space.getForm();
 		space.setup({
diff --git a/src/lib/widget/comparing-scalers/Comparison.svelte b/src/lib/widget/comparing-scalers/Comparison.svelte
index d903eac3..d9779dea 100644
--- a/src/lib/widget/comparing-scalers/Comparison.svelte
+++ b/src/lib/widget/comparing-scalers/Comparison.svelte
@@ -1,9 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import * as d3 from 'd3';
-	import Chart from 'chart.js/auto';
-
-	import annotationPlugin from 'chartjs-plugin-annotation';
 	import scalingData from '$lib/data/learn/comparing-scalers/analysis.json';
 	import Button from '$lib/components/Button.svelte';
 
@@ -14,11 +10,15 @@
 		return entries.map((pt, i) => ({ x: pt[1][0], y: pt[1][1], id: pt[0] }));
 	};
 
-	const entries = Object.entries(scalingData.norm);
-	const colours = entries.map((_, i) => d3.interpolateSinebow(i / entries.length));
-
 	onMount(async () => {
+		const [d3, Chart, annotationPlugin] = await Promise.all([
+			import('d3'),
+			import('chart.js/auto').then(m => m.default),
+			import('chartjs-plugin-annotation').then(m => m.default)
+		]);
 		const ctx = canvas.getContext('2d');
+		const entries = Object.entries(scalingData.norm);
+		const colours = entries.map((_, i) => d3.interpolateSinebow(i / entries.length));
 		let data = {
 			datasets: [
 				{
diff --git a/src/lib/widget/comparing-scalers/Slices.svelte b/src/lib/widget/comparing-scalers/Slices.svelte
index 8f9eb251..aff33f53 100644
--- a/src/lib/widget/comparing-scalers/Slices.svelte
+++ b/src/lib/widget/comparing-scalers/Slices.svelte
@@ -1,8 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import * as d3 from 'd3';
-	import { Chart, registerables } from 'chart.js';
-	import annotationPlugin from 'chartjs-plugin-annotation';
 	import scalingData from '$lib/data/learn/comparing-scalers/analysis.json';
 	import Button from '$lib/components/Button.svelte';
 
@@ -12,12 +9,16 @@
 		const entries = Object.entries(i);
 		return entries.map((pt, i) => ({ x: pt[1][0], y: pt[1][1], id: pt[0] }));
 	};
-	const entries = Object.entries(scalingData.norm);
-	const colours = entries.map((x, i) => d3.interpolateTurbo(x[1][0] * 4 * x[1][1]));
-
-	onMount(() => {
+	onMount(async () => {
+		const [{ Chart, registerables }, d3, annotationPlugin] = await Promise.all([
+			import('chart.js'),
+			import('d3'),
+			import('chartjs-plugin-annotation').then(m => m.default)
+		]);
 		Chart.register(...registerables, annotationPlugin);
 		const ctx = canvas.getContext('2d');
+		const entries = Object.entries(scalingData.norm);
+		const colours = entries.map((x, i) => d3.interpolateTurbo(x[1][0] * 4 * x[1][1]));
 		let data = {
 			datasets: [
 				{
diff --git a/src/routes/(content)/explore/bradbury/bricolage/ForceDirected.svelte b/src/routes/(content)/explore/bradbury/bricolage/ForceDirected.svelte
index 62cb3f6a..dc929105 100755
--- a/src/routes/(content)/explore/bradbury/bricolage/ForceDirected.svelte
+++ b/src/routes/(content)/explore/bradbury/bricolage/ForceDirected.svelte
@@ -2,7 +2,6 @@
 	import { onMount } from 'svelte';
 	import { dragNetwork } from './dragNetwork.js';
 	import { clip } from '$lib/util';
-	import * as d3 from 'd3';
 
 	export let id = 'bricolage';
 	export let blurb = '';
@@ -60,7 +59,8 @@
 			counter += 1;
 		}
 	});
-	onMount(() => {
+	onMount(async () => {
+		const d3 = await import('d3');
 		let svg = d3.select(container);
 		simulation = d3
 			.forceSimulation(nodes)
diff --git a/src/routes/(content)/getting-started/Map.svelte b/src/routes/(content)/getting-started/Map.svelte
index 3346fe77..87ef2fef 100644
--- a/src/routes/(content)/getting-started/Map.svelte
+++ b/src/routes/(content)/getting-started/Map.svelte
@@ -1,8 +1,6 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
-	import * as d3 from 'd3';
-	import * as _ from 'lodash';
+	import { sample } from '$lib/util';
 	import metric0 from '$lib/data/reference/mds/metric_0.json';
 	import metric1 from '$lib/data/reference/mds/metric_1.json';
 	import metric2 from '$lib/data/reference/mds/metric_2.json';
@@ -11,6 +9,7 @@
 	import metric5 from '$lib/data/reference/mds/metric_5.json';
 
 	let canvas, ctx, chart, timer;
+	let d3;
 
 	const metric = [
 		Object.values(metric0.data).map(x => [...x, Math.random() * 4]),
@@ -23,13 +22,11 @@
 
 	const numpoints = 200;
 
-	const colours = metric[0].map(v => d3.interpolateBlues(v[0] * 4 * v[1] + 0.4));
-
 	const change = () => {
 		clearInterval(timer);
 		const time = Math.random() * 3000 + 2000;
 		timer = setInterval(change, time);
-		chart.data.datasets[0].data = _.sample(metric).slice(0, numpoints);
+		chart.data.datasets[0].data = sample(metric).slice(0, numpoints);
 		let colour;
 		const choice = Math.random();
 		if (choice > 0.66) {
@@ -46,9 +43,16 @@
 	};
 
 	onMount(async () => {
+		const [{ Chart, registerables }, d3Mod] = await Promise.all([
+			import('chart.js'),
+			import('d3')
+		]);
+		d3 = d3Mod;
 		Chart.register(...registerables);
 		ctx = canvas.getContext('2d');
 
+		const colours = metric[0].map(v => d3.interpolateBlues(v[0] * 4 * v[1] + 0.4));
+
 		const data = {
 			datasets: [
 				{
diff --git a/src/routes/(content)/learn/refining-pitch-analysis/BanditGraph.svelte b/src/routes/(content)/learn/refining-pitch-analysis/BanditGraph.svelte
index c2506fad..55c081d9 100644
--- a/src/routes/(content)/learn/refining-pitch-analysis/BanditGraph.svelte
+++ b/src/routes/(content)/learn/refining-pitch-analysis/BanditGraph.svelte
@@ -1,7 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
-	import annotationPlugin from 'chartjs-plugin-annotation';
 	import analysis from '$lib/data/learn/refining-pitch-analysis/normpitch.json';
 
 	let chart, canvas;
@@ -9,6 +7,10 @@
 	const pitchData = Object.values(analysis.data).map(x => ({ x: x[0], y: x[1] }));
 
 	onMount(async () => {
+		const [{ Chart, registerables }, annotationPlugin] = await Promise.all([
+			import('chart.js'),
+			import('chartjs-plugin-annotation')
+		]);
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		const data = {
diff --git a/src/routes/(content)/learn/refining-pitch-analysis/RawPitchGraph.svelte b/src/routes/(content)/learn/refining-pitch-analysis/RawPitchGraph.svelte
index ce3df7a4..b7075933 100644
--- a/src/routes/(content)/learn/refining-pitch-analysis/RawPitchGraph.svelte
+++ b/src/routes/(content)/learn/refining-pitch-analysis/RawPitchGraph.svelte
@@ -1,6 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 	import analysis from '$lib/data/learn/refining-pitch-analysis/rawpitch.json';
 
 	const pitch = analysis.data.pitch;
@@ -9,6 +8,7 @@
 	let chart, canvas;
 
 	onMount(async () => {
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		let data = {
diff --git a/src/routes/(content)/learn/smoothing-data/MFCCSmooth.svelte b/src/routes/(content)/learn/smoothing-data/MFCCSmooth.svelte
index 7c139186..0ee1557d 100644
--- a/src/routes/(content)/learn/smoothing-data/MFCCSmooth.svelte
+++ b/src/routes/(content)/learn/smoothing-data/MFCCSmooth.svelte
@@ -1,6 +1,5 @@
 <script>
 	import * as Meyda from 'meyda';
-	import { Chart, registerables } from 'chart.js';
 	import { onMount } from 'svelte';
 	import { colors } from '$lib/color.js';
 	import PlayTog from '../time/PlayTog.svelte';
@@ -23,6 +22,7 @@
 	};
 
 	onMount(async () => {
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		let data = {
diff --git a/src/routes/(content)/learn/smoothing-data/Smoothing.svelte b/src/routes/(content)/learn/smoothing-data/Smoothing.svelte
index c7f47397..a20364e9 100644
--- a/src/routes/(content)/learn/smoothing-data/Smoothing.svelte
+++ b/src/routes/(content)/learn/smoothing-data/Smoothing.svelte
@@ -1,7 +1,6 @@
 <script>
 	import { onMount } from 'svelte';
 	import smooth from 'array-smooth';
-	import Two from 'two.js';
 
 	let container;
 	let raw = new Array(100).fill(0.5).map(() => Math.random()); // the value the probe reads
@@ -12,6 +11,7 @@
 	$: smoothed = smooth(raw, window);
 
 	onMount(async () => {
+		const { default: Two } = await import('two.js');
 		two = new Two({
 			type: Two.Types.svg,
 			autostart: true,
diff --git a/src/routes/(content)/learn/time/NoisePitchShape.svelte b/src/routes/(content)/learn/time/NoisePitchShape.svelte
index befbaa9b..61ded649 100644
--- a/src/routes/(content)/learn/time/NoisePitchShape.svelte
+++ b/src/routes/(content)/learn/time/NoisePitchShape.svelte
@@ -4,10 +4,10 @@ A component that plays back filtered noise, while showing how a curve can be dra
 -->
 <script>
 	import { onMount } from 'svelte';
-	import * as Tone from 'tone';
-	import Two from 'two.js';
 	import PlayTog from './PlayTog.svelte';
 
+	let Tone, Two;
+
 	let container;
 	let ampProbe, pitchProbe; // a probe to extract LFO values
 	let pitchProbeReading = new Array(90).fill(0.5); // the value the probe reads
@@ -20,6 +20,12 @@ A component that plays back filtered noise, while showing how a curve can be dra
 	let everPlayed = false;
 
 	onMount(async () => {
+		[Tone, { default: TwoModule }] = await Promise.all([
+			import('tone'),
+			import('two.js')
+		]);
+		Two = TwoModule;
+
 		two = new Two({
 			type: Two.Types.svg,
 			autostart: true,
diff --git a/src/routes/(content)/learn/time/NoiseShape.svelte b/src/routes/(content)/learn/time/NoiseShape.svelte
index 2aa01b6e..ccc96188 100644
--- a/src/routes/(content)/learn/time/NoiseShape.svelte
+++ b/src/routes/(content)/learn/time/NoiseShape.svelte
@@ -4,10 +4,10 @@ A component that plays back filtered noise, while showing how a curve can be dra
 -->
 <script>
 	import { onMount } from 'svelte';
-	import * as Tone from 'tone';
-	import Two from 'two.js';
 	import PlayTog from './PlayTog.svelte';
 
+	let Tone, Two;
+
 	let container;
 	let probe; // a probe to extract LFO values
 	let probeReading = new Array(90).fill(0.5); // the value the probe reads
@@ -18,6 +18,12 @@ A component that plays back filtered noise, while showing how a curve can be dra
 	let everPlayed = false;
 
 	onMount(async () => {
+		[Tone, { default: TwoModule }] = await Promise.all([
+			import('tone'),
+			import('two.js')
+		]);
+		Two = TwoModule;
+
 		two = new Two({
 			type: Two.Types.svg,
 			autostart: true,
diff --git a/src/routes/(content)/learn/time/PitchShape.svelte b/src/routes/(content)/learn/time/PitchShape.svelte
index bd12b53f..c6de5f91 100644
--- a/src/routes/(content)/learn/time/PitchShape.svelte
+++ b/src/routes/(content)/learn/time/PitchShape.svelte
@@ -4,10 +4,10 @@
 -->
 <script>
 	import { onMount } from 'svelte';
-	import * as Tone from 'tone';
-	import Two from 'two.js';
 	import PlayTog from './PlayTog.svelte';
 
+	let Tone, Two;
+
 	let container;
 	let probe; // a probe to extract LFO values
 	let probeReading = new Array(90).fill(0.5); // the value the probe reads
@@ -18,6 +18,12 @@
 	let everPlayed = false;
 
 	onMount(async () => {
+		[Tone, { default: TwoModule }] = await Promise.all([
+			import('tone'),
+			import('two.js')
+		]);
+		Two = TwoModule;
+
 		two = new Two({
 			type: Two.Types.svg,
 			autostart: true,
diff --git a/src/routes/(content)/reference/ampfeature/AmpFeature.svelte b/src/routes/(content)/reference/ampfeature/AmpFeature.svelte
index 79302976..8b8b9ce4 100644
--- a/src/routes/(content)/reference/ampfeature/AmpFeature.svelte
+++ b/src/routes/(content)/reference/ampfeature/AmpFeature.svelte
@@ -1,11 +1,11 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 	import feature from '$lib/data/reference/ampfeature/data.json';
 
 	let chart, canvas;
 
 	onMount(async () => {
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		let data = {
diff --git a/src/routes/(content)/reference/chroma/Chroma.svelte b/src/routes/(content)/reference/chroma/Chroma.svelte
index f67456b6..7c5cbfe6 100644
--- a/src/routes/(content)/reference/chroma/Chroma.svelte
+++ b/src/routes/(content)/reference/chroma/Chroma.svelte
@@ -1,6 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 	import * as Meyda from 'meyda';
 	import Button from '$lib/components/Button.svelte';
 
@@ -32,6 +31,7 @@
 
 	onMount(async () => {
 		// Chart
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		ctx = canvas.getContext('2d');
 		const labels = 'A A# B C C# D D# E F F# G G#'.split(' ');
diff --git a/src/routes/(content)/reference/grid/Grid.svelte b/src/routes/(content)/reference/grid/Grid.svelte
index b082c84d..4558161d 100644
--- a/src/routes/(content)/reference/grid/Grid.svelte
+++ b/src/routes/(content)/reference/grid/Grid.svelte
@@ -1,7 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
-	import * as d3 from 'd3';
 	import Button from '$lib/components/Button.svelte';
 	import gaussian4 from '$lib/data/datasets/gaussian4.json';
 	import out from '$lib/data/reference/grid/out.json';
@@ -10,9 +8,12 @@
 
 	const raw = Object.values(gaussian4.data);
 	const grid = Object.values(out.data);
-	const colours = raw.map(x => d3.interpolateSinebow(x[0] * x[1]));
-
 	onMount(async () => {
+		const [{ Chart, registerables }, d3] = await Promise.all([
+			import('chart.js'),
+			import('d3')
+		]);
+		const colours = raw.map(x => d3.interpolateSinebow(x[0] * x[1]));
 		Chart.register(...registerables);
 		ctx = canvas.getContext('2d');
 
diff --git a/src/routes/(content)/reference/grid/GridExtent.svelte b/src/routes/(content)/reference/grid/GridExtent.svelte
index 9394d2ea..afd0bdaf 100644
--- a/src/routes/(content)/reference/grid/GridExtent.svelte
+++ b/src/routes/(content)/reference/grid/GridExtent.svelte
@@ -1,7 +1,5 @@
 <script>
-	import * as d3 from 'd3';
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 	import Button from '$lib/components/Button.svelte';
 	import gaussian4 from '$lib/data/datasets/gaussian4.json';
 	import extent1 from '$lib/data/reference/grid/extent.2.v.json';
@@ -14,9 +12,12 @@
 	const btnHeight = '50px';
 
 	const raw = Object.values(gaussian4.data);
-	const colours = raw.map(x => d3.interpolateSinebow(x[0] * x[1]));
-
 	onMount(async () => {
+		const [{ Chart, registerables }, d3] = await Promise.all([
+			import('chart.js'),
+			import('d3')
+		]);
+		const colours = raw.map(x => d3.interpolateSinebow(x[0] * x[1]));
 		Chart.register(...registerables);
 		ctx = canvas.getContext('2d');
 
diff --git a/src/routes/(content)/reference/grid/GridOversample.svelte b/src/routes/(content)/reference/grid/GridOversample.svelte
index 8d2e644e..72694b9a 100644
--- a/src/routes/(content)/reference/grid/GridOversample.svelte
+++ b/src/routes/(content)/reference/grid/GridOversample.svelte
@@ -1,7 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
-	import * as d3 from 'd3';
 	import Button from '$lib/components/Button.svelte';
 	import gaussian4 from '$lib/data/datasets/gaussian4.json';
 	import oversample1 from '$lib/data/reference/grid/help.grid.oversample.1.json';
@@ -15,9 +13,12 @@
 	const btnWidth = '180px';
 
 	const raw = Object.values(gaussian4.data);
-	const colours = raw.map(x => d3.interpolateSinebow(x[0] * x[1]));
-
 	onMount(async () => {
+		const [{ Chart, registerables }, d3] = await Promise.all([
+			import('chart.js'),
+			import('d3')
+		]);
+		const colours = raw.map(x => d3.interpolateSinebow(x[0] * x[1]));
 		Chart.register(...registerables);
 		ctx = canvas.getContext('2d');
 
diff --git a/src/routes/(content)/reference/kdtree/KDTree.svelte b/src/routes/(content)/reference/kdtree/KDTree.svelte
index aa438efd..da6fd62a 100644
--- a/src/routes/(content)/reference/kdtree/KDTree.svelte
+++ b/src/routes/(content)/reference/kdtree/KDTree.svelte
@@ -4,7 +4,6 @@
  -->
 <script>
 	import { onMount } from 'svelte';
-	import { CanvasSpace, Create, Circle } from 'pts';
 	import Slider from '$lib/components/Slider.svelte';
 	import Button from '$lib/components/Button.svelte';
 
@@ -26,6 +25,7 @@
 	}
 
 	onMount(async () => {
+		const { CanvasSpace, Create, Circle } = await import('pts');
 		let space = new CanvasSpace('#sketch');
 		let darkBlue = 'rgba(8, 60, 100,0.5)';
 		space.setup({
diff --git a/src/routes/(content)/reference/kmeans/KMeans.svelte b/src/routes/(content)/reference/kmeans/KMeans.svelte
index cb6272fd..959ef64a 100644
--- a/src/routes/(content)/reference/kmeans/KMeans.svelte
+++ b/src/routes/(content)/reference/kmeans/KMeans.svelte
@@ -1,10 +1,8 @@
 <script>
-	import { interpolateSinebow } from 'd3';
-	import { tensor } from '@tensorflow/tfjs';
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
+
+	let interpolateSinebow, tensor, KMeans;
 	import Button from '$lib/components/Button.svelte';
-	import KMeans from '@flucoma/tf-kmeans';
 	import Select from 'svelte-select';
 	import datasets from '$lib/data/datasets/datasets.json';
 
@@ -59,6 +57,20 @@
 	};
 
 	onMount(async () => {
+		const [
+			{ Chart, registerables },
+			d3Mod,
+			tfjsMod,
+			tfKmeansMod
+		] = await Promise.all([
+			import('chart.js'),
+			import('d3'),
+			import('@tensorflow/tfjs'),
+			import('@flucoma/tf-kmeans')
+		]);
+		interpolateSinebow = d3Mod.interpolateSinebow;
+		tensor = tfjsMod.tensor;
+		KMeans = tfKmeansMod.default;
 		Chart.register(...registerables);
 		ctx = canvas.getContext('2d');
 
diff --git a/src/routes/(content)/reference/loudness/Loudness.svelte b/src/routes/(content)/reference/loudness/Loudness.svelte
index 7ca5fe76..a7407d52 100644
--- a/src/routes/(content)/reference/loudness/Loudness.svelte
+++ b/src/routes/(content)/reference/loudness/Loudness.svelte
@@ -1,7 +1,6 @@
 <script>
 	import { fromArrayBuffer } from 'numpy-parser';
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 
 	const db = '/reference/loudness/db.npy';
 	const freq = '/reference/loudness/filter.npy';
@@ -31,6 +30,7 @@
 			});
 
 		// Chart
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		let data = {
diff --git a/src/routes/(content)/reference/mds/MDS.svelte b/src/routes/(content)/reference/mds/MDS.svelte
index eba816a9..bfecfc8b 100644
--- a/src/routes/(content)/reference/mds/MDS.svelte
+++ b/src/routes/(content)/reference/mds/MDS.svelte
@@ -1,7 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
-	import * as d3 from 'd3';
 	import Button from '$lib/components/Button.svelte';
 	import metric0 from '$lib/data/reference/mds/metric_0.json';
 	import metric1 from '$lib/data/reference/mds/metric_1.json';
@@ -25,9 +23,12 @@
 
 	const labels = ['Manhattan', 'Euclidian', 'Squared Euclidian', 'Max Distance', 'Min Distance', 'KL Divergence'];
 
-	const colours = metric[0].map(v => d3.interpolateSinebow(v[0] * 2 * v[1]));
-
 	onMount(async () => {
+		const [{ Chart, registerables }, d3] = await Promise.all([
+			import('chart.js'),
+			import('d3')
+		]);
+		const colours = metric[0].map(v => d3.interpolateSinebow(v[0] * 2 * v[1]));
 		Chart.register(...registerables);
 		ctx = canvas.getContext('2d');
 
diff --git a/src/routes/(content)/reference/mfcc/DropZero.svelte b/src/routes/(content)/reference/mfcc/DropZero.svelte
index 3d849b7b..24318786 100644
--- a/src/routes/(content)/reference/mfcc/DropZero.svelte
+++ b/src/routes/(content)/reference/mfcc/DropZero.svelte
@@ -1,6 +1,5 @@
 <script>
 	import * as Meyda from 'meyda';
-	import { Chart, registerables } from 'chart.js';
 	import { onMount } from 'svelte';
 	import { colors } from '$lib/color.js';
 	import Audio from '$lib/components/Audio.svelte';
@@ -23,6 +22,7 @@
 	};
 
 	onMount(async () => {
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		let data = {
diff --git a/src/routes/(content)/reference/noveltyfeature/NoveltyFeature.svelte b/src/routes/(content)/reference/noveltyfeature/NoveltyFeature.svelte
index 70bd18a4..eff5ed41 100644
--- a/src/routes/(content)/reference/noveltyfeature/NoveltyFeature.svelte
+++ b/src/routes/(content)/reference/noveltyfeature/NoveltyFeature.svelte
@@ -1,11 +1,11 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 	import feature from '$lib/data/reference/noveltyfeature/data.json';
 
 	let chart, canvas;
 
 	onMount(async () => {
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		let data = {
diff --git a/src/routes/(content)/reference/onsetfeature/OnsetFeature.svelte b/src/routes/(content)/reference/onsetfeature/OnsetFeature.svelte
index 8b96d536..a310ae34 100644
--- a/src/routes/(content)/reference/onsetfeature/OnsetFeature.svelte
+++ b/src/routes/(content)/reference/onsetfeature/OnsetFeature.svelte
@@ -1,11 +1,11 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 	import feature from '$lib/data/reference/onsetfeature/data.json';
 
 	let chart, canvas;
 
 	onMount(async () => {
+		const { Chart, registerables } = await import('chart.js');
 		Chart.register(...registerables);
 		const ctx = canvas.getContext('2d');
 		let data = {
diff --git a/src/routes/(content)/reference/onsetslice/OnsetSlice.svelte b/src/routes/(content)/reference/onsetslice/OnsetSlice.svelte
index cf1eee78..39b0aec8 100644
--- a/src/routes/(content)/reference/onsetslice/OnsetSlice.svelte
+++ b/src/routes/(content)/reference/onsetslice/OnsetSlice.svelte
@@ -1,9 +1,7 @@
 <script>
 	import { onMount } from 'svelte';
 	import { fromArrayBuffer } from 'numpy-parser';
-	import { Chart, registerables } from 'chart.js';
 	import { pairwise, scale } from '$lib/util';
-	import annotationPlugin from 'chartjs-plugin-annotation';
 
 	let canvas, ctx, chart;
 	let curve = [0, 0];
@@ -55,6 +53,10 @@
 			window.ResizeObserver = module.ResizeObserver;
 		}
 		// Chart
+		const [{ Chart, registerables }, annotationPlugin] = await Promise.all([
+			import('chart.js'),
+			import('chartjs-plugin-annotation').then(m => m.default)
+		]);
 		Chart.register(...registerables, annotationPlugin);
 		ctx = canvas.getContext('2d');
 		const data = {
diff --git a/src/routes/(content)/reference/spectralshape/Spectrogram.svelte b/src/routes/(content)/reference/spectralshape/Spectrogram.svelte
index 115bd128..e3dc1cfe 100644
--- a/src/routes/(content)/reference/spectralshape/Spectrogram.svelte
+++ b/src/routes/(content)/reference/spectralshape/Spectrogram.svelte
@@ -1,7 +1,5 @@
 <script>
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
-	import annotationPlugin from 'chartjs-plugin-annotation';
 
 	export let windowSize = 512;
 	export let spectrum = new Array(windowSize).fill(0.0);
@@ -14,6 +12,10 @@
 
 	onMount(async () => {
 		// Chart
+		const [{ Chart, registerables }, annotationPlugin] = await Promise.all([
+			import('chart.js'),
+			import('chartjs-plugin-annotation').then(m => m.default)
+		]);
 		Chart.register(...registerables, annotationPlugin);
 		ctx = canvas.getContext('2d');
 		const data = {
diff --git a/src/routes/(content)/reference/umap/UMAP.svelte b/src/routes/(content)/reference/umap/UMAP.svelte
index 75ca9469..ca0ae98f 100644
--- a/src/routes/(content)/reference/umap/UMAP.svelte
+++ b/src/routes/(content)/reference/umap/UMAP.svelte
@@ -1,10 +1,9 @@
 <script>
-	import { UMAP } from 'umap-js';
 	import { onMount } from 'svelte';
-	import { Chart, registerables } from 'chart.js';
 	import Slider from '$lib/components/Slider.svelte';
 	import Button from '$lib/components/Button.svelte';
-	import * as d3 from 'd3';
+
+	let UMAP, d3;
 
 	let canvas, chart, ctx;
 
@@ -120,6 +119,14 @@
 	};
 
 	onMount(async () => {
+		const [{ Chart, registerables }, d3Mod, umapMod] = await Promise.all([
+			import('chart.js'),
+			import('d3'),
+			import('umap-js')
+		]);
+		d3 = d3Mod;
+		UMAP = umapMod.UMAP;
+
 		newData();
 		// Do an initial reduction from the random data to 2 dimensions
 		step();

From 81e454ca1716bd7b32155e44c345765ae1e30e68 Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:30:16 +0800
Subject: [PATCH 02/13] add CSS design token system

---
 src/app.css           | 378 ++++++++++++++++++++++++++++++++----------
 src/design-tokens.css | 177 ++++++++++++++++++++
 2 files changed, 466 insertions(+), 89 deletions(-)
 create mode 100644 src/design-tokens.css

diff --git a/src/app.css b/src/app.css
index d22767e7..726a0c09 100644
--- a/src/app.css
+++ b/src/app.css
@@ -1,8 +1,8 @@
 /* 
-Taking lots of inspiration from Distill.pub 
-https://github.com/distillpub/template/blob/master/src/styles/d-article.css 
-g*/
+   Inspired by Distill.pub: https://github.com/distillpub/template/blob/master/src/styles/d-article.css
+*/
 
+@import './design-tokens.css';
 @import './fonts.css';
 @import './code.css';
 @import './utils.css';
@@ -10,146 +10,346 @@ g*/
 @import './flair.css';
 @import './classes.css';
 
-:root {
-	--breakpoint: 1200px;
-	--font: 'overpassregular', sans-serif;
-	--mono: 'Overpass Mono', monospace;
-	--dark-blue: #083c64;
-	--med-blue: #0371b5;
-	--light-blue: #1ca4fc;
-	--max-text-width: 70ch;
-	--min-text-width: 30ch;
-	--footer-height: 55px;
-	--event-flair: rgb(235, 161, 23);
-	--article-flair: var(--med-blue);
-	--reference-flair: rgb(34, 140, 34);
-	--podcast-flair: palevioletred;
-	--tutorial-flair: rgba(102, 103, 171, 255);
-	--grey: rgb(89, 89, 89);
-}
-
-* {
+/* ── Reset & Base ────────────────────────────────────────── */
+
+*,
+*::before,
+*::after {
 	box-sizing: border-box;
 }
 
 html {
-	font-family: var(--font);
+	font-family: var(--font-sans);
 	font-size: 16px;
 	-ms-text-size-adjust: 100%;
 	-webkit-text-size-adjust: 100%;
+	scroll-behavior: smooth;
 }
 
 body {
 	margin: 0;
-	line-height: 1.5;
+	line-height: var(--leading-normal);
 	text-rendering: optimizeLegibility;
 	-webkit-font-smoothing: antialiased;
 	-moz-osx-font-smoothing: grayscale;
-	color: #333; /* Default text color */
+	color: var(--color-text);
+	background-color: var(--color-background);
+}
+
+/* ── Typography ──────────────────────────────────────────── */
+
+h1, h2, h3, h4, h5, h6 {
+	font-family: var(--font-sans);
+	color: var(--color-neutral-900);
+	text-wrap: balance;
+}
+
+h1 {
+	font-size: var(--text-4xl);
+	font-weight: var(--font-extrabold);
+	line-height: var(--leading-tight);
+	letter-spacing: var(--tracking-tight);
+	margin: 0 0 0.5em;
+}
+
+h2 {
+	font-size: var(--text-3xl);
+	font-weight: var(--font-bold);
+	line-height: var(--leading-snug);
+	letter-spacing: var(--tracking-tight);
+	margin: var(--heading-spacing) 0 var(--heading-spacing);
+	padding: 0;
+}
+
+h3 {
+	font-size: var(--text-2xl);
+	font-weight: var(--font-semibold);
+	line-height: var(--leading-snug);
+	margin: 1.25em 0 0.5em;
+}
+
+h4 {
+	font-size: var(--text-xl);
+	font-weight: var(--font-semibold);
+	line-height: var(--leading-snug);
+	margin: 1em 0 0.4em;
 }
 
-h1,
-h2,
-h3,
-h4,
-h5,
-h6 {
-	font-family: var(--font);
-	margin: 0.6em 0;
-	line-height: 1.3;
+h5, h6 {
+	font-size: var(--text-lg);
+	font-weight: var(--font-bold);
+	line-height: var(--leading-snug);
+	margin: 1em 0 0.4em;
+}
+
+/* Body text with consistent rhythm */
+p {
+	margin: 0 0 var(--paragraph-spacing);
+	line-height: var(--leading-relaxed);
 }
 
-ul,
-ol,
-p,
 blockquote {
-	margin-top: 0;
-	margin-bottom: 1em;
-	margin-left: 0;
-	margin-right: 0;
-	line-height: 1.7em;
+	margin: var(--space-8) 0;
+	padding: 0;
 }
 
-li > p {
-	line-height: 1.2em;
+/* ── Lists ───────────────────────────────────────────────── */
+
+ul, ol {
+	margin: 0 0 var(--paragraph-spacing);
+	padding-left: 1.75em;
+	line-height: var(--leading-relaxed);
 }
 
 li {
-	margin-left: 0;
-	margin-right: 0;
+	margin-bottom: 0.35em;
 }
 
-h1 {
-	font-size: 2.625em;
-	line-height: 1.2;
+li:last-child {
+	margin-bottom: 0;
 }
 
-h2 {
-	font-size: 1.625em;
-	line-height: 1.2;
+li > p {
+	line-height: var(--leading-normal);
+	margin-bottom: 0.3em;
 }
 
-h3 {
-	font-size: 1.3125em;
-	line-height: 1.24;
+/* Nested lists */
+li > ul, li > ol {
+	margin-top: 0.35em;
+	margin-bottom: 0;
 }
 
-h4 {
-	font-size: 1.1875em;
-	line-height: 1.23;
+/* Custom bullet for unordered lists in articles */
+main ul {
+	list-style: none;
+	padding-left: 1.5em;
+}
+
+main ul > li {
+	position: relative;
+}
+
+main ul > li::before {
+	content: '';
+	position: absolute;
+	left: -1.25em;
+	top: 0.6em;
+	width: 6px;
+	height: 6px;
+	border-radius: 50%;
+	background-color: var(--color-primary-300);
+}
+
+main ul ul > li::before {
+	width: 5px;
+	height: 5px;
+	border-radius: 50%;
+	border: 1.5px solid var(--color-primary-300);
+	background-color: transparent;
+	top: 0.55em;
+}
+
+/* ── Definition Lists ────────────────────────────────────── */
+
+dl {
+	margin: var(--space-6) 0;
+}
+
+dt {
+	font-weight: var(--font-bold);
+	font-size: var(--text-base);
+	color: var(--color-primary-800);
+	margin-top: var(--space-4);
+	margin-bottom: var(--space-1);
+}
+
+dt:first-child {
+	margin-top: 0;
+}
+
+dd {
+	margin-left: var(--space-5);
+	margin-bottom: var(--space-3);
+	color: var(--color-text-muted);
+	line-height: var(--leading-normal);
+	font-size: var(--text-sm);
+}
+
+dd:last-child {
+	margin-bottom: 0;
+}
+
+/* ── Tables ──────────────────────────────────────────────── */
+
+table {
+	width: 100%;
+	margin: var(--space-6) 0;
+	border-collapse: collapse;
+	font-size: var(--text-sm);
+	line-height: var(--leading-normal);
+	border-radius: var(--radius-md);
+	overflow: hidden;
+	box-shadow: var(--shadow-sm);
+}
+
+thead {
+	background-color: var(--color-primary-50);
+}
+
+th {
+	text-align: left;
+	padding: var(--space-3) var(--space-4);
+	font-weight: var(--font-bold);
+	color: var(--color-primary-800);
+	font-size: var(--text-xs);
+	text-transform: uppercase;
+	letter-spacing: var(--tracking-wide);
+	border-bottom: 2px solid var(--color-primary-200);
+}
+
+td {
+	padding: var(--space-3) var(--space-4);
+	border-bottom: 1px solid var(--color-neutral-200);
+	color: var(--color-text);
 }
 
-h5,
-h6 {
-	font-size: 1em;
-	font-weight: bold;
+tbody tr:last-child td {
+	border-bottom: none;
 }
 
+tbody tr:nth-child(even) {
+	background-color: var(--color-neutral-50);
+}
+
+tbody tr:hover {
+	background-color: rgba(28, 164, 252, 0.04);
+}
+
+/* Responsive table wrapper — wrap tables in a div.table-wrap */
+.table-wrap {
+	width: 100%;
+	overflow-x: auto;
+	-webkit-overflow-scrolling: touch;
+	margin: var(--space-6) 0;
+}
+
+.table-wrap table {
+	margin: 0;
+	min-width: 100%;
+}
+
+/* ── Links ───────────────────────────────────────────────── */
+
 a {
-	color: var(--med-blue);
-	max-width: max-content;
+	color: var(--color-link);
+	text-decoration-thickness: 1px;
+	text-underline-offset: 2px;
+	transition: color var(--transition-fast), background-color var(--transition-fast);
+	border-radius: 2px;
 }
 
 a:hover {
-	color: white;
-	background: var(--med-blue);
+	color: var(--color-link-hover-text);
+	background: var(--color-link-hover-bg);
+	text-decoration-color: transparent;
 }
 
-.title-box:after {
-	margin-top: 0.5em;
-	margin-bottom: 0.5em;
+/* Inline links in paragraphs get subtler treatment */
+p a, li a, figcaption a {
+	text-decoration: underline;
+	text-decoration-color: rgba(3, 113, 181, 0.3);
+}
+
+p a:hover, li a:hover, figcaption a:hover {
+	text-decoration-color: transparent;
+}
+
+/* ── Code ────────────────────────────────────────────────── */
+
+code {
+	font-family: var(--font-mono);
+	font-size: 0.9em;
+	color: var(--color-code-text);
+	background-color: var(--color-code-bg);
+	padding: 0.15em 0.35em;
+	border-radius: 3px;
+	border: 1px solid var(--color-neutral-200);
+}
+
+pre code {
+	border: none;
+	padding: 0;
+	background: none;
+	font-size: 0.875rem;
+}
+
+/* ── Title Box ───────────────────────────────────────────── */
+
+.title-box::after {
+	margin-top: var(--space-4);
+	margin-bottom: var(--space-4);
 	height: 1px;
-	content: ' ';
+	content: '';
 	display: block;
-	border-top: 0.5px solid #dcdee0;
+	border: none;
+	background: linear-gradient(
+		to right,
+		var(--color-border),
+		transparent 80%
+	);
 }
 
-code {
-	font-family: var(--mono);
-	font-size: 1em;
-	color: #555;
-	background-color: #f0f0f0;
-	padding: 0.1em 0.1em;
-	border-radius: 2px;
+/* ── Horizontal Rules ────────────────────────────────────── */
+
+hr {
+	border: none;
+	height: 1px;
+	margin: var(--space-8) 0;
+	background: linear-gradient(
+		to right,
+		transparent,
+		var(--color-neutral-300) 20%,
+		var(--color-neutral-300) 80%,
+		transparent
+	);
 }
 
+/* ── Heading Anchor Links ────────────────────────────────── */
+
 .autolink {
 	width: 16px;
 	height: 16px;
 	padding-left: 0.3em;
 	padding-right: 0.3em;
+	opacity: 0;
+	transition: opacity var(--transition-fast);
+}
+
+h2:hover .autolink,
+h3:hover .autolink,
+h4:hover .autolink {
+	opacity: 0.5;
 }
 
 h2 > a:hover {
 	background-color: transparent;
 }
 
-/* New styles for consistency across components */
+/* ── Selection ───────────────────────────────────────────── */
+
+::selection {
+	background-color: rgba(28, 164, 252, 0.2);
+	color: var(--color-neutral-900);
+}
+
+/* ── Shared Utility Classes ──────────────────────────────── */
+
 .component-title {
-	font-size: 1.2rem;
-	font-weight: bold;
-	margin-bottom: 0.5em;
-	line-height: 1.3;
+	font-size: var(--text-md);
+	font-weight: var(--font-bold);
+	margin-bottom: var(--space-2);
+	line-height: var(--leading-snug);
 }
 
 .component-text {
@@ -158,24 +358,24 @@ h2 > a:hover {
 }
 
 .small-text {
-	font-size: 0.8rem;
+	font-size: var(--text-xs);
 }
 
 .flair, .url {
-	font-size: 0.75rem;
-	font-weight: bold;
+	font-size: var(--text-xs);
+	font-weight: var(--font-bold);
 }
 
 .hover-effect {
-	transition: transform 0.3s ease, box-shadow 0.3s ease;
+	transition: transform var(--transition-slow), box-shadow var(--transition-slow);
 }
 
 .hover-effect:hover {
 	transform: translateY(-2px);
-	box-shadow: 0 8px 12px rgba(0, 0, 0, 0.1), 0 3px 6px rgba(0, 0, 0, 0.08);
+	box-shadow: var(--shadow-md);
 }
 
 .rounded-corners {
-	border-radius: 12px;
+	border-radius: var(--radius-lg);
 	overflow: hidden;
 }
diff --git a/src/design-tokens.css b/src/design-tokens.css
new file mode 100644
index 00000000..19c304c8
--- /dev/null
+++ b/src/design-tokens.css
@@ -0,0 +1,177 @@
+/* FluCoMa Learn — Design Tokens */
+
+:root {
+	/* ── Color Palette ─────────────────────────────────────── */
+
+	/* Primary (Brand Blue) */
+	--color-primary-50: #e6f2fa;
+	--color-primary-100: #b3d8f0;
+	--color-primary-200: #80bef0;
+	--color-primary-300: #4da8f5;
+	--color-primary-400: #1ca4fc;
+	--color-primary-500: #0390d6;
+	--color-primary-600: #0371b5;
+	--color-primary-700: #025891;
+	--color-primary-800: #083c64;
+	--color-primary-900: #042038;
+
+	/* Neutral (Gray) */
+	--color-neutral-50: #f8f9fa;
+	--color-neutral-100: #f0f0f0;
+	--color-neutral-200: #e0e0e0;
+	--color-neutral-300: #dcdee0;
+	--color-neutral-400: #b0b3b5;
+	--color-neutral-500: #8a8d90;
+	--color-neutral-600: #595959;
+	--color-neutral-700: #4a4d50;
+	--color-neutral-800: #333333;
+	--color-neutral-900: #1a1a1a;
+
+	/* Content-Type Accents (flairs) */
+	--color-article: #1ca4fc;
+	--color-event: #eba117;
+	--color-reference: #228c22;
+	--color-podcast: #db7093;
+	--color-tutorial: #6667ab;
+
+	/* Admonition / Semantic */
+	--color-note-bg: rgba(52, 52, 171, 0.2);
+	--color-note-border: rgba(31, 31, 136, 0.63);
+	--color-note-text: #414141;
+	--color-warning-bg: rgba(255, 204, 0, 0.2);
+	--color-warning-border: rgba(255, 204, 0, 0.63);
+	--color-danger-bg: rgba(204, 51, 0, 0.2);
+	--color-danger-border: rgba(204, 51, 0, 0.63);
+	--color-success-bg: rgba(230, 252, 224, 1);
+	--color-success-border: rgb(133, 229, 106);
+
+	/* Semantic Aliases (consume these in components) */
+	--color-text: var(--color-neutral-800);
+	--color-text-muted: var(--color-neutral-600);
+	--color-text-inverted: #ffffff;
+	--color-background: #ffffff;
+	--color-surface: var(--color-neutral-50);
+	--color-border: var(--color-neutral-300);
+	--color-link: var(--color-primary-600);
+	--color-link-hover-bg: var(--color-primary-600);
+	--color-link-hover-text: #ffffff;
+	--color-code-bg: var(--color-neutral-100);
+	--color-code-text: #555555;
+	--color-code-block-bg: #f7f7f7;
+
+	/* ── Typography ────────────────────────────────────────── */
+
+	--font-sans: 'overpassregular', sans-serif;
+	--font-mono: 'Overpass Mono', monospace;
+
+	/* Type Scale (1.25 major-third ratio) */
+	--text-xs: 0.75rem;     /* 12px */
+	--text-sm: 0.875rem;    /* 14px */
+	--text-base: 1rem;      /* 16px */
+	--text-md: 1.125rem;    /* 18px */
+	--text-lg: 1.25rem;     /* 20px */
+	--text-xl: 1.5rem;      /* 24px */
+	--text-2xl: 1.75rem;    /* 28px */
+	--text-3xl: 2.125rem;   /* 34px */
+	--text-4xl: 2.5rem;     /* 40px (h1) */
+
+	/* Font Weights */
+	--font-normal: 400;
+	--font-semibold: 600;
+	--font-bold: 700;
+	--font-extrabold: 800;
+
+	/* Letter Spacing */
+	--tracking-tight: -0.015em;
+	--tracking-normal: 0;
+	--tracking-wide: 0.02em;
+
+	/* Line Heights */
+	--leading-tight: 1.15;
+	--leading-snug: 1.25;
+	--leading-normal: 1.6;
+	--leading-relaxed: 1.75;
+
+	/* Content Rhythm */
+	--paragraph-spacing: 1.25em;
+	--heading-spacing: 0.5em;
+	--section-spacing: 2em;
+
+	/* ── Spacing Scale (4px base) ──────────────────────────── */
+
+	--space-0: 0;
+	--space-1: 0.25rem;   /* 4px */
+	--space-2: 0.5rem;    /* 8px */
+	--space-3: 0.75rem;   /* 12px */
+	--space-4: 1rem;      /* 16px */
+	--space-5: 1.25rem;   /* 20px */
+	--space-6: 1.5rem;    /* 24px */
+	--space-8: 2rem;      /* 32px */
+	--space-10: 2.5rem;   /* 40px */
+	--space-12: 3rem;     /* 48px */
+	--space-16: 4rem;     /* 64px */
+
+	/* ── Border Radius ─────────────────────────────────────── */
+
+	--radius-none: 0;
+	--radius-sm: 0.25rem;  /* 4px — subtle rounding */
+	--radius-md: 0.5rem;   /* 8px — cards, inputs */
+	--radius-lg: 0.75rem;  /* 12px — containers, modals */
+	--radius-xl: 1rem;     /* 16px */
+	--radius-full: 9999px; /* pills, badges */
+
+	/* ── Shadows / Elevation ───────────────────────────────── */
+
+	--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.06), 0 1px 3px rgba(0, 0, 0, 0.1);
+	--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07), 0 2px 4px rgba(0, 0, 0, 0.06);
+	--shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.08), 0 4px 6px rgba(0, 0, 0, 0.05);
+	--shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.1), 0 10px 10px rgba(0, 0, 0, 0.04);
+
+	/* Interactive shadow (brand-tinted for raised cards/buttons) */
+	--shadow-interactive: var(--color-primary-600) -5px 5px 0px -3px,
+		rgba(3, 113, 181, 0.2) -10px 10px,
+		rgba(3, 113, 181, 0.1) -15px 15px,
+		rgba(3, 113, 181, 0.05) -20px 20px;
+
+	/* ── Transitions ───────────────────────────────────────── */
+
+	--transition-fast: 150ms ease;
+	--transition-base: 200ms ease;
+	--transition-slow: 300ms ease;
+
+	/* ── Breakpoints (reference; use in media queries) ─────── */
+
+	--bp-tablet: 768px;
+	--bp-desktop: 1200px;
+
+	/* ── Layout ────────────────────────────────────────────── */
+
+	--max-text-width: 70ch;
+	--min-text-width: 30ch;
+	--header-height: 55px;
+	--footer-height: 55px;
+
+	/* ── Cards ─────────────────────────────────────────────── */
+
+	--card-radius: var(--radius-lg);
+	--card-shadow: 0 1px 3px rgba(0, 0, 0, 0.06), 0 4px 12px rgba(0, 0, 0, 0.04);
+	--card-shadow-hover: 0 2px 6px rgba(0, 0, 0, 0.08), 0 8px 24px rgba(0, 0, 0, 0.06);
+	--card-image-overlay: linear-gradient(180deg, transparent 55%, rgba(8, 60, 100, 0.75) 100%);
+	--card-transition: transform 0.35s cubic-bezier(0.25, 0.46, 0.45, 0.94),
+		box-shadow 0.35s cubic-bezier(0.25, 0.46, 0.45, 0.94);
+
+	/* ── Backwards-compat aliases (keep old var names working) ─ */
+
+	--font: var(--font-sans);
+	--mono: var(--font-mono);
+	--dark-blue: var(--color-primary-800);
+	--med-blue: var(--color-primary-600);
+	--light-blue: var(--color-primary-400);
+	--grey: var(--color-neutral-600);
+	--breakpoint: var(--bp-desktop);
+	--event-flair: var(--color-event);
+	--article-flair: var(--color-article);
+	--reference-flair: var(--color-reference);
+	--podcast-flair: var(--color-podcast);
+	--tutorial-flair: var(--color-tutorial);
+}

From 421f2ab44c12161f458a6bf3338f9f28754a936b Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:30:19 +0800
Subject: [PATCH 03/13] add Button variants and anchor support

---
 src/lib/components/Button.svelte | 113 +++++++++++++++++++++++--------
 1 file changed, 86 insertions(+), 27 deletions(-)

diff --git a/src/lib/components/Button.svelte b/src/lib/components/Button.svelte
index 16521dfc..e6e57de7 100644
--- a/src/lib/components/Button.svelte
+++ b/src/lib/components/Button.svelte
@@ -1,47 +1,106 @@
 <script>
 	export let label = 'button';
-	export let width = '100px';
-	export let height = '38px';
+	export let variant = 'primary';
+	export let width = undefined;
+	export let height = undefined;
 	export let disabled = false;
+	export let href = '';
 </script>
 
-<button class="btn" style:width style:height class:disabled on:click {disabled}>
-	{label}
-</button>
+{#if href}
+	<a
+		class="btn {variant}"
+		class:disabled
+		style:width
+		style:height
+		{href}
+		on:click
+	>
+		{label}
+	</a>
+{:else}
+	<button
+		class="btn {variant}"
+		class:disabled
+		style:width
+		style:height
+		{disabled}
+		on:click
+	>
+		{label}
+	</button>
+{/if}
 
-<style >
+<style>
 	.btn {
-		cursor:pointer;
-		border: 2px outset var(--med-blue);
-		display: grid;
+		display: inline-grid;
 		place-items: center;
-		width: 150px;
-		height: 40px;
-		background-color: var(--light-blue);
-		color: white;
+		font-family: var(--font-sans);
+		font-size: var(--text-base);
+		font-weight: var(--font-bold);
 		text-decoration: none;
-		transition: background-color 75ms linear;
-		word-wrap: none;
-		overflow: hidden;
+		color: var(--color-text-inverted);
+		border: 2px solid transparent;
+		border-radius: var(--radius-lg);
+		cursor: pointer;
+		padding: var(--space-2) var(--space-5);
 		min-width: fit-content;
-		font-size: 1rem;
-		font-family: var(--font);
+		white-space: nowrap;
+		transition:
+			background-color var(--transition-fast),
+			transform var(--transition-base),
+			box-shadow var(--transition-base);
+		line-height: 1.2;
 	}
 
-	.btn:hover {
-		background-color: var(--med-blue);
+	.primary {
+		background-color: var(--color-primary-800);
+		box-shadow: 0 4px 6px rgba(3, 113, 181, 0.2),
+					0 1px 3px rgba(3, 113, 181, 0.1);
+	}
+	.primary:hover {
+		background-color: var(--color-primary-600);
+		transform: translateY(-2px);
+		box-shadow: 0 8px 12px rgba(3, 113, 181, 0.2),
+					0 3px 6px rgba(3, 113, 181, 0.1);
+	}
+	.primary:active {
+		background-color: var(--color-primary-400);
+		transform: translateY(0);
 	}
 
-	.btn:active {
-		background-color: var(--dark-blue);
+	.secondary {
+		background-color: var(--color-primary-400);
+		border-color: var(--color-primary-600);
+		border-style: outset;
+	}
+	.secondary:hover {
+		background-color: var(--color-primary-600);
+	}
+	.secondary:active {
+		background-color: var(--color-primary-800);
+	}
+
+	.outline {
+		background-color: transparent;
+		color: var(--color-primary-800);
+		border-color: var(--color-primary-600);
+	}
+	.outline:hover {
+		background-color: var(--color-primary-600);
+		color: var(--color-text-inverted);
+		transform: translateY(-2px);
 	}
 
 	.disabled,
-	.disabled:active,
-	.disabled:hover {
-		cursor:not-allowed;
-		background-color: grey;
-		border: grey;
+	.disabled:hover,
+	.disabled:active {
+		cursor: not-allowed;
+		background-color: var(--color-neutral-400);
+		border-color: var(--color-neutral-400);
+		color: var(--color-text-inverted);
 		opacity: 0.5;
+		transform: none;
+		box-shadow: none;
 	}
 </style>

From d03e4b075bdbde8072307a97dcabaa66453ff12f Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:30:22 +0800
Subject: [PATCH 04/13] replace svelte-bricks with native Masonry grid

---
 src/lib/components/mosaic/Masonry.svelte | 56 ++++++++++++++++++++++++
 src/routes/(content)/+page.svelte        | 28 ++++++------
 2 files changed, 71 insertions(+), 13 deletions(-)
 create mode 100644 src/lib/components/mosaic/Masonry.svelte

diff --git a/src/lib/components/mosaic/Masonry.svelte b/src/lib/components/mosaic/Masonry.svelte
new file mode 100644
index 00000000..6496e17f
--- /dev/null
+++ b/src/lib/components/mosaic/Masonry.svelte
@@ -0,0 +1,56 @@
+<script>
+	export let items = [];
+	export let minColWidth = 330;
+	export let maxColWidth = 500;
+	export let gap = 20;
+	export let idKey = 'id';
+	export let animate = false;
+	export let width = 0;
+	export let height = 0;
+
+	let el;
+
+	// animate reserved for API compatibility (currently unused)
+	animate;
+
+	/** Number of columns derived from container width */
+	$: nCols =
+		width <= 0
+			? Math.min(items.length, Math.floor((1920 + gap) / (minColWidth + gap)) || 1)
+			: Math.min(items.length, Math.floor((width + gap) / (minColWidth + gap)) || 1);
+
+	/** Round-robin column distribution */
+	$: cols = (() => {
+		const result = Array.from({ length: nCols }, () => []);
+		items.forEach((item, idx) => {
+			result[idx % nCols].push({ item, idx });
+		});
+		return result;
+	})();
+
+	function keyOf(item) {
+		if (typeof item === 'number') return item;
+		if (typeof item === 'string') return item;
+		if (idKey in item) return item[idKey];
+		return JSON.stringify(item);
+	}
+</script>
+
+<div
+	bind:this={el}
+	bind:clientWidth={width}
+	bind:clientHeight={height}
+	class="svelte-bricks"
+	style="display:flex;gap:{gap}px;justify-content:center;width:100%;box-sizing:border-box;overflow-wrap:anywhere"
+>
+	{#each cols as col (col)}
+		<div
+			class="col"
+			style="flex:1 1 0;min-width:0;display:grid;gap:{gap}px;height:max-content;max-width:{maxColWidth}px"
+		>
+			{#each col as { item, idx } (keyOf(item))}
+				<slot {item} {idx} />
+			{/each}
+		</div>
+	{/each}
+</div>
diff --git a/src/routes/(content)/+page.svelte b/src/routes/(content)/+page.svelte
index 05ca3932..b2195fe9 100644
--- a/src/routes/(content)/+page.svelte
+++ b/src/routes/(content)/+page.svelte
@@ -4,7 +4,7 @@
 
 	import WelcomeBanner from '$lib/components/front-page/WelcomeBanner.svelte';
 	import Article from '$lib/components/mosaic/Article.svelte';
-	import Masonry from 'svelte-bricks';
+	import Masonry from '$lib/components/mosaic/Masonry.svelte';
 
 	
 	let learn = db.filter(x => x.section === 'learn');
@@ -15,7 +15,7 @@
 	const featuredExplore = explore.filter(x => x.url === config.frontPage.featuredExplore.url)[0];
 	
 	learn = learn.filter(x => x.url !== config.frontPage.featuredLearn.url);
-	explore = explore.filter(x => x !== config.frontPage.featuredExplore.url);
+	explore = explore.filter(x => x.url !== config.frontPage.featuredExplore.url);
 	
 	let randomLearn = [featuredLearn].concat(_.shuffle(learn).slice(0, 7));
 	let randomExplore = [featuredExplore].concat(_.shuffle(explore).slice(0, 7));
@@ -45,23 +45,25 @@
 
 <style>
 	.feature {
-		padding-left: 2em;
-		padding-right: 2em;
+		padding-left: var(--space-8);
+		padding-right: var(--space-8);
+		padding-bottom: var(--space-8);
 	}
 
-	h2 {
-		font-size: 1.5rem;
-		margin-bottom: 0.5em;
+	.feature h2 {
+		font-size: var(--text-2xl);
+		font-weight: var(--font-bold);
+		margin: var(--space-6) 0 var(--space-1);
 	}
 
-	p {
-		font-size: 1rem;
-		color: #595959;
-		margin-bottom: 1em;
+	.feature p {
+		font-size: var(--text-base);
+		color: var(--color-text-muted);
+		margin-bottom: var(--space-6);
 	}
 
 	:global(.svelte-bricks) {
-		border-radius: 12px;
-		overflow: hidden;
+		border-radius: var(--card-radius);
+		overflow: visible;
 	}
 </style>
\ No newline at end of file

From 7694802e87038124fc8061aad48ab44af4d1640c Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:30:25 +0800
Subject: [PATCH 05/13] migrate global CSS to design tokens

---
 src/classes.css                | 15 +++++++--------
 src/flair.css                  | 24 ++++++------------------
 src/lib/layouts/Content.svelte |  1 -
 src/utils.css                  |  9 ++++-----
 4 files changed, 17 insertions(+), 32 deletions(-)

diff --git a/src/classes.css b/src/classes.css
index c3e2f072..5c1836ec 100644
--- a/src/classes.css
+++ b/src/classes.css
@@ -1,11 +1,10 @@
 .interactive-example-container {
-	margin-top: 2em;
-	margin-bottom: 2em;
+	margin-top: var(--space-8);
+	margin-bottom: var(--space-8);
 	display: flex;
 	flex-direction: column;
-	gap: 1em;
-	border-width: 2px;
-	border-style: solid;
-	border-color: rgba(28, 164, 252, 0.3);
-	padding: 1em;
-}
\ No newline at end of file
+	gap: var(--space-4);
+	border: 2px solid rgba(28, 164, 252, 0.3);
+	padding: var(--space-4);
+	border-radius: var(--radius-md);
+}
diff --git a/src/flair.css b/src/flair.css
index 63c00313..63e5875f 100644
--- a/src/flair.css
+++ b/src/flair.css
@@ -1,19 +1,7 @@
-.event {
-	background-color: rgb(235, 161, 23);
-}
+/* Flair (content-type) colors — used as background pills/badges */
 
-.article {
-	background-color: var(--light-blue);
-}
-
-.reference {
-	background-color: forestgreen;
-}
-
-.podcast {
-	background-color: palevioletred;
-}
-
-.tutorial {
-	background-color: rgba(102, 103, 171, 255);
-}
+.flair-event    { background-color: var(--color-event); }
+.flair-article  { background-color: var(--color-article); }
+.flair-reference { background-color: var(--color-reference); }
+.flair-podcast  { background-color: var(--color-podcast); }
+.flair-tutorial { background-color: var(--color-tutorial); }
diff --git a/src/lib/layouts/Content.svelte b/src/lib/layouts/Content.svelte
index fa9afe5a..391f3eea 100644
--- a/src/lib/layouts/Content.svelte
+++ b/src/lib/layouts/Content.svelte
@@ -86,7 +86,6 @@
 
 	.navigation {
 		grid-area: navigation;
-		height: max-content;
 	}
 
 	.blank {
diff --git a/src/utils.css b/src/utils.css
index 12e741d0..3deef30b 100644
--- a/src/utils.css
+++ b/src/utils.css
@@ -10,22 +10,21 @@
 }
 
 .neutral-link {
-	background-color: white;
+	background-color: var(--color-background);
 	text-decoration: none;
 }
 
 .neutral-link:hover {
-	background-color: white;
+	background-color: var(--color-background);
 	text-decoration: none;
 }
 
 .raisedbox {
-	transition: box-shadow 200ms cubic-bezier(0.175, 0.885, 0.32, 1.275);
+	transition: box-shadow var(--transition-base) cubic-bezier(0.175, 0.885, 0.32, 1.275);
 }
 
 .raisedbox:hover {
-	box-shadow: rgb(255, 255, 255) -5px 5px, rgba(3, 113, 181, 0.2) -10px 10px, rgba(3, 113, 181, 0.1) -15px 15px, rgba(3, 113, 181, 0.05) -20px 20px;
-	/* box-shadow: rgba(3, 113, 181, 0.2) -5px 5px, rgba(3, 113, 181, 0.1) -10px 10px, rgba(3, 113, 181, 0.05) -15px 15px; */
+	box-shadow: var(--shadow-interactive);
 }
 
 .noscroll {

From ad4401bc07e3b50253d329d9e069ebe6648d8c32 Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:33:20 +0800
Subject: [PATCH 06/13] add ARIA attributes and design system to tab components

---
 src/lib/components/tabs/Tab.svelte      | 33 +++++++++++++++----------
 src/lib/components/tabs/TabList.svelte  | 10 +++++---
 src/lib/components/tabs/TabPanel.svelte |  9 ++++---
 src/lib/components/tabs/Tabs.svelte     |  6 ++---
 4 files changed, 36 insertions(+), 22 deletions(-)

diff --git a/src/lib/components/tabs/Tab.svelte b/src/lib/components/tabs/Tab.svelte
index 345a6e85..356c517c 100644
--- a/src/lib/components/tabs/Tab.svelte
+++ b/src/lib/components/tabs/Tab.svelte
@@ -8,7 +8,12 @@
 	registerTab(tab);
 </script>
 
-<button class:selected={$selectedTab === tab} on:click={() => selectTab(tab)}>
+<button
+	role="tab"
+	aria-selected={$selectedTab === tab}
+	class:selected={$selectedTab === tab}
+	on:click={() => selectTab(tab)}
+>
 	<slot />
 </button>
 
@@ -16,25 +21,27 @@
 	button {
 		background: none;
 		border: 1px solid transparent;
-		padding: 1em;
+		padding: var(--space-2) var(--space-4);
 		cursor: pointer;
-		color: #495057;
-		font-size: 1rem;
-		font-family: var(--font);
+		color: var(--color-text-muted);
+		font-size: var(--text-sm);
+		font-family: var(--font-sans);
+		font-weight: var(--font-semibold);
 		margin: 0;
-		min-width: 13ch; /* Number of characters in the word SuperCollider */
-		transition: border-bottom 0.05s linear;
-		transition: background-color 0.05s linear;
+		border-radius: var(--radius-md);
+		transition: all var(--transition-fast);
+		white-space: nowrap;
 	}
 
 	button:hover {
-		background-color: rgba(28, 164, 252, 0.05);
+		color: var(--color-primary-700);
+		background-color: rgba(28, 164, 252, 0.08);
 	}
 
 	.selected {
-		background-color: #fff;
-		border-bottom: 4px solid var(--light-blue);
-		color: black;
-		background-color: rgba(28, 164, 252, 0.1);
+		background-color: var(--color-background) !important;
+		color: var(--color-primary-800) !important;
+		box-shadow: var(--shadow-sm);
+		border-color: var(--color-neutral-200);
 	}
 </style>
diff --git a/src/lib/components/tabs/TabList.svelte b/src/lib/components/tabs/TabList.svelte
index f4e41596..2e2cb3c4 100644
--- a/src/lib/components/tabs/TabList.svelte
+++ b/src/lib/components/tabs/TabList.svelte
@@ -1,4 +1,4 @@
-<div class="tab-list">
+<div class="tab-list" role="tablist">
 	<slot />
 </div>
 
@@ -6,7 +6,11 @@
 	.tab-list {
 		display: flex;
 		flex-direction: row;
-		gap: 0;
-		box-shadow: 0, 0, rgba(60, 64, 67, 1), 0;
+		flex-wrap: wrap;
+		gap: var(--space-1);
+		padding: var(--space-1);
+		background-color: var(--color-neutral-100);
+		border-radius: var(--radius-lg);
+		border: 1px solid var(--color-neutral-200);
 	}
 </style>
diff --git a/src/lib/components/tabs/TabPanel.svelte b/src/lib/components/tabs/TabPanel.svelte
index f63dd027..781b42de 100644
--- a/src/lib/components/tabs/TabPanel.svelte
+++ b/src/lib/components/tabs/TabPanel.svelte
@@ -9,14 +9,17 @@
 </script>
 
 {#if $selectedPanel === panel}
-	<div class="panel">
+	<div class="panel" role="tabpanel">
 		<slot />
 	</div>
 {/if}
 
 <style>
 	.panel {
-		margin-bottom: 1em;
-		border-radius: 0.25rem;
+		margin-top: var(--space-4);
+		padding: var(--space-5);
+		border: 1px solid var(--color-neutral-200);
+		border-radius: var(--radius-md);
+		background-color: var(--color-background);
 	}
 </style>
diff --git a/src/lib/components/tabs/Tabs.svelte b/src/lib/components/tabs/Tabs.svelte
index 5feded3c..cb4a2616 100644
--- a/src/lib/components/tabs/Tabs.svelte
+++ b/src/lib/components/tabs/Tabs.svelte
@@ -45,12 +45,12 @@
 	});
 </script>
 
-<div class="tabs">
+<div class="tabs-root">
 	<slot />
 </div>
 
 <style>
-	.tabs {
-		margin-bottom: 1em;
+	.tabs-root {
+		margin: var(--space-8) 0;
 	}
 </style>

From 6b4c44d9e42c6a8818e0df29ad136365264af473 Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:33:23 +0800
Subject: [PATCH 07/13] remove WelcomeButton, redesign WelcomeBanner

---
 .../front-page/WelcomeBanner.svelte           | 136 ++++++++++++------
 .../front-page/WelcomeButton.svelte           |  38 -----
 2 files changed, 96 insertions(+), 78 deletions(-)
 delete mode 100644 src/lib/components/front-page/WelcomeButton.svelte

diff --git a/src/lib/components/front-page/WelcomeBanner.svelte b/src/lib/components/front-page/WelcomeBanner.svelte
index c0dc8f03..fc3a257e 100644
--- a/src/lib/components/front-page/WelcomeBanner.svelte
+++ b/src/lib/components/front-page/WelcomeBanner.svelte
@@ -1,65 +1,121 @@
 <script>
-	import WelcomeButton from '$lib/components/front-page/WelcomeButton.svelte';
+	import Button from '$lib/components/Button.svelte';
 </script>
 
-<section id='welcome-banner'>
-	<div id="welcome-left">
-		<h1><strong>Welcome to the Fluid Corpus Manipulation Learn Platform!</strong></h1>
-		<p>The Fluid Corpus Manipulation project (FluCoMa) instigates new musical ways of exploiting ever-growing banks of sound and gestures within the digital composition process, by bringing breakthroughs of signal decomposition DSP and machine learning to the toolset of techno-fluent computer composers, creative coders and digital artists.</p>
-		<div id="buttons">
-			<WelcomeButton url='/learn/getting-started' text='Getting Started'/>
-			<WelcomeButton url='/learn' text='Learn'/>
-			<WelcomeButton url='/reference' text='Reference'/>
-			<WelcomeButton url='/explore' text='Explore'/>
+<section class="welcome-banner">
+	<div class="welcome-left">
+		<h1>Welcome to the Fluid Corpus Manipulation Learn Platform</h1>
+		<p class="welcome-subtitle">
+			The Fluid Corpus Manipulation project (FluCoMa) instigates new musical ways of
+			exploiting ever-growing banks of sound and gestures within the digital composition
+			process, by bringing breakthroughs of signal decomposition DSP and machine learning
+			to the toolset of techno-fluent computer composers, creative coders and digital artists.
+		</p>
+		<div class="welcome-buttons">
+			<Button href="/learn/getting-started" label="Getting Started" width="160px" height="44px" />
+			<Button href="/learn" label="Learn" width="160px" height="44px" />
+			<Button href="/reference" label="Reference" width="160px" height="44px" />
+			<Button href="/explore" label="Explore" width="160px" height="44px" />
 		</div>
 	</div>
-	<div id='welcome-right'>
-		<img id='logo' src="/img/onlylogo.svg" alt="FluCoMa Logo">
+	<div class="welcome-right">
+		<img class="welcome-logo" src="/img/onlylogo.svg" alt="FluCoMa Logo" />
 	</div>
 </section>
 
 <style>
-	#welcome-banner {
-		padding-left: 2em;
-		padding-right: 2em;
-		margin-bottom: 1em;
-		margin-top: 1em;
-		padding-top: 2em;
-		padding-bottom: 2em;
-		gap: 2em;
+	.welcome-banner {
 		display: flex;
 		flex-direction: row;
-		background: rgb(255,255,255);
-		background: linear-gradient(90deg, rgba(255,255,255,0.25) 55%, rgba(146,200,246,0.25) 82%, rgba(71,158,248,0.25) 100%);
-		min-width: 100%;
+		align-items: center;
+		gap: var(--space-12);
+		padding: var(--space-12) var(--space-8);
+		margin: var(--space-4) 0 var(--space-8);
+		background:
+			linear-gradient(
+				105deg,
+				rgba(255, 255, 255, 0) 40%,
+				rgba(146, 200, 246, 0.15) 70%,
+				rgba(71, 158, 248, 0.2) 100%
+			);
 		position: relative;
+		border-radius: var(--radius-lg);
+		overflow: hidden;
 	}
-	#welcome-left {
-		max-width: 50%;
+
+	.welcome-banner::after {
+		content: '';
+		position: absolute;
+		bottom: 0;
+		left: 0;
+		right: 0;
+		height: 1px;
+		background: linear-gradient(
+			to right,
+			transparent,
+			var(--color-primary-200) 30%,
+			var(--color-primary-200) 70%,
+			transparent
+		);
+	}
+
+	.welcome-left {
+		flex: 1;
+		max-width: 55%;
 		display: flex;
 		flex-direction: column;
 	}
-	#welcome-left > p {
-		max-width: 100%;
-		font-size: 20px;
+
+	.welcome-left h1 {
+		font-size: var(--text-3xl);
+		font-weight: var(--font-extrabold);
+		margin: 0 0 var(--space-5);
+		line-height: var(--leading-tight);
+		color: var(--color-primary-900);
 	}
-	@media (max-width: 768px) {
-		#logo, #welcome-right {
-			display: none;
-		}
-		#welcome-left {
-			max-width: 100%;
-		}
+
+	.welcome-subtitle {
+		font-size: var(--text-md);
+		line-height: var(--leading-relaxed);
+		color: var(--color-text-muted);
+		margin: 0 0 var(--space-8);
+		max-width: 55ch;
 	}
-	#welcome-left > #buttons {
+
+	.welcome-buttons {
 		display: flex;
 		flex-direction: row;
 		flex-wrap: wrap;
-		gap: 1em;
+		gap: var(--space-3);
 	}
-	#logo {
+
+	.welcome-right {
+		flex-shrink: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+	}
+
+	.welcome-logo {
 		width: 100%;
-		max-height: 500px;
+		max-width: 280px;
+		max-height: 280px;
+		opacity: 0.85;
+		filter: drop-shadow(0 4px 12px rgba(8, 60, 100, 0.12));
 	}
 
-</style>
\ No newline at end of file
+	@media (max-width: 768px) {
+		.welcome-right {
+			display: none;
+		}
+		.welcome-left {
+			max-width: 100%;
+		}
+		.welcome-banner {
+			padding: var(--space-8) var(--space-5);
+		}
+		.welcome-left h1 {
+			font-size: var(--text-2xl);
+		}
+	}
+</style>
diff --git a/src/lib/components/front-page/WelcomeButton.svelte b/src/lib/components/front-page/WelcomeButton.svelte
deleted file mode 100644
index 193784a6..00000000
--- a/src/lib/components/front-page/WelcomeButton.svelte
+++ /dev/null
@@ -1,38 +0,0 @@
-<script>
-	export let url = '';
-	export let text = '';
-</script>
-
-<a class='btn' href={url}>
-	{text}
-</a>
-
-<style>
-	.btn {
-		display: grid;
-		place-items: center;
-		width: 150px;
-		height: 40px;
-		background-color: var(--dark-blue);
-		padding: 0.5em;
-		color: white;
-		text-decoration: none;
-		border-radius: 12px;
-		transition: background-color 150ms linear, transform 0.3s ease, box-shadow 0.3s ease;
-		box-shadow: 0 4px 6px rgba(3, 113, 181, 0.2), 0 1px 3px rgba(3, 113, 181, 0.1);
-		word-wrap: none;
-		overflow: hidden;
-		min-width: fit-content;
-	}
-
-	.btn:hover {
-		background-color: var(--med-blue);
-		transform: translateY(-2px);
-		box-shadow: 0 8px 12px rgba(3, 113, 181, 0.2), 0 3px 6px rgba(3, 113, 181, 0.1);
-	}
-
-	.btn:active {
-		background-color: var(--light-blue);
-		transform: translateY(0);
-	}
-</style>
\ No newline at end of file

From b84bcb91e64e242cab15abea8ab394773609e73c Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:33:27 +0800
Subject: [PATCH 08/13] migrate card components to design system

---
 src/lib/components/cards/Article.svelte      | 132 ++++++++++---------
 src/lib/components/cards/Landing.svelte      |  46 +++----
 src/lib/components/explore/ArtistCard.svelte |  65 +++++----
 3 files changed, 133 insertions(+), 110 deletions(-)

diff --git a/src/lib/components/cards/Article.svelte b/src/lib/components/cards/Article.svelte
index d6e00fae..4b80ef75 100644
--- a/src/lib/components/cards/Article.svelte
+++ b/src/lib/components/cards/Article.svelte
@@ -6,102 +6,110 @@
 	export let data = {};
 </script>
 
-<a class="container raisedbox" href={data.url}>
-	<div class="top">
-		<h2>{data.title}</h2>
+<a class="list-card raisedbox" href={data.url}>
+	<div class="card-header">
+		<h2 class="card-title">{data.title}</h2>
 		<Flair flair={data.flair} />
 	</div>
 
-	<div class="img_container">
+	<div class="card-image-wrap">
 		<div
-			class="feature_image"
+			class="card-image"
 			style="background-image: url({data.feature.featuredimage ||
 				_.sample(data.feature.images) ||
 				'/general/learn_default.jpeg'});"
 		/>
 	</div>
 
-	<p>{data.blurb}</p>
-	<a class="linkout" href={data.url}>Learn More <ArrowRight /></a>
+	<p class="card-blurb">{data.blurb}</p>
+	<span class="card-cta">Learn More <ArrowRight /></span>
 </a>
 
 <style>
-	.img_container {
-		background-repeat: no-repeat;
-		background-size: cover;
-		background-position: 50% 50%;
-		border-radius: 0.25rem;
-		padding: 0em 0em 0em 0em;
-		margin-top: 0em;
-		margin-bottom: 0.25em;
+	.list-card {
+		display: flex;
+		flex-direction: column;
+		border-radius: var(--card-radius);
+		border: 1px solid var(--color-border);
+		padding: var(--space-5);
+		margin: var(--space-2) 0;
+		background: var(--color-background);
+		color: var(--color-text);
+		text-decoration: none;
+		transition: var(--card-transition);
+		position: relative;
 	}
 
-	.feature_image {
-		position: relative;
-		max-width: 100%;
-		height: 10em;
-		margin: 0.5em 0em 0.5em 0em;
-		border: 0.063rem solid #dcdee0;
-		background-position: center;
-		background-repeat: no-repeat;
-		background-size: cover;
+	.list-card:hover {
+		color: var(--color-text);
+		background: var(--color-background);
+		cursor: pointer;
+		border-color: var(--color-primary-200);
 	}
 
-	.container {
-		border-radius: 0.25rem;
-		border: 0.063rem solid #dcdee0;
-		padding: 0.75em;
-		margin-top: 0.5em;
-		margin-bottom: 0.5em;
-		max-width: 100%;
+	.card-header {
+		display: grid;
+		grid-template-columns: 1fr auto;
+		align-items: start;
+		gap: var(--space-3);
+		margin-bottom: var(--space-3);
 	}
 
-	.container > p {
-		color: var(--grey);
-		text-align: justify;
-		text-justify: inter-word;
+	.card-title {
+		font-size: var(--text-lg);
+		font-weight: var(--font-bold);
+		margin: 0;
+		line-height: var(--leading-snug);
 	}
 
-	/* Overwrite hover behaviour */
-	.container,
-	.container:hover {
-		color: black;
-		background-color: white;
-		text-decoration: none;
+	.card-image-wrap {
+		border-radius: var(--radius-sm);
+		overflow: hidden;
+		margin-bottom: var(--space-3);
 	}
 
-	.container:hover {
-		cursor: pointer;
+	.card-image {
+		width: 100%;
+		height: 10em;
+		border: 1px solid var(--color-neutral-200);
+		background-position: center;
+		background-repeat: no-repeat;
+		background-size: cover;
+		border-radius: var(--radius-sm);
+		transition: transform 0.5s ease;
 	}
 
-	.top {
-		display: grid;
-		grid-template-columns: auto auto;
-		place-items: center;
-		justify-content: space-between;
-		margin-bottom: 0.5em;
+	.list-card:hover .card-image {
+		transform: scale(1.02);
 	}
 
-	.top > :global(h2) {
-		margin: 0;
+	.card-blurb {
+		color: var(--color-text-muted);
+		font-size: var(--text-sm);
+		line-height: var(--leading-normal);
+		margin: 0 0 var(--space-3);
+		text-align: justify;
+		text-justify: inter-word;
 	}
 
-	.linkout {
-		display: grid;
+	.card-cta {
+		display: inline-grid;
 		grid-template-columns: auto auto;
-		justify-content: left;
-		place-items: center;
+		align-items: center;
 		gap: 0.2em;
+		font-size: var(--text-sm);
+		font-weight: var(--font-semibold);
+		color: var(--color-link);
+		transition: gap var(--transition-fast), color var(--transition-fast);
+		margin-top: auto;
 	}
 
-	.linkout:hover {
-		background-color: transparent;
-		color: var(--med-blue);
-		gap: 0.3em;
+	.list-card:hover .card-cta {
+		gap: 0.4em;
+		color: var(--color-primary-700);
 	}
 
-	.linkout,
-	.linkout:hover {
-		transition: gap 80ms ease-in-out;
+	.card-cta:hover {
+		background: transparent;
 	}
 </style>
diff --git a/src/lib/components/cards/Landing.svelte b/src/lib/components/cards/Landing.svelte
index d3b5f767..b3df673a 100644
--- a/src/lib/components/cards/Landing.svelte
+++ b/src/lib/components/cards/Landing.svelte
@@ -4,50 +4,50 @@
 	export let link = '/';
 </script>
 
-<div class="container">
+<div class="landing-card">
 	<slot name="title" />
 	<slot name="blurb" />
 	<a
 		on:click={() => {
 			$nav_expanded = false;
 		}}
-		class="linkout"
+		class="landing-cta"
 		href={link}>Learn More <ArrowRight /></a
 	>
 </div>
 
 <style>
-	.container {
-		margin-top: 0.5em;
-		margin-bottom: 0.5em;
+	.landing-card {
+		margin: var(--space-2) 0;
 	}
 
-	.container > :global(h2) {
+	.landing-card :global(h2) {
 		margin: 0;
+		font-size: var(--text-xl);
 	}
 
-	.container > :global(p) {
-		margin: 0;
-		margin-bottom: 0.25em;
-		margin-top: 0.25em;
+	.landing-card :global(p) {
+		margin: 0 0 var(--space-2);
+		color: var(--color-text-muted);
+		font-size: var(--text-sm);
+		line-height: var(--leading-normal);
 	}
 
-	.linkout {
-		display: grid;
+	.landing-cta {
+		display: inline-grid;
 		grid-template-columns: auto auto;
-		justify-content: left;
-		place-items: center;
+		align-items: center;
 		gap: 0.2em;
+		font-size: var(--text-sm);
+		font-weight: var(--font-semibold);
+		color: var(--color-link);
+		text-decoration: none;
+		transition: gap var(--transition-fast), color var(--transition-fast);
 	}
 
-	.linkout:hover {
-		background-color: transparent;
-		color: var(--med-blue);
-		gap: 0.3em;
-	}
-
-	.linkout,
-	.linkout:hover {
-		transition: gap 80ms ease-in-out;
+	.landing-cta:hover {
+		background: transparent;
+		color: var(--color-primary-700);
+		gap: 0.4em;
 	}
 </style>
diff --git a/src/lib/components/explore/ArtistCard.svelte b/src/lib/components/explore/ArtistCard.svelte
index e60cde4e..7bee1854 100644
--- a/src/lib/components/explore/ArtistCard.svelte
+++ b/src/lib/components/explore/ArtistCard.svelte
@@ -4,44 +4,59 @@
 	export let website = '';
 </script>
 
-<a class="container neutral-link" href={website}>
-	<div class="top">
+<a class="artist-card neutral-link" href={website}>
+	<div class="card-top">
 		<img loading="lazy" alt={`${name} profile picture`} {src} />
-		<h3>{name}</h3>
+		<span class="card-name">{name}</span>
 	</div>
-	<!-- <div class="bio"> -->
-	<!-- <slot name="bio"></slot> -->
-	<!-- </div> -->
+
+	{#if $$slots.bio}
+		<div class="card-bio">
+			<slot name="bio" />
+		</div>
+	{/if}
 </a>
 
-<style >
-	.container {
-		gap: 0.5em;
-		margin-top: 1em;
-		margin-right: 2em;
+<style>
+	.artist-card {
+		display: block;
+		margin: var(--space-4) 0;
 	}
 
-	.top {
+	.card-top {
 		display: flex;
-		flex-direction: row;
-		place-items: center;
-		gap: 1em;
+		align-items: center;
+		gap: var(--space-4);
+	}
+
+	img {
+		flex-shrink: 0;
+		width: 80px;
+		height: 80px;
+		border-radius: var(--radius-full);
+		object-fit: cover;
+		box-shadow: var(--shadow-sm);
 	}
 
-	h3 {
-		color: var(--med-blue);
+	.card-name {
+		font-size: var(--text-2xl);
+		font-weight: var(--font-semibold);
+		color: var(--color-primary-800);
+		line-height: var(--leading-snug);
 	}
 
-	h3:hover {
+	.artist-card:hover .card-name {
 		text-decoration: underline;
 	}
 
-	img {
-		max-width: 80px;
-		max-height: 80px;
-		width: auto;
-		height: auto;
-		border-radius: 50%;
-		box-shadow: rgba(99, 99, 99, 0.2) 0px 2px 8px 0px;
+	.card-bio {
+		margin-top: var(--space-3);
+		line-height: var(--leading-normal);
+	}
+
+	.card-bio :global(p) {
+		font-size: var(--text-sm);
+		color: var(--color-text-muted);
+		margin: 0;
 	}
 </style>

From cef2850892627a515228155f2d67e27a58f2a107 Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:33:30 +0800
Subject: [PATCH 09/13] migrate mosaic components to design system

---
 src/lib/components/mosaic/Article.svelte     | 175 ++++++++++---------
 src/lib/components/mosaic/List.svelte        |  11 +-
 src/lib/components/mosaic/RefCategory.svelte |  49 +++---
 src/lib/components/mosaic/References.svelte  |  13 +-
 4 files changed, 129 insertions(+), 119 deletions(-)

diff --git a/src/lib/components/mosaic/Article.svelte b/src/lib/components/mosaic/Article.svelte
index 995541da..ada59ad2 100644
--- a/src/lib/components/mosaic/Article.svelte
+++ b/src/lib/components/mosaic/Article.svelte
@@ -1,116 +1,131 @@
 <script>
 	import _ from 'lodash';
 	export let item = {
-		url : '',
+		url: '',
 		title: '',
-		flair : '',
-		blurb : '',
-		feature : {
+		flair: '',
+		blurb: '',
+		feature: {
 			featuredimage: '',
-			images: [
-				'/image/path'
-			],
+			images: ['/image/path']
 		}
-	}
+	};
 </script>
 
-<div class="container">
-	<a href={item.url}>
-		<div class="img_container">
-			<img
-				class="feature_image"
-				src={item.feature.featuredimage || _.sample(item.feature.images) || '/general/learn_default.jpeg'}
-				alt={item.title}
-			/>
-		</div>
+<a class="mosaic-card" href={item.url}>
+	<div class="card-image-wrap">
+		<img
+			class="card-image"
+			src={item.feature.featuredimage || _.sample(item.feature.images) || '/general/learn_default.jpeg'}
+			alt={item.title}
+			loading="lazy"
+		/>
+		<div class="card-image-overlay" />
+		<div class="card-flair-pill flair-{item.flair}">{item.flair}</div>
+	</div>
 
-		<div class="text_cont">
-			<h2>{item.title}</h2>
-			<div class={`item-${item.flair} flair`}>{item.flair}</div>
-			<p class="blurb">{item.blurb}</p>
-		</div>
-	</a>
-</div>
+	<div class="card-body">
+		<h2 class="card-title">{item.title}</h2>
+		<p class="card-blurb">{item.blurb}</p>
+	</div>
+</a>
 
 <style>
-	.container {
-		max-width: 100%;
-		height: 100%;
-		width: 100%;
-		border-radius: 12px;
-		overflow: hidden;
-		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 1px 3px rgba(0, 0, 0, 0.08);
-		transition: transform 0.3s ease, box-shadow 0.3s ease;
-	}
-
-	.container:hover {
-		transform: translateY(-2px);
-		box-shadow: 0 8px 12px rgba(0, 0, 0, 0.1), 0 3px 6px rgba(0, 0, 0, 0.08);
-	}
-
-	.container > a {
-		color: inherit;
-		text-decoration: none;
+	.mosaic-card {
 		display: flex;
 		flex-direction: column;
+		border-radius: var(--card-radius);
+		overflow: hidden;
+		background: var(--color-background);
+		box-shadow: var(--card-shadow);
+		text-decoration: none;
+		color: inherit;
+		transition: var(--card-transition);
 		height: 100%;
-		background-color: transparent;  /* Add this line */
+		width: 100%;
 	}
 
-	.container > a:hover {
-		background-color: transparent;  /* Add this line */
+	.mosaic-card:hover {
+		transform: translateY(-4px);
+		box-shadow: var(--card-shadow-hover);
+		color: inherit;
+		background: var(--color-background);
 	}
 
-	.img_container {
-		flex: 0 0 auto;
+	.card-image-wrap {
+		position: relative;
 		aspect-ratio: 16 / 9;
 		overflow: hidden;
+		background-color: var(--color-neutral-100);
 	}
 
-	.text_cont {
-		flex: 1 0 auto;
-		padding: 1.5em;
-		display: flex;
-		flex-direction: column;
-	}
-
-	.feature_image {
+	.card-image {
 		width: 100%;
 		height: 100%;
 		object-fit: cover;
-		transition: transform 0.3s ease;
+		transition: transform 0.6s cubic-bezier(0.25, 0.46, 0.45, 0.94);
 	}
 
-	.container:hover .feature_image {
-		transform: scale(1.05);
+	.mosaic-card:hover .card-image {
+		transform: scale(1.06);
 	}
 
-	h2 {
-		margin: 0 0 0.5em;
-		font-size: 1.2rem;
-		line-height: 1.3;
+	.card-image-overlay {
+		position: absolute;
+		inset: 0;
+		background: var(--card-image-overlay);
+		pointer-events: none;
 	}
 
-	.blurb {
-		font-size: 0.9rem;
-		color: #595959;
-		margin-top: 0.5em;
-		flex-grow: 1;
+	.card-flair-pill {
+		position: absolute;
+		bottom: var(--space-3);
+		left: var(--space-3);
+		text-transform: capitalize;
+		font-size: var(--text-xs);
+		font-weight: var(--font-bold);
+		padding: 0.25em 0.75em;
+		border-radius: var(--radius-full);
+		color: #fff;
+		letter-spacing: var(--tracking-wide);
+		backdrop-filter: blur(4px);
+		-webkit-backdrop-filter: blur(4px);
 	}
 
-	.flair {
-		align-self: flex-start;
-		text-transform: capitalize;
-		font-size: 0.75rem;
-		font-weight: bold;
-		padding: 0.3em 0.8em;
-		border-radius: 20px;
-		margin-top: auto;
+	.flair-article  { background-color: var(--color-article); }
+	.flair-event    { background-color: var(--color-event); }
+	.flair-reference { background-color: var(--color-reference); }
+	.flair-podcast  { background-color: var(--color-podcast); }
+	.flair-tutorial { background-color: var(--color-tutorial); }
+
+	.card-body {
+		padding: var(--space-4) var(--space-5) var(--space-5);
+		display: flex;
+		flex-direction: column;
+		flex: 1;
 	}
 
-	.item-event { background-color: var(--event-flair); color: white; }
-	.item-article { background-color: var(--article-flair); color: white; }
-	.item-reference { background-color: var(--reference-flair); color: white; }
-	.item-podcast { background-color: var(--podcast-flair); color: white; }
-	.item-tutorial { background-color: var(--tutorial-flair); color: white; }
+	.card-title {
+		font-size: var(--text-lg);
+		font-weight: var(--font-bold);
+		margin: 0 0 var(--space-1);
+		line-height: var(--leading-snug);
+		color: var(--color-neutral-900);
+		display: -webkit-box;
+		-webkit-line-clamp: 2;
+		-webkit-box-orient: vertical;
+		overflow: hidden;
+	}
+
+	.card-blurb {
+		font-size: var(--text-sm);
+		color: var(--color-text-muted);
+		margin: 0;
+		line-height: var(--leading-normal);
+		display: -webkit-box;
+		-webkit-line-clamp: 3;
+		-webkit-box-orient: vertical;
+		overflow: hidden;
+		flex: 1;
+	}
 </style>
diff --git a/src/lib/components/mosaic/List.svelte b/src/lib/components/mosaic/List.svelte
index ef8e7ffd..54cecdad 100644
--- a/src/lib/components/mosaic/List.svelte
+++ b/src/lib/components/mosaic/List.svelte
@@ -1,19 +1,14 @@
-<!-- 
-This component abstracts the rendering process for each "card" in madewith and overview sections.
-References are slightly different and use the ReferenceEntry component.
--->
 <script>
 	import { db } from '$lib/app.js';
 	import Article from '$lib/components/mosaic/Article.svelte';
-	import Masonry from 'svelte-bricks';
+	import Masonry from '$lib/components/mosaic/Masonry.svelte';
 
 	export let section = 'learn';
 
-	let [minColWidth, maxColWidth, gap] = [300, 800, 15];
+	const items = db.filter(x => x.section === section);
+	const [minColWidth, maxColWidth, gap] = [300, 800, 20];
 	let width = 0;
 	let height = 0;
-
-	const items = db.filter(x => x.section === section);
 </script>
 
 <Masonry {items} {minColWidth} {maxColWidth} {gap} idKey={'url'} animate={false} let:item bind:width bind:height>
diff --git a/src/lib/components/mosaic/RefCategory.svelte b/src/lib/components/mosaic/RefCategory.svelte
index 86f05a36..edd4673b 100644
--- a/src/lib/components/mosaic/RefCategory.svelte
+++ b/src/lib/components/mosaic/RefCategory.svelte
@@ -1,18 +1,13 @@
 <script>
 	export let item = {
 		category: 'Decomposition',
-		refs: [
-			{
-				url: '/',
-				title: 'hpss'
-			}
-		]
+		refs: [{ url: '/', title: 'hpss' }]
 	};
 </script>
 
-<section>
-	<h3 class:faded={item.refs.length == 0}>{item.category}</h3>
-	<ul>
+<section class="ref-category">
+	<h3 class="ref-cat-title" class:faded={item.refs.length === 0}>{item.category}</h3>
+	<ul class="ref-cat-list">
 		{#each item.refs as r}
 			<li><a href={r.url}>{r.title}</a></li>
 		{/each}
@@ -20,36 +15,42 @@
 </section>
 
 <style>
-	.faded {
-		color: var(--grey);
-	}
-	section {
+	.ref-category {
 		display: flex;
 		flex-direction: column;
-		gap: 1em;
+		gap: var(--space-2);
 		min-width: max-content;
 	}
-	h3 {
-		min-width: max-content;
+
+	.ref-cat-title {
 		margin: 0;
+		font-size: var(--text-base);
+		min-width: max-content;
 	}
 
-	ul {
+	.faded {
+		color: var(--color-text-muted);
+	}
+
+	.ref-cat-list {
 		margin: 0;
 		padding: 0;
+		list-style: none;
 	}
 
-	li {
+	.ref-cat-list li {
 		display: block;
-		margin: 0;
+		margin: 0 0 var(--space-1);
 	}
 
-	a {
+	.ref-cat-list a {
 		min-width: max-content;
 		text-decoration: none;
-		display: grid;
-		grid-template-columns: auto auto;
-		place-items: center;
-		gap: 0.125em;
+		font-size: var(--text-sm);
+		color: var(--color-link);
+	}
+
+	.ref-cat-list a:hover {
+		color: var(--color-link-hover-text);
 	}
 </style>
diff --git a/src/lib/components/mosaic/References.svelte b/src/lib/components/mosaic/References.svelte
index 00808340..43d1dc49 100644
--- a/src/lib/components/mosaic/References.svelte
+++ b/src/lib/components/mosaic/References.svelte
@@ -4,17 +4,16 @@
 	export let items = [];
 </script>
 
-<div class="items">
+<div class="ref-grid">
 	{#each items as item}
 		<RefCategory {item} />
 	{/each}
 </div>
 
 <style>
-	.items {
-		display: flex;
-		flex-direction: row;
-		flex-wrap: wrap;
-		gap: 1em;
+	.ref-grid {
+		display: grid;
+		grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+		gap: var(--space-6);
 	}
-</style>
\ No newline at end of file
+</style>

From d7ca70fc039736c5fe6863a4ab1ae526f13c2f9f Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:33:33 +0800
Subject: [PATCH 10/13] migrate page chrome components to design system

---
 src/lib/components/Footer.svelte |  21 +++--
 src/lib/components/Header.svelte |  68 +++++++-------
 src/lib/components/Search.svelte | 151 +++++++++++++++++--------------
 src/lib/components/TOC.svelte    |  73 +++++++++------
 4 files changed, 173 insertions(+), 140 deletions(-)

diff --git a/src/lib/components/Footer.svelte b/src/lib/components/Footer.svelte
index cea2b774..7fc0ca15 100644
--- a/src/lib/components/Footer.svelte
+++ b/src/lib/components/Footer.svelte
@@ -2,8 +2,8 @@
 	import ArrowRight from '$lib/components/ArrowRight.svelte';
 
 	const links = [
-		{ href: "https://github.com/flucoma/learn-website/issues/new", text: "File an issue" },
-		{ href: "https://flucoma.org", text: "FluCoMa Home" }
+		{ href: 'https://github.com/flucoma/learn-website/issues/new', text: 'File an issue' },
+		{ href: 'https://flucoma.org', text: 'FluCoMa Home' }
 	];
 </script>
 
@@ -20,7 +20,7 @@
 <style>
 	footer {
 		min-height: var(--footer-height);
-		background-color: var(--dark-blue);
+		background-color: var(--color-primary-800);
 		display: grid;
 		place-items: center;
 	}
@@ -29,20 +29,23 @@
 		display: flex;
 		justify-content: space-around;
 		width: 100%;
-		padding: 1rem;
+		padding: var(--space-4);
 	}
 
 	.content > a {
-		color: white;
-		font-size: 1rem;
+		color: var(--color-text-inverted);
+		font-size: var(--text-base);
 		text-decoration: none;
 		display: flex;
 		align-items: center;
-		gap: 0.5rem;
-		transition: opacity 0.2s ease-in-out;
+		gap: var(--space-2);
+		transition: opacity var(--transition-fast);
+		border-radius: var(--radius-sm);
+		padding: var(--space-1) var(--space-2);
 	}
 
-	a:hover {
+	.content > a:hover {
 		opacity: 0.8;
+		background: transparent;
 	}
 </style>
diff --git a/src/lib/components/Header.svelte b/src/lib/components/Header.svelte
index a1dbb92a..a0c96436 100644
--- a/src/lib/components/Header.svelte
+++ b/src/lib/components/Header.svelte
@@ -15,79 +15,75 @@
 
 <header>
 	{#if w > 1200}
-	<div class='logo-area'>
+		<div class="logo-area">
+			<a class="logo-link" href="/">
+				<img class="logo" src="/img/onlylogo.svg" alt="FluCoMa Logo" />
+				<span class="title">FluCoMa Learn</span>
+			</a>
+			<nav class="links">
+				<a href="/learn">Learn</a>
+				<a href="/reference">Reference</a>
+				<a href="/explore">Explore</a>
+				<a href="/podcast">Podcast</a>
+				<a href="https://discourse.flucoma.org" target="_blank" rel="noreferrer">Discourse</a>
+			</nav>
+		</div>
+		<Search />
+	{:else}
+		<Hamburger on:click={expandHandler} open={$nav_expanded} />
 		<a class="logo-link" href="/">
 			<img class="logo" src="/img/onlylogo.svg" alt="FluCoMa Logo" />
-			<a class="title" href="/"> FluCoMa Learn </a>
 		</a>
-		<div class="links">
-			<a href="/learn">Learn</a>
-			<a href='/reference'>Reference</a>
-			<a href="/explore">Explore</a>
-			<a href="/podcast">Podcast</a>
-			<a href="https://discourse.flucoma.org" target='_blank' rel='noreferrer'>Discourse</a>
-		</div>
-	</div>
-	<Search />
-	{:else}
-	<Hamburger on:click={expandHandler} open={$nav_expanded} />
-	<a class="logo-link" href="/">
-		<img class="logo" src="/img/onlylogo.svg" alt="FluCoMa Logo" />
-	</a>
-	<Search />
+		<Search />
 	{/if}
 </header>
 
 <PopoverNav />
 
-<style >
+<style>
 	header {
 		display: flex;
 		flex-direction: row;
 		align-items: center;
 		justify-content: space-between;
-		background: var(--dark-blue);
-		height: 55px;
+		background: var(--color-primary-800);
+		height: var(--header-height);
 		position: fixed;
 		width: 100%;
 		z-index: 10000;
-		padding-left: 2em;
-		padding-right: 2em;
+		padding-left: var(--space-8);
+		padding-right: var(--space-8);
 	}
 
 	.links {
 		display: flex;
 		flex-direction: row;
-		justify-content: left;
-		gap: 1em;
+		gap: var(--space-4);
 	}
 
 	.links > a {
-		color: white;
+		color: var(--color-text-inverted);
 		text-decoration: none;
+		font-size: var(--text-base);
 	}
 
 	.links > a:hover {
 		text-decoration: underline;
 		background: transparent;
+		color: var(--color-text-inverted);
 	}
 
 	.title {
-		color: white;
-		text-decoration: none;
-	}
-
-	.title:hover {
-		text-decoration: underline;
-		background-color: transparent;
+		color: var(--color-text-inverted);
+		font-size: var(--text-md);
+		font-weight: var(--font-bold);
 	}
 
 	.logo-area {
 		display: flex;
 		align-items: center;
-		justify-content: left;
-		gap: 2em;
-		font-family: var(--font);
+		gap: var(--space-8);
+		font-family: var(--font-sans);
 	}
 
 	.logo {
@@ -99,7 +95,7 @@
 		display: flex;
 		flex-direction: row;
 		align-items: center;
-		gap: 0.5em;
+		gap: var(--space-2);
 		text-decoration: none;
 	}
 
diff --git a/src/lib/components/Search.svelte b/src/lib/components/Search.svelte
index fbdca473..bfac90de 100644
--- a/src/lib/components/Search.svelte
+++ b/src/lib/components/Search.svelte
@@ -19,14 +19,12 @@
 
 	function blurSearch() {
 		focused = false;
-		// $blur = false;
 		searchBar.blur();
 	}
 
-	function focusSearch(e) {
+	function focusSearch() {
 		searchBar.focus();
 		focused = true;
-		// $blur = true;
 	}
 
 	function updateFocus() {
@@ -53,13 +51,11 @@
 				focusedEntry -= 1;
 				updateFocus();
 			}
-
 			if (e.key === 'ArrowDown') {
 				e.preventDefault();
 				focusedEntry += 1;
 				updateFocus();
 			}
-
 			if (e.key === 'Enter') {
 				if (focusedEntry !== -1) {
 					clickResult(results[focusedEntry].item.url);
@@ -86,34 +82,34 @@
 	</form>
 
 	{#if results.length >= 1 && focused}
-	<div class="results">
-		{#each results as r, i}
-			<div
-				class="result"
-				on:mousedown={() => clickResult(r.item.url)}
-				on:mouseleave={() => { focusedEntry = -1 }}
-				on:mouseenter={() => { focusedEntry = i }}
-				class:entryhover={i === focusedEntry}
-				on:click={() => clickResult(r.item.url)}
-				on:keypress={() => clickResult(r.item.url)}
-				on:focus={focusSearch}
-				on:blur={blurSearch}
-				bind:this={entries[i]}
-				role="button"
-				tabindex="0"
-			>
-				<div class="top">
-					<h3 class="title">{r.item.title}</h3>
-					{#if r.item.flair}
-					<div class={`item-${r.item.flair} flair`}>{r.item.flair}</div>
-					{/if}
+		<div class="results">
+			{#each results as r, i}
+				<div
+					class="result"
+					on:mousedown={() => clickResult(r.item.url)}
+					on:mouseleave={() => { focusedEntry = -1; }}
+					on:mouseenter={() => { focusedEntry = i; }}
+					on:click={() => clickResult(r.item.url)}
+					on:keypress={() => clickResult(r.item.url)}
+					on:focus={focusSearch}
+					on:blur={blurSearch}
+					bind:this={entries[i]}
+					role="button"
+					tabindex="0"
+					class:hovered={i === focusedEntry}
+				>
+					<div class="top">
+						<h3 class="title">{r.item.title}</h3>
+						{#if r.item.flair}
+							<div class="result-flair flair-{r.item.flair}">{r.item.flair}</div>
+						{/if}
+					</div>
+					<p class="bottom">
+						{r.item.blurb.slice(0, 150) + '...'}
+					</p>
 				</div>
-				<p class="bottom">
-					{r.item.blurb.slice(0, 150) + '...'}
-				</p>
-			</div>
-		{/each}
-	</div>
+			{/each}
+		</div>
 	{/if}
 </div>
 
@@ -122,86 +118,103 @@
 		z-index: 999;
 		position: relative;
 	}
+
 	.query {
-		font-family: var(--font);
+		font-family: var(--font-sans);
 		font-size: 0.9rem;
-		border: 1px solid #e0e0e0;
-		padding: 0.5em 0.75em;
-		border-radius: 12px;
+		border: 1px solid var(--color-border);
+		padding: var(--space-2) var(--space-3);
+		border-radius: var(--radius-lg);
 		width: 100%;
 		height: 36px;
 		box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
-		transition: all 0.3s ease;
+		transition: all var(--transition-slow);
+		background-color: var(--color-background);
+		color: var(--color-text);
 	}
-	.query:hover, .query:focus {
-		border-color: var(--med-blue);
-		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+
+	.query:hover,
+	.query:focus {
+		border-color: var(--color-primary-600);
+		box-shadow: var(--shadow-sm);
 		outline: none;
 	}
+
 	.results {
 		display: flex;
 		flex-direction: column;
 		position: absolute;
 		right: 0;
 		width: min(90vw, 400px);
-		background: white;
-		border-radius: 12px;
+		background: var(--color-background);
+		border-radius: var(--radius-lg);
 		overflow: hidden;
-		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 1px 3px rgba(0, 0, 0, 0.08);
+		box-shadow: var(--shadow-md);
 		z-index: 1000;
-		margin-top: 0.5em;
+		margin-top: var(--space-2);
 	}
+
 	.result {
-		padding: 1em;
+		padding: var(--space-4);
 		display: flex;
 		flex-direction: column;
 		text-align: left;
-		transition: all 0.3s ease;
+		transition: all var(--transition-slow);
 		border-left: 4px solid transparent;
 	}
-	.entryhover, .result:hover, .result:focus {
+
+	.hovered,
+	.result:hover,
+	.result:focus {
 		background-color: rgba(146, 200, 246, 0.15);
-		border-left-color: var(--med-blue);
+		border-left-color: var(--color-primary-600);
 		cursor: pointer;
 	}
-	.result:hover .title, .result:focus .title {
-		color: var(--med-blue);
+
+	.result:hover .title,
+	.result:focus .title {
+		color: var(--color-primary-600);
 	}
+
 	.top {
 		display: flex;
 		justify-content: space-between;
 		align-items: center;
-		gap: 0.5em;
-		margin-bottom: 0.5em;
+		gap: var(--space-2);
+		margin-bottom: var(--space-2);
 	}
+
 	.title {
-		font-weight: bold;
-		font-size: 1.1rem;
-		line-height: 1.3;
+		font-weight: var(--font-bold);
+		font-size: var(--text-md);
+		line-height: var(--leading-snug);
 		margin: 0;
-		color: var(--dark-blue);
-		transition: color 0.3s ease;
+		color: var(--color-primary-800);
+		transition: color var(--transition-slow);
 	}
+
 	.bottom {
-		color: #595959;
+		color: var(--color-text-muted);
 		font-size: 0.9rem;
 		margin: 0;
 		line-height: 1.4;
 	}
-	.flair {
+
+	.result-flair {
 		align-self: flex-start;
 		text-transform: capitalize;
-		font-size: 0.75rem;
-		font-weight: bold;
+		font-size: var(--text-xs);
+		font-weight: var(--font-bold);
 		padding: 0.3em 0.8em;
-		border-radius: 20px;
-		color: white;
-	}
-	.item-event { background-color: var(--event-flair); }
-	.item-article { background-color: var(--article-flair); }
-	.item-reference { background-color: var(--reference-flair); }
-	.item-podcast { background-color: var(--podcast-flair); }
-	.item-tutorial { background-color: var(--tutorial-flair); }
+		border-radius: var(--radius-full);
+		color: var(--color-text-inverted);
+	}
+
+	.flair-event    { background-color: var(--color-event); }
+	.flair-article  { background-color: var(--color-article); }
+	.flair-reference { background-color: var(--color-reference); }
+	.flair-podcast  { background-color: var(--color-podcast); }
+	.flair-tutorial { background-color: var(--color-tutorial); }
 
 	.visually-hidden {
 		position: absolute;
diff --git a/src/lib/components/TOC.svelte b/src/lib/components/TOC.svelte
index 39b8a665..fcc9c010 100644
--- a/src/lib/components/TOC.svelte
+++ b/src/lib/components/TOC.svelte
@@ -1,71 +1,92 @@
 <script>
 	import { page } from '$app/stores';
 	import { structure } from '$lib/app.js';
-	let headings = [''];
+
+	let headings = [];
+	let activeHash = '';
 
 	$: {
 		let path = $page.url.pathname;
 		path = path.endsWith('/') ? path.slice(0, -1) : path;
 		headings = structure[path] || [];
+		activeHash = $page.url.hash;
 	}
 </script>
 
 {#if headings.length > 0}
-<div class="toc-container">
+	<aside class="toc">
 		<h3 class="toc-title">Table of Contents</h3>
 		<nav class="toc-nav">
 			{#each headings as heading}
-				<a href={heading.url} class="toc-link" style="padding-left: {heading.depth * 0.5}em">
+				<a
+					href={heading.url}
+					class="toc-link"
+					class:active={heading.url === activeHash}
+					style="--depth: {heading.depth}"
+				>
 					{heading.text}
 				</a>
 			{/each}
 		</nav>
-	</div>
+	</aside>
 {/if}
 
 <style>
-	.toc-container {
-		background-color: white;
-		border-radius: 12px;
-		box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
-		padding: 1em;
-		margin-top: 1em;
-		max-width: 300px;
+	.toc {
+		position: sticky;
+		top: calc(var(--header-height) + var(--space-4));
+		background-color: var(--color-background);
+		border-radius: var(--radius-lg);
+		box-shadow: var(--shadow-sm);
+		padding: var(--space-4);
+		margin-top: var(--space-4);
 		width: 100%;
 	}
 
 	.toc-title {
-		font-size: 1.2rem;
-		font-weight: bold;
-		color: var(--dark-blue);
-		margin: 0 0 0.5em;
-		/* line-height: 1.3; */
+		font-size: var(--text-md);
+		font-weight: var(--font-bold);
+		color: var(--color-primary-800);
+		margin: 0 0 var(--space-3);
+		padding-bottom: var(--space-2);
+		border-bottom: 1px solid var(--color-neutral-200);
 	}
 
 	.toc-nav {
 		display: flex;
 		flex-direction: column;
+		gap: var(--space-1);
 	}
 
 	.toc-link {
-		font-size: 0.9rem;
-		color: var(--dark-blue);
+		font-size: var(--text-sm);
+		color: var(--color-primary-800);
 		text-decoration: none;
-		padding: 0.25em 0.5em;
+		line-height: var(--leading-snug);
+		padding: var(--space-1) var(--space-2);
+		padding-left: calc(var(--space-2) + var(--depth, 0) * 0.75rem);
 		border-left: 2px solid transparent;
+		border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+		transition: all var(--transition-fast);
 	}
 
 	.toc-link:hover {
-		color: var(--med-blue);
-		background-color: rgba(146, 200, 246, 0.15);
-		border-left-color: var(--med-blue);
+		color: var(--color-primary-500);
+		background-color: transparent;
+		border-left-color: var(--color-primary-500);
+		transform: translateX(2px);
+	}
+
+	.toc-link.active {
+		color: var(--color-primary-700);
+		background-color: var(--color-primary-50);
+		border-left-color: var(--color-primary-600);
+		font-weight: var(--font-semibold);
 	}
 
-	/* Media query for smaller screens */
 	@media (max-width: 1200px) {
-		.toc-container {
-			max-width: 250px;
-			margin: 1em 2em 1em 0;
+		.toc {
+			margin: var(--space-4) var(--space-8) var(--space-4) 0;
 		}
 	}
 </style>

From a7bdcc0dfd1492b7f25450744f9074e0fca6d1a3 Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:33:37 +0800
Subject: [PATCH 11/13] migrate content components to design system

---
 src/lib/components/Admonition.svelte      |  66 +++++-----
 src/lib/components/AuthorTag.svelte       |  80 ++++++-------
 src/lib/components/BigQuote.svelte        |  88 ++++++++++----
 src/lib/components/CodeBlock.svelte       |  63 ++++++----
 src/lib/components/Copy.svelte            |  34 +++---
 src/lib/components/Flair.svelte           |  43 ++-----
 src/lib/components/HR.svelte              |   5 -
 src/lib/components/Image.svelte           |  64 ++++++----
 src/lib/components/RelatedLinks.svelte    | 140 ++++++++++++----------
 src/lib/components/ResourceLink.svelte    | 134 ++++++++++++++-------
 src/lib/components/YouTubeChapters.svelte |  50 +++++---
 11 files changed, 452 insertions(+), 315 deletions(-)

diff --git a/src/lib/components/Admonition.svelte b/src/lib/components/Admonition.svelte
index e9ba0c0a..d1770056 100644
--- a/src/lib/components/Admonition.svelte
+++ b/src/lib/components/Admonition.svelte
@@ -1,64 +1,64 @@
 <script>
 	export let type = 'note';
 
-	const lookup = new Map([
-		['note', 'Note'],
-		['warn', 'Warning'],
-		['danger', 'Danger'],
-		['pointer', 'Pointer']
-	]);
+	const labels = {
+		note: 'Note',
+		warn: 'Warning',
+		danger: 'Danger',
+		pointer: 'Pointer'
+	};
 </script>
 
-<div class="container {type}">
-	<div class="header">{lookup.get(type)}</div>
-	<div class="text">
+<div class="admonition {type}">
+	<div class="admonition-header">{labels[type] ?? 'Note'}</div>
+	<div class="admonition-body">
 		<slot />
 	</div>
 </div>
 
 <style>
-	.container {
-		--bg-color: rgba(224, 244, 252, 1);
-		--border-color: rgba(52, 52, 171, 0.63);
-		border-left: 4px solid var(--border-color);
-		color: rgb(65, 65, 65);
-		border-radius: 12px;
-		margin: 1.5em 0; 
-		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 1px 3px rgba(0, 0, 0, 0.08);
+	.admonition {
+		--_bg: var(--color-note-bg);
+		--_border: var(--color-note-border);
+		border-left: 4px solid var(--_border);
+		color: var(--color-note-text);
+		border-radius: var(--radius-lg);
+		margin: var(--space-6) 0;
+		box-shadow: var(--shadow-sm);
 		overflow: hidden;
 	}
 
-	.text > :global(p) {
-		padding: 1.25em;
+	.admonition-body :global(p) {
+		padding: var(--space-5);
 		margin: 0;
 		font-size: 0.95rem;
-		line-height: 1.5;
+		line-height: var(--leading-normal);
 	}
 
-	.header {
-		background-color: var(--bg-color);
-		font-weight: 800;
-		padding: 0.75em 1.25em;
-		font-size: 1.1rem;
+	.admonition-header {
+		background-color: var(--_bg);
+		font-weight: var(--font-extrabold);
+		padding: var(--space-3) var(--space-5);
+		font-size: var(--text-md);
 	}
 
 	.note {
-		--bg-color: rgba(52, 52, 171, 0.2);
-		--border-color: rgba(31, 31, 136, 0.63);
+		--_bg: var(--color-note-bg);
+		--_border: var(--color-note-border);
 	}
 
 	.warn {
-		--bg-color: rgba(255, 204, 0, 0.2);
-		--border-color: rgba(255, 204, 0, 0.63);
+		--_bg: var(--color-warning-bg);
+		--_border: var(--color-warning-border);
 	}
 
 	.danger {
-		--bg-color: rgba(204, 51, 0, 0.2);
-		--border-color: rgba(204, 51, 0, 0.63);
+		--_bg: var(--color-danger-bg);
+		--_border: var(--color-danger-border);
 	}
 
 	.pointer {
-		--bg-color: rgba(230, 252, 224, 1);
-		--border-color: rgb(133, 229, 106);
+		--_bg: var(--color-success-bg);
+		--_border: var(--color-success-border);
 	}
 </style>
diff --git a/src/lib/components/AuthorTag.svelte b/src/lib/components/AuthorTag.svelte
index 900926cc..d14cac20 100644
--- a/src/lib/components/AuthorTag.svelte
+++ b/src/lib/components/AuthorTag.svelte
@@ -1,53 +1,47 @@
 <script>
-	/**
-	 * A convenient way to render an author attribution.
-	 * @constructor
-	 * @param {string} author - The name of the author.
-	 */
 	export let author = '';
 
-	const authors = new Map(
-		Object.entries({
-			Jacob: {
-				name: 'Jacob Hart',
-				website: 'https://jacob-hart.com/'
-			},
-			James: {
-				name: 'James Bradbury',
-				website: 'https://www.jamesbradbury.net/'
-			},
-			Ted: {
-				name: 'Ted Moore',
-				website: 'https://www.tedmooremusic.com/'
-			},
-			PA: {
-				name: 'Pierre Alexandre Tremblay',
-				website: 'https://www.pierrealexandretremblay.com/'
-			},
-			Owen: {
-				name: 'Owen Green',
-				website: 'http://owengreen.net/'
-			}
-		})
-	);
-	const author_name = authors.get(author)['name'];
-	const author_website = authors.get(author)['website'];
+	const authors = {
+		Jacob: { name: 'Jacob Hart', website: 'https://jacob-hart.com/' },
+		James: { name: 'James Bradbury', website: 'https://www.jamesbradbury.net/' },
+		Ted: { name: 'Ted Moore', website: 'https://www.tedmooremusic.com/' },
+		PA: { name: 'Pierre Alexandre Tremblay', website: 'https://www.pierrealexandretremblay.com/' },
+		Owen: { name: 'Owen Green', website: 'http://owengreen.net/' }
+	};
+	$: info = authors[author] || { name: author, website: '#' };
 </script>
 
-<!--
-@component
-Render authors names in articles.
+<p class="author-tag">
+	<span class="author-by">by</span>
+	<a class="author-link" href={info.website} target="_blank" rel="noopener noreferrer">
+		{info.name}
+	</a>
+</p>
 
-```svelte
-<AuthorTag {author} />
-```
--->
+<style>
+	.author-tag {
+		display: flex;
+		align-items: center;
+		gap: 0.4em;
+		font-size: var(--text-sm);
+		margin: 0 0 var(--space-2);
+		color: var(--color-text-muted);
+	}
+
+	.author-by {
+		font-style: italic;
+	}
 
-<p class="author_link">by <a href={author_website}>{author_name}</a></p>
+	.author-link {
+		font-weight: var(--font-semibold);
+		color: var(--color-primary-700);
+		text-decoration: none;
+		transition: color var(--transition-fast);
+	}
 
-<style>
-	.author_link {
-		font-weight: bold;
-		font-size: 1.1em;
+	.author-link:hover {
+		color: var(--color-primary-500);
+		background: transparent;
+		text-decoration: underline;
 	}
 </style>
diff --git a/src/lib/components/BigQuote.svelte b/src/lib/components/BigQuote.svelte
index 3f79080a..17f2d2cd 100644
--- a/src/lib/components/BigQuote.svelte
+++ b/src/lib/components/BigQuote.svelte
@@ -2,33 +2,77 @@
 	export let txt = '';
 </script>
 
-<blockquote class="container">
-	{@html txt}
-</blockquote>
+<figure class="big-quote">
+	<blockquote>
+		{@html txt}
+	</blockquote>
+</figure>
 
 <style>
-	.container {
-		font-size: 1.25rem;
-		margin: 1.5em;
-		padding: 1.5em;
+	.big-quote {
+		margin: var(--space-10) auto;
+		padding: 0;
+		max-width: 85%;
+		text-align: center;
+	}
+
+	blockquote {
+		margin: 0;
+		padding: var(--space-6) var(--space-8);
+		font-size: var(--text-xl);
+		font-weight: var(--font-normal);
 		font-style: italic;
-		border-left: 4px solid rgb(191, 191, 191);
-		background-color: rgba(128, 128, 128, 0.04);
+		line-height: var(--leading-relaxed);
+		color: var(--color-primary-800);
+		position: relative;
+		border: none;
+		background: linear-gradient(
+			135deg,
+			rgba(28, 164, 252, 0.04) 0%,
+			rgba(28, 164, 252, 0.01) 100%
+		);
+		border-radius: var(--radius-md);
 	}
-	.container:before {
-		color: #ccc;
-		content: open-quote;
-		font-size: 3em;
-		margin-right: 0.25em;
+
+	blockquote::before {
+		content: '“';
+		position: absolute;
+		top: -0.2em;
+		left: -0.05em;
+		font-size: 5rem;
+		font-weight: var(--font-extrabold);
+		line-height: 1;
+		color: rgba(28, 164, 252, 0.12);
+		font-style: normal;
+		font-family: Georgia, 'Times New Roman', serif;
+		pointer-events: none;
 	}
-	.container:after {
-		color: #ccc;
-		content: close-quote;
+
+	blockquote::after {
+		content: '”';
+		position: absolute;
+		bottom: -0.5em;
+		right: -0.05em;
+		font-size: 5rem;
+		font-weight: var(--font-extrabold);
+		line-height: 1;
+		color: rgba(28, 164, 252, 0.12);
+		font-style: normal;
+		font-family: Georgia, 'Times New Roman', serif;
+		pointer-events: none;
 	}
-	.container:after,
-	.container:before {
-		font-size: 2em;
-		line-height: 0.1em;
-		vertical-align: -0.4em;
+
+	@media (max-width: 768px) {
+		.big-quote {
+			max-width: 95%;
+		}
+		blockquote {
+			font-size: var(--text-md);
+			padding: var(--space-5) var(--space-6);
+		}
+		blockquote::before,
+		blockquote::after {
+			font-size: 3rem;
+		}
 	}
 </style>
diff --git a/src/lib/components/CodeBlock.svelte b/src/lib/components/CodeBlock.svelte
index ea86b4fb..558dc6db 100644
--- a/src/lib/components/CodeBlock.svelte
+++ b/src/lib/components/CodeBlock.svelte
@@ -4,11 +4,12 @@
 
 	export let title = '';
 	export let snippet = false;
+
 	let block;
 
 	const copyCode = () => {
 		if (browser) {
-			let code = block.querySelectorAll('pre > code');
+			const code = block.querySelectorAll('pre > code');
 			code.forEach(c => {
 				navigator.clipboard.writeText(c.innerText);
 			});
@@ -16,41 +17,55 @@
 	};
 </script>
 
-<div bind:this={block} class="container" class:not-snippet={!snippet}>
-	{#if !snippet}
-	<div class="header">
-		{title}
-		<Copy on:click={copyCode} />
-	</div>
+<div bind:this={block} class="code-block" class:snippet>
+	{#if title}
+		<div class="code-header">
+			<span class="code-label">{title}</span>
+			<Copy on:click={copyCode} />
+		</div>
 	{/if}
-	<div class="code">
+	<div class="code-body">
 		<slot />
 	</div>
 </div>
 
 <style>
-	.container {
-		position: relative;
-		max-height: 600px;
-		border-radius: 12px;
-		margin-bottom: 1em;
-		max-height: 500px;
-		overflow: auto;
-		box-shadow: rgba(99, 99, 99, 0.2) 0px 2px 8px 0px;
+	.code-block {
+		border-radius: var(--radius-md);
+		overflow: hidden;
+		margin: var(--space-6) 0;
+		border: 1px solid var(--color-neutral-200);
+		box-shadow: var(--shadow-sm);
 	}
 
-	.not-snippet {
-		border-left: 4px solid rgb(191, 191, 191);
+	.snippet {
+		border-left: 4px solid var(--color-primary-400);
 	}
 
-	.header {
-		background-color: rgb(233, 233, 233);
-		padding: 0.5em;
-		padding-left: 1em;
-		font-weight: bold;
+	.code-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		padding: var(--space-2) var(--space-4);
+		background-color: var(--color-neutral-100);
+		border-bottom: 1px solid var(--color-neutral-200);
 	}
 
-	.code {
+	.code-label {
+		font-family: var(--font-mono);
+		font-size: var(--text-xs);
+		font-weight: var(--font-semibold);
+		color: var(--color-text-muted);
+		text-transform: uppercase;
+		letter-spacing: var(--tracking-wide);
+	}
+
+	.code-body {
 		position: relative;
 	}
+
+	.code-body :global(pre) {
+		margin: 0;
+		border-radius: 0;
+	}
 </style>
diff --git a/src/lib/components/Copy.svelte b/src/lib/components/Copy.svelte
index 62e1bcd8..ff03498a 100644
--- a/src/lib/components/Copy.svelte
+++ b/src/lib/components/Copy.svelte
@@ -17,36 +17,38 @@
 	};
 </script>
 
-<button aria-label="copy code" on:click={compositeEvent} transition:fade>
+<button aria-label="copy code" on:click={compositeEvent}>
 	{#if showToast}
-		copied!
+		<span class="toast" transition:fade>copied!</span>
 	{:else}
-		<img src="/img/copy.svg" alt="copy code" />
+		<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+			<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+			<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+		</svg>
 	{/if}
 </button>
 
 <style>
 	button {
-		display: grid;
+		display: inline-grid;
 		place-items: center;
-		font-family: var(--font);
-		position: absolute;
-		top: 0px;
-		right: 0px;
+		font-family: var(--font-sans);
+		font-size: var(--text-xs);
 		border: none;
-		background-color: rgb(216, 216, 216);
-		width: 64px;
-		height: 40px;
+		background: none;
 		cursor: pointer;
-		text-align: center;
+		padding: var(--space-1);
+		color: inherit;
+		border-radius: var(--radius-sm);
+		transition: background-color var(--transition-fast);
 	}
 
 	button:hover {
-		background-color: rgb(200, 200, 200);
+		background-color: rgba(0,0,0,0.08);
 	}
 
-	img {
-		width: 20px;
-		height: 20px;
+	.toast {
+		color: var(--color-primary-600);
+		font-weight: var(--font-semibold);
 	}
 </style>
diff --git a/src/lib/components/Flair.svelte b/src/lib/components/Flair.svelte
index dceecae3..e2aa11ca 100644
--- a/src/lib/components/Flair.svelte
+++ b/src/lib/components/Flair.svelte
@@ -1,44 +1,27 @@
 <script>
 	export let flair = '';
+
+	const colorMap = {
+		article: 'var(--color-article)',
+		reference: 'var(--color-reference)',
+		podcast: 'var(--color-podcast)',
+		event: 'var(--color-event)',
+		tutorial: 'var(--color-tutorial)'
+	};
+	$: flairColor = colorMap[flair] ?? 'var(--color-text-muted)';
 </script>
 
-<div
-	class="flair"
-	class:item-article={flair === 'article'}
-	class:item-reference={flair === 'reference'}
-	class:item-podcast={flair === 'podcast'}
-	class:item-event={flair === 'event'}
-	class:item-tutorial={flair === 'tutorial'}
->
+<div class="flair" style="color: {flairColor}">
 	{flair}
 </div>
 
-<style >
+<style>
 	.flair {
 		display: grid;
 		align-items: center;
 		justify-content: center;
 		text-transform: capitalize;
-		font-size: 0.75rem;
-		font-weight: bold;
-	}
-
-	.item-event {
-		color: var(--event-flair);
-	}
-	.item-article {
-		color: var(--article-flair);
-	}
-	
-	.item-reference {
-		color: var(--reference-flair);
-	}
-	
-	.item-podcast {
-		color: var(--podcast-flair);
-	}
-	
-	.item-tutorial {
-		color: var(--tutorial-flair);
+		font-size: var(--text-xs);
+		font-weight: var(--font-bold);
 	}
 </style>
diff --git a/src/lib/components/HR.svelte b/src/lib/components/HR.svelte
index a8f00b5e..ece2a4e2 100644
--- a/src/lib/components/HR.svelte
+++ b/src/lib/components/HR.svelte
@@ -1,9 +1,4 @@
 <hr />
 
 <style>
-	hr {
-		height: 1px;
-		background-color: rgba(128, 128, 128, 0.187);
-		border: none;
-	}
 </style>
diff --git a/src/lib/components/Image.svelte b/src/lib/components/Image.svelte
index 2413c4e1..3bf8bd6d 100644
--- a/src/lib/components/Image.svelte
+++ b/src/lib/components/Image.svelte
@@ -5,46 +5,68 @@
 	export let alt = '';
 	export let label = '';
 	export let id = '';
+
+	let loaded = false;
 </script>
 
-<figure class="container" {id}>
-	<a target="_blank" href={src} rel='noreferrer'>
-		<img loading="lazy" {alt} {src} />
+<figure class="image-figure" {id}>
+	<a target="_blank" href={src} rel="noreferrer" class:loaded>
+		<img
+			loading="lazy"
+			{alt}
+			{src}
+			on:load={() => (loaded = true)}
+			class:loaded
+		/>
 	</a>
-	<figcaption class="label">
-		{@html markdown.toHTML(label)}
-	</figcaption>
+	{#if label}
+		<figcaption class="image-caption">
+			{@html markdown.toHTML(label)}
+		</figcaption>
+	{/if}
 </figure>
 
-<style >
-	.container {
+<style>
+	.image-figure {
 		display: grid;
 		place-items: center;
 		width: 80%;
-		margin: 0 auto;
-		margin-top: 1em;
-		margin-bottom: 1em;
+		margin: var(--space-8) auto;
 	}
 
-	img {
-		padding-top: 1em;
-		padding-bottom: 1em;
+	.image-figure > a {
 		max-width: 100%;
+		border-radius: var(--radius-sm);
+		overflow: hidden;
+		display: block;
+		background-color: var(--color-neutral-100);
 	}
 
-	.container > a {
+	.image-figure > a:hover {
+		background: transparent;
+	}
+
+	img {
+		display: block;
 		max-width: 100%;
-		transition: opacity linear 100ms;
+		padding-top: var(--space-4);
+		padding-bottom: var(--space-4);
+		opacity: 0;
+		transform: scale(0.98);
+		transition: opacity 0.5s ease, transform 0.5s ease;
 	}
 
-	.container > a:hover {
-		background: transparent;
-		opacity: 0.95;
+	img.loaded {
+		opacity: 1;
+		transform: scale(1);
 	}
 
-	.label {
+	.image-caption {
 		text-align: center;
-		font-size: 0.8rem;
+		font-size: var(--text-sm);
 		font-style: italic;
+		color: var(--color-text-muted);
+		margin-top: var(--space-2);
+		line-height: var(--leading-normal);
 	}
 </style>
diff --git a/src/lib/components/RelatedLinks.svelte b/src/lib/components/RelatedLinks.svelte
index df95f5ea..0b266e84 100644
--- a/src/lib/components/RelatedLinks.svelte
+++ b/src/lib/components/RelatedLinks.svelte
@@ -12,6 +12,7 @@
 	$: articles = links.filter(x => x.flair === 'article') || [];
 	$: tutorials = links.filter(x => x.flair === 'tutorial') || [];
 	$: renderables = [articles, tutorials, references];
+
 	let hoverable;
 	let hover = false;
 	let hoverInfo = { flair: '', blurb: '' };
@@ -33,108 +34,121 @@
 
 {#if hover}
 	<div
-	class={`hoverable rel-${hoverInfo.flair}`}
-	style:left={`${hoverPos.x}px`}
-	style:top={`${hoverPos.y + hoverPos.offset}px`}
-	bind:this={hoverable}
+		class="tooltip tooltip-{hoverInfo.flair}"
+		style:left={`${hoverPos.x}px`}
+		style:top={`${hoverPos.y + hoverPos.offset}px`}
+		bind:this={hoverable}
 	>
-		<div class="flair">{hoverInfo.flair}</div>
-		<hr class={hoverInfo.flair} />
-		<div class="blurb">{hoverInfo.blurb}</div>
+		<div class="tooltip-flair">{hoverInfo.flair}</div>
+		<hr class="tooltip-divider" />
+		<div class="tooltip-blurb">{hoverInfo.blurb}</div>
 	</div>
 {/if}
 
-<div class="container">
+<div class="related-container">
 	{#each renderables as c}
 		{#each c as link}
 			<a
-				class={`link rel-${link.flair}`}
+				class="related-link related-link-{link.flair}"
 				href={link.url}
 				on:mouseenter={e => mouseEnter(e, link)}
 				on:mouseleave={stopHover}
-			>{link.title}
+			>
+				{link.title}
 			</a>
 		{/each}
 	{/each}
 </div>
 
 <style>
-	.container {
+	.related-container {
 		font-size: 0.9rem;
 		display: flex;
 		flex-direction: row;
 		flex-wrap: wrap;
-		gap: 0.75em;
-		margin-bottom: 1.5em;
+		gap: var(--space-3);
+		margin-bottom: var(--space-6);
 	}
-	.link {
-		padding: 0.5em 0.75em;
+
+	.related-link {
+		padding: var(--space-2) var(--space-3);
 		text-decoration: none;
-		color: var(--dark-blue);
-		border-radius: 12px;
-		transition: all 0.3s ease;
+		color: var(--color-primary-800);
+		border-radius: var(--radius-lg);
+		transition: all var(--transition-slow);
 		border: 1px solid transparent;
 	}
-	.link:hover {
-		color: white;
+
+	.related-link:hover {
+		color: var(--color-text-inverted);
 		transform: translateY(-2px);
 	}
-	.hoverable {
+
+	/* Per-flair colors using accent tokens */
+	.related-link-tutorial {
+		color: var(--color-tutorial);
+		border-color: var(--color-tutorial);
+	}
+	.related-link-tutorial:hover {
+		background-color: var(--color-tutorial);
+	}
+
+	.related-link-reference {
+		color: var(--color-reference);
+		border-color: var(--color-reference);
+	}
+	.related-link-reference:hover {
+		background-color: var(--color-reference);
+	}
+
+	.related-link-article {
+		color: var(--color-article);
+		border-color: var(--color-article);
+	}
+	.related-link-article:hover {
+		background-color: var(--color-article);
+	}
+
+	/* Tooltip */
+	.tooltip {
 		position: absolute;
 		max-width: 300px;
 		z-index: 98;
-		background-color: white;
-		padding: 1em;
-		border-radius: 12px;
-		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 1px 3px rgba(0, 0, 0, 0.08);
+		background-color: var(--color-background);
+		padding: var(--space-4);
+		border-radius: var(--radius-lg);
+		box-shadow: var(--shadow-md);
 		font-size: 0.9rem;
 	}
-	.flair {
-		font-size: 0.75rem;
-		font-weight: bold;
+
+	.tooltip-flair {
+		font-size: var(--text-xs);
+		font-weight: var(--font-bold);
 		text-transform: capitalize;
-		margin-bottom: 0.5em;
+		margin-bottom: var(--space-2);
 	}
-	.blurb {
-		color: #595959;
+
+	.tooltip .tooltip-flair {
+		color: var(--color-text-muted);
+	}
+
+	.tooltip-blurb {
+		color: var(--color-text-muted);
 		line-height: 1.4;
 	}
-	hr {
+
+	.tooltip-divider {
 		border: none;
 		height: 2px;
-		margin: 0.5em 0;
+		margin: var(--space-2) 0;
 	}
 
-	.rel-tutorial {
-		color: var(--tutorial-flair);
-		border-color: var(--tutorial-flair);
-	}
-	.rel-tutorial:hover {
-		background-color: var(--tutorial-flair);
-	}
-	.rel-tutorial hr {
-		background-color: var(--tutorial-flair);
-	}
+	.tooltip-article .tooltip-flair { color: var(--color-article); }
+	.tooltip-article .tooltip-divider { background-color: var(--color-article); }
 
-	.rel-reference {
-		color: var(--reference-flair);
-		border-color: var(--reference-flair);
-	}
-	.rel-reference:hover {
-		background-color: var(--reference-flair);
-	}
-	.rel-reference hr {
-		background-color: var(--reference-flair);
-	}
+	.tooltip-reference .tooltip-flair { color: var(--color-reference); }
+	.tooltip-reference .tooltip-divider { background-color: var(--color-reference); }
 
-	.rel-article {
-		color: var(--article-flair);
-		border-color: var(--article-flair);
-	}
-	.rel-article:hover {
-		background-color: var(--article-flair);
-	}
-	.rel-article hr {
-		background-color: var(--article-flair);
-	}
+	.tooltip-tutorial .tooltip-flair { color: var(--color-tutorial); }
+	.tooltip-tutorial .tooltip-divider { background-color: var(--color-tutorial); }
 </style>
diff --git a/src/lib/components/ResourceLink.svelte b/src/lib/components/ResourceLink.svelte
index b0db5fc3..04ac20e4 100644
--- a/src/lib/components/ResourceLink.svelte
+++ b/src/lib/components/ResourceLink.svelte
@@ -2,65 +2,115 @@
 	export let title = '';
 	export let url = '';
 	export let blurb = '';
+
+	$: domain = (() => {
+		try {
+			const u = new URL(url);
+			return u.hostname.replace(/^www\./, '');
+		} catch {
+			return url;
+		}
+	})();
 </script>
 
-<div class='container'>
-	<a href={url}>
-		<div class="content">
-			<h3 class="title">{title}</h3>
-			<p class="blurb">{blurb}</p>
-			<span class="url">{url}</span>
-		</div>
-	</a>
-</div>
+<a
+	class="resource-link"
+	href={url}
+	target="_blank"
+	rel="noopener noreferrer"
+>
+	<span class="resource-icon" aria-hidden="true">↗</span>
+	<div class="resource-body">
+		<h3 class="resource-title">{title}</h3>
+		{#if blurb}
+			<p class="resource-blurb">{blurb}</p>
+		{/if}
+		<span class="resource-domain">{domain}</span>
+	</div>
+</a>
 
 <style>
-	.container {
-		margin: 1em 0;
-		border-radius: 12px;
-		overflow: hidden;
-		box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 1px 3px rgba(0, 0, 0, 0.08);
-		transition: transform 0.3s ease, box-shadow 0.3s ease;
+	.resource-link {
+		display: flex;
+		align-items: flex-start;
+		gap: var(--space-3);
+		padding: var(--space-4);
+		margin: var(--space-4) 0;
+		border-radius: var(--radius-md);
+		border: 1px solid var(--color-neutral-200);
+		border-left: 4px solid var(--color-primary-400);
+		background: linear-gradient(
+			90deg,
+			rgba(28, 164, 252, 0.03) 0%,
+			transparent 50%
+		);
+		text-decoration: none;
+		color: inherit;
+		transition: all var(--transition-base);
+	}
+
+	.resource-link:hover {
+		border-left-color: var(--color-primary-600);
+		border-color: var(--color-primary-200);
+		background: linear-gradient(
+			90deg,
+			rgba(28, 164, 252, 0.06) 0%,
+			transparent 60%
+		);
+		color: inherit;
+		transform: translateX(2px);
 	}
 
-	.container:hover {
-		transform: translateY(-2px);
-		box-shadow: 0 8px 12px rgba(0, 0, 0, 0.1), 0 3px 6px rgba(0, 0, 0, 0.08);
+	.resource-link:focus-visible {
+		outline: 2px solid var(--color-primary-400);
+		outline-offset: 2px;
+		border-radius: var(--radius-md);
 	}
 
-	.container > a {
-		text-decoration: none;
-		color: inherit;
-		display: block;
-		background-color: white;
+	.resource-icon {
+		flex-shrink: 0;
+		font-size: var(--text-lg);
+		color: var(--color-primary-400);
+		margin-top: 1px;
+		transition: color var(--transition-fast), transform var(--transition-fast);
 	}
 
-	.content {
-		padding: 1.5em;
+	.resource-link:hover .resource-icon {
+		color: var(--color-primary-600);
+		transform: translateX(2px) translateY(-2px);
 	}
 
-	.title {
-		font-size: 1.2rem;
-		font-weight: bold;
-		color: var(--dark-blue);
-		margin: 0 0 0.5em;
-		line-height: 1.3;
+	.resource-body {
+		flex: 1;
+		min-width: 0;
 	}
 
-	.blurb {
-		font-size: 0.9rem;
-		color: #595959;
-		margin: 0 0 0.5em;
-		line-height: 1.4;
+	.resource-title {
+		font-size: var(--text-base);
+		font-weight: var(--font-bold);
+		color: var(--color-primary-800);
+		margin: 0 0 var(--space-1);
+		line-height: var(--leading-snug);
 	}
 
-	.url {
-		font-size: 0.8rem;
-		color: var(--med-blue);
-		word-break: break-all;
+	.resource-blurb {
+		font-size: var(--text-sm);
+		color: var(--color-text-muted);
+		margin: 0 0 var(--space-1);
+		line-height: var(--leading-normal);
 	}
 
-	.container:hover .title {
-		color: var(--med-blue);
+	.resource-domain {
+		display: inline-block;
+		font-size: var(--text-xs);
+		font-weight: var(--font-semibold);
+		color: var(--color-primary-500);
+		background-color: var(--color-primary-50);
+		padding: 0.15em 0.5em;
+		border-radius: var(--radius-sm);
+		max-width: 100%;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
 	}
 </style>
diff --git a/src/lib/components/YouTubeChapters.svelte b/src/lib/components/YouTubeChapters.svelte
index 13bc68c0..cb9c3d65 100644
--- a/src/lib/components/YouTubeChapters.svelte
+++ b/src/lib/components/YouTubeChapters.svelte
@@ -24,22 +24,24 @@
 
 <h2>Chapters</h2>
 
-<ol class="chapter-container">
+<div class="chapter-container">
 	{#each chapters as chapter, i}
-		<li class="chapter" 
-		on:keypress={() => chapterClick(chapter)} 
-		on:click={() => chapterClick(chapter)}
+		<button
+			class="chapter"
+			on:click={() => chapterClick(chapter)}
+			on:keypress={() => chapterClick(chapter)}
 		>
-			<p>
+			<span class="chapter-time">
 				{#if chapter.start.length == 2}
-				<div>{chapter.label} ({chapter.start[0]}:{chapter.start[1]})</div>
+					{chapter.start[0]}:{chapter.start[1].toString().padStart(2, '0')}
 				{:else}
-				<div>{chapter.label} ({chapter.start[0]}:{chapter.start[1]}:{chapter.start[2]})</div>
+					{chapter.start[0]}:{chapter.start[1].toString().padStart(2, '0')}:{chapter.start[2].toString().padStart(2, '0')}
 				{/if}
-			</p>
-		</li>
+			</span>
+			{chapter.label}
+		</button>
 	{/each}
-</ol>
+</div>
 
 <style>
 	.youtube-container {
@@ -51,16 +53,26 @@
 	}
 
 	.chapter-container {
-		margin-left: -1em;
-		line-height: 1.0em;
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.5em;
+		margin: calc(2 * var(--heading-spacing)) 0;
+		padding: 0;
 	}
 
 	.chapter {
-		text-decoration: none;
-		cursor: pointer;
+		display: inline-flex;
+		align-items: center;
+		gap: 0.4em;
+		padding: 0.4em 0.75em;
+		border: 1px solid var(--med-blue);
+		border-radius: 999px;
+		background: transparent;
 		color: var(--med-blue);
-		max-width: fit-content;
-		line-height: 1.7em;
+		font-size: 0.875em;
+		line-height: 1.4;
+		cursor: pointer;
+		transition: background-color 0.15s, color 0.15s;
 	}
 
 	.chapter:hover {
@@ -70,6 +82,12 @@
 
 	.chapter:active {
 		background-color: rgb(96, 96, 96);
+		border-color: rgb(96, 96, 96);
 		color: white;
 	}
+
+	.chapter-time {
+		font-variant-numeric: tabular-nums;
+		opacity: 0.8;
+	}
 </style>

From 5587c521050d1ef00433ade484a020aecd4304cb Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:33:43 +0800
Subject: [PATCH 12/13] add Button variant to widget and reference consumers

---
 .../comparing-scalers/Comparison.svelte       |  2 +-
 .../widget/comparing-scalers/Slices.svelte    |  2 +-
 src/routes/(content)/reference/+page.svx      | 29 ++++++++++---------
 .../reference/bufselect/BufSelect.svelte      |  6 ++--
 .../(content)/reference/chroma/Chroma.svelte  |  8 ++---
 .../datasetquery/DataSetQuery.svelte          |  8 ++---
 .../(content)/reference/grid/Grid.svelte      |  4 +--
 .../reference/grid/GridExtent.svelte          |  8 ++---
 .../reference/grid/GridOversample.svelte      | 12 ++++----
 .../(content)/reference/kdtree/KDTree.svelte  |  2 +-
 .../(content)/reference/kmeans/KMeans.svelte  |  2 +-
 src/routes/(content)/reference/mds/MDS.svelte |  2 +-
 .../(content)/reference/mfcc/DropZero.svelte  |  4 +--
 .../spectralshape/SpectralShape.svelte        |  2 +-
 .../(content)/reference/umap/UMAP.svelte      |  2 +-
 15 files changed, 48 insertions(+), 45 deletions(-)

diff --git a/src/lib/widget/comparing-scalers/Comparison.svelte b/src/lib/widget/comparing-scalers/Comparison.svelte
index d9779dea..b20680e7 100644
--- a/src/lib/widget/comparing-scalers/Comparison.svelte
+++ b/src/lib/widget/comparing-scalers/Comparison.svelte
@@ -239,7 +239,7 @@
 	<p>Select a scaling type below:</p>
 	<div class="scaling-mode-selector">
 		{#each buttonSpec as spec}
-			<Button width={'150px'} on:click={spec.func} label={spec.label} disabled={activeScale === spec.label} />
+			<Button variant="secondary" width={'150px'} on:click={spec.func} label={spec.label} disabled={activeScale === spec.label} />
 		{/each}
 	</div>
 </div>
diff --git a/src/lib/widget/comparing-scalers/Slices.svelte b/src/lib/widget/comparing-scalers/Slices.svelte
index aff33f53..0c65fd2e 100644
--- a/src/lib/widget/comparing-scalers/Slices.svelte
+++ b/src/lib/widget/comparing-scalers/Slices.svelte
@@ -274,7 +274,7 @@
 
 <div class="swapper">
 	{#each buttonSpec as spec}
-		<Button width={'150px'} on:click={spec.func} label={spec.label} disabled={activeScale === spec.label} />
+		<Button variant="secondary" width={'150px'} on:click={spec.func} label={spec.label} disabled={activeScale === spec.label} />
 	{/each}
 </div>
 
diff --git a/src/routes/(content)/reference/+page.svx b/src/routes/(content)/reference/+page.svx
index 49b0e477..94d8a6cf 100644
--- a/src/routes/(content)/reference/+page.svx
+++ b/src/routes/(content)/reference/+page.svx
@@ -70,38 +70,41 @@ layout: contentindex
 <style>
 	.reference-page {
 		width: 100%;
+		padding: var(--space-8);
 	}
 
 	.title {
-		color: var(--dark-blue);
-		margin-bottom: 1em;
+		color: var(--color-primary-800);
+		margin-bottom: var(--space-6);
 	}
 
 	.sticky-search {
 		position: sticky;
-		top: 0;
-		background-color: var(--background-color, white);
-		padding: 1em 0;
+		top: var(--header-height);
+		background-color: var(--color-background);
+		padding: var(--space-4) 0;
 		z-index: 10;
 	}
 
 	form {
-		margin-bottom: 2em;
+		margin-bottom: var(--space-8);
 	}
 
 	input {
 		width: 100%;
-		font-size: 1rem;
-		padding: 0.75em 1em;
-		border: 1px solid #e0e0e0;
-		border-radius: 12px;
-		transition: all 0.3s ease;
+		font-size: var(--text-base);
+		padding: var(--space-3) var(--space-4);
+		border: 1px solid var(--color-neutral-200);
+		border-radius: var(--radius-lg);
+		transition: all var(--transition-base);
+		background-color: var(--color-background);
+		color: var(--color-text);
 	}
 
 	input:focus {
 		outline: none;
-		border-color: var(--med-blue);
-		box-shadow: 0 0 0 2px rgba(3, 113, 181, 0.2);
+		border-color: var(--color-primary-600);
+		box-shadow: 0 0 0 3px rgba(3, 113, 181, 0.15);
 	}
 
 	.visually-hidden {
diff --git a/src/routes/(content)/reference/bufselect/BufSelect.svelte b/src/routes/(content)/reference/bufselect/BufSelect.svelte
index ee16bfdd..b7931e93 100644
--- a/src/routes/(content)/reference/bufselect/BufSelect.svelte
+++ b/src/routes/(content)/reference/bufselect/BufSelect.svelte
@@ -61,7 +61,7 @@
 	</div>
 
 	<div class="preset">
-		<Button
+		<Button variant="secondary"
 			on:click={() => {
 				indices = '0';
 				channels = '0 1 2 3';
@@ -69,7 +69,7 @@
 			width="100%"
 			label="First index of every channel"
 		/>
-		<Button
+		<Button variant="secondary"
 			on:click={() => {
 				indices = '0 1 2 3';
 				channels = '1';
@@ -77,7 +77,7 @@
 			width="100%"
 			label="Every index of second channel"
 		/>
-		<Button
+		<Button variant="secondary"
 			on:click={() => {
 				indices = '0 3';
 				channels = '1 3';
diff --git a/src/routes/(content)/reference/chroma/Chroma.svelte b/src/routes/(content)/reference/chroma/Chroma.svelte
index 7c5cbfe6..d08c89b3 100644
--- a/src/routes/(content)/reference/chroma/Chroma.svelte
+++ b/src/routes/(content)/reference/chroma/Chroma.svelte
@@ -121,28 +121,28 @@
 
 	<div class="controls">
 		<div class="sound-select">
-			<Button
+			<Button variant="secondary"
 				label="Bass 🎸"
 				on:click={() => {
 					updateWaveform('/audio/Tremblay-AaS-AcBassGuit-Melo-M');
 				}}
 			/>
 
-			<Button
+			<Button variant="secondary"
 				label="Piano 🎹"
 				on:click={() => {
 					updateWaveform('/audio/Tremblay-SA-UprightPianoPedalWide');
 				}}
 			/>
 
-			<Button
+			<Button variant="secondary"
 				label="Oboe 🎷"
 				on:click={() => {
 					updateWaveform('/audio/Harker-DS-TenOboeMultiphonics-M');
 				}}
 			/>
 
-			<Button
+			<Button variant="secondary"
 				label="Trombone 🎺"
 				on:click={() => {
 					updateWaveform('/audio/Olencki-TenTromboneLongTones-M');
diff --git a/src/routes/(content)/reference/datasetquery/DataSetQuery.svelte b/src/routes/(content)/reference/datasetquery/DataSetQuery.svelte
index d1644cef..00c833c4 100644
--- a/src/routes/(content)/reference/datasetquery/DataSetQuery.svelte
+++ b/src/routes/(content)/reference/datasetquery/DataSetQuery.svelte
@@ -17,7 +17,7 @@
 
 	<div class="filter-control">
 		<div class="filters">
-			<Button
+			<Button variant="secondary"
 				width={btnWidth}
 				label="filter 0 < 3, addcolumn 0"
 				on:click={() => {
@@ -28,7 +28,7 @@
 				}}
 			/>
 
-			<Button
+			<Button variant="secondary"
 				width={btnWidth}
 				label="filter 0 < 3, addrange 0 2"
 				on:click={() => {
@@ -39,7 +39,7 @@
 				}}
 			/>
 
-			<Button
+			<Button variant="secondary"
 				width={btnWidth}
 				label="filter 3 < 3, addcolumn 0, addcolumn 3"
 				on:click={() => {
@@ -49,7 +49,7 @@
 				}}
 			/>
 
-			<Button
+			<Button variant="secondary"
 				width={btnWidth}
 				label="filter 0 <= 2, addrange 0 2, addcolumn 3"
 				on:click={() => {
diff --git a/src/routes/(content)/reference/grid/Grid.svelte b/src/routes/(content)/reference/grid/Grid.svelte
index 4558161d..99d6a878 100644
--- a/src/routes/(content)/reference/grid/Grid.svelte
+++ b/src/routes/(content)/reference/grid/Grid.svelte
@@ -50,7 +50,7 @@
 	<canvas bind:this={canvas} id="scatter-plot" />
 
 	<div id="controls">
-		<Button
+		<Button variant="secondary"
 			width={'max-content'}
 			on:click={() => {
 				chart.data.datasets[0].data = grid;
@@ -59,7 +59,7 @@
 			label="Assign to Grid"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={'max-content'}
 			on:click={() => {
 				chart.data.datasets[0].data = raw;
diff --git a/src/routes/(content)/reference/grid/GridExtent.svelte b/src/routes/(content)/reference/grid/GridExtent.svelte
index afd0bdaf..f78aa81e 100644
--- a/src/routes/(content)/reference/grid/GridExtent.svelte
+++ b/src/routes/(content)/reference/grid/GridExtent.svelte
@@ -54,7 +54,7 @@
 	<canvas bind:this={canvas} id="scatter-plot" />
 
 	<div id="controls">
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			height={btnHeight}
 			on:click={() => {
@@ -64,7 +64,7 @@
 			label="Original State"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			height={btnHeight}
 			on:click={() => {
@@ -74,7 +74,7 @@
 			label="Extent 2 vertical"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			height={btnHeight}
 			on:click={() => {
@@ -84,7 +84,7 @@
 			label="Extent 5 horizontal"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			height={btnHeight}
 			on:click={() => {
diff --git a/src/routes/(content)/reference/grid/GridOversample.svelte b/src/routes/(content)/reference/grid/GridOversample.svelte
index 72694b9a..457687f1 100644
--- a/src/routes/(content)/reference/grid/GridOversample.svelte
+++ b/src/routes/(content)/reference/grid/GridOversample.svelte
@@ -55,7 +55,7 @@
 	<canvas bind:this={canvas} id="scatter-plot" />
 
 	<div id="controls">
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			on:click={() => {
 				chart.data.datasets[0].data = raw;
@@ -64,7 +64,7 @@
 			label="Original State"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			on:click={() => {
 				chart.data.datasets[0].data = Object.values(oversample1.data).map(x => x);
@@ -73,7 +73,7 @@
 			label="No Oversampling (1)"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			on:click={() => {
 				chart.data.datasets[0].data = Object.values(oversample2.data).map(x => x);
@@ -82,7 +82,7 @@
 			label="Oversampling (2)"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			on:click={() => {
 				chart.data.datasets[0].data = Object.values(oversample3.data).map(x => x);
@@ -91,7 +91,7 @@
 			label="Oversampling (3)"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			on:click={() => {
 				chart.data.datasets[0].data = Object.values(oversample4.data).map(x => x);
@@ -100,7 +100,7 @@
 			label="Oversampling (4)"
 		/>
 
-		<Button
+		<Button variant="secondary"
 			width={btnWidth}
 			on:click={() => {
 				chart.data.datasets[0].data = Object.values(oversample5.data).map(x => x);
diff --git a/src/routes/(content)/reference/kdtree/KDTree.svelte b/src/routes/(content)/reference/kdtree/KDTree.svelte
index da6fd62a..db9e4a2e 100644
--- a/src/routes/(content)/reference/kdtree/KDTree.svelte
+++ b/src/routes/(content)/reference/kdtree/KDTree.svelte
@@ -71,7 +71,7 @@
 </script>
 
 <div class="container">
-	<Button
+	<Button variant="secondary"
 		on:click={() => {
 			fit = true;
 		}}
diff --git a/src/routes/(content)/reference/kmeans/KMeans.svelte b/src/routes/(content)/reference/kmeans/KMeans.svelte
index 959ef64a..b01b48fe 100644
--- a/src/routes/(content)/reference/kmeans/KMeans.svelte
+++ b/src/routes/(content)/reference/kmeans/KMeans.svelte
@@ -173,7 +173,7 @@
 </script>
 
 <div class="container">
-	<Button on:click={doMeans} label="Calculate Means" width="100%" disabled={trainDisabled} />
+	<Button variant="secondary" on:click={doMeans} label="Calculate Means" width="100%" disabled={trainDisabled} />
 
 	<div class="controls">
 		<Select {items} on:select={updateData} placeholder="Select a dataset..." showChevron={true} />
diff --git a/src/routes/(content)/reference/mds/MDS.svelte b/src/routes/(content)/reference/mds/MDS.svelte
index bfecfc8b..8063b1c3 100644
--- a/src/routes/(content)/reference/mds/MDS.svelte
+++ b/src/routes/(content)/reference/mds/MDS.svelte
@@ -68,7 +68,7 @@
 
 	<div class="controls">
 		{#each metric as m, i}
-			<Button
+			<Button variant="secondary"
 				width={'150px'}
 				on:click={() => {
 					chart.data.datasets[0].data = m;
diff --git a/src/routes/(content)/reference/mfcc/DropZero.svelte b/src/routes/(content)/reference/mfcc/DropZero.svelte
index 24318786..1d236b27 100644
--- a/src/routes/(content)/reference/mfcc/DropZero.svelte
+++ b/src/routes/(content)/reference/mfcc/DropZero.svelte
@@ -119,8 +119,8 @@
 	<canvas id="filter" bind:this={canvas} />
 	<div class="controls">
 		<Audio {...audioSpec} bind:audio on:play={play} on:pause={pause} />
-		<Button {...zero} on:click={() => dropzero(0)} />
-		<Button {...one} on:click={() => dropzero(1)} />
+		<Button variant="secondary" {...zero} on:click={() => dropzero(0)} />
+		<Button variant="secondary" {...one} on:click={() => dropzero(1)} />
 	</div>
 </div>
 
diff --git a/src/routes/(content)/reference/spectralshape/SpectralShape.svelte b/src/routes/(content)/reference/spectralshape/SpectralShape.svelte
index 3218572c..d34861d1 100644
--- a/src/routes/(content)/reference/spectralshape/SpectralShape.svelte
+++ b/src/routes/(content)/reference/spectralshape/SpectralShape.svelte
@@ -70,7 +70,7 @@
 
 <div class="container">
 	<div class="start">
-		<Button on:click={startAudioDescriptor} label="Start Audio" width="200px" height="40px" disabled={enabled} />
+		<Button variant="secondary" on:click={startAudioDescriptor} label="Start Audio" width="200px" height="40px" disabled={enabled} />
 	</div>
 	<div class="frame" class:disabled={!enabled}>
 		<div class="plot">
diff --git a/src/routes/(content)/reference/umap/UMAP.svelte b/src/routes/(content)/reference/umap/UMAP.svelte
index ca0ae98f..b56fc853 100644
--- a/src/routes/(content)/reference/umap/UMAP.svelte
+++ b/src/routes/(content)/reference/umap/UMAP.svelte
@@ -169,7 +169,7 @@
 			<Slider bind:value={neighbors} title="Number of Neighbours" min="3" max="99" step="1" chFunc={doStep} />
 		</div>
 		<div class="btns">
-			<Button on:click={doStep} label="Go" />
+			<Button variant="secondary" on:click={doStep} label="Go" />
 
 			<Button
 				on:click={() => {

From 84c6eb262ce28ca6971e618ec7fd93b9bae46119 Mon Sep 17 00:00:00 2001
From: James Bradbury <gh@jbry.me>
Date: Sat, 11 Jul 2026 13:44:05 +0800
Subject: [PATCH 13/13] cleanup SpectralShape widget

---
 src/lib/components/Audio.svelte               |   7 +-
 .../spectralshape/SpectralShape.svelte        | 132 ++++++++++++------
 .../spectralshape/Spectrogram.svelte          |   7 +-
 3 files changed, 100 insertions(+), 46 deletions(-)

diff --git a/src/lib/components/Audio.svelte b/src/lib/components/Audio.svelte
index 3a15d122..698fd9d1 100644
--- a/src/lib/components/Audio.svelte
+++ b/src/lib/components/Audio.svelte
@@ -6,7 +6,7 @@
 	 * @param {string} label - The caption to render underneath the element.
 	 * @param {boolean} waveform - Toggle for waveform display.
 	 */
-	import { onMount } from 'svelte';
+	import { onMount, onDestroy } from 'svelte';
 	export let src = '';
 	export let label = '';
 	export let waveform = false;
@@ -47,6 +47,11 @@
 			});
 		}
 	});
+
+	onDestroy(() => {
+		if (instance) instance.destroy();
+		if (ctx) ctx.close();
+	});
 </script>
 
 <div class="container">
diff --git a/src/routes/(content)/reference/spectralshape/SpectralShape.svelte b/src/routes/(content)/reference/spectralshape/SpectralShape.svelte
index d34861d1..3d93e077 100644
--- a/src/routes/(content)/reference/spectralshape/SpectralShape.svelte
+++ b/src/routes/(content)/reference/spectralshape/SpectralShape.svelte
@@ -1,18 +1,21 @@
 <script>
+	import { onDestroy } from 'svelte';
 	import * as Meyda from 'meyda';
 	import { binToHz, clip } from '$lib/util';
 	import Audio from '$lib/components/Audio.svelte';
 	import Button from '$lib/components/Button.svelte';
 	import Spectrogram from './Spectrogram.svelte';
 
-	const windowSize = 512;
 	const bufferSize = 512;
+	const DISPLAY_INTERVAL = 100; // ms
 
 	let audio;
 
 	// Visuals
-	let chart, audioContext;
+	let chart, audioContext, meydaAnalyzer;
 	let enabled = false;
+	let isPlaying = false;
+	let error = '';
 
 	let shape = {
 		centroid: 10000,
@@ -24,63 +27,99 @@
 		crest: 0
 	};
 
+	let displayShape = { ...shape };
+	let lastDisplayUpdate = 0;
+
 	function startAudioDescriptor() {
-		enabled = true;
-		const AudioContext = window.AudioContext || window.webkitAudioContext;
-		audioContext = new AudioContext();
-		const source = audioContext.createMediaElementSource(audio);
-		source.connect(audioContext.destination);
-
-		const analyser = Meyda.createMeydaAnalyzer({
-			audioContext: audioContext,
-			source: source,
-			bufferSize: bufferSize,
-			featureExtractors: [
-				'amplitudeSpectrum',
-				'spectralCentroid',
-				'spectralSpread',
-				'spectralSkewness',
-				'spectralKurtosis',
-				'spectralRolloff',
-				'spectralFlatness',
-				'spectralCrest'
-			],
-			callback: (...features) => {
-				const desc = features[0];
-				const spectrum = desc.amplitudeSpectrum;
-				chart.data.datasets[0].data = spectrum;
-				shape.centroid = binToHz(desc.spectralCentroid, windowSize, 44100);
-				shape.spread = desc.spectralSpread;
-				shape.skewness = desc.spectralSkewness;
-				shape.kurtosis = desc.spectralKurtosis;
-				shape.rolloff = desc.spectralRolloff;
-				shape.flatness = desc.spectralFlatness;
-				shape.crest = desc.spectralCrest;
-				chart.update();
-			}
-		});
-		analyser.start();
+		try {
+			const AudioContext = window.AudioContext || window.webkitAudioContext;
+			audioContext = new AudioContext();
+			audioContext.resume();
+			const source = audioContext.createMediaElementSource(audio);
+			source.connect(audioContext.destination);
+
+			meydaAnalyzer = Meyda.createMeydaAnalyzer({
+				audioContext,
+				source,
+				bufferSize,
+				featureExtractors: [
+					'amplitudeSpectrum',
+					'spectralCentroid',
+					'spectralSpread',
+					'spectralSkewness',
+					'spectralKurtosis',
+					'spectralRolloff',
+					'spectralFlatness',
+					'spectralCrest'
+				],
+				callback: (features) => {
+					chart.data.datasets[0].data = features.amplitudeSpectrum;
+					shape.centroid = binToHz(features.spectralCentroid, bufferSize, audioContext.sampleRate);
+					shape.spread = features.spectralSpread;
+					shape.skewness = features.spectralSkewness;
+					shape.kurtosis = features.spectralKurtosis;
+					shape.rolloff = features.spectralRolloff;
+					shape.flatness = features.spectralFlatness;
+					shape.crest = features.spectralCrest;
+
+					const now = performance.now();
+					if (now - lastDisplayUpdate >= DISPLAY_INTERVAL) {
+						lastDisplayUpdate = now;
+						displayShape = { ...shape };
+						chart.update();
+					}
+				}
+			});
+			meydaAnalyzer.start();
+			enabled = true;
+		} catch (e) {
+			error = 'Failed to start audio analysis. Please try again.';
+			console.error('Audio analysis error:', e);
+		}
+	}
+
+	function onPlay() {
+		isPlaying = true;
+	}
+
+	function onPause() {
+		isPlaying = false;
+	}
+
+	$: if (chart) {
+		const ann = chart.options.plugins.annotation.annotations;
+		ann.centroid.display = isPlaying;
+		ann.rolloff.display = isPlaying;
+		if (isPlaying) {
+			ann.centroid.xMin = clip(shape.centroid, 0, 20000);
+			ann.centroid.xMax = clip(shape.centroid, 0, 20000);
+			ann.rolloff.xMin = Math.min(shape.rolloff, 20000);
+			ann.rolloff.xMax = Math.min(shape.rolloff, 20000);
+		}
 	}
 
-	$: if (chart) chart.options.plugins.annotation.annotations.centroid.xMin = clip(shape.centroid, 0, 20000);
-	$: if (chart) chart.options.plugins.annotation.annotations.centroid.xMax = clip(shape.centroid, 0, 20000);
-	$: if (chart) chart.options.plugins.annotation.annotations.rolloff.xMin = Math.min(shape.rolloff, 20000);
-	$: if (chart) chart.options.plugins.annotation.annotations.rolloff.xMax = Math.min(shape.rolloff, 20000);
+	onDestroy(() => {
+		if (meydaAnalyzer) meydaAnalyzer.stop();
+		if (audioContext) audioContext.close();
+	});
 </script>
 
 <div class="container">
 	<div class="start">
 		<Button variant="secondary" on:click={startAudioDescriptor} label="Start Audio" width="200px" height="40px" disabled={enabled} />
+		{#if error}
+			<div class="error">{error}</div>
+		{/if}
 	</div>
 	<div class="frame" class:disabled={!enabled}>
 		<div class="plot">
 			<Spectrogram bind:chart smoothing="200" />
 
 			<div class="values">
-				{#each Object.entries(shape) as [k, v]}
+				{#each Object.entries(displayShape) as [k, v]}
 					<div class="descriptor">
 						<div class:centroid={k === 'centroid'} class:rolloff={k === 'rolloff'}>{k}:</div>
-						<div class:centroid={k === 'centroid'} class:rolloff={k === 'rolloff'}>{v.toFixed(1)}</div>
+						<div class:centroid={k === 'centroid'} class:rolloff={k === 'rolloff'}>{isPlaying ? v.toFixed(1) : '—'}</div>
 					</div>
 				{/each}
 			</div>
@@ -92,6 +131,8 @@
 			label="Evolving Sound"
 			waveform={true}
 			loop={true}
+			on:play={onPlay}
+			on:pause={onPause}
 		/>
 	</div>
 </div>
@@ -103,6 +144,11 @@
 	.rolloff {
 		color: blue;
 	}
+	.error {
+		color: var(--color-error, #c00);
+		font-size: 0.875rem;
+		margin-top: 0.5em;
+	}
 	.container {
 		display: flex;
 		flex-direction: column;
diff --git a/src/routes/(content)/reference/spectralshape/Spectrogram.svelte b/src/routes/(content)/reference/spectralshape/Spectrogram.svelte
index e3dc1cfe..60f2ac05 100644
--- a/src/routes/(content)/reference/spectralshape/Spectrogram.svelte
+++ b/src/routes/(content)/reference/spectralshape/Spectrogram.svelte
@@ -109,14 +109,17 @@
 	});
 
 	export let scale = 1;
-	$: if (chart) chart.options.scales.x.type = scale === 0 ? 'linear' : 'logarithmic';
+	$: if (chart) {
+		chart.options.scales.x.type = scale === 0 ? 'linear' : 'logarithmic';
+		chart.update();
+	}
 </script>
 
 <div class="container">
 	<form>
 		<select bind:value={scale} id="scaling" name="spectrogram-scale" placeholder="spectrogram scaling">
 			<option value={0}>Linear</option>
-			<option value={1}>Logarthmic</option>
+			<option value={1}>Logarithmic</option>
 		</select>
 	</form>
 	<canvas id="vis" bind:this={canvas} />