Card
Content container with typed slots. A card packages a related set of information - image, title, supertitle, body, date, tags, metadata, actions, and icon - into a single, reusable surface consumers can drop into grids, lists, or hero sections. Slots accept either structured props (for default rendering) or raw HTML (for full control), so cards cover everything from simple teasers to rich composite listings.
Usage
When to use
- To present a single, self-contained piece of content (article teaser, product, profile, mission summary)
- To create consistent teasers in a grid or list
- To make a whole content block clickable via a stretched link
When not to use
- For wide editorial layouts - use a section or a hero
- For key-value facts with no visual surface - use a description list
- For navigation items - use a navbar or link list
Do
- Keep card titles concise and scannable
- Use the same slots consistently across cards in the same grid
- Use the stretched-link pattern to make cards fully clickable rather than wrapping the whole card in
<a>
Don't
- Don't nest interactive elements inside a fully clickable card without isolating them
- Don't mix cards with different slot structures in a single grid
- Don't overload a card with every slot - pick the ones that add value
The horizontal orientation reserves a fixed column for the image, so it needs a card wide enough to hold that column and a readable text column beside it. A narrower card stacks its content under a full-bleed image instead. The width is measured from the card itself, so a card reacts to the column it sits in rather than to the viewport - three cards across a grid stack, and the same card in a single-column layout does not.
API
Slots
| Slot | Required | Description |
|---|---|---|
icon | - | Decorative icon mark, typically inline SVG. |
media | - | Media markup: <img>, <picture>, <video>, or <svg>. |
content | Yes | Body content markup (any flow HTML). |
tags | - | Tags markup, typically a list of badge items, rendered in the footer. |
actions | - | Actions markup, typically anchors or buttons, rendered in the footer. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | - | Card title text. |
title_id | string | - | id for the title element, referenced by aria-labelledby. Defaults to a generated value when omitted. |
title_tag | Enum: strong, p, h1, h2, h3, h4, h5, h6 | h3 | Tag used to render the title. |
supertitle | string | - | Supertitle text rendered above the title. |
date | string | - | Human-readable date display. |
date_iso | string | - | Machine-readable ISO 8601 date. Paired with date for accessible datetime rendering. |
url | string | - | Optional destination URL. When set, the title becomes a link covering the card. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.info | Intent | - | Informational message. |
.warning | Intent | - | Warning or caution. |
.danger | Intent | - | Error, destructive, or critical. |
.success | Intent | - | Confirmation or completion. |
.solid | Fill | - | Filled surface; background and border rendered. |
.outline | Fill | - | Bordered surface; transparent background. |
.ghost | Fill | - | No surface; text or icon only. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.rounded | Shape | - | Rounded corners. |
.square | Shape | - | Sharp corners. |
.horizontal | Orientation | Yes | Children flow along the horizontal axis. |
.vertical | Orientation | - | Children flow along the vertical axis. |
.flat | Elevation | - | No elevation. |
.raised | Elevation | Yes | Slight elevation. |
.elevated | Elevation | - | High elevation. |
Examples
Default
Card with title, supertitle, image, content, and tags, in the default horizontal orientation - image on the left, content on the right, while the card is wide enough for both.
Vertical
The vertical orientation stacks the content under a full-bleed image.
Clickable
Full-area clickable card using the stretched link pattern.
With meta
Card with meta key-value pairs and actions.
Accent
The accent emphasis, which raises the surface and border above the neutral default.
With icon
An icon in place of the media slot, for a card that leads with a symbol rather than a photograph.
Title as paragraph
title_tag set to p, for a card that carries a title visually without claiming a heading level in the document outline.
Cards in grid
Three cards across a grid leave each one too narrow for a side-by-side image column, so they stack. Hovering a card lifts it, and the whole surface is clickable through the title's stretched link.
Accessibility
- WCAG 2.2 AA
- Card is a semantic grouping (
<article>) so assistive tech can navigate between cards - Clickable cards use the stretched link pattern, not a wrapping
<a> - Card title uses an appropriate heading level for the surrounding document outline
- Focus indicator visible on all interactive children
Related
- collection - collection of cards and related components
- callout - editorial emphasis within body copy
- link - standalone link component