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:
- 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.
- The intent:
acknowledge, confirm, reject, reveal, connect,
progress, or settle.
- What already communicates the result without motion or sound. If the answer
is nothing, repair the state semantics before animating it.
- The full-motion feedback, its reduced and no-motion substitutions, and every
equivalent input route.
- 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 |
1---2name: semantic-micro-interactions3description: Define bounded interface feedback from a real state transition, including accessible visual motion, reduced-motion and input-equivalent behavior, and an optional semantic sound hook without owning audio playback. Use when a control, gesture, validation, progress state, or completion needs meaningful feedback rather than decorative animation. Triggers on micro-interaction, interaction motion, button feedback, state transition, drag settle, satisfying interaction, reduced motion, hover feedback, completion animation, semantic motion.4---56# Semantic Micro-interactions78**Announce at start:** "I'm using the humane:semantic-micro-interactions skill to make state changes feel clear without making motion carry the meaning."910A micro-interaction is a bounded response to a meaningful state transition. Start11with what changed and what the person needs to understand; motion, highlight,12status text, haptics, and sound are possible channels after that decision. An13effect with no state change or orientation job is decoration and does not belong14in the interaction map.1516## Quick reference1718| Need | Read |19| --- | --- |20| Pattern selection, interruption, gesture and status guidance | `references/patterns.md` |21| The interaction-map fields and accessibility invariants | `references/contract.md` |2223## Map the transition2425For each moment, record:26271. The semantic trigger and the before/after states. Use `activate`, `focus`,28 `hover`, `state-change`, `validation`, `completion`, or `gesture-end`; do not29 make raw DOM events the design contract.302. The intent: `acknowledge`, `confirm`, `reject`, `reveal`, `connect`,31 `progress`, or `settle`.323. What already communicates the result without motion or sound. If the answer33 is nothing, repair the state semantics before animating it.344. The full-motion feedback, its reduced and no-motion substitutions, and every35 equivalent input route.365. Interruption, cancellation, repetition and rate-limit behavior.3738Write the result as an interaction map using `references/contract.md`. When the39user wants a saved artifact, resolve `artifact_path(name,40"semantic-micro-interactions", "json")`; never assemble a `.design` path at the41call site. Validate a saved map with `python3 scripts/validate_map.py <map.json>`.4243## Hard boundaries4445- Use native controls and platform keyboard conventions before custom gesture46 handling. Hover may enrich; it never reveals required information or the only47 control.48- A press appearance may begin on pointer-down. Navigation, submission,49 destructive actions, and persistent changes commit on activation/pointer-up,50 unless an explicit undo or essential exception makes the alternative safe.51- Dragging has both a keyboard route and a non-dragging single-pointer route.52 Keyboard support alone does not satisfy the latter.53- Motion never moves focus. A reveal preserves logical focus order, and a status54 update is announced only when it is actually a status message.55- Non-essential spatial travel, parallax, scale, path and rotation have a56 reduced-motion substitution. Do not implement reduced motion as a global57 near-zero duration that leaves vestibular movement intact.58- Reject ambient loops, strobing, repeated shake, and effects that delay the59 true state. Feedback is interruptible and settles into the actual state.6061These are Humane production policies informed by WCAG, not a claim that every62one is a normative WCAG AA requirement. `references/contract.md` names the63relevant criteria and the scope of each.6465## Sound is a hook, not a layer6667An interaction map may emit one semantic identifier such as68`action.confirmed` or `panel.settled`. It never contains a file path, prompt,69provider, autoplay flag, volume, preload or mixer configuration. Sound is off70until the person opts in, silent operation preserves the same meaning, and rapid71events are deduplicated.7273Hand an approved `soundEvent` to `humane:sound-effects`; that skill owns the74palette, generated asset, receipt and playback guidance. Do not add a sound75merely because the interface moves.7677## Verification and handoff7879Before calling the map implemented, check it with keyboard, pointer and touch80where supported; full, reduced and no-motion modes; sound off; interruption81mid-transition; rapid repeat; and error/slow states. Record what was actually82observed and mark the rest **Not verified**.8384Then hand the operable interface to `humane:walkthrough`. This skill specifies85feedback behavior; `walkthrough` decides whether the feedback actually helps a86person complete the task.8788## What this skill does not own8990| Concern | Owner |91| --- | --- |92| Duration, dimension, color and typography values | `design-tokens` |93| Narrative order, sticky stages and scroll activation | `narrative-scrollytelling` |94| Sound prompts, providers, files and playback layer | `sound-effects` |95| Task success in the working interface | `walkthrough` |96| Framework-specific animation craft and accessibility engineering depth | `interfaces` when installed; otherwise mark the implementation depth Not reviewed |
glebis