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

Basic Badge via label Prop

The canonical form. Use the label prop for the badge’s text content - it is the preferred source and the slot is deprecated.

<mds-badge label="Attivo" variant="success" tone="weak"></mds-badge>

Variant and Tone for Emphasis

Pair the same variant with a different tone to control visual weight. tone="weak" (default) is the lightest fill; tone="strong" is a saturated solid; tone="outline" adds a visible border with a transparent background.

<!-- Low emphasis: subtle tinted fill (default) -->
<mds-badge label="Bozza" variant="warning" tone="weak"></mds-badge>

<!-- High emphasis: solid saturated fill -->
<mds-badge label="Urgente" variant="error" tone="strong"></mds-badge>

<!-- Minimal emphasis: bordered, no fill -->
<mds-badge label="Archiviato" variant="dark" tone="outline"></mds-badge>

Status Variants

Use status variants (info, success, warning, error) to communicate state. Match the variant to the meaning, not to the colour you want.

<mds-badge label="Completato" variant="success" tone="weak"></mds-badge>
<mds-badge label="In attesa" variant="info" tone="weak"></mds-badge>
<mds-badge label="Attenzione" variant="warning" tone="weak"></mds-badge>
<mds-badge label="Errore" variant="error" tone="weak"></mds-badge>

Decorative Label Variants

Use decorative label variants (green, blue, violet, red, orange, yellow, lime, aqua, sky, orchid, purple, amaranth) for categorical tags, topics, or visual grouping that carries no semantic state meaning. The default variant is green.

<mds-badge label="Ambiente" variant="green"></mds-badge>
<mds-badge label="Tecnologia" variant="blue"></mds-badge>
<mds-badge label="Design" variant="violet"></mds-badge>
<mds-badge label="Marketing" variant="orange"></mds-badge>

Neutral Variants

variant="dark" and variant="light" are painted with neutral roles that follow the mode, so neither is tied to a light or dark background. They differ only with tone="strong": dark is the inverse chip (dark on a light UI, light on a dark UI), light is the paper of the mode (white in light, black in dark). With weak and outline the two render the same.

<!-- Inverse chip, flips with the mode -->
<mds-badge label="Categoria" variant="dark" tone="strong"></mds-badge>

<!-- Paper of the mode -->
<mds-badge label="Categoria" variant="light" tone="strong"></mds-badge>

Typography Scale

The default "option" is the smaller scale and suits dense contexts such as table cells; use typography="label", which is larger, when the badge needs more presence.

<!-- Default, smaller scale - inside tables or tight UI rows -->
<mds-badge label="Nuovo" variant="sky" typography="option"></mds-badge>

<!-- Larger scale - standalone labels, cards, sidebars -->
<mds-badge label="Nuovo" variant="sky" typography="label"></mds-badge>

Badge Inside a Table Cell

<mds-badge> is commonly used as a status indicator inside mds-table cells.

<mds-table>
  <mds-table-body>
    <mds-table-row>
      <mds-table-cell>
        <mds-badge label="Approvato" variant="success" tone="weak"></mds-badge>
      </mds-table-cell>
      <mds-table-cell>
        <mds-badge label="In revisione" variant="warning" tone="weak"></mds-badge>
      </mds-table-cell>
    </mds-table-row>
  </mds-table-body>
</mds-table>

Badge Inside a File Listing

mds-file and mds-file-preview render a badge internally to show the file type; you do not slot a badge into them. When adding a badge alongside file content elsewhere, compose it in the surrounding markup.

<div class="file-meta">
  <mds-file filename="relazione-2024.pdf"></mds-file>
  <mds-badge label="Firmato" variant="success" tone="weak"></mds-badge>
</div>

Styling Customization

Style the badge only through its documented --mds-badge-* CSS custom properties. Use Magma color tokens via rgb(var(--<token>)) so dark mode and high-contrast modes keep working.

.custom-tag mds-badge {
  --mds-badge-background: rgb(var(--label-orchid-09));
  --mds-badge-color: rgb(var(--label-orchid-02));
  --mds-badge-radius: var(--magma-radius-full);
}

For tone="outline", also set the border properties. The outline badge is always transparent, so --mds-badge-background has no effect on it:

.custom-tag mds-badge[tone='outline'] {
  --mds-badge-border-color: rgb(var(--label-orchid-06));
  --mds-badge-border-width: 2px;
}