Semantic Micro-interactions

Announce at start: "I'm using the humane:semantic-micro-interactions skill to make state changes feel clear without making motion carry the meaning."

A micro-interaction is a bounded response to a meaningful state transition. Start with what changed and what the person needs to understand; motion, highlight, status text, haptics, and sound are possible channels after that decision. An effect with no state change or orientation job is decoration and does not belong in the interaction map.

Quick reference

Need	Read
Pattern selection, interruption, gesture and status guidance	references/patterns.md
The interaction-map fields and accessibility invariants	references/contract.md

Map the transition

For each moment, record:

1. The semantic trigger and the before/after states. Use activate, focus, hover, state-change, validation, completion, or gesture-end; do not make raw DOM events the design contract.
2. The intent: acknowledge, confirm, reject, reveal, connect, progress, or settle.
3. What already communicates the result without motion or sound. If the answer is nothing, repair the state semantics before animating it.
4. The full-motion feedback, its reduced and no-motion substitutions, and every equivalent input route.
5. Interruption, cancellation, repetition and rate-limit behavior.

Write the result as an interaction map using references/contract.md. When the user wants a saved artifact, resolve artifact_path(name, "semantic-micro-interactions", "json"); never assemble a .design path at the call site. Validate a saved map with python3 scripts/validate_map.py <map.json>.

Hard boundaries

• Use native controls and platform keyboard conventions before custom gesture handling. Hover may enrich; it never reveals required information or the only control.
• A press appearance may begin on pointer-down. Navigation, submission, destructive actions, and persistent changes commit on activation/pointer-up, unless an explicit undo or essential exception makes the alternative safe.
• Dragging has both a keyboard route and a non-dragging single-pointer route. Keyboard support alone does not satisfy the latter.
• Motion never moves focus. A reveal preserves logical focus order, and a status update is announced only when it is actually a status message.
• Non-essential spatial travel, parallax, scale, path and rotation have a reduced-motion substitution. Do not implement reduced motion as a global near-zero duration that leaves vestibular movement intact.
• Reject ambient loops, strobing, repeated shake, and effects that delay the true state. Feedback is interruptible and settles into the actual state.

These are Humane production policies informed by WCAG, not a claim that every one is a normative WCAG AA requirement. references/contract.md names the relevant criteria and the scope of each.

Sound is a hook, not a layer

An interaction map may emit one semantic identifier such as action.confirmed or panel.settled. It never contains a file path, prompt, provider, autoplay flag, volume, preload or mixer configuration. Sound is off until the person opts in, silent operation preserves the same meaning, and rapid events are deduplicated.

Hand an approved soundEvent to humane:sound-effects; that skill owns the palette, generated asset, receipt and playback guidance. Do not add a sound merely because the interface moves.

Verification and handoff

Before calling the map implemented, check it with keyboard, pointer and touch where supported; full, reduced and no-motion modes; sound off; interruption mid-transition; rapid repeat; and error/slow states. Record what was actually observed and mark the rest Not verified.

Then hand the operable interface to humane:walkthrough. This skill specifies feedback behavior; walkthrough decides whether the feedback actually helps a person complete the task.

What this skill does not own

Concern	Owner
Duration, dimension, color and typography values	design-tokens
Narrative order, sticky stages and scroll activation	narrative-scrollytelling
Sound prompts, providers, files and playback layer	sound-effects
Task success in the working interface	walkthrough
Framework-specific animation craft and accessibility engineering depth	interfaces when installed; otherwise mark the implementation depth Not reviewed