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.
| Component | Owns | Path |
|---|---|---|
OfferCard | one read; no press | src/components/ui/offer-card/ |
FavoriteButton | one write | src/components/ui/favorite-button/ |
ProductCard | two writes; the read region belongs to InteractionSlot | src/components/ui/product-card/ |
Button | paints a handed-down effect; does not originate one | src/components/ui/button/ |
InteractionSlot | one read region | src/components/ui/interaction-slot/ |
What emits what
The design system has eleven names and no more. Each name has one behaviour behind it.
| Name | Emitted by |
|---|---|
com.augeo.ui.component.rendered | useRenderReport, on mount and on a content-state change |
com.augeo.ui.component.viewed | useViewability, once the MRC pair is met for an identity |
com.augeo.ui.action.pressed | a converted press handler, once per gesture |
com.augeo.ui.effect.requested | useEffectReport().request, which mints the effectId |
com.augeo.ui.effect.settled | useEffectReport, when it is handed a terminal effect phase |
com.augeo.ui.media.failed | a media onError handler on the component |
com.augeo.ui.slot.declared | useSlotReport, on the first render of the slot |
com.augeo.ui.slot.filled | useSlotReport, when the phase first carries content |
com.augeo.ui.slot.settled | useSlotReport, on a settled slot phase |
com.augeo.ui.slot.failed | useSlotReport, when a requested slot terminates on a failure |
com.augeo.ui.slot.dropped | useSlotReport, when a decorative slot terminates empty |
The procedure
-
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.ProductCardowns 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.
-
Add the surface. Call
useInteractionSurface("<slug>", { instanceId, politeness })once, at the top of the component.slugis lower snake_case (product_card,favorite_button,offer_card). The runtime asserts this.source.surfacealways carries the slug.occurrence.componentNameis set byuseRenderReport. That field lives onui.component.rendered/viewed, not on every event. Accept an optionalinstanceIdprop and pass it through. Omit the prop and the hook derives a stable id fromReact.useId(). Never build an instance id by hand. Do not take aslotIdprop. Slot identity comes fromuseSlotScope(), andcorrelation.slotIdis 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-surfacecheck, which fails a component that emits without one.
-
Report the render. Skip this step and the next for a control that renders no content.
FavoriteButtonskips both, because it paints one glyph and holds no slot. CalluseRenderReport(surface, options)directly after the surface. PasscomponentName, and passvariantwhen the component has visual versions. DerivecontentStatefrom the slot phase you were handed.Slot phase contentStateloadingskeletonemptyemptytimeout,failureerrorfallbackpartialanything else fullKeep 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.
-
Measure viewability. Call
useViewability(surface, options)and attach the callback ref it returns. Merge it with any forwarded ref throughmergeRefs. Passidentity: item?.id ?? null, so a recycled card measures the new item. PasscausedByas the ref from step 3. Disable it while the slot phase isloading. 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.
-
Convert each press. Bind
useActivationSource().bindto the control, and keep the caller's handlers. Mint onegestureKeyper press withmintGestureKey(). Emitui.action.pressedwith anactionIdandactionKinddeclared on the component. ReadinputMethodfromactivation.consume(event). Never guess it. Sendlabelonly 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 asButtonsends 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. Emitui.action.pressed. Keep the caller callback. Example: ProductCard card click; ActivityCardonOpenif that control is a native button. - Compose
Button/IconButton/FavoriteButton→ do not bind activation here. PassactionIdonly 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 formedia.faileddoes not convert the press. The audit'sadoptedrow can flip on media-failure alone; that is not OfferCard-complete.
- Done when one press emits one pressed event with the canonical
-
Open and settle each effect. Call
useEffectReport(surface, state)and request the write inside the press handler. Pass the samegestureKeyto the press event and the request. Address the subject withsubjectKeyFor(item), or accept asubjectKeyprop. Hand the resolvedAugeoEffectStatestraight 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-requestedandeffect-settledchecks. - Caught by the terminal-count assertions in
src/interaction/hooks.test.tsx.
-
Render every phase of the state space you claimed. Render the five effect phases, the eight slot phases, or both. Use
InteractionSlotfor a read. It renders all eight exits for you. Renderemptyas a designed answer. Never render it as an error. Rendercancelledas nothing. A member's own decision needs no notice. Setdata-effect-phaseordata-slot-phaseas the styling and test hook. Read the optimistic value withoptimisticValue, and keeparia-pressedon the confirmed one. Setaria-busyfromstate.a11y.busy, and disable the control while it is pending. Style each phase from--augds-*tokens. Never add a per-partclassNameprop. Take phase colour from thephasegroup intokens/v2/semantic/color.json. Never drawunacknowledgedinstatus/error. Nobody said no, and the write may have landed. Emitui.media.failedfrom theonErrorof any image the component renders. Reportreason: "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-rendercheck, which names each unrendered phase. - Caught by the audit's
media-failurecheck for an unhandled image. - Caught by
bun run lint, whoselocal/no-escape-hatch-propsrule blocks the styling prop.
-
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. Letstate.a11y.politenesschoose the role. Let the visual variant choose the colour. RenderInteractionNoticeonce per effect on the composing surface.ProductCardrenders one notice for the favorite and one for the redeem.FavoriteButtonrenders neither, so a standalone consumer composes the notice. Never restate the replay rule.InteractionNoticealready asksrendersReplayAffordance.- 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-testcheck, for a component that announces untested.
-
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 asonFavoriteChange. A press is not a save.savedis 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 typecheckacross the repo, and by the story and test updates it forces.
-
Write the story matrix. Write one story per phase of the space the component claimed. Build every fixture with
resolveSlotStateorresolveEffectState. Give the pending fixture apendingValuethat disagrees with the confirmed value. Wrap the stories inEmitProviderto watch the envelopes.- Done when a reviewer can see every phase without editing code.
- Caught by the audit's
story-per-phasecheck, which names each unstoried phase.
-
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-pressedreports the confirmed value while a write is pending. Assert that anunacknowledgedstate 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.
-
Run the audit. Run
bun run audit:interaction --strictand 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.
- Done when the audit reports the component as
-
Update the README frontmatter. Add
@kigo-digital/augeo-eventsandsrc.interactiontocomposition.dependencies. List every new story id underrendering.storybook.story_ids. Record the aria rules for the phases underaccessibility.aria_requirements. Record the locked decisions underreferences.design_notes, with the ticket key. Add theinteraction_statesblock: the space, every covered phase, onefigmaentry each. Writenullfor a phase nobody has drawn. An absent key fails validation. Runbun run ds-readme:validate, thenbun run sync:docs.- Done when the frontmatter validates and the generated MDX has no diff.
- Caught by
bun run ds-readme:validateandbun 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.