Augeo AI Docs
Augeo Design System

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

ContractTypeDirectionWritten by
Event envelopeAugeoEventupthe design system, then each layer above it
Resolved stateAugeoInteractionStatedownthe host
Effect acknowledgementAugeoAckdownthe 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.

NameReports
com.augeo.ui.component.rendereda component painted, and the content state it painted
com.augeo.ui.component.viewedthe MRC viewability pair was met
com.augeo.ui.action.presseda member pressed a named control
com.augeo.ui.effect.requesteda write was opened
com.augeo.ui.effect.settledthat write reached a terminal phase
com.augeo.ui.media.failedan image or media element failed to load
com.augeo.ui.slot.declareda region of content was promised
com.augeo.ui.slot.filledcontent arrived in that region
com.augeo.ui.slot.settledthe region reached a settled phase
com.augeo.ui.slot.failedthe region terminated with a failure
com.augeo.ui.slot.droppeda 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:

KeyKnown because
effectIdit minted the identifier for this write
slotIdan InteractionSlot it mounted declared that slot (declaredHere)
causationIdit 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.

SpaceTypeExits
ReadSlotPhaseidle, loading, success, empty, fallback, cancelled, timeout, failure
WriteEffectPhaseidle, 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.

KeyHolds
spaceslot, effect, both or none
coveredthe phases the item renders, per space
figmaone node id per covered phase, explicitly null where no frame is drawn
designerOwnsthe frames, and the copy the design system writes itself
engineerOwnsthe resolver that selects a frame
handoffSeams<seam>: <what crosses it>, the vocabulary blocks already use
politeness_sourcehanded-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.

KindAffordance
retrya replay control, and only when retrySafe is true
verifya verify control on onVerify
reauthenticatea sign-in control on onReauthenticate
rephrasea rephrase control on onRephrase
wait, auto-retry-on-reconnectcopy only, and no control
nonethe 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.

AbsentWhyEnforced by
ThresholdsA threshold turns an observation into a judgement, and that judgement is derived aboveonly observed stage-1 names can be emitted
IdentityThe design system knows a control and an item, never a personsubject is absent from InteractionEmission
Retry safetyOnly the host knows whether a repeat is saferetrySafe arrives on the resolved state, and is read through rendersReplayAffordance
Network callsDelivery, batching, and retry belong to the hostEmitPort is the only exit, and it defaults to noopEmit
PlacementCampaign, placement, and attribution belong to the layers that own themAugdsMeasurements covers the augds namespace alone
A scroll positionA deck reports which cards were seen, not how far the track moved. Mount useViewability on the cardscomponent.viewed names an element, and a track names nothing
A dismissalThe host owns open and is told the surface closed. Radix's onEscapeKeyDown and onPointerDownOutside reach it through ...props, so it can tell escape from scrimno name reports a surface going away

Three further absences hold across every occurrence:

  • No precise money or point amounts. ui.action.pressed has 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 or aria-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.

CaseRoute
A design-system Button or IconButton presspass actionId
A Radix menu triggerpass the result of useOpenPress as the menu's onOpenChange
A press the app ownsmount useInteractionSurface and bind useActivationSource
A toast actionpass the result of useToastAction as the toast's action
A writeuseEffectReport
A read regionuseSlotReport 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

AppFormExample
Hubhub.<area>.<action>hub.wallet.history.retry
Admin consolehub.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.

KindFinding
ds-press-unlabelleda design-system Button or IconButton press, a kit primitive press, or a SheetActions primary object, with no actionId
native-press-silenta native <button>, <a> or router Link press in a component that mounts no surface
mutation-unreporteda useMutation with no useEffectReport in the same component or hook
query-no-slota query in a page or route file with no slot
menu-trigger-silenta 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

RuleKindWhere
Only the eleven stage-1 namestype, runtime and lintDesignSystemEventName, assertDesignSystemEventName, local/no-unregistered-event-name
No local-to-contract adapter tabletype auditscripts/audit-adapter-tables.mjs via bun run audit:interaction:strict
Write authoritytype and lintInteractionEmission, DesignSystemCorrelation, local/no-foreign-event-authority
A component never advances its own phaselintlocal/no-self-advanced-phase
Slot and effect states never mixtypeAugeoSlotState, AugeoEffectState
No replay on an unacknowledged writetype and testUnacknowledgedRecovery, the a11y absence test
One terminal event per slottestsrc/interaction/hooks.test.tsx
Every envelope matches the schematestsrc/interaction/emitter.test.ts
No per-part styling escape hatchlintlocal/no-escape-hatch-props
Every component declares its statusauditbun run audit:interaction --strict
Every app press carries an actionIdauditbun 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-startedauditNOT_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 emitsauditscripts/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 spaceschemainteraction_states, bun run ds-readme:validate
An undrawn frame stays visible as MISSINGscriptscripts/generate-docs.mjs, bun run check:docs-sync
A phase is never drawn in a severity rolereviewthe phase group in tokens/v2/semantic/color.json; no automated check yet
Both of these documents stay readablescriptbun 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.