Claude-Code-Workflow/.codex/skills/team-interactive-craft/roles/interaction-designer/role.md

role, prefix, inner_loop, message_types

role	prefix	inner_loop	message_types
interaction-designer	INTERACT	false	state_update

Interaction Blueprint Designer

Design complete interaction blueprints: state machines, event flows, gesture specifications, animation choreography, and input mapping tables. Consume research artifacts to produce blueprints for the builder role.

Phase 2: Context & Artifact Loading

Input	Source	Required
Research artifacts	/research/*.json	Yes
.msg/meta.json	/wisdom/.msg/meta.json	Yes
Existing blueprints	/interaction/blueprints/*.md	Only for INTERACT-002+

1. Extract session path from task description
2. Read research findings: interaction-inventory.json, browser-api-audit.json, pattern-reference.json
3. Detect task type from subject: "001" -> Primary blueprint, "002" -> Secondary/gallery blueprint
4. If INTERACT-002+: read existing blueprints for consistency with base component

Phase 3: Design Execution

Primary Blueprint (INTERACT-001):

For each target component, produce a blueprint document containing:

State Machine

Define complete state diagram:

[idle] --(pointerenter)--> [hover]
[hover] --(pointerdown)--> [active]
[hover] --(pointerleave)--> [idle]
[active] --(pointermove)--> [dragging/animating]
[active] --(pointerup)--> [hover]
[dragging] --(pointerup)--> [settling]
[settling] --(transitionend)--> [idle]
[any] --(focus)--> [focused]
[focused] --(blur)--> [previous-state]
[any] --(keydown:Escape)--> [idle]

• All states must be reachable
• All states must have exit transitions
• Error/reset transitions from every state back to idle

Event Flow Map

Map events to handlers to state transitions:

Event	Source	Handler	State Transition	Side Effect
pointerdown	element	onPointerDown	idle->active	setPointerCapture, preventDefault
pointermove	document	onPointerMove	active->dragging	update position via lerp
pointerup	document	onPointerUp	dragging->settling	releasePointerCapture
keydown:ArrowLeft	element	onKeyDown	-	decrement value
keydown:ArrowRight	element	onKeyDown	-	increment value
keydown:Escape	element	onKeyDown	any->idle	reset to default
keydown:Enter/Space	element	onKeyDown	idle->active	toggle/activate

Gesture Specification

For pointer/touch interactions:

Gesture	Detection	Parameters
Drag	pointerdown + pointermove > 3px	lerp speed: 0.15, axis: x/y/both
Swipe	pointerup with velocity > 0.5px/ms	direction: left/right/up/down
Pinch	2+ touch points, distance change	scale factor, min/max zoom
Scroll snap	CSS scroll-snap-type: x mandatory	align: start/center, behavior: smooth

• Lerp interpolation: current += (target - current) * speed
• Dead zone: ignore movements < 3px from start
• Velocity tracking: store last 3-5 pointer positions with timestamps

Animation Choreography

Define animation sequences:

Animation	Trigger	Properties	Duration	Easing	GPU
Entry	mount/reveal	opacity 0->1, translateY 20px->0	400ms	cubic-bezier(0.16,1,0.3,1)	Yes
Exit	unmount/hide	opacity 1->0, translateY 0->-10px	200ms	ease-in	Yes
Drag follow	pointermove	translateX via lerp	per-frame	linear (lerp)	Yes
Settle	pointerup	translateX to snap point	300ms	cubic-bezier(0.16,1,0.3,1)	Yes
Hover	pointerenter	scale 1->1.02	200ms	ease-out	Yes
Focus ring	focus-visible	outline-offset 0->2px	150ms	ease-out	No (outline)
Stagger	intersection	delay: index * 80ms	400ms+delay	cubic-bezier(0.16,1,0.3,1)	Yes

• ALL animations must use transform + opacity only (GPU-composited)
• Exception: outline for focus indicators
• Reduced motion: replace all motion with opacity-only crossfade (200ms)

Input Mapping Table

Unified mapping across input methods:

Action	Mouse	Touch	Keyboard	Screen Reader
Activate	click	tap	Enter/Space	Enter/Space
Navigate prev	-	swipe-right	ArrowLeft	ArrowLeft
Navigate next	-	swipe-left	ArrowRight	ArrowRight
Drag/adjust	pointerdown+move	pointerdown+move	Arrow keys (step)	Arrow keys (step)
Dismiss	click outside	tap outside	Escape	Escape
Focus	pointermove (hover)	-	Tab	Tab

Platform API Preference

When designing interaction blueprints, prefer native APIs over custom implementations:

Need	Native API	Custom Fallback
Modal dialog	<dialog> + showModal()	Custom with focus trap + inert
Tooltip/popover	Popover API (popover attribute)	Custom with click-outside listener
Dropdown positioning	CSS Anchor Positioning	position: fixed + JS coords
Focus trap	<dialog> built-in or inert attribute	Manual focus cycling with tabindex
Escape-to-close	Built into <dialog> and Popover	Manual keydown listener

Document in blueprint: which native API to use, what the fallback is for unsupported browsers, and how to feature-detect.

Gallery/Secondary Blueprint (INTERACT-002):

• Design scroll-snap container interaction
• Navigation controls (prev/next arrows, dots/indicators)
• Active item detection via IntersectionObserver
• Keyboard navigation within gallery (ArrowLeft/ArrowRight between items)
• Touch momentum and snap behavior
• Reference base component blueprint for consistency

Output: <session>/interaction/blueprints/{component-name}.md

Phase 4: Self-Validation

Check	Pass Criteria
State machine complete	All states reachable, all states have exit
Event coverage	All events mapped to handlers
Keyboard complete	All interactive actions have keyboard equivalent
Touch parity	All mouse actions have touch equivalent
GPU-only animations	No width/height/top/left animations
Reduced motion	prefers-reduced-motion fallback defined
Screen reader path	All actions accessible via screen reader

If any check fails, revise the blueprint before output.

Update <session>/wisdom/.msg/meta.json under interaction-designer namespace:

• Read existing -> merge { "interaction-designer": { task_type, components_designed, states_count, events_count, gestures } } -> write back