# Alert

Ein Alert macht den User auf eine wichtige Information aufmerksam. Er ist visuell hervorgehoben und sollte nur bei relevanten, nicht ignorierbaren Inhalten verwendet werden.

## Guidelines

# Grundlagen

Ein Alert ist ein UI-Element zur Kommunikation wichtiger Informationen, die
Aufmerksamkeit erfordern. Alerts sollten sparsam und gezielt eingesetzt werden,
da sie visuell hervorgehoben sind und den Nutzerfluss unterbrechen können. Sie
können informativ, warnend, kritisch oder bestätigend sein.

## Best practices

Achte bei der Verwendung eines Alerts darauf, dass ...

- der Alert nur verwendet wird, wenn der Inhalt wirklich die Aufmerksamkeit des
  Users benötigt. Für rein informative Hinweise kann ein weniger auffälliges
  Element (z. B. ein Hinweistext) ausreichend sein.
- der Schweregrad sinnvoll gewählt ist – `danger` für sofortigen
  Handlungsbedarf, `warning` für Handlungsbedarf, `info` für eine wichtige
  Information und `success` für einen Erfolg.
- der Text klar, prägnant und lösungsorientiert formuliert ist. Vermeide
  technische Fachbegriffe oder Schuldzuweisungen. Beachte die Content Guidelines
  für
  [Fehlermeldungen](/02-foundations/03-content-guidelines/03-fehlermeldungen).
- er möglichst eine Handlungsmöglichkeit bietet.

## Verwendung

Verwende einen Alert, um ...

- dem User mitzuteilen, dass ein Fehler aufgetreten ist – verursacht durch sein
  Handeln oder durch das System.
- vor einer möglichen Folge oder Auswirkung zu warnen.
- wichtige Statusänderungen oder Systemereignisse mitzuteilen.
- zusätzliche wichtige Informationen oder Hinweise in einem bestimmten Kontext
  bereitzustellen.

## Alert vs AccentBox

Alerts und [AccentBoxen](/04-components/structure/accent-box/overview) dienen
beide dazu, dem User zusätzliche Informationen bereitzustellen. Eine einfache
Faustregel hilft bei der Entscheidung: Kann die Information ignoriert werden,
ohne negative Folgen? Dann ist eine AccentBox die richtige Wahl. Wenn das
Ignorieren hingegen zu Problemen führen könnte – etwa bei sicherheitsrelevanten
Hinweisen oder wichtigen Systemmeldungen – sollte ein Alert mit entsprechendem
Status verwendet werden.

  

- den User auf sicherheits- oder funktionsrelevante Informationen hinzuweisen.
    - vor möglichen Problemen oder Systemzuständen zu warnen.
    - dringende oder aktionsrelevante Statusmeldungen zu kommunizieren.

  

- ergänzende, aber nicht kritische Hinweise anzuzeigen.
    - kontextuelle Informationen oder Tipps zu geben.
    - visuell strukturierende Inhalte einzubetten, ohne zu unterbrechen.

---

# Anwendung

## Position

Ein Alert sollte immer in unmittelbarem Zusammenhang mit dem betroffenen Inhalt
platziert werden. Er wird in der passenden
[Section](/04-components/structure/section/overview) untergebracht oder, wenn
sein Hinweis für die gesamte Seite gilt, in der
[LayoutCard](/04-components/structure/layout-card/overview) oberhalb aller
Sections.

**✅ Do**

Bezieht sich der Alert auf eine bestimmte Section, wird er im Content der Section platziert.

```tsx
import {
  Alert,
  Heading,
  LayoutCard,
  Section,
  Text,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <Section>
    <Heading>E-Mail-Adresse</Heading>
    <Text>...</Text>
  </Section>
  <Section>
    <Heading>Speicherplatz</Heading>
    <Alert status="danger">
      <Heading>Speicherplatz ist voll</Heading>
      <Text>
        Der Speicherplatz deines Postfachs ist voll. Um
        wieder E-Mails erhalten zu können, kannst du der
        E-Mail-Adresse mehr Speicher zuweisen.
      </Text>
    </Alert>
    <Text>...</Text>
  </Section>
</LayoutCard>
```

**✅ Do**

Bezieht sich der Alert auf den gesamten Inhalt, wird er prominent oberhalb der
ersten Section innerhalb der LayoutCard platziert.

```tsx
import {
  Alert,
  LayoutCard,
  Heading,
  Text,
  Section,
} from "@mittwald/flow-react-components";

<LayoutCard>
  <Alert status="danger">
    <Heading>E-Mail-Adresse wurde archiviert</Heading>
    <Text>
      Da deine Domain gelöscht wurde, wurde diese
      E-Mail-Adresse archiviert. Um E-Mails empfangen und
      senden zu können musst du die E-Mail-Adresse
      bearbeiten.
    </Text>
  </Alert>
  <Section>
    <Heading>E-Mail-Adresse</Heading>
    <Text>...</Text>
  </Section>
  <Section>
    <Heading>Speicherplatz</Heading>
    <Text>...</Text>
  </Section>
</LayoutCard>
```

---

# Writing guidelines

## Heading

Die [Heading](/04-components/content/heading/overview) sollte das Problem oder Ereignis kurz und prägnant benennen. 

## Content

Zuerst sollte die Ursache vermittelt werden: Was ist passiert und welche Folgen ergeben sich daraus? Anschließend sollte erklärt werden, was der User tun kann, um die Situation zu lösen. Wenn es den User unterstützt, können optional zusätzlicher Kontext oder technische Hintergründe erklärt werden.

Weitere Formulierungshilfen stehen in unseren Content Guidelines unter [Fehlermeldungen](/02-foundations/03-content-guidelines/03-fehlermeldungen).

## Action (optional)

Optional kann ein Alert auch eine direkte Handlung ermöglichen, etwa über einen [Button](/04-components/actions/button/overview) zur Problemlösung oder einen [Link](/04-components/navigation/link/overview) zu weiteren Informationen bzw. zur relevanten Stelle.

## Beispiel 

```tsx
import {
  Alert,
  Button,
  Content,
  Heading,
} from "@mittwald/flow-react-components";

<Alert>
  <Heading>E-Mail-Empfang wurde deaktiviert</Heading>
  <Content>
    Der Empfang der E-Mails für dieses Postfach ist aufgrund
    fehlerhafter MX-Records deaktiviert. Bitte setze die
    richtigen Mailserver. Bei einer Neuregistrierung einer
    Domain kann es einige Minuten dauern, bis die MX-Records
    global im DNS verfügbar sind. Die E-Mail-Adresse wird in
    diesem Fall automatisch aktiviert.
    <Button>MX-Records anpassen</Button>
  </Content>
</Alert>
```