Add LinkCard Component (#397)

Co-authored-by: Lorenzo Lewis <lorenzo@crabnebula.dev>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

5 files changed, 121 insertions, 0 deletions

diff --git a/.changeset/swift-kiwis-wash.md b/.changeset/swift-kiwis-wash.md
new file mode 100644
index 00000000..b282c63e
--- /dev/null
+++ b/.changeset/swift-kiwis-wash.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Add `LinkCard` component
diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx
index 1b7638b0..ee128795 100644
--- a/docs/src/content/docs/guides/components.mdx
+++ b/docs/src/content/docs/guides/components.mdx
@@ -125,6 +125,44 @@ Add the `stagger` attribute to shift the second column of cards vertically and a
 
 :::
 
+### Link Cards
+
+Use the `<LinkCard>` component to link prominently to different pages.
+
+A `<LinkCard>` requires a `title` and an [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) attribute. You can optionally include a short `description` or other link attributes such as `target`.
+
+Group multiple `<LinkCard>` components in `<CardGrid>` to display cards side-by-side when there’s enough space.
+
+```mdx
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
+
+<LinkCard
+	title="Customizing Starlight"
+	description="Learn how to make your Starlight site your own with custom styles, fonts, and more."
+	href="/guides/customization/"
+/>
+
+<CardGrid>
+	<LinkCard title="Authoring Markdown" href="/guides/authoring-content/" />
+	<LinkCard title="Components" href="/guides/components/" />
+</CardGrid>
+```
+
+The above code generates the following on the page:
+
+import { LinkCard } from '@astrojs/starlight/components';
+
+<LinkCard
+	title="Customizing Starlight"
+	description="Learn how to make your Starlight site your own with custom styles, fonts, and more."
+	href="/guides/customization/"
+/>
+
+<CardGrid>
+	<LinkCard title="Authoring Markdown" href="/guides/authoring-content/" />
+	<LinkCard title="Components" href="/guides/components/" />
+</CardGrid>
+
 ### Icon
 
 import { Icon } from '@astrojs/starlight/components';
diff --git a/packages/starlight/components.ts b/packages/starlight/components.ts
index 6fd711e8..ac1c0f7b 100644
--- a/packages/starlight/components.ts
+++ b/packages/starlight/components.ts
@@ -3,3 +3,4 @@ export { default as CardGrid } from './user-components/CardGrid.astro';
 export { default as Icon } from './user-components/Icon.astro';
 export { default as Tabs } from './user-components/Tabs.astro';
 export { default as TabItem } from './user-components/TabItem.astro';
+export { default as LinkCard } from './user-components/LinkCard.astro';
diff --git a/packages/starlight/style/util.css b/packages/starlight/style/util.css
index 7451f6e0..57ed29d4 100644
--- a/packages/starlight/style/util.css
+++ b/packages/starlight/style/util.css
@@ -41,3 +41,15 @@
 		display: block;
 	}
 }
+
+/*
+Flip an element around the y-axis when in an RTL context.
+Primarily useful for things where we can’t rely on writing direction like icons.
+
+<Icon name="right-arrow" class="rtl:flip" />
+
+In a LTR context: →					In a RTL context: ←
+*/
+[dir='rtl'] .rtl\:flip:not(:where([dir='rtl'] [dir='ltr'] *)) {
+	transform: matrix(-1, 0, 0, 1, 0, 0);
+}
diff --git a/packages/starlight/user-components/LinkCard.astro b/packages/starlight/user-components/LinkCard.astro
new file mode 100644
index 00000000..683ac749
--- /dev/null
+++ b/packages/starlight/user-components/LinkCard.astro
@@ -0,0 +1,65 @@
+---
+import Icon from './Icon.astro';
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends Omit<HTMLAttributes<'a'>, 'title'> {
+	title: string;
+	description?: string;
+}
+
+const { title, description, ...attributes } = Astro.props;
+---
+
+<div>
+	<a {...attributes}>
+		<span class="flex stack">
+			<span class="title" set:html={title} />
+			{description && <span class="description" set:html={description} />}
+		</span>
+		<Icon name="right-arrow" size="1.333em" class="icon rtl:flip" />
+	</a>
+</div>
+
+<style>
+	a {
+		display: grid;
+		grid-template-columns: 1fr auto;
+		gap: 0.5rem;
+		border: 1px solid var(--sl-color-gray-5);
+		border-radius: 0.5rem;
+		padding: 1rem;
+		text-decoration: none;
+		box-shadow: var(--sl-shadow-sm);
+	}
+
+	.stack {
+		flex-direction: column;
+		gap: 0.5rem;
+	}
+
+	.title {
+		color: var(--sl-color-white);
+		font-weight: 600;
+		font-size: var(--sl-text-lg);
+		line-height: var(--sl-line-height-headings);
+	}
+
+	.description {
+		color: var(--sl-color-gray-3);
+		line-height: 1.5;
+	}
+
+	.icon {
+		color: var(--sl-color-gray-3);
+	}
+
+	/* Hover state */
+	a:hover {
+		background: var(--sl-color-gray-7, var(--sl-color-gray-6));
+		border-color: var(--sl-color-gray-2);
+	}
+
+	a:hover .icon {
+		color: var(--sl-color-white);
+	}
+</style>