--- a/design_system/README.md	Tue Aug 04 09:14:57 2026 -0700
+++ b/design_system/README.md	Tue Aug 04 11:57:16 2026 -0700
@@ -60,12 +60,49 @@
 | `zen-card` | direct `article` or `section` | `interactive` | native descendant events |
 | `zen-alert` | message HTML | `tone`, `dismissible` | `zen-dismiss` |
 | `zen-field` | direct `label`, form control, help text | native control attributes | native input/change/invalid |
+| `zen-notifications` | descendant event producers | `aria-label`, `dismiss-label` | `zen-notification-action`, `zen-notification-removed` |
 | `zen-stack` | any HTML | `direction`, `gap` | native descendant events |
 
 Do not put business state into the design-system components. They provide
 presentation, small accessibility wiring, and interaction affordances while
 applications retain data and workflow ownership.
 
+### Notifications
+
+See [`NOTIFICATIONS.md`](NOTIFICATIONS.md) for the complete event contract,
+queue semantics, actions, timing, and accessibility behavior.
+
+Place one scope around the part of the application that owns notifications:
+
+```html
+<zen-notifications aria-label="Notifications">
+  <main id="application"></main>
+</zen-notifications>
+```
+
+Any descendant can dispatch a non-composed bubbling event:
+
+```js
+source.dispatchEvent(new CustomEvent("zen-notify", {
+  bubbles: true,
+  composed: false,
+  detail: {
+    version: 1,
+    id: "deployment-complete",
+    tone: "success",
+    message: "Deployment complete",
+    announcement: "polite",
+    durationMs: 5000,
+  },
+}));
+```
+
+Use `zen-dismiss-notification` with `{ version: 1, id }` to dismiss by ID.
+Actions contain only an opaque token and label; clicking dispatches
+`zen-notification-action`. Tokens are held in private component state and never
+written to DOM attributes. The component renders three records and retains up
+to 20 additional queued records.
+
 ## Tests
 
 ```bash