Card

Flexible content container with optional header, body, and footer regions.

Class reference

Class	Kind	Description
`.card`	Component	Neutral raised surface for grouped content.
`.raised`	Variant	Elevated surface with a soft shadow.
`.subtle`	Variant	Lower contrast against the page surface.
`.surface`	Variant	The page surface; intent in the text only.
`.compact`	Density	Tighter padding and compact descendant context.

.surface is a shared variant: it paints the page surface instead of --surface-raised and leaves the intent to the text. For a dark card on a light page (or the reverse), put data-theme="dark" on the card.

Shared .soft with an intent class gives the card a tone: an opaque surface tinted by the intent, with the soft ink. See Tones.

On .card.solid, bare and .prose links follow the surrounding text color, including hover and keyboard focus, instead of the theme's --link ink. Nested cards and data-theme islands establish their own link context.

Basic usage

Use semantic elements inside the card. A direct <header> or <footer> is the card's header or footer slot. When the card has spare height, its footer stays at the bottom, aligning prices and actions across equal-height cards.

Use layout primitives such as .grid to space cards. Within a bare card, --card-gap spaces the direct children. Add .stack or .media to the card to let that primitive control its layout and gap.

Understanding Semantic HTML

A quick primer for new contributors

Using the right HTML tags improves both SEO and accessibility. Lean on landmarks and live lists.

HTML
Accessibility
5 min read

<div style="max-inline-size: 32rem">
  <article class="card stack">
    <header>
      <hgroup>
        <h3>Understanding Semantic HTML</h3>
        <p class="muted">A quick primer for new contributors</p>
      </hgroup>
    </header>

    <p>Using the right HTML tags improves both SEO and accessibility. Lean on landmarks and live lists.</p>

    <ul class="cluster tight" aria-label="Tags">
      <li><span class="badge primary soft secondary">HTML</span></li>
      <li><span class="badge soft primary">Accessibility</span></li>
      <li><span class="badge outline">5 min read</span></li>
    </ul>

    <footer>
      <time datetime="2026-06-12" class="muted">June 12, 2026</time>
      <button type="button" class="btn outline">Read more</button>
    </footer>
  </article>
</div>

Slot rows

A direct <header> or <footer> is a wrapping split row by default: title and badge, date and action, one left one right. A primitive, role or utility on the slot replaces that row — .media for an avatar beside a title, .cluster for a start-aligned group, cluster form-actions for a form's action row, .justify-content-end to push actions right. The footer stays anchored to the bottom either way.

Each child of the slot is one side of the row. A heading and its subtitle placed as two direct children split apart, the subtitle pushed to the far side; group them in an <hgroup> so they stay one block, title above description. Text that is not a split row (a centered intro, a stacked title) belongs in a plain <div>, not in the <header> slot.

Ada Meridian

Design systems

Reviews every token change before it ships.

<div style="max-inline-size: 32rem">
  <article class="card">
    <header class="media">
      <span class="avatar"><abbr>AM</abbr></span>
      <hgroup>
        <h3>Ada Meridian</h3>
        <p class="muted">Design systems</p>
      </hgroup>
    </header>
    <p>Reviews every token change before it ships.</p>
    <footer class="cluster justify-content-end">
      <button type="button" class="btn ghost">Dismiss</button>
      <button type="button" class="btn primary">Follow</button>
    </footer>
  </article>
</div>

Bleed

Use .bleed on a direct child to bring an image or band to the card edge. See Bleed for the shared surface contract and its modular import.

In grids

Cards display nicely in grids with equal-height behavior. Each card in a row stretches to the row height, and a direct <footer> anchors to the bottom, so all footers in the row line up regardless of body length.

Components

Buttons, alerts, dialogs — all opt-in.

Layout

Stack, cluster, grid, switcher, sidebar.

Patterns

Actions, nav-list — small structural helpers.

<section class="grid">
  <article class="card">
    <header>
      <h3>Components</h3>
    </header>
    <p>Buttons, alerts, dialogs — all opt-in.</p>
    <footer>
      <a class="btn outline" href="#">Browse</a>
    </footer>
  </article>

  <article class="card">
    <header>
      <h3>Layout</h3>
    </header>
    <p>Stack, cluster, grid, switcher, sidebar.</p>
    <footer>
      <a class="btn outline" href="#">Browse</a>
    </footer>
  </article>

  <article class="card">
    <header>
      <h3>Patterns</h3>
    </header>
    <p>Actions, nav-list — small structural helpers.</p>
    <footer>
      <a class="btn outline" href="#">Browse</a>
    </footer>
  </article>
</section>

Tones

A toned, tinted, or colored card (accent card, highlight card) is .soft plus an intent class. The tint is opaque, so it holds over an image, and the ink follows the soft recipe, so muted text and links stay readable on it.

Primary

A highlighted plan or feature.

Success

A completed step.

Warning

Something to check.

<section class="grid">
  <article class="card soft primary">
    <h3>Primary</h3>
    <p class="muted">A highlighted plan or feature.</p>
  </article>
  <article class="card soft success">
    <h3>Success</h3>
    <p class="muted">A completed step.</p>
  </article>
  <article class="card soft warning">
    <h3>Warning</h3>
    <p class="muted">Something to check.</p>
  </article>
</section>

For a fully colored card, use a data-theme island rather than .solid: the island recomputes muted text, links, and fields for the new surface, where .solid only repaints the fill and the main ink.

Surfaces

A card is a surface-owning component: inside a painted band it keeps its own surface and resets the context for its content. A card with data-theme="dark" is a complete dark island — its fields, intents and states all follow.

.surface is the shared variant on a card: it drops the card to the page surface instead of --surface-raised, keeps the theme border, and lets an intent class color the text only. .raised and .subtle are the card-local treatments on either side of it.

Raised

Elevated surface with a soft shadow.

Subtle

Lower contrast against the page surface.

Surface

The page surface with the theme border.

Dark island

A complete dark theme on one card.

Compact

Tighter padding for dense contexts.

<section class="grid">
  <article class="card raised">
    <hgroup>
      <h3>Raised</h3>
      <p class="muted">Elevated surface with a soft shadow.</p>
    </hgroup>
  </article>

  <article class="card subtle">
    <hgroup>
      <h3>Subtle</h3>
      <p class="muted">Lower contrast against the page surface.</p>
    </hgroup>
  </article>

  <article class="card surface">
    <hgroup>
      <h3>Surface</h3>
      <p class="muted">The page surface with the theme border.</p>
    </hgroup>
  </article>

  <article class="card stack" data-theme="dark">
    <hgroup>
      <h3>Dark island</h3>
      <p class="muted">A complete dark theme on one card.</p>
    </hgroup>
    <button type="button" class="btn primary outline">Action</button>
  </article>

  <article class="card compact">
    <hgroup>
      <h3>Compact</h3>
      <p class="muted">Tighter padding for dense contexts.</p>
    </hgroup>
  </article>
</section>

CSS hooks

--card-radius — corner radius.
--card-max-inline-size — maximum width.
--card-pad — inner padding, relayed to direct children for .bleed. .compact lowers it.
--card-gap — space between direct children of a bare card. .compact lowers it; a parent's --gap and an inherited density do not reach it. A composed layout primitive owns its own gap instead.
--items-align — cross-axis alignment of the slot rows, set by the .items-* helpers on the card or the slot.

Edit on GitHub View Markdown