Add LinkCard Component (#397)

Co-authored-by: Lorenzo Lewis <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>

Author: 3 people

.changeset/swift-kiwis-wash.md

@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Add `LinkCard` component

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';

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';

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);
+}

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>