Overview
What the design system may emit, render, and refuse for interaction events.
The design system reports what the interface did. It never decides what that means.
This standard states what the package may emit, what it may render, and what it must
refuse. The vocabulary lives in @kigo-digital/augeo-events, an installed runtime
dependency. Nothing here restates it. src/interaction/ re-exports that vocabulary and
adds the React layer.
Follow the migration guide to convert a component. This document is the rule set behind that procedure.
The two directions
Events travel up. Resolved state travels down.
Up: a component emits an envelope into a port. Each layer above enriches its own namespace and passes the envelope on.
Down: the host resolves an outcome into a state object. The component renders that state, and only that state.
A component never closes the loop itself. It cannot know whether a write reached a server. So it never says that one did.
The three contracts
| Contract | Type | Direction | Written by |
|---|---|---|---|
| Event envelope | AugeoEvent | up | the design system, then each layer above it |
| Resolved state | AugeoInteractionState | down | the host |
| Effect acknowledgement | AugeoAck | down | the host |
The design system emits envelopes. It renders resolved states. It never mints an ack.
AugeoSlotState and AugeoEffectState in src/interaction/contract.ts narrow the
resolved state. Both are discriminated unions, so an impossible pair cannot be built.
Enforced by the type checker, and by src/interaction/emitter.test.ts. Every emitted
envelope is validated there against the real Zod schema.
The eleven stage-1 names
namesForStage(1) returns exactly eleven names. Each one is class observed, lifecycle
stable, and owned by @augeo/design-system.
| Name | Reports |
|---|---|
com.augeo.ui.component.rendered | a component painted, and the content state it painted |
com.augeo.ui.component.viewed | the MRC viewability pair was met |
com.augeo.ui.action.pressed | a member pressed a named control |
com.augeo.ui.effect.requested | a write was opened |
com.augeo.ui.effect.settled | that write reached a terminal phase |
com.augeo.ui.media.failed | an image or media element failed to load |
com.augeo.ui.slot.declared | a region of content was promised |
com.augeo.ui.slot.filled | content arrived in that region |
com.augeo.ui.slot.settled | the region reached a settled phase |
com.augeo.ui.slot.failed | the region terminated with a failure |
com.augeo.ui.slot.dropped | a decorative region terminated without content |
That list is the whole vocabulary. Emitting any other name from this package is a defect.
A measured name such as engagement.* is derived one layer up. It carries a judgement
the design system did not make.
Enforced by three things. DesignSystemEventName admits only the eleven.
assertDesignSystemEventName throws on any name at another stage or class. The emitter
suite emits all eleven and validates each envelope.
Write authority
The design system may write spec, specversion, id, type, typeversion, time,
class, source, data.occurrence, data.context.augds, and the correlation keys it
honestly knows.
It honestly knows three correlation keys:
| Key | Known because |
|---|---|
effectId | it minted the identifier for this write |
slotId | an InteractionSlot it mounted declared that slot (declaredHere) |
causationId | it emitted the causing event itself |
A component that sits inside a slot it did not declare emits correlation: {}.
slotId is never a prop. SlotScopeProvider is the only way a child learns the id,
and writableSlotId refuses to stamp it unless this package declared the slot.
The design system must never write subject, correlation.conversationId,
correlation.turnId, correlation.interactionId, or any namespace other than augds.
Those fields belong to layers that can know them.
The v1 specification text still names effectId alone. AIA-1577 widened it to the three
keys above, each of which the design system mints or is handed.
Enforced by the input type, not by review. InteractionEmission has no subject
key. DesignSystemCorrelation carries three keys and no others. emitter.test.ts
asserts each absence at the type level.
Two state spaces
A read and a write fail differently, so they carry different phases.
| Space | Type | Exits |
|---|---|---|
| Read | SlotPhase | idle, loading, success, empty, fallback, cancelled, timeout, failure |
| Write | EffectPhase | idle, pending, confirmed, rejected, unacknowledged |
One enum cannot hold both, because two of the exits have no counterpart.
empty is a successful read that found nothing. A write has no such outcome, and a
surface must never scold a member for it.
unacknowledged means the write may already have landed. A read is never in that
position, because a read changes nothing.
Merging the two spaces would make a renderer guess which meaning it was handed.
Enforced by the type checker. A slot-typed prop handed an effect state does not compile.
Where a phase is reviewed, tokenised and tracked
A phase nobody can review is a phase nobody drew. Three repo-level pieces carry that.
interaction_states is an optional block in a component README's frontmatter. It sits beside
accessibility and rendering. The schema is src/metadata/readme-frontmatter.schema.ts.
| Key | Holds |
|---|---|
space | slot, effect, both or none |
covered | the phases the item renders, per space |
figma | one node id per covered phase, explicitly null where no frame is drawn |
designerOwns | the frames, and the copy the design system writes itself |
engineerOwns | the resolver that selects a frame |
handoffSeams | <seam>: <what crosses it>, the vocabulary blocks already use |
politeness_source | handed-down, derived-locally or none |
Claiming a space means covering every phase of it. A partial claim fails validation, so a missing exit cannot hide behind a shorter list.
figma is where the undrawn phases are tracked. Eleven of the thirteen have no frame today, and
an absent key fails while a null one passes. That is the difference between MISSING and
forgotten.
scripts/generate-docs.mjs renders the block as a phase table on the docs site. A phase with
no node id prints MISSING, so a designer outside this repository sees the gap.
Enforced by bun run ds-readme:validate and bun run check:docs-sync.
The phase roles are not the status roles
tokens/v2/semantic/color.json carries a phase group: pending, confirmed, rejected,
unacknowledged, timeout and fallback. Each is a background and foreground pair.
status is a four-value severity axis. interaction in that file means pointer state, hover
and pressed, and predates this contract. Neither answers where a request got to.
phase/unacknowledged must never alias status/error. Nobody said no; the answer never
arrived, and the write may already have landed. A phase drawn in the danger token reads as
danger whatever the copy says.
Values reference the primitive ramps directly rather than aliasing status, so a phase and a
severity sharing a ramp step today can diverge tomorrow.
Enforced by bun run build:tokens:v2. A role that resolves to no custom property does not
exist. Nothing yet stops a component reaching for status instead. That one is still review.
The component renders the phase it was handed
A component never advances its own phase. It holds no outcome in local state.
A component that advances itself reports a success the host never confirmed. That is a measurement nobody took.
Enforced by the props. No converted component exposes a phase setter or a default outcome prop.
pendingValue and aria-pressed
pendingValue is the only channel for optimistic rendering. It exists only on the
pending arm of AugeoEffectState.
aria-pressed reports the confirmed value in every phase. data-pressed and the visual
treatment follow the optimistic value.
The two are split because a screen reader must not hear a save as done. The eye may run ahead of the host; the announcement may not.
Read the optimistic value through optimisticValue(state, confirmed, isBooleanValue).
Never reach into pendingValue by hand.
The confirmed value does not live on AugeoInteractionState. That document is one
attempt — target.effectId — and phase: "confirmed" is identical for a save and an
unsave. The durable fact is a host-owned saved: boolean, required to render the
control. Omitting it is not false: a card that never received a confirmed value paints
no heart. pendingValue is discarded at the terminal phase because at that point either
the confirmed value moved or the intent was not honoured.
Enforced by the type, and by one a11y test per announcing phase.
The replay rule
A replay affordance renders only when the recovery kind is retry and retrySafe is
true. Ask rendersReplayAffordance(recovery). Never restate the rule in a component.
Every other recovery kind renders its own affordance on its own handler.
| Kind | Affordance |
|---|---|
retry | a replay control, and only when retrySafe is true |
verify | a verify control on onVerify |
reauthenticate | a sign-in control on onReauthenticate |
rephrase | a rephrase control on onRephrase |
wait, auto-retry-on-reconnect | copy only, and no control |
none | the message alone |
An unacknowledged write never offers a replay. The write may already have landed.
A second attempt could double a member's action, and the design system cannot tell. Offering one would ask the member to gamble.
UnacknowledgedRecovery therefore excludes retry and fixes retrySafe to false.
Enforced by the type, and by an a11y test that asserts the control is absent.
One terminal event per slot
A declared slot emits exactly one terminal event. It is slot.settled, slot.failed,
or slot.dropped, and never two of them.
slot.settled excludes timeout. A slot that ran out of time did not settle.
A slot with intent: "requested" that terminates without content emits slot.failed,
and needs a failure block. A decorative slot emits slot.dropped instead.
useSlotReport owns every slot emission. A component that composes InteractionSlot
emits nothing itself.
Abandoning a slot
A slot can also end by going away. The component unmounts, or the host swaps slotId on
a mounted slot, while the region is still declared and unterminated.
A decorative slot closes itself. useSlotReport emits slot.dropped with
terminatedBy: "superseded". That occurrence needs no failure block, so the design system
invents nothing to send it.
A requested slot does not. slot.failed requires a failure block, and only the layer that
held the call knows why the read ended. Pass termination on the render before you
abandon the slot. Skip that and the slot stays declared with no terminal event. That reads
downstream as an unresolved region, not as a silent success.
Enforced by useSlotReport, and by the terminal-count assertions in
src/interaction/hooks.test.tsx.
Viewability is a design-system capability
useViewability emits component.viewed when the MRC pair is met. The pair is a visible
ratio of at least half, held for one continuous second.
The page must be visible for the whole dwell. A hidden tab never arms one, a dwell in progress is discarded when the page hides, and the timer re-checks visibility before it emits. Returning to a visible page re-arms measurement from a fresh dwell.
Mounting into a background tab is the case worth naming. No visibilitychange fires
after that mount, so a rule that only reacts to the transition would count an exposure
nobody saw.
This measurement belongs here because only the component holds the element. No layer above it can observe intersection.
The design system measures the exposure. It never decides what the exposure was worth.
Enforced by MRC_VIEWABLE_RATIO, MRC_VIEWABLE_DWELL_MS, and the viewability tests
in src/interaction/hooks.test.tsx.
What is deliberately absent
Seven things are missing on purpose. Adding any of them is a contract break, not a feature.
| Absent | Why | Enforced by |
|---|---|---|
| Thresholds | A threshold turns an observation into a judgement, and that judgement is derived above | only observed stage-1 names can be emitted |
| Identity | The design system knows a control and an item, never a person | subject is absent from InteractionEmission |
| Retry safety | Only the host knows whether a repeat is safe | retrySafe arrives on the resolved state, and is read through rendersReplayAffordance |
| Network calls | Delivery, batching, and retry belong to the host | EmitPort is the only exit, and it defaults to noopEmit |
| Placement | Campaign, placement, and attribution belong to the layers that own them | AugdsMeasurements covers the augds namespace alone |
| A scroll position | A deck reports which cards were seen, not how far the track moved. Mount useViewability on the cards | component.viewed names an element, and a track names nothing |
| A dismissal | The host owns open and is told the surface closed. Radix's onEscapeKeyDown and onPointerDownOutside reach it through ...props, so it can tell escape from scrim | no name reports a surface going away |
Three further absences hold across every occurrence:
- No precise money or point amounts.
ui.action.pressedhas no field for them. - No member-authored free text. A label is copy the design system wrote itself. A name the
caller passes, such as a
Button's children oraria-label, never becomes a label. - No reason invented for a browser event. A failed image reports
reason: "unknown".
Apps
The hub (apps/hub) and the admin console (apps/admin) are hosts. Both boot through
apps/hub/src/boot.tsx, which mounts one EmitProvider at the root.
Its port is appEventSink in apps/hub/src/events/eventSink.ts, an in-memory ring
buffer. A development build validates each envelope with
@kigo-digital/augeo-events/validate. An invalid envelope logs a console warning that
names the type and the Zod issue. Nothing leaves the window, because host delivery waits
for the SDK stage.
The Events button in the review bar lists the buffer live. A device preview frame forwards its records to the bar above it.
What an app may emit
An app emits the stage-1 names only, and only through the design-system hooks.
| Case | Route |
|---|---|
A design-system Button or IconButton press | pass actionId |
| A Radix menu trigger | pass the result of useOpenPress as the menu's onOpenChange |
| A press the app owns | mount useInteractionSurface and bind useActivationSource |
| A toast action | pass the result of useToastAction as the toast's action |
| A write | useEffectReport |
| A read region | useSlotReport or InteractionSlot |
A host or measured name waits for its stage. com.augeo.recognition.given is defined at
stage 2 and opens with the SDK stage. An app never calls the port by hand to emit one
early. A case with no registered name goes to augeo-events first.
Naming an actionId
| App | Form | Example |
|---|---|---|
| Hub | hub.<area>.<action> | hub.wallet.history.retry |
| Admin console | hub.admin.<area>.<action> | hub.admin.campaigns.save_draft |
Dots separate the segments. A segment of more than one word is lower snake_case. That
is the dominant form in the apps, and it matches source.surface.
<area> is the feature folder in snake_case, so features/groupActivities gives
group_activities. <action> is the verb, after its object where one helps.
An id names a control. It never carries a person, an amount or member text. A dynamic segment comes from a closed set, such as a step id.
The app audit
bun run audit:interaction:apps reads both apps with the TypeScript parser. It lists
these kinds of finding, per app and per feature folder, with a file and line for each.
| Kind | Finding |
|---|---|
ds-press-unlabelled | a design-system Button or IconButton press, a kit primitive press, or a SheetActions primary object, with no actionId |
native-press-silent | a native <button>, <a> or router Link press in a component that mounts no surface |
mutation-unreported | a useMutation with no useEffectReport in the same component or hook |
query-no-slot | a query in a page or route file with no slot |
menu-trigger-silent | a Radix menu trigger whose menu has no onOpenChange, or whose control carries an actionId |
It skips tests, stories and the lab, test, mock, server and generated folders.
A Button with a spread is skipped, because the spread may carry the id.
A control slotted into a Radix trigger that opens a layer counts as a press. It needs no
onClick of its own, because the trigger owns the click. A local such as {trigger}
resolves to the element it names.
A menu trigger is different. The menu opens on pointerdown or a key. Its modal layer
swallows the click that follows, and the key prevents its own click. So the control's
actionId never fires, and the menu's onOpenChange reports the press through
useOpenPress. jsdom still fires the click, so only the audit can see this.
A link element passed to a component's link prop is that component's press. It owes
nothing more when the component carries an actionId, because the component emits it.
A hub kit primitive that owns a native press emits inside itself and takes an actionId
prop. usePress in apps/hub/src/events/usePress.ts wires that press. Unset, the press
stays silent, so chrome such as BackLink may omit it. KIT_PRESSES in the audit
script lists the primitives whose callsites owe the id.
Report mode exits 0. --strict exits 1 on any press finding.
Enforcement map
| Rule | Kind | Where |
|---|---|---|
| Only the eleven stage-1 names | type, runtime and lint | DesignSystemEventName, assertDesignSystemEventName, local/no-unregistered-event-name |
| No local-to-contract adapter table | type audit | scripts/audit-adapter-tables.mjs via bun run audit:interaction:strict |
| Write authority | type and lint | InteractionEmission, DesignSystemCorrelation, local/no-foreign-event-authority |
| A component never advances its own phase | lint | local/no-self-advanced-phase |
| Slot and effect states never mix | type | AugeoSlotState, AugeoEffectState |
| No replay on an unacknowledged write | type and test | UnacknowledgedRecovery, the a11y absence test |
| One terminal event per slot | test | src/interaction/hooks.test.tsx |
| Every envelope matches the schema | test | src/interaction/emitter.test.ts |
| No per-part styling escape hatch | lint | local/no-escape-hatch-props |
| Every component declares its status | audit | bun run audit:interaction --strict |
Every app press carries an actionId | audit | bun run audit:interaction:apps, report mode until the apps are labelled |
A mute native <button>, <a>, or media slug fails --strict as stale-surface; status stays not-started | audit | NOT_STARTED_GRANDFATHER in scripts/audit-interaction-contract.mjs is today's mute debt, not a hatch. Composed Button/IconButton/Radix and role without a native tag are out of scope |
A @deprecated wrapper that forwards only to design-system controls is exempt, because the component it forwards to emits | audit | scripts/audit-interaction-contract.mjs. One export that is not deprecated, a native control or media removes the exemption |
| A claimed space covers every phase of that space | schema | interaction_states, bun run ds-readme:validate |
| An undrawn frame stays visible as MISSING | script | scripts/generate-docs.mjs, bun run check:docs-sync |
| A phase is never drawn in a severity role | review | the phase group in tokens/v2/semantic/color.json; no automated check yet |
| Both of these documents stay readable | script | bun run check:docs-style |
The three interaction rules read their vocabulary from @kigo-digital/augeo-events. A
name, a phase or a namespace added upstream reaches the rules with no edit here.
Adapter tables typecheck. Catch them with the TypeScript checker, never an
untyped object-literal walk. AIA-1800 shipped that heuristic. It missed real
tables and flagged SlotDeclaration. Do not revive it. The type audit follows
import and alias declarations to @kigo-digital/augeo-events. A local union
that overlaps SlotPhase is not the contract type. Assignability of string
unions is not provenance. A domain object that only shares a field name
(kind: string) is not an adapter. Inferred as const tables are in scope
even when their keys copy contract literals.
CI cannot install this package without a token. @kigo-digital/augeo-events is published
to GitHub Packages. validate.yml and pr-checks.yml declare packages: read and pass
the token through oven-sh/setup-bun registries. Drop either and every install step fails.
One cast, and the upstream defect behind it
src/interaction/emitter.ts carries a single cast when it writes data.context. It is
the only as unknown as cast in the contract layer. state.ts carries two narrowing
casts, and neither hides a defect.
The cause is upstream. AugeoEventContext in @kigo-digital/augeo-events resolves to an
object with a string index signature of Record<string, never>.
The catchall exists to stop an unregistered namespace becoming a scalar. Its inferred type is stricter than intended.
So augds cannot satisfy its own index signature, and a correct object is rejected. The
cast restores the assignment the schema already allows.
Remove the cast when upstream constrains the catchall to a namespace object. Until then,
the schema validation in emitter.test.ts is what keeps the cast honest.
Why bunfig.toml excludes the events package
minimumReleaseAge in bunfig.toml delays adoption of a freshly published version. It
guards against a malicious release on a public registry.
@kigo-digital/augeo-events is neither. It is first-party code on our own restricted
GitHub Packages registry, published by our own pipeline.
The exclude was added because the install genuinely fails without it. That failure was reproduced, not assumed.
The exclude is therefore narrow by design. It names one first-party package and reopens nothing for the public registry.
Add another entry only after reproducing an install that fails without it. Say which package forced it, and why the package is trusted.