KMD prose alerts

Inline markdown alert callouts ([!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] / [!CAUTION]) embedded in prose via the blockquote syntax, rendered with a per-type icon + semantic color token. The lightweight, in-flow cousin of the callout-card component. GitHub-Flavored Markdown parity. Used wherever Koder renders KMD/Markdown: Wiki, Dok, Flow READMEs/issues/PRs, Chat, Hub package pages.

Status: v0.1.0 — Draft. Promoted from the GitHub Primer parity scan (metadocsstack #092). Source (GFM alerts): https://github.com/orgs/community/discussions/16925

R1 — Syntax

An alert is a blockquote whose first line is an alert marker:

> [!NOTE]
> Useful information the user should know, even when skimming.
  • The marker is [!TYPE] on the first line of the blockquote, alone.
  • TYPE is one of the five keywords in R2 — *ase-insensitive on input,

    canonicalized to uppercase* any other keyword is NOT an alert (the block renders as a plain blockquote — graceful degradation).

  • Subsequent blockquote lines are the alert body (full inline + block

    markdown).

The [!TYPE] keyword is a stable token and is not translated in source (authors write [!NOTE] in any locale); the rendered visible label IS localized (R5).

R2 — The five types (closed set)

Type Intent Semantic token Icon
NOTE Neutral, useful aside info (blue) info
TIP Optional advice that helps success (green) light-bulb
IMPORTANT Key info needed to succeed accent (Koder purple) report/alert
WARNING Needs attention to avoid a problem caution (amber) alert
CAUTION Risk of a negative/destructive outcome danger (red) stop

No other types. IMPORTANT vs WARNING vs CAUTION is an escalating severity ladder (helpful → attention → risk).

R3 — Anatomy & rendering

  • A bordered/left-accent block tinted with the type's semantic color.
  • Header row = type icon + the localized type label (R5), in the type

    color.

  • Body = the blockquote content, default text color (NOT the type color —

    keep body readable).

  • Visual weight sits between plain prose and a full

    specs/patterns/callout-card.kmd (which is a standalone card with heading/actions); alerts are in-flow and action-less.

R4 — Tokens

Bordertinticon colors come from Verge semantic tokens (specs/themes/verge.kmd) — never raw hex. Light/dark handled by the token layer. The body-text token is the normal prose token so contrast is preserved on the tint.

R5 — Accessibility & i18n

  • Color is never the sole signal: the type icon + the visible type label

    ("Note", "Warning", …) always render (WCAG 1.4.1).

  • The icon is decorative (aria-hidden); the label text carries meaning.
  • The visible type label is localized per specs/i18n/contract.kmd

    (NOTE→"Nota", WARNING→"Aviso", CAUTION→"Cuidado", TIP→"Dica", IMPORTANT→"Importante"). The [!TYPE] source keyword stays English.

  • An alert is not a live region (it is static authored content); no

    role=alert (which is for dynamic, time-sensitive messages — that is the domain of specs/components/banners.kmd/snackbars).

Não-escopo

  • The standalone callout-card component (specs/patterns/callout-card.kmd).
  • Dynamic runtime notifications (bannerssnackbarstoasts).
  • Custom/author-defined alert types (the set is closed at five).
  • Collapsible alerts (out of v0).