From 3e674c939b984167eff894f2f00ad9eff150284e Mon Sep 17 00:00:00 2001
From: Keavon Chambers <keavon@keavon.com>
Date: Tue, 30 Jun 2026 01:42:40 -0700
Subject: [PATCH] Revamp the stand-in for embedded YouTube videos on the
 website

---
 website/content/_index.md                     | 10 +--
 ...01-looking-back-on-2023-and-what's-next.md |  4 +-
 ...view-2024-highlights-and-a-peek-at-2025.md |  4 +-
 ...ps-for-a-rust-graphics-engine-gsoc-2025.md |  4 +-
 website/content/features.md                   |  4 +-
 website/content/learn/_index.md               |  4 +-
 website/content/learn/introduction/_index.md  |  4 +-
 .../guide/codebase-overview/_index.md         |  4 +-
 website/sass/component/youtube-embed.scss     | 73 +++++++++++++++++--
 website/static/js/component/youtube-embed.js  | 36 +++++----
 .../templates/shortcodes/youtube_embed.html   | 14 ++++
 11 files changed, 109 insertions(+), 52 deletions(-)
 create mode 100644 website/templates/shortcodes/youtube_embed.html

diff --git a/website/content/_index.md b/website/content/_index.md
index 196e67f0ef..dc3930aa65 100644
--- a/website/content/_index.md
+++ b/website/content/_index.md
@@ -85,7 +85,7 @@ meta_description = "Open source free software. A vector graphics creativity suit
 <section id="screenshots" class="carousel window-size-1" data-carousel data-carousel-jostle-hint>
 
 <div class="carousel-slide" data-carousel-slide>
-	<img src="https://static.graphite.art/content/index/gui-demo-creative-coding-poster.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="" style="transform: translateX(-100%)" data-carousel-image />
+	<img src="https://static.graphite.art/content/index/gui-demo-fractal__4.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="" style="transform: translateX(-100%)" data-carousel-image />
 	<!-- Above is a copy of the last -->
 	<img onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="" style="transform: translateX(-100%)" data-carousel-image width="1920" height="1080" loading="lazy" src="https://static.graphite.art/content/index/gui-demo-painted-dreams__4.avif" />
 	<img onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="" style="transform: translateX(-100%)" data-carousel-image width="1920" height="1080" loading="lazy" src="https://static.graphite.art/content/index/gui-demo-magazine-page-layout.avif" />
@@ -165,9 +165,7 @@ The latest major update is out now! See what the team has been cooking up recent
 
 <div class="block video-container">
 <div>
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="U3E-sWo2H_M" loading="lazy" src="https://static.graphite.art/content/index/video-may-2026-update.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="May Update - Graphite, the Open Source 2D Graphics Suite" />
-</div>
+{{ youtube_embed(id="U3E-sWo2H_M", title="May Update - Graphite, the Open Source 2D Graphics Suite") }}
 </div>
 </div>
 
@@ -496,9 +494,7 @@ Get started with Graphite by following along to a hands-on quickstart tutorial.
 
 <div class="block video-container">
 <div>
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="7gjUhl_3X10" loading="lazy" src="https://static.graphite.art/content/learn/introduction/tutorial-1-vector-art-quickstart-youtube__2.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite" />
-</div>
+{{ youtube_embed(id="7gjUhl_3X10", title="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite") }}
 </div>
 </div>
 
