Augeo AI Docs
Augeo Design SystemInteraction Events

Component Migration

The procedure for converting a component to the interaction contract.

This page is a procedure. Follow the steps in order and the component ends up reporting honestly.

Read the interaction events standard once before you start. It holds the rules. This page holds the steps.

Five first movers are already converted. Use them as the worked examples.

ComponentOwnsPath
OfferCardone read; no presssrc/components/ui/offer-card/
FavoriteButtonone writesrc/components/ui/favorite-button/
ProductCardtwo writes; the read region belongs to InteractionSlotsrc/components/ui/product-card/
Buttonpaints a handed-down effect; does not originate onesrc/components/ui/button/
InteractionSlotone read regionsrc/components/ui/interaction-slot/

What emits what

The design system has eleven names and no more. Each name has one behaviour behind it.

NameEmitted by
com.augeo.ui.component.rendereduseRenderReport, on mount and on a content-state change
com.augeo.ui.component.vieweduseViewability, once the MRC pair is met for an identity
com.augeo.ui.action.presseda converted press handler, once per gesture
com.augeo.ui.effect.requesteduseEffectReport().request, which mints the effectId
com.augeo.ui.effect.settleduseEffectReport, when it is handed a terminal effect phase
com.augeo.ui.media.faileda media onError handler on the component
com.augeo.ui.slot.declareduseSlotReport, on the first render of the slot
com.augeo.ui.slot.filleduseSlotReport, when the phase first carries content
com.augeo.ui.slot.settleduseSlotReport, on a settled slot phase
com.augeo.ui.slot.faileduseSlotReport, when a requested slot terminates on a failure
com.augeo.ui.slot.droppeduseSlotReport, when a decorative slot terminates empty

