Add a new dedicated theme showcase page (#2911)

Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>

Author: delucis

CONTRIBUTING.md

@@ -290,6 +290,8 @@ To add a language, you will need its BCP-47 tag and a label. See [“Adding a ne
 
 ## Showcase
 
+### Sites
+
 We love to see websites built with Starlight and share them with the community on our [showcase](https://starlight.astro.build/resources/showcase/) page.
 If you’ve built a documentation site with Starlight, adding it to the showcase is just a pull request away!
 
@@ -312,3 +314,43 @@ If you’ve built a documentation site with Starlight, adding it to the showcase
    ```
 
 4. Open a pull request on GitHub to add your changes.
+
+### Themes
+
+Share themes for Starlight you built by adding them to our [themes](https://starlight.astro.build/resources/themes/) page. Here’s how!
+
+1. Set up a development environment by following the [“Setting up a development environment”](#setting-up-a-development-environment) instructions.
+
+2. Take screenshots of your theme’s light and dark modes using our demo project.
+
+   1. Open the [theme demo project](https://stackblitz.com/edit/github-jj1kzx5x?file=astro.config.mjs) on StackBlitz.
+
+   2. Install your theme using StackBlitz’s integrated terminal:
+
+      ```sh
+      npm i your-theme-name
+      ```
+
+   3. Update `astro.config.mjs` to import your theme and add it to Starlight’s `plugins` array.
+
+   4. Run the dev server:
+
+      ```sh
+      npm run dev
+      ```
+
+   5. Open the theme preview in a new tab and use dev tools’ responsive view to take screenshots with the screen sized to 1280×720 pixels.
+
+3. Add your screenshots of the theme’s light and dark modes to the `docs/src/assets/themes/` directory. The images must:
+
+   - be PNG files with your theme’s name and the color variant, e.g. a theme named “Moon” would have files named `moon-light.png` and `moon-dark.png`
+   - have dimensions of 1280×720 pixels
+
+4. Add a new entry for your website in `docs/src/content/docs/resources/themes.mdx`.
+   You can look at existing entries to see how to format this.
+
+   - The new entry must be appended at the end of the existing list of sites.
+   - The `title` attribute must be the name of your theme.
+   - The `description` attribute should briefly describe your theme’s aesthetic, inspiration, or key features.
+   - The `href` attribute must be the URL of your theme’s website demonstrating what the theme looks like.
+   - The `previews` attribute must be an object listing the filenames of the screenshots you added in step 3.

docs/src/assets/themes/black-dark.png

@@ -1,17 +1,18 @@
 ---
 interface Props {
 	minColumnWidth?: string;
+	gap?: string;
 }
-const { minColumnWidth } = Astro.props;
+const { minColumnWidth, gap } = Astro.props;
 ---
 
 <ul class="fluid-grid"><slot /></ul>
 
-<style define:vars={{ minColumnWidth }}>
+<style define:vars={{ minColumnWidth, gap }}>
 	.fluid-grid {
 		display: grid;
 		grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--minColumnWidth, 11rem)), 1fr));
-		gap: 1rem;
+		gap: var(--gap, 1rem);
 		list-style: none;
 		padding: 0;
 	}

docs/src/assets/themes/black-light.png

@@ -34,7 +34,7 @@ const El = href ? 'a' : 'span';
 
 	.media :global(img) {
 		display: block;
-		max-width: 100%;
+		width: 100%;
 		height: auto;
 		aspect-ratio: 16 / 9;
 		object-fit: cover;

docs/src/assets/themes/catppuccin-dark.png

@@ -0,0 +1,221 @@
+---
+import { Icon } from '@astrojs/starlight/components';
+import FluidGrid from './fluid-grid.astro';
+import MediaCard from './media-card.astro';
+import ThemeImage from './theme-image.astro';
+
+interface Props {
+	labels: {
+		/** Accessible label for the theme toggle. */
+		legend: string;
+		/** Accessible label for the dark color scheme variant. */
+		dark: string;
+		/** Accessible label for the light color scheme variant. */
+		light: string;
+	};
+	themes: Array<{
+		/** The name of this theme. */
+		title: string;
+		/** A short description of this theme. */
+		description: string;
+		/** URL for this theme’s website. Ideally should link to a demo site showing off the theme. */
+		href: string;
+		previews: {
+			/** Image filename as found in `src/assets/themes/`, e.g. `ion-light.png`. */
+			light: string;
+			/** Image filename as found in `src/assets/themes/`, e.g. `ion-dark.png`. */
+			dark: string;
+		};
+	}>;
+}
+
+const { labels, themes } = Astro.props;
+---
+
+<starlight-theme-preview data-theme-preview="dark">
+	<fieldset class="not-content sl-flex">
+		{
+			/* `<legend>` is a pain to position, so we visually hide it and use an `aria-hidden` duplicate
+		for the visual representation. See https://adrianroselli.com/2022/07/use-legend-and-fieldset.html */
+		}
+		<legend class="sr-only">{labels.legend}</legend>
+		<strong aria-hidden="true">{labels.legend}</strong>
+		{
+			(['dark', 'light'] as const).map((variant) => (
+				<label class:list={['sl-flex', variant]} for={`${variant}-input`}>
+					<span class="radio">
+						<Icon name="approve-check" />
+					</span>
+					<span>{labels[variant]}</span>
+					<input
+						id={`${variant}-input`}
+						class="sr-only"
+						name="preview-theme"
+						value={variant}
+						type="radio"
+						checked={variant === 'dark'}
+					/>
+				</label>
+			))
+		}
+		{/* If the currently active theme is light mode, default to showing the light mode previews. */}
+		<script is:inline>
+			// @ts-nocheck
+			const theme = document.documentElement.dataset.theme || 'dark';
+			const input = document.querySelector(`input[value="${theme}"]`);
+			if (input) input.checked = true;
+			const customEl = document.querySelector('starlight-theme-preview');
+			if (customEl) customEl.dataset.themePreview = theme;
+		</script>
+	</fieldset>
+
+	<FluidGrid minColumnWidth="25rem" gap="clamp(1rem, calc(0.75rem + 1vw), 1.5rem)">
+		{
+			themes.map(
+				async ({ title, description, href, previews }) =>
+					previews && (
+						<MediaCard {href}>
+							<div class="preview-images" slot="media" aria-hidden="true">
+								<ThemeImage src={previews.light} class="light" />
+								<ThemeImage src={previews.dark} class="dark" />
+							</div>
+							<div class="meta sl-flex">
+								<p class="title">{title}</p>
+								<p class="description" set:html={description} />
+							</div>
+						</MediaCard>
+					)
+			)
+		}
+	</FluidGrid>
+</starlight-theme-preview>
+
+<script>
+	customElements.define(
+		'starlight-theme-preview',
+		class ThemePreview extends HTMLElement {
+			constructor() {
+				super();
+				this.querySelector('fieldset')?.addEventListener('change', ({ target }) => {
+					if (target instanceof HTMLInputElement) {
+						this.dataset.themePreview = target.value;
+					}
+				});
+			}
+		}
+	);
+</script>
+
+<style>
+	starlight-theme-preview {
+		--transition-time: 0.25s;
+		display: block;
+	}
+
+	fieldset {
+		/* Snappier transitions for the form controls. */
+		--transition-time: 0.15s;
+
+		/* Stick the control bar to bottom of the nav bar on scroll. */
+		position: sticky;
+		top: var(--sl-nav-height);
+		z-index: var(--sl-z-index-toc);
+		/* Pull the bar out so it is full width on small screens. */
+		margin-inline: calc(-1 * var(--sl-nav-pad-x));
+		padding: var(--sl-nav-pad-y) var(--sl-nav-pad-x);
+		/* Internal layout and styles. */
+		gap: 1rem;
+		align-items: center;
+		justify-content: end;
+		border: 1px solid var(--sl-color-hairline);
+		font-size: var(--sl-text-sm);
+		background-color: var(--sl-color-bg-nav);
+		box-shadow: var(--sl-shadow-md);
+	}
+	@media (min-width: 50rem) and (max-width: 72rem) {
+		/* Medium-width screens need a custom value to avoid x-axis overflow. */
+		fieldset {
+			margin-inline: -1rem;
+		}
+	}
+
+	label {
+		align-items: center;
+		gap: 0.375rem;
+		color: var(--sl-color-gray-3);
+		transition: color var(--transition-time) ease-in-out;
+	}
+	label:hover,
+	label:has(:checked) {
+		color: var(--sl-color-white);
+	}
+
+	.radio {
+		display: grid;
+		place-content: center;
+		border: 1px solid var(--sl-color-gray-5);
+		border-radius: 100%;
+		width: 1.5rem;
+		height: 1.5rem;
+		background-color: #000;
+		color: #fff;
+		transition: transform var(--transition-time) ease-in-out;
+	}
+	label:not(:has(:checked)):hover .radio {
+		transform: scale(1.15);
+	}
+	.light .radio {
+		background-color: #fff;
+		color: #000;
+	}
+
+	/* Show the input’s focus ring on the label. */
+	label:has(:focus-visible) {
+		outline: auto;
+		outline-offset: 2px;
+	}
+
+	/* Show check mark icon only when input is checked. */
+	label svg {
+		opacity: 0;
+		transition: opacity var(--transition-time) ease-in-out;
+	}
+	label:has(:checked) svg {
+		opacity: 1;
+	}
+
+	/* Stack light/dark images in the same grid row and column. */
+	.preview-images {
+		display: grid;
+		grid-template-columns: 1fr;
+	}
+	.preview-images > * {
+		grid-area: 1 / 1;
+	}
+
+	/* Fade out the preview image that isn’t currently selected. */
+	img {
+		transition: opacity var(--transition-time) ease-in-out;
+	}
+	[data-theme-preview='dark'] img.light {
+		opacity: 0;
+	}
+	[data-theme-preview='light'] img.dark {
+		opacity: 0;
+	}
+
+	.meta {
+		padding: 1rem;
+		flex-direction: column;
+		gap: 0.5rem;
+	}
+
+	.title {
+		font-size: var(--sl-text-lg);
+	}
+
+	.description {
+		color: var(--sl-color-gray-3);
+		line-height: 1.5;
+	}
+</style>

docs/src/assets/themes/catppuccin-light.png

@@ -0,0 +1,37 @@
+---
+import { AstroError } from 'astro/errors';
+import { Image } from 'astro:assets';
+
+interface Props {
+	src: string;
+	class: 'light' | 'dark';
+}
+
+const thumbnails = import.meta.glob<{ default: ImageMetadata }>(
+	'../assets/themes/*{.png,.jpg,.jpeg,.webp,.avif}'
+);
+
+const thumbnail = thumbnails[`../assets/themes/${Astro.props.src}`];
+if (!thumbnail) {
+	throw new Error(`Could not resolve showcase thumbnail: ${Astro.props.src}`);
+}
+const src = (await thumbnail()).default;
+
+if (src.width !== 1280 || src.height !== 720) {
+	let fileName = src.src.split('/').pop();
+	const queryIndex = fileName?.indexOf('?');
+	if (queryIndex !== undefined && queryIndex > -1) {
+		fileName = fileName?.slice(0, queryIndex);
+	}
+	throw new AstroError(
+		'Theme screenshots must be **1280×720px**',
+		`Dimensions of **${src.width}×${src.height}px** found for theme 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 **1280×720px** if necessary 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#themes)\n`
+	);
+}
+---
+
+<Image {src} alt="" width="960" class={Astro.props.class} />

docs/src/assets/themes/flexoki-dark.png

@@ -7,6 +7,8 @@ import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
 
 You can style your Starlight site with custom CSS files or use the Starlight Tailwind plugin.
 
+For a quick way to change the default style of your site, check out [community themes](/resources/themes/).
+
 ## Custom CSS styles
 
 Customize the styles applied to your Starlight site by providing additional CSS files to modify or extend Starlight’s default styles.

docs/src/assets/themes/flexoki-light.png

@@ -130,38 +130,6 @@ Extend your site with official plugins supported by the Starlight team and commu
 	/>
 </CardGrid>
 
-### Community themes
-
-A theme is a Starlight plugin that changes the visual appearance of a site with component overrides, custom CSS, or other new features.
-
-<CardGrid>
-	<LinkCard
-		href="https://github.com/HiDeoo/starlight-theme-rapide"
-		title="starlight-theme-rapide"
-		description="Starlight theme inspired by the Visual Studio Code Vitesse theme."
-	/>
-	<LinkCard
-		href="https://github.com/Fevol/starlight-theme-obsidian"
-		title="starlight-theme-obsidian"
-		description="Starlight theme inspired by the style of Obsidian Publish sites."
-	/>
-	<LinkCard
-		href="https://github.com/TheOtterlord/catppuccin-starlight"
-		title="catppuccin-starlight"
-		description="Soothing pastel theme for Starlight"
-	/>
-	<LinkCard
-		href="https://github.com/louisescher/starlight-ion-theme"
-		title="starlight-ion-theme"
-		description="A sleek, modern theme for Starlight."
-	/>
-	<LinkCard
-		href="https://github.com/adrian-ub/starlight-theme-black"
-		title="starlight-theme-black"
-		description="Starlight theme inspired by shadcn docs"
-	/>
-</CardGrid>
-
 ## Community tools and integrations
 
 import { CardGrid, LinkCard } from '@astrojs/starlight/components';