Overview
One event contract shared by the design system, the SDKs and every host application.
What this is
One dictionary of event definitions, shared by the Augeo design system, every product built on it, every SDK, and every application that embeds one. 53 names, 64 JSON Schemas, published as a typed npm package.
The JSON Schema is the artifact of record, because the dictionary has to serve Go and Python consumers as well as browsers. The TypeScript package is generated from it, never maintained beside it.
The one idea to take away
A component can honestly report only what it observed. It cannot know which program it is in, who is looking at it, or where it was placed.
So a single flat schema either forces those fields into component props — making the component unreusable — or leaves them empty, making the schema a lie. Instead there is a small base envelope every layer can fill honestly, plus a declared, namespaced place for each layer to add what only it knows.
Events bubble up, enriched. State comes back down, resolved.
The asymmetry is the point. Only the layer holding the network call knows whether a mutation was acknowledged, so a component can never resolve its own state. That is what makes it impossible — not merely discouraged — for a control to announce a save that was never confirmed.
What each layer owns
| Layer | Owns | Must not know |
|---|---|---|
| Design system | the state space, how each phase renders, ARIA politeness, viewability, and emission of what it observed | program, participant, campaign, placement, consent |
| SDK | policy (thresholds, failure classification, retry safety), context enrichment, the acknowledgement round trip | which phases exist, or how any phase looks |
| Host application | the destination, its own enrichment, committing mutations, answering the acknowledgement | the meaning of a phase |
A design system that knows a user id is a design system that cannot be reused.
The two state spaces
There are two, not one.
SlotPhase — a region of content arriving (a read). Eight exits: idle,
loading, success, empty, timeout, failure, fallback, cancelled.
EffectPhase — a mutation the member initiated (a write). Five exits: idle,
pending, confirmed, rejected, unacknowledged.
empty and fallback are meaningless for a mutation. unacknowledged is
meaningless for a read. One flat enum cannot hold both, which is exactly why an
unacknowledged mutation tends to render as though nothing happened.
Two classes of name
measured | observed | |
|---|---|---|
| Governed by | Intelligence and Product, registry review | the design system team, versioned with the package |
| Emitted when | a composing feature declared what this component means | always — it is a mechanical fact |
| Feeds | billing, attribution, ML, external projections | UI, debugging, quality signals, accessibility tests |
| Volume | low | high |
A Button emits observed only, and that is not a gap. An OfferCard handed a
monetized item payload emits both.
Class is per name, not per family. The conversation family holds fifteen
measured names and five observed ones.
Where to go next
- Getting started — install it and emit your first event
- Event names — the vocabulary, and how to look a name up
- Destination analytics — map events onto gtag, GTM, or a custom writer
- Destination names — default destination event for every registered name
- Validating events — check a document at a boundary
- Landing stages — what you can implement today