The procedure

  1. Decide what the component owns. Ask one question. Does this component read content, write an outcome, or both? A read region is InteractionSlot. A write needs an effect. ProductCard owns two writes.

    • Done when you can name the read, the write, or both, in one line.
    • Caught by bun run audit:interaction --strict, which reports every component's status.
  2. Add the surface. Call useInteractionSurface("<slug>", { instanceId, politeness }) once, at the top of the component. slug is lower snake_case (product_card, favorite_button, offer_card). The runtime asserts this. source.surface always carries the slug. occurrence.componentName is set by useRenderReport. That field lives on ui.component.rendered / viewed, not on every event. Accept an optional instanceId prop and pass it through. Omit the prop and the hook derives a stable id from React.useId(). Never build an instance id by hand. Do not take a slotId prop. Slot identity comes from useSlotScope(), and correlation.slotId is written only when this package declared the slot.

    • Done when the component holds one surface and emits only through it.
    • Caught by the audit's interaction-surface check, which fails a component that emits without one.
  3. Report the render. Skip this step and the next for a control that renders no content. FavoriteButton skips both, because it paints one glyph and holds no slot. Call useRenderReport(surface, options) directly after the surface. Pass componentName, and pass variant when the component has visual versions. Derive contentState from the slot phase you were handed.

    Slot phasecontentState
    loadingskeleton
    emptyempty
    timeout, failureerror
    fallbackpartial
    anything elsefull

    Keep the returned ref. It is the causation for the viewability event.

    • Done when one event fires on mount, and one more on each content-state change.
    • Caught by the component test, which asserts the render report and its renderReason.
  4. Measure viewability. Call useViewability(surface, options) and attach the callback ref it returns. Merge it with any forwarded ref through mergeRefs. Pass identity: item?.id ?? null, so a recycled card measures the new item. Pass causedBy as the ref from step 3. Disable it while the slot phase is loading. A skeleton is not an exposure.

    • Done when one viewed event fires per identity, and none for a skeleton.
    • Caught by the component test, which crosses the threshold and advances the timers.
  5. Convert each press. Bind useActivationSource().bind to the control, and keep the caller's handlers. Mint one gestureKey per press with mintGestureKey(). Emit ui.action.pressed with an actionId and actionKind declared on the component. Read inputMethod from activation.consume(event). Never guess it. Send label only when the component wrote that copy itself. Never send member-authored text. A name the caller passes may carry a person, so a generic control such as Button sends none. Fire the caller's own callback as well. Emitting is additive, never a replacement.

    • Done when one press emits one pressed event with the canonical actionId.
    • Done when the existing callback still fires for every caller.
    • Caught by the component test, which asserts the address and the input method.

    Decide whether this component owns the press.

    • Own the press (native handler on this component) → bind useActivationSource. Emit ui.action.pressed. Keep the caller callback. Example: ProductCard card click; ActivityCard onOpen if that control is a native button.
    • Compose Button/IconButton/FavoriteButton → do not bind activation here. Pass actionId only when this surface should report the press. Omit it for silent chrome. Example: a composed Button with no actionId.
    • No press → skip step 5. Example: OfferCard, TextField mount-only.
    • Media-only emit (ui.media.failed) still requires step 5 if the component also owns a native press. Mounting a surface for media.failed does not convert the press. The audit's adopted row can flip on media-failure alone; that is not OfferCard-complete.
  6. Open and settle each effect. Call useEffectReport(surface, state) and request the write inside the press handler. Pass the same gestureKey to the press event and the request. Address the subject with subjectKeyFor(item), or accept a subjectKey prop. Hand the resolved AugeoEffectState straight back in. The hook settles the effect. Never emit a settled event yourself.

    • Done when one request emits exactly one settled event, at a terminal phase.
    • Caught by the audit's effect-requested and effect-settled checks.
    • Caught by the terminal-count assertions in src/interaction/hooks.test.tsx.
  7. Render every phase of the state space you claimed. Render the five effect phases, the eight slot phases, or both. Use InteractionSlot for a read. It renders all eight exits for you. Render empty as a designed answer. Never render it as an error. Render cancelled as nothing. A member's own decision needs no notice. Set data-effect-phase or data-slot-phase as the styling and test hook. Read the optimistic value with optimisticValue, and keep aria-pressed on the confirmed one. Set aria-busy from state.a11y.busy, and disable the control while it is pending. Style each phase from --augds-* tokens. Never add a per-part className prop. Take phase colour from the phase group in tokens/v2/semantic/color.json. Never draw unacknowledged in status/error. Nobody said no, and the write may have landed. Emit ui.media.failed from the onError of any image the component renders. Report reason: "unknown" there. A browser error event states no reason.

    • Done when every phase has a treatment, and no phase falls through to the default.
    • Caught by the audit's phase-render check, which names each unrendered phase.
    • Caught by the audit's media-failure check for an unhandled image.
    • Caught by bun run lint, whose local/no-escape-hatch-props rule blocks the styling prop.
  8. Place the recovery affordance. Announce in the component. Render the affordance on the surface that has room. Add a visually hidden live region carrying state.a11y.message. Let state.a11y.politeness choose the role. Let the visual variant choose the colour. Render InteractionNotice once per effect on the composing surface. ProductCard renders one notice for the favorite and one for the redeem. FavoriteButton renders neither, so a standalone consumer composes the notice. Never restate the replay rule. InteractionNotice already asks rendersReplayAffordance.

    • Done when every failure reaches a member as copy, and at most one control.
    • Caught by bun run test:a11y, which asserts the role and the announcement.
    • Caught by the audit's a11y-test check, for a component that announces untested.
  9. Delete the props that hold an outcome. Delete any prop that seeds uncontrolled state, such as defaultFavorite. Delete it outright. Do not deprecate it. Delete outcome callbacks such as onFavoriteChange. A press is not a save. saved is the value a host confirmed. Omit it to render no heart; absent is not false. Name the removal in your commit message. Deleting a prop is a breaking change. A consumer who relied on the uncontrolled value gets a control that never fills.

    • Done when no prop lets a caller start the component in a state nobody confirmed.
    • Caught by bun run typecheck across the repo, and by the story and test updates it forces.
  10. Write the story matrix. Write one story per phase of the space the component claimed. Build every fixture with resolveSlotState or resolveEffectState. Give the pending fixture a pendingValue that disagrees with the confirmed value. Wrap the stories in EmitProvider to watch the envelopes.

    • Done when a reviewer can see every phase without editing code.
    • Caught by the audit's story-per-phase check, which names each unstoried phase.
  11. Write the a11y tests, including the absence assertion. Write one test per announcing phase. Assert the live region, its politeness, and the message it carries. Assert that aria-pressed reports the confirmed value while a write is pending. Assert that an unacknowledged state renders no replay control. Keep that absence assertion. It is the one test that proves the replay rule holds.

    • Done when the suite fails if a replay control appears on an unacknowledged write.
    • Caught by bun run test:a11y.
  12. Run the audit. Run bun run audit:interaction --strict and read every row. Fix each reported gap in the component, never in the audit.

    • Done when the audit reports the component as adopted, with nothing missing.
    • Caught by the pull request gate, which runs the audit in strict mode.
  13. Update the README frontmatter. Add @kigo-digital/augeo-events and src.interaction to composition.dependencies. List every new story id under rendering.storybook.story_ids. Record the aria rules for the phases under accessibility.aria_requirements. Record the locked decisions under references.design_notes, with the ticket key. Add the interaction_states block: the space, every covered phase, one figma entry each. Write null for a phase nobody has drawn. An absent key fails validation. Run bun run ds-readme:validate, then bun run sync:docs.

    • Done when the frontmatter validates and the generated MDX has no diff.
    • Caught by bun run ds-readme:validate and bun run check:docs-sync.

Three mistakes worth naming

Each of these has shipped somewhere before. Each one reads as a small convenience at the time.

Collapsing empty into failure. A read that found nothing did not fail. Rendering an error there tells a member something untrue, and it teaches them to distrust real errors. Give empty its own designed answer.

Advancing a phase locally. A component that sets its own phase reports an outcome the host never confirmed. The optimistic value is the only thing that may run ahead, and it travels in pendingValue.

Offering retry on unacknowledged. That phase means the write may already have landed. A replay could double a member's action. Render the warning treatment, and no control.