diff --git a/docs/src/components/showcase-card.astro b/docs/src/components/showcase-card.astro
index 8d942af2c32..2ca38fdb434 100644
--- a/docs/src/components/showcase-card.astro
+++ b/docs/src/components/showcase-card.astro
@@ -2,6 +2,7 @@
 import type { ImageMetadata } from 'astro';
 import { Image } from 'astro:assets';
 import MediaCard from './media-card.astro';
+import { AstroError } from 'astro/errors';
 
 interface Props {
 	href: string;
@@ -18,6 +19,22 @@ if (!thumbnail) {
 	throw new Error(`Could not resolve showcase thumbnail: ${Astro.props.thumbnail}`);
 }
 const src = (await thumbnail()).default;
+
+if (src.width !== 800 || src.height !== 450) {
+	let fileName = src.src.split('/').pop();
+	const queryIndex = fileName?.indexOf('?');
+	if (queryIndex !== undefined && queryIndex > -1) {
+		fileName = fileName?.slice(0, queryIndex);
+	}
+	throw new AstroError(
+		'Showcase images must be **800×450px**',
+		`Dimensions of **${src.width}×${src.height}px** found for showcase image \`${fileName || src.src}\`\n\n` +
+			`For best results:\n\n` +
+			`1. Take a screenshot of the site using a browser resized to **1280×720px**. The responsive view in dev tools can be helpful for this.\n\n` +
+			`2. Resize the screenshot to **800×450px** and make sure it is saved as a PNG. An online tool like [Squoosh](https://squoosh.app/) can help here.\n\n` +
+			`See more details in the [Starlight contributing guide](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md#showcase)\n`
+	);
+}
 ---
 
 <MediaCard {href}>