diff --git a/website/content/blog/2024-01-01-looking-back-on-2023-and-what's-next.md b/website/content/blog/2024-01-01-looking-back-on-2023-and-what's-next.md
index ccc171a1af..96ee185633 100644
--- a/website/content/blog/2024-01-01-looking-back-on-2023-and-what's-next.md
+++ b/website/content/blog/2024-01-01-looking-back-on-2023-and-what's-next.md
@@ -93,9 +93,7 @@ The next big news of August was my formation of [Graphite Labs, LLC](https://www
 
 I allocated my time at several points throughout the year into growing and evolving this website with a refreshed and more visually-appealing home page, dedicated pages for information [about](/about) the project and its [features](/features), an area providing resources and help for [volunteers](/volunteer) and [code contributors](/volunteer/guide), and just this month— a [user manual](/learn) complete with an introductory tutorial series. The first video went up yesterday:
 
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="7gjUhl_3X10" src="https://static.graphite.art/content/learn/introduction/tutorial-1-vector-art-quickstart-youtube__2.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite" />
-</div>
+{{ youtube_embed(id="7gjUhl_3X10", title="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite") }}
 
 The user manual and tutorial series will continue expanding throughout the coming weeks. Additional website features including user accounts, forums, and other community features are being planned.
 
diff --git a/website/content/blog/2025-01-16-year-in-review-2024-highlights-and-a-peek-at-2025.md b/website/content/blog/2025-01-16-year-in-review-2024-highlights-and-a-peek-at-2025.md
index c127e3c933..51450a629d 100644
--- a/website/content/blog/2025-01-16-year-in-review-2024-highlights-and-a-peek-at-2025.md
+++ b/website/content/blog/2025-01-16-year-in-review-2024-highlights-and-a-peek-at-2025.md
@@ -119,9 +119,7 @@ The next month in April, Oliver and I went to our second conference of the year:
 
 I also took to the main stage to present a lightning talk introducing Graphite to the community:
 
-<div class="youtube-embed aspect-16x9">
-	<img src="https://static.graphite.art/content/blog/2025-01-16-year-in-review-2024-highlights-and-a-peek-at-2025/bcon-la-talk-video-cover.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" data-youtube-embed="x3P5eYv11EU" data-youtube-timestamp="1603" alt="BCON LA 2024 - Lightning Talks" />
-</div>
+{{ youtube_embed(id="x3P5eYv11EU", timestamp=1603, title="BCON LA 2024 - Lightning Talks") }}
 
 ### Graphite booth at Open Sauce
 
diff --git a/website/content/blog/2025-04-02-internships-for-a-rust-graphics-engine-gsoc-2025.md b/website/content/blog/2025-04-02-internships-for-a-rust-graphics-engine-gsoc-2025.md
index 358ff48b72..390fea5201 100644
--- a/website/content/blog/2025-04-02-internships-for-a-rust-graphics-engine-gsoc-2025.md
+++ b/website/content/blog/2025-04-02-internships-for-a-rust-graphics-engine-gsoc-2025.md
@@ -24,9 +24,7 @@ Do you love Rust and focus on computer graphics, compiler development, or algori
 
 Hear from our mentoring team about Graphite's tech stack and engineering vision by listening to last month's episode of the Developer Voices podcast:
 
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="ZUbcwUC5lxA" src="https://static.graphite.art/content/blog/2025-04-02-internships-for-a-rust-graphics-engine-gsoc-2025/developer-voices-podcast-youtube.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Graphite: Image Editing as a Syntax Tree (with Keavon Chambers & Dennis Kobert)" />
-</div>
+{{ youtube_embed(id="ZUbcwUC5lxA", title="Graphite: Image Editing as a Syntax Tree (with Keavon Chambers & Dennis Kobert)") }}
 
 For GSoC 2025, our priority focus is mentoring projects revolving around advanced graphics techniques and compiler development, meeting our goal of extending Graphite into the domain of raster image manipulation. Demonstrated experience in these areas is highly advantageous.
 
diff --git a/website/content/features.md b/website/content/features.md
index 5970fe23d8..0c08a3d63a 100644
--- a/website/content/features.md
+++ b/website/content/features.md
@@ -21,9 +21,7 @@ The current alpha version of Graphite is a tool for vector art and graphic desig
 
 <div class="block video-container">
 <div>
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="ZUbcwUC5lxA" loading="lazy" src="https://static.graphite.art/content/features/podcast-interview-youtube.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Rust-Powered Graphics Editor: How Graphite's Syntax Trees Revolutionize Image Editing" />
-</div>
+{{ youtube_embed(id="ZUbcwUC5lxA", title="Rust-Powered Graphics Editor: How Graphite's Syntax Trees Revolutionize Image Editing") }}
 </div>
 </div>
 
diff --git a/website/content/learn/_index.md b/website/content/learn/_index.md
index 5fe4aaaabf..da410be059 100644
--- a/website/content/learn/_index.md
+++ b/website/content/learn/_index.md
@@ -25,6 +25,4 @@ If you're ever stuck or confused, ask your questions in the `#🧭user-help` cha
 
 The fastest way to get started is to watch and follow along steps-by-step in the hands-on quickstart tutorial:
 
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="7gjUhl_3X10" src="https://static.graphite.art/content/learn/introduction/tutorial-1-vector-art-quickstart-youtube__2.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite" />
-</div>
+{{ youtube_embed(id="7gjUhl_3X10", title="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite") }}
diff --git a/website/content/learn/introduction/_index.md b/website/content/learn/introduction/_index.md
index dcd3c980fd..894e2ce662 100644
--- a/website/content/learn/introduction/_index.md
+++ b/website/content/learn/introduction/_index.md
@@ -15,8 +15,6 @@ Begin learning Graphite by watching the introductory tutorial video below.
 
 One is available now, and more will be released on a regular basis throughout early 2026.
 
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="7gjUhl_3X10" src="https://static.graphite.art/content/learn/introduction/tutorial-1-vector-art-quickstart-youtube__2.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite" />
-</div>
+{{ youtube_embed(id="7gjUhl_3X10", title="Vector Art Quickstart - Graphite, the Open Source 2D Graphics Suite") }}
 
 *More tutorials coming soon.*
diff --git a/website/content/volunteer/guide/codebase-overview/_index.md b/website/content/volunteer/guide/codebase-overview/_index.md
index baeda09e7e..d827f019f6 100644
--- a/website/content/volunteer/guide/codebase-overview/_index.md
+++ b/website/content/volunteer/guide/codebase-overview/_index.md
@@ -11,9 +11,7 @@ css = ["/component/youtube-embed.css", "/page/contributor-guide/crate-hierarchy.
 
 The best introduction for getting up-to-speed with Graphite contribution comes from watching this webcast recording. Before asking questions in Discord, please watch the full video because it gives a comprehensive overview of most things you will need to know.
 
-<div class="youtube-embed aspect-16x9">
-	<img data-youtube-embed="vUzIeg8frh4" src="https://static.graphite.art/content/volunteer/guide/workshop-intro-to-coding-for-graphite-youtube.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Workshop: Intro to Coding for Graphite" />
-</div>
+{{ youtube_embed(id="vUzIeg8frh4", title="Workshop: Intro to Coding for Graphite") }}
 
 ## Codebase structure
 
diff --git a/website/sass/component/youtube-embed.scss b/website/sass/component/youtube-embed.scss
index 63e962e6d9..92480dd25e 100644
--- a/website/sass/component/youtube-embed.scss
+++ b/website/sass/component/youtube-embed.scss
@@ -1,21 +1,78 @@
 .youtube-embed {
 	position: relative;
 	width: 100%;
+	padding-top: calc(100% / (16 / 9));
+	// Lets the overlay chrome scale proportionally with the player's width via `cqw` units
+	container-type: inline-size;
 
-	&.aspect-16x9 {
-		padding-top: calc(100% / (16 / 9));
-	}
-
-	img,
+	.youtube-embed-thumbnail,
+	.youtube-embed-shade,
 	iframe {
 		position: absolute;
 		width: 100%;
 		height: 100%;
-		top: 0;
-		left: 0;
+		inset: 0;
+		border: none;
 	}
 
-	img {
+	.youtube-embed-thumbnail {
 		cursor: pointer;
+		object-fit: cover;
+		background: #000;
+	}
+
+	.youtube-embed-shade {
+		height: 8.75cqw;
+		background: linear-gradient(rgba(0, 0, 0, 0.8), rgba(0, 0, 0, 0.6), transparent);
+		pointer-events: none;
+	}
+
+	.youtube-embed-play {
+		position: absolute;
+		transform: translate(-50%, -50%);
+		top: 50%;
+		left: 50%;
+		width: 8.5cqw;
+		height: auto;
+		pointer-events: none;
+	}
+
+	.youtube-embed-title {
+		position: absolute;
+		top: 1cqw;
+		left: 3.4cqw;
+		right: 3.4cqw;
+		font-size: 2.5cqw;
+		font-weight: 700;
+		white-space: nowrap;
+		overflow: hidden;
+		text-decoration: none;
+		color: #fff;
+		mask-image: linear-gradient(to right, #fff 95%, transparent);
+	}
+
+	.youtube-embed-watch {
+		display: flex;
+		align-items: center;
+		position: absolute;
+		border-radius: 3cqw;
+		height: 6cqw;
+		right: 3.6cqw;
+		bottom: 1.5cqw;
+		padding: 0 3cqw;
+		gap: 0.5cqw;
+		background: rgba(0, 0, 0, 0.3);
+		font-size: 2.25cqw;
+		font-weight: 400;
+		color: #fff;
+		text-decoration: none;
+
+		&:hover {
+			background: rgba(40, 40, 40, 0.6);
+		}
+
+		img {
+			height: 2.3cqw;
+		}
 	}
 }
diff --git a/website/static/js/component/youtube-embed.js b/website/static/js/component/youtube-embed.js
index 9963f8ff08..6f9aa8646d 100644
--- a/website/static/js/component/youtube-embed.js
+++ b/website/static/js/component/youtube-embed.js
@@ -1,24 +1,28 @@
 window.addEventListener("DOMContentLoaded", () => {
 	document.querySelectorAll("[data-youtube-embed]").forEach((placeholder) => {
 		if (!(placeholder instanceof HTMLElement)) return;
-		placeholder.addEventListener("click", () => {
+
+		const loadIframe = () => {
 			const videoId = placeholder.getAttribute("data-youtube-embed") || "";
 			const timestamp = placeholder.getAttribute("data-youtube-timestamp") || "";
-			placeholder.outerHTML = `
-				<iframe \\
-				width="1280" \\
-				height="720" \\
-				src="https://www.youtube.com/embed/${videoId}?${timestamp ? `start=${timestamp}&` : ""}autoplay=1" \\
-				frameborder="0" \\
-				allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" \\
-				allowfullscreen\\
-				>\\
-				</iframe>\\
-				`
-				.split("\n")
-				.map((line) => line.trim())
-				.join("")
-				.replaceAll(`\\`, "");
+
+			const iframe = document.createElement("iframe");
+			iframe.width = "1280";
+			iframe.height = "720";
+			iframe.src = `https://www.youtube.com/embed/${videoId}?autoplay=1${timestamp ? `&start=${timestamp}` : ""}`;
+			iframe.allow = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture";
+			iframe.allowFullscreen = true;
+
+			const embed = placeholder.closest("[data-youtube-embed]");
+			embed?.replaceChildren(iframe);
+		};
+
+		placeholder.addEventListener("click", loadIframe);
+		placeholder.addEventListener("keydown", (event) => {
+			if (event.key === "Enter" || event.key === " ") {
+				event.preventDefault();
+				loadIframe();
+			}
 		});
 	});
 });
diff --git a/website/templates/shortcodes/youtube_embed.html b/website/templates/shortcodes/youtube_embed.html
new file mode 100644
index 0000000000..1220f1eb87
--- /dev/null
+++ b/website/templates/shortcodes/youtube_embed.html
@@ -0,0 +1,14 @@
+{%- set alt = alt | default(value = title) -%}
+{%- set timestamp = timestamp | default(value = 0) -%}
+{%- set watch_url = "https://www.youtube.com/watch?v=" ~ id -%}
+{%- if timestamp %}{% set watch_url = watch_url ~ "&t=" ~ timestamp %}{% endif -%}
+<div class="youtube-embed" data-youtube-embed="{{ id }}" {% if timestamp %}data-youtube-timestamp="{{ timestamp }}"{% endif %} role="button" tabindex="0">
+	<img class="youtube-embed-thumbnail" loading="lazy" src="https://img.youtube.com/vi/{{ id }}/maxresdefault.jpg" onload="if (this.naturalWidth < 1000 && this.src.includes('maxresdefault')) this.src = 'https://img.youtube.com/vi/{{ id }}/hqdefault.jpg'" onerror="this.onerror = null; this.src = 'https://img.youtube.com/vi/{{ id }}/hqdefault.jpg'" alt="{{ alt }}" />
+	<div class="youtube-embed-shade"></div>
+	<img class="youtube-embed-play" src="https://static.graphite.art/icons/youtube-embed-play.svg" />
+	<a class="youtube-embed-title" href="{{ watch_url }}" target="_blank" rel="noopener">{{ title }}</a>
+	<a class="youtube-embed-watch" href="{{ watch_url }}" target="_blank" rel="noopener">
+		<span>Watch on</span>
+		<img src="https://static.graphite.art/icons/youtube-embed-logo.svg" alt="YouTube" />
+	</a>
+</div>