Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
adr-wc
Architectural Decision Record card in MADR format with status badges, slotted title/date content, context/decision/consequences sections, and supersedes chain linking.
Overview
A web component for rendering Architectural Decision Records (ADRs) in MADR format. The decision title and date are slotted content (headings and <time> elements), while status, supersedes chains, and detail level are attributes. Each card shows context, decision, and consequences with optional chain linking to other ADRs via fragment anchors.
Basic usage
<adr-wc adr-id="ADR-001" status="accepted"> <h2 slot="title">Use PostgreSQL for persistence</h2> <time slot="date" datetime="2026-01-15">January 15, 2026</time> <p slot="context">We need a relational database that supports complex queries and full-text search.</p> <p slot="decision">Use PostgreSQL 16 with pgvector extension.</p> <ul slot="consequences"> <li>Good: mature ecosystem, strong SQL support</li> <li>Bad: operational overhead vs managed NoSQL</li> </ul></adr-wc>Attributes
Attributes are for state and configuration — not content. The decision title and date are content and use slots instead.
| Attribute | Type | Default | Description |
|---|---|---|---|
adr-id | string | — | Identifier (e.g., "ADR-001"). Auto-sets HTML id. |
status | string | "proposed" | proposed, accepted, deprecated, superseded |
supersedes | string | — | Comma-separated ADR IDs this supersedes |
superseded-by | string | — | Comma-separated ADR IDs that supersede this |
detail | string | "full" | full, compact, minimal |
compact | boolean | — | Alias for detail="compact" |
src | string (URL) | — | JSON data URL |
Slots
| Slot | Expected Content | Description |
|---|---|---|
title | <h2>, <h3>, etc. | Decision heading — the author controls the heading level |
date | <time datetime="..."> | Decision date — machine-readable via datetime, human-readable via text content |
context | <p> | Why the decision was needed |
decision | <p> | What was decided |
consequences | <ul> | Outcomes (prefix items with "Good:" or "Bad:" for clarity) |
Supersedes Chain
ADRs form a decision evolution chain. Use supersedes and superseded-by to link related decisions. These render as clickable anchor chips that scroll to the referenced ADR card.
Linked ADRs
<!-- Original decision (superseded) --><adr-wc adr-id="ADR-001" status="superseded" superseded-by="ADR-002"> <h2 slot="title">Use MongoDB</h2> <time slot="date" datetime="2025-06-01">June 1, 2025</time> <p slot="context">Need flexible schema for early prototyping.</p> <p slot="decision">Use MongoDB Atlas.</p></adr-wc> <!-- Replacement decision --><adr-wc adr-id="ADR-002" status="accepted" supersedes="ADR-001"> <h2 slot="title">Switch to PostgreSQL</h2> <time slot="date" datetime="2026-01-15">January 15, 2026</time> <p slot="context">Query complexity outgrew MongoDB.</p> <p slot="decision">Migrate to PostgreSQL 16.</p></adr-wc>Status Colors
| Status | Color | Meaning |
|---|---|---|
proposed | Blue | Under discussion, not yet decided |
accepted | Green | Decision is active and in effect |
deprecated | Amber | Decision is being phased out |
superseded | Gray | Replaced by a newer decision |
Events
| Event | Detail | When |
|---|---|---|
adr-wc:ready | { adrId, title, status } | After render |
Accessibility
- Card is an
<article>witharia-label - The title slot accepts any heading level — the author controls the document outline
- The date slot uses
<time>for machine-readable dates - Status badge uses colored background (not color-only)
- Supersedes/superseded-by links are real
<a>elements - Respects
prefers-reduced-motion: reduce
Related
<work-item>— Engineering work that implements decisions<glossary-wc>— Define terms referenced in ADRs<user-story>— Stories that drive architectural decisions- UX Planning Pack