Correct and idiomatic ways to use the <mds-card> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Full Card with All Four Regions

The most common form. Use <mds-card-header>, <mds-card-media>, <mds-card-content>, and <mds-card-footer> as direct children. Each compound child self-assigns to its slot - no explicit slot attribute needed.

<mds-card>
  <mds-card-header>
    <mds-text typography="h6">Titolo della scheda</mds-text>
  </mds-card-header>
  <mds-card-media>
    <mds-img src="/immagini/copertina.jpg" class="object-cover"></mds-img>
  </mds-card-media>
  <mds-card-content>
    <mds-text>
      Descrizione dettagliata del contenuto della scheda.
    </mds-text>
  </mds-card-content>
  <mds-card-footer>
    <mds-button variant="dark" tone="text" label="Annulla"></mds-button>
    <mds-button variant="primary" tone="strong" label="Conferma"></mds-button>
  </mds-card-footer>
</mds-card>

Header + Content (No Media)

Omit the regions you do not need - the card detects which regions are present and adapts its grid layout accordingly. A header-and-content-only card stays single-column.

<mds-card>
  <mds-card-header>
    <mds-text typography="h6">Riepilogo ordine</mds-text>
  </mds-card-header>
  <mds-card-content>
    <mds-text>
      Il tuo ordine e' stato elaborato correttamente.
    </mds-text>
  </mds-card-content>
</mds-card>

Media + Content + Footer (No Header)

Omitting the header region shifts media to the top and content immediately below. Useful for image-led catalog cards.

<mds-card>
  <mds-card-media>
    <mds-img src="/immagini/prodotto.jpg" class="object-cover"></mds-img>
  </mds-card-media>
  <mds-card-content>
    <mds-text>Descrizione prodotto disponibile nella gamma autunnale.</mds-text>
  </mds-card-content>
  <mds-card-footer>
    <mds-button variant="primary" label="Aggiungi al carrello"></mds-button>
  </mds-card-footer>
</mds-card>

Header with Action Button via mds-card-header

<mds-card-header> has a dedicated action slot for icon buttons placed in the trailing position. Use it instead of laying out the button manually.

<mds-card>
  <mds-card-header>
    <mds-text typography="h6">Profilo utente</mds-text>
    <mds-button
      slot="action"
      icon="mi/round/more-vert"
      aria-label="Altre azioni"
      variant="dark"
      tone="text"
    ></mds-button>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Mario Rossi - Amministratore di sistema</mds-text>
  </mds-card-content>
</mds-card>

Media with Overlay Content via mds-card-media

<mds-card-media> exposes a content slot that renders in front of the media element. Use it for captions, badges, or status chips overlaid on an image.

<mds-card>
  <mds-card-media>
    <mds-img src="/immagini/evento.jpg" class="object-cover"></mds-img>
    <mds-badge slot="content" variant="info" tone="strong">In corso</mds-badge>
  </mds-card-media>
  <mds-card-content>
    <mds-text typography="h6">Conferenza annuale 2025</mds-text>
  </mds-card-content>
</mds-card>

Using Raw Slot Attributes Instead of Compound Children

When the compound children (mds-card-*) do not fit the use case, assign the slot attribute directly on any element, with the same four values: media, header, content, and footer. The card infers its managed grid from the tag names of its children, so plain elements need disable-auto-grid: without it the regions overlap. The regions then stack in slot order (media, header, content, footer).

<mds-card disable-auto-grid>
  <div slot="header" class="flex items-center gap-400 px-400 py-400">
    <mds-avatar initials="LB"></mds-avatar>
    <mds-text typography="h6">Luca Bianchi</mds-text>
  </div>
  <mds-img slot="media" src="/immagini/lavoro.jpg" class="object-cover"></mds-img>
  <mds-text slot="content" class="px-400">
    Responsabile del progetto infrastrutture.
  </mds-text>
</mds-card>

Disabling the Auto-Grid

Set disable-auto-grid to opt out of the managed responsive grid. The regions stack in slot order (media, header, content, footer), whatever their order in the markup, and you own all layout decisions.

<mds-card disable-auto-grid>
  <mds-card-header>
    <mds-text typography="h6">Layout personalizzato</mds-text>
  </mds-card-header>
  <mds-card-content>
    <mds-text>Il contenuto e' disposto senza griglia automatica.</mds-text>
  </mds-card-content>
</mds-card>

Styling Customization via CSS Custom Properties

Set --mds-card-gap and --mds-card-padding on the host or a parent selector. Use Magma spacing tokens so the values remain consistent across themes.

.scheda-articolo mds-card {
  --mds-card-gap: calc(var(--spacing) * 200);
  --mds-card-padding: calc(var(--spacing) * 400);
}

Customizing the Layout Part

The inner grid element is exposed as ::part(layout). Use it only for layout-level overrides that the CSS custom properties cannot cover, such as overriding the border-radius of the inner container.

.scheda-highlight mds-card::part(layout) {
  border-radius: var(--magma-radius-xl);
}