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.
When this spec applies
Primary triggers
- Add GFM alert rendering to a KMD/Markdown renderer
All triggers
- Render a Markdown note/warning/tip callout inside prose
- Support GitHub-style [!NOTE] alert syntax in a Koder markdown surface
Specification body
KMD — Prose alerts
Status: v0.1.0 — Draft. Promoted from the GitHub Primer parity scan (meta/docs/stack #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. TYPEis one of the five keywords in R2 — case-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
Border/tint/icon 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 (banners/snackbars/toasts).
- Custom/author-defined alert types (the set is closed at five).
- Collapsible alerts (out of v0).
References
specs/kmd/format.kmdspecs/patterns/callout-card.kmdspecs/themes/verge.kmdspecs/i18n/contract.kmd