Card

Example

<ul class="cards">
	<li>
		<article data-slean="card">
			<div data-slean-part="media"><img src="/demo/card-harbor.svg" alt="" /></div>
			<header data-slean-part="header">
				<h3 data-slean-part="title">
					<a href="/primitives/disclosure" data-slean-part="link">Disclosure</a>
				</h3>
				<p data-slean-part="description">Tier 0, details and summary</p>
			</header>
			<div data-slean-part="body">A region that opens and closes, with no script.</div>
			<footer data-slean-part="footer">
				<button type="button" data-slean="button" data-variant="outline" data-size="sm">Save</button>
			</footer>
		</article>
	</li>
	<li>
		<article data-slean="card" data-variant="filled">
			<header data-slean-part="header">
				<h3 data-slean-part="title">Storage</h3>
				<p data-slean-part="description">Team plan, renews in October</p>
			</header>
			<div data-slean-part="body">Exports older than thirty days are removed.</div>
			<footer data-slean-part="footer">
				<button type="button" data-slean="button" data-size="sm">Upgrade</button>
				<button type="button" data-slean="button" data-variant="ghost" data-size="sm">Details</button>
			</footer>
		</article>
	</li>
</ul>

<script lang="ts">
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/card.css';
</script>

<ul class="cards">
	<li>
		<article data-slean="card">
			<div data-slean-part="media"><img src="/demo/card-harbor.svg" alt="" /></div>
			<header data-slean-part="header">
				<h3 data-slean-part="title">
					<a href="/primitives/disclosure" data-slean-part="link">Disclosure</a>
				</h3>
				<p data-slean-part="description">Tier 0, details and summary</p>
			</header>
			<div data-slean-part="body">A region that opens and closes, with no script.</div>
			<footer data-slean-part="footer">
				<button type="button" data-slean="button" data-variant="outline" data-size="sm">Save</button>
			</footer>
		</article>
	</li>
	<li>
		<article data-slean="card" data-variant="filled">
			<header data-slean-part="header">
				<h3 data-slean-part="title">Storage</h3>
				<p data-slean-part="description">Team plan, renews in October</p>
			</header>
			<div data-slean-part="body">Exports older than thirty days are removed.</div>
			<footer data-slean-part="footer">
				<button type="button" data-slean="button" data-size="sm">Upgrade</button>
				<button type="button" data-slean="button" data-variant="ghost" data-size="sm">Details</button>
			</footer>
		</article>
	</li>
</ul>

<style>
	.cards {
		display: grid;
		grid-template-columns: repeat(auto-fill, minmax(min(100%, 15rem), 1fr));
		gap: 1rem;
		margin: 0;
		padding: 0;
		list-style: none;
	}

	/* Each list item stretches, so the cards in a row share one height. */
	.cards > li {
		display: grid;
	}
</style>

Why this implementation exists

A card is layout: a surface, a heading, some text and actions. <article> gives it meaning when the item stands on its own, the heading gives it a place in the outline, and links and buttons inside it are native. Nothing about a card needs a script or a component.

The one pattern that tempts a script is the clickable card. Wrapping the card in <a> makes the whole text the link name and cannot hold a button; a click handler on the card is invisible to the keyboard. The stretched link keeps one real <a> in the title and enlarges its hit area with a pseudo-element, so the browser still owns focus, Enter, the name and the navigation.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/card.css';

Use <article> for self-contained items and a <div> or <section> for plain groups. Put the title at the heading level the page needs. In a list of cards, put each card in an <li>.

Wrap media in data-slean-part="media" rather than marking the <img>: a global img { max-width: 100% } in the application would otherwise undo the bleed to the edges. Mark the title link data-slean-part="link" only when the whole card should open it.

Anatomy

Runtime profile

Tier 0: the card has no behavior module, the Vite plugin maps card to no module, and the native-only fixture proves the path ships no Svelte Lean JavaScript.

Accessibility contract

• <article> is exposed as an article; name it with aria-labelledby on the title when a page lists many cards.
• The stretched link is one tab stop named by the title; the other controls keep their own names and tab stops.
• The card itself is never focusable. Where :has() is supported the focus ring of the link is drawn around the card, otherwise around the title.
• Media that repeats the title is decorative (alt=""); an image that carries information gets its own alt text.

Keyboard

Platform features

Without JavaScript

Fully functional: the stretched link, the focus ring and the lifted buttons are CSS.

Server rendering

Static HTML.

Before hydration

Nothing is attached; the card behaves the same before and after hydration.

Styling

card.css draws the surface and border, the filled variant, the media bleed with the card's corners, the header, title, description, body and footer layout, and the stretched link with the focus ring on the card. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: :first-child, :focus-visible, :hover, :last-child, [href], [tabindex].

Variant attributes: data-variant (filled).

Compatibility notes

Only :has() is newer than the rest (Baseline 2023, widely available since June 2026). Without it the stretched link also covers the other buttons of a linked card and keeps its focus ring on the title.

Examples

Stretched link

A card that opens one page has one link, in its title. The stylesheet stretches the link's ::after over the card, lifts every other link and button above it, and moves the focus ring from the title to the card. The link's accessible name stays the title, and the Save button in the first example above remains a separate target. The cost: text inside the card cannot be selected with the pointer.

<!-- One real link, inside the title. Its ::after covers the card; the Save button is
     lifted above it by the stylesheet, so it stays a separate target. -->
<article data-slean="card">
	<header data-slean-part="header">
		<h3 data-slean-part="title">
			<a href="/stories/harbor-lights" data-slean-part="link">Harbor lights</a>
		</h3>
	</header>
	<footer data-slean-part="footer">
		<button type="button" data-slean="button">Save</button>
	</footer>
</article>

<!-- Not this: the link's name becomes the whole card, and a link may not contain a button. -->
<a href="/stories/harbor-lights"><article>…<button>Save</button></article></a>

Testing

• apps/playground/tests/primitives/display.spec.ts Playwright: open state, exclusive groups, stretched links, roles and names, carousel scrolling, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/card/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/card/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/card.css the optional stylesheet