arkaos 5.6.0 → 5.8.0

package/README.md

@@ -4,7 +4,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-89 agents. 17 departments. 338 skills. Enterprise frameworks. Multi-runtime. One install.
+89 agents. 17 departments. 340 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install
@@ -97,7 +97,7 @@ npx arkaos doctor    # Health check
 
 ### Skill packs, à la carte
 
-The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 264 skills, generated straight from the same sources the core uses. Inside Claude Code:
+The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 266 skills, generated straight from the same sources the core uses. Inside Claude Code:
 
 ```
 /plugin marketplace add andreagroferreira/arka-os

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.6.0 — 89 agents, 17 departments, 338 skills, 299 commands, 20 ADRs.
+> v5.8.0 — 89 agents, 17 departments, 340 skills, 299 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-5.6.0
+5.8.0

package/arka/SKILL.md

@@ -63,7 +63,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 89 agents. 17 departments. 338 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 89 agents. 17 departments. 340 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/config/skills-provenance.yaml

@@ -148,6 +148,25 @@ derived:
     origin: community
     source: https://github.com/AThevon/genjutsu
     license: MIT
+  # Animation/design absorption campaign PR-5 — motion doctrine derived
+  # from lottiefiles/motion-design-skill (MIT): director/, patterns/ and
+  # reference/ trees verbatim under references/, SKILL.md body upstream
+  # near-verbatim with ArkaOS frontmatter, header and Output.
+  departments/brand/skills/motion-design:
+    origin: community
+    source: https://github.com/lottiefiles/motion-design-skill
+    license: MIT
+  # Animation/design absorption campaign PR-6 — the official GreenSock
+  # pack (MIT): eight upstream SKILL.md modules become references/ under
+  # one router slug (dev/diagram progressive-disclosure pattern), with
+  # sibling cross-refs rewritten from gsap-<name> to references/<name>.md.
+  # This absorption RETIRES the external dependency: the npx-skills-add
+  # instruction and every gsap-<name> load in brand/content/dev docs now
+  # point at the in-repo skill.
+  departments/dev/skills/gsap:
+    origin: community
+    source: https://github.com/greensock/gsap-skills
+    license: MIT
   # Marketing skills integration campaign — derived from
   # coreyhaines31/marketingskills (MIT). Frontmatter metadata must match
   # each entry field-for-field (test_registry_matches_frontmatter_field_for_field).

package/departments/brand/references/uiux-knowledge-and-tools.md

@@ -204,7 +204,7 @@ line BEFORE the first file edit:
   Airbnb…). Pick it FIRST and state what its design lead would reject in
   your plan.
 - `skills=` — the design skills ACTUALLY loaded this session via the
-  Skill tool (e.g. `frontend-design,ui-ux-pro-max,gsap-core`). If a
+  Skill tool (e.g. `frontend-design,ui-ux-pro-max,arka-gsap`). If a
   plugin is not installed, be honest: `skills=degraded:<missing-name>`
   and fall back to §3 + §8 of this reference. Never claim a load that
   did not happen; never silently proceed as if it had.
@@ -241,10 +241,13 @@ axis free, seed a direction from the curated TypeUI catalog
 
 Catalog tokens are a SEED for the project's own token system, never the
 final design system. Motion is absent from the catalog — that is GSAP's
-job: load `gsap-core` + `gsap-timeline` for any animation work,
-`gsap-scrolltrigger`/`gsap-plugins` as the work demands, `gsap-react` on
-React, and treat `gsap-performance` as the review bar
-(`npx skills add https://github.com/greensock/gsap-skills` when absent).
+job: load `Skill(arka-gsap)` (the in-repo `dev/gsap`, absorbed from the
+official GreenSock pack) and read `references/core.md` +
+`references/timeline.md` for any animation work,
+`references/scrolltrigger.md`/`references/plugins.md` as the work
+demands, `references/react.md` on React, and treat
+`references/performance.md` as the review bar. Direction (what moves and
+why) comes from `brand/motion-design` first.
 
 Four in-repo theme specs (hallmark-derived, opt-in seeds like the TypeUI
 directions — never the final system) live at

package/departments/brand/skills/design-system/SKILL.md

@@ -41,8 +41,10 @@ actually loaded:
    `design-tokens.json`.
 2. **`Skill(ui-ux-pro-max)`** — 161 palettes + 57 font pairings as
    comparative evidence for the primitive layer; never a pick-list.
-3. **Motion tokens involved?** Load the GSAP skills (`gsap-core`,
-   `gsap-timeline`; `gsap-performance` as the review bar).
+3. **Motion tokens involved?** Load `brand/motion-design` for the
+   direction (what moves, durations, easing families) and `dev/gsap`
+   for the implementation (its `references/core.md` + `references/timeline.md`;
+   `references/performance.md` as the review bar).
 4. **Aesthetic seed (optional, no visual history only)** — a curated
    TypeUI direction (`npx typeui.sh pull <slug>`, §10 of the squad
    reference) may seed primitives; it is never the final system.

package/departments/brand/skills/motion-design/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: brand/motion-design
+description: >
+  Motion design direction — decides WHAT should move, how fast, and why,
+  before any code: emotional intent, motion personality archetypes, Disney
+  principles adapted for UI, choreography and stagger rules, timing/easing
+  tables, and a quality checklist. Framework-agnostic: the output drives
+  CSS, GSAP, Framer Motion, Lottie or springs equally.
+  TRIGGER: "motion design", "como deve animar", "linguagem de movimento",
+  "easing", "motion personality", "princípios Disney", "coreografia de
+  animação", "motion system", "motion audit", "/brand motion-design".
+  SKIP: writing the animation code once the direction exists ->
+  dev/gsap (timelines, scroll), dev/css-native (pure CSS),
+  dev/framer-motion (React) or dev/canvas-generative (generative
+  canvas); motion tokens inside a full
+  design-system delivery -> brand/design-system (which loads this skill
+  for its motion chapter); video production -> content/video-produce.
+allowed-tools: [Read, Write, Edit, Grep, Glob]
+metadata:
+  origin: community
+  source: https://github.com/lottiefiles/motion-design-skill
+  license: MIT
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Motion Design — `/brand motion-design`
+
+> **Agent:** Isabel (Visual Designer) with Sofia D. (UX) | **Framework:** LottieFiles motion doctrine (Disney principles, emotion mapping)
+> **Squad reference:** `departments/brand/references/uiux-knowledge-and-tools.md` (§3 tokens, **§4 Motion System**, §8 anti-default, §9 marker)
+
+## Precedence — the brand's Motion System outranks the imported doctrine
+
+For ArkaOS-brand surfaces, §4 of the squad reference wins wherever the
+LottieFiles body below disagrees. Concretely, §4's **Forbidden list**
+reads: rotation/spin, bounce/elastic *on the logo*, 3D/perspective,
+particles, morphing, color-cycling. Applied to this doctrine: the
+rotation spinners, particle bursts, perspective transforms and the
+morphing taught in the linked pattern files are vetoed outright; bounce
+settles and elastic easings are vetoed **on the logo only** — elsewhere
+they remain available exactly as the body teaches them. Scale, shadow
+and parallax depth cues are NOT the forbidden `3D/perspective` and stay
+allowed. And durations map to the brand token scale —
+`motion-instant` 100ms · `motion-fast` 150ms (default) · `motion-normal`
+300ms · `motion-slow` 500ms · `motion-deliberate` 800ms — with the
+imported ms tables read as *relative* guidance inside that scale, not as
+absolute values. For client-brand work, the client's own motion system
+plays the same trumping role; the doctrine below is the default only
+where no system exists.
+
+## When to Apply
+
+Use this skill when:
+- Creating UI animations (buttons, cards, modals, page transitions)
+- Designing micro-interactions and feedback animations
+- Building loading, success, or error states
+- Animating illustrations or decorative elements
+- Planning scroll-triggered or progress-based animations
+- Establishing brand motion identity
+- Choreographing multi-element sequences
+
+**Decision tree:**
+1. Does it serve a functional purpose (feedback, guidance)? → Timing rules for responsiveness
+2. Does it express brand personality? → Motion Personality archetypes
+3. Does it tell a story or guide attention? → Disney principles + choreography
+4. Is this a complex multi-element scene? → 1/3 Rule + stagger patterns
+
+---
+
+## Quick Reference: 8-Step Checklist
+
+Before creating any animation:
+
+1. **Emotional target?** — joy, calm, urgency, elegance
+2. **Motion Personality?** — Playful, Premium, Corporate, Energetic
+3. **Primary property?** — position, scale, rotation, opacity
+4. **Duration?** — see duration table below
+5. **Easing family?** — entrance=decelerate, exit=accelerate
+6. **Hero element?** — apply staging principles
+7. **Secondary + ambient layers?** — add richness
+8. **1/3 rules?** — motion distance, simultaneous elements
+
+---
+
+## Three Pillars (CRITICAL)
+
+Every animation must satisfy three pillars before any technical decisions:
+
+| Pillar | Question | Drives |
+|--------|----------|--------|
+| **Emotional Intent** | What should the viewer FEEL? | Easing, timing, amplitude |
+| **Visual Narrative** | What's the micro-story? | Setup → Action → Resolution |
+| **Motion Craft** | How do we make it believable? | Physics, secondary motion, paths |
+
+**Three motion layers** (flat animation = missing layers):
+- **Primary**: Main action the viewer follows
+- **Secondary**: Supporting richness (shadows, icons shifting)
+- **Ambient**: Background life (gradients, subtle pulses)
+
+> Deep dive: [director/core-philosophy.md](references/director/core-philosophy.md)
+
+---
+
+## Motion Personality
+
+Select ONE archetype per project. Apply consistently.
+
+| Archetype | Duration | Easing | Overshoot | Keywords |
+|-----------|----------|--------|-----------|----------|
+| **Playful** | 150-300ms | ease-out-back | 10-20% | fun, whimsical, bouncy, cute |
+| **Premium** | 350-600ms | cubic-bezier(0.4,0,0.2,1) | 0% | elegant, minimal, luxury, sophisticated |
+| **Corporate** | 200-400ms | cubic-bezier(0.2,0,0,1) | 0-3% | clean, professional, business, dashboard |
+| **Energetic** | 100-250ms | ease-out-expo | 15-30% | dynamic, energetic, bold, exciting |
+
+**Default**: Corporate for UI, Playful for illustrations.
+
+**Brand Motion Identity** — define three constants:
+1. **Signature easing**: One curve for 80% of animations
+2. **Duration palette**: 3 durations (quick / standard / slow)
+3. **Entrance pattern**: One consistent entry style
+
+> Deep dive: [director/motion-personality.md](references/director/motion-personality.md)
+
+---
+
+## Property Selection
+
+| Effect Goal | Primary Property | Secondary Properties |
+|-------------|------------------|---------------------|
+| Entrance/Exit | position | opacity, scale |
+| Emphasis/Attention | scale | rotation (subtle), opacity pulse |
+| State Change | opacity, color | scale (press feedback) |
+| Direction/Flow | position | rotation (follow path) |
+| Depth/3D Feel | scale + shadow | position (parallax) |
+| Loading/Progress | rotation (spinner) | scale, opacity pulse |
+| Success | scale (pop) | color, rotation (checkmark draw) |
+| Error/Alert | position (shake) | color, rotation (wobble) |
+
+**Simplicity threshold**: Use the minimum properties needed. One = direct. Two = polished. Three+ = potentially overwhelming.
+
+> Deep dive: [reference/property-selection.md](references/reference/property-selection.md)
+
+---
+
+## Duration Table
+
+| Element Type | Duration | Rationale |
+|-------------|----------|-----------|
+| Tooltip / micro-feedback | 80-120ms | Must feel instant |
+| Button press / toggle | 120-180ms | Responsive feedback |
+| Icon transition | 150-250ms | Clear state change |
+| Card enter / exit | 200-350ms | Spatial awareness |
+| Modal / dialog | 300-400ms | Focus shift |
+| Page transition | 400-600ms | Context switch |
+| Dramatic reveal | 600-1200ms | Theatrical build |
+
+**Distance scales duration**: 100px = base. 200px = 1.3x. 400px = 1.6x.
+
+**Enter > Exit**: Entrances 30-50% longer than exits. Users care about what appears.
+
+**Interactive feedback**:
+- Hover: <100ms
+- Press: <150ms
+- Release/settle: 200-300ms
+- Error shake: 300-400ms (2-3 oscillations)
+
+> Deep dive: [reference/timing-easing-tables.md](references/reference/timing-easing-tables.md)
+
+---
+
+## Easing Selection
+
+**Directional rules**:
+- **Entrance** → decelerate (fast start, gentle landing): ease-out family
+- **Exit** → accelerate (gentle start, fast departure): ease-in family
+- **On-screen** → smooth both ends: ease-in-out family
+- **Looping ambient** → seamless: sine-based ease-in-out
+
+**Industry standards**:
+
+| Standard | Cubic Bezier | Use For |
+|----------|-------------|---------|
+| Material Design 3 | (0.2, 0, 0, 1) | Default on-screen |
+| MD3 Emphasized | (0.05, 0.7, 0.1, 1) | Entrances, attention |
+| MD3 Accelerate | (0.3, 0, 1, 1) | Exits, dismissals |
+| Apple HIG | (0.25, 0.1, 0.25, 1) | Standard iOS |
+| Snappy UI | (0.2, 0, 0, 1) | Fast, decisive |
+| Gentle float | (0.4, 0, 0.2, 1) | Ambient, background |
+| Bounce settle | (0.175, 0.885, 0.32, 1.275) | Overshoot, playful |
+
+**Material-based easing**:
+
+| Material | Duration Scale | Overshoot |
+|----------|---------------|-----------|
+| Rigid (metal, stone) | 1.2x | 0% |
+| Elastic (rubber, gel) | 0.8x | 15-25% |
+| Fluid (water, paint) | 1.5x | 5% |
+| Paper (cards, sheets) | 1.0x | 3-5% |
+| Gas (smoke, fog) | 2.0x | 0% |
+| Glass (brittle) | 0.9x | 0% |
+
+> Deep dive: [reference/timing-easing-tables.md](references/reference/timing-easing-tables.md)
+
+---
+
+## Common Patterns
+
+### Button Press (Playful)
+1. **Anticipation**: Scale to 0.97 (50ms, ease-out)
+2. **Squash**: Scale to [1.04, 0.96] (100ms, ease-in)
+3. **Follow through**: Overshoots to 1.02, settles to 1.0 (spring, 200ms)
+4. **Secondary**: Shadow shrinks during press, icon shifts down 2px
+5. **Total**: ~150ms press + 200ms settle
+
+### Card Entrance (Premium)
+1. **Start**: 20px below target, opacity 0
+2. **Path**: Slight curve (10px X offset at midpoint)
+3. **Easing**: ease-out-cubic deceleration
+4. **Follow through**: Shadow arrives 50ms after card
+5. **Secondary**: Content fades in 100ms after card lands
+6. **Staging**: Other cards dim to 80%
+
+### Success State (Playful)
+1. **Primary**: Scale pop with ease-out-back
+2. **Secondary**: Checkmark draws in
+3. **Ambient**: Subtle particle burst
+4. **Color**: Green fill
+5. **Total**: 300-400ms
+
+### Error Shake (Corporate)
+1. **Primary**: Position oscillates 2-3 times, ±10-15px horizontal
+2. **Easing**: ease-in-out for sharp stops
+3. **Color**: Red tint
+4. **Total**: 300-400ms
+5. **No overshoot**: Errors feel firm
+
+> More patterns: [patterns/entrance-exit.md](references/patterns/entrance-exit.md) | [patterns/state-feedback.md](references/patterns/state-feedback.md)
+
+---
+
+## Choreography Essentials
+
+**Coordinated entry**:
+- Lead with the hero — primary element enters first or most prominently
+- Spatial consistency — all elements enter from same direction
+- Counter-motion — hero moves right → ambient moves left at 20-30% speed
+
+**1/3 Rule (distance)**: No motion travels more than 1/3 of screen without a keyframe change.
+
+**1/3 Rule (elements)**: With 3+ elements, no more than 1/3 in active motion simultaneously.
+
+**Stagger budgets**:
+
+| Pattern | Delay | Total Budget | Use Case |
+|---------|-------|-------------|----------|
+| Micro cascade | 20-40ms | <200ms | List items, grid cells |
+| Standard | 50-100ms | <400ms | Cards, panels, nav |
+| Dramatic | 100-200ms | <600ms | Hero sections |
+| Wave | 30-60ms | <500ms | Data visualizations |
+
+**Critical**: Total stagger must stay under 500ms.
+
+> Deep dive: [director/choreography.md](references/director/choreography.md)
+
+---
+
+## Emotion-to-Motion Map
+
+| Emotion | Character | Path | Easing | Duration |
+|---------|-----------|------|--------|----------|
+| Joy | Bouncy, arcs | Curved, upward | ease-out-back | 200-400ms |
+| Calm | Smooth, flowing | Gentle curves | sine ease-in-out | 500-1000ms |
+| Urgency | Sharp, fast | Straight lines | ease-out | 100-200ms |
+| Sadness | Slow, downward | Drooping curves | cubic ease-in-out | 600-1200ms |
+| Surprise | Sudden, expanding | Radial outward | ease-out-expo | 150-300ms |
+| Elegance | Slow, controlled | Long arcs | (0.4,0,0.2,1) | 400-700ms |
+| Playfulness | Bouncy, irregular | Arcs, squiggly | ease-out-back | 200-350ms |
+
+**Path as language**: Angular = tense. Curved = friendly. Spiral = whimsical. Diagonal = purposeful. Vertical = growth/weight. Horizontal = progress.
+
+> Deep dive: [director/emotion-mapping.md](references/director/emotion-mapping.md)
+
+---
+
+## Weight Classification
+
+| Weight | Examples | Duration | Overshoot | Easing |
+|--------|----------|----------|-----------|--------|
+| Heavy | Modals, overlays | 300-500ms | 0% | Gentle, high damping |
+| Medium | Cards, panels | 200-350ms | 3-5% | Moderate |
+| Light | Tooltips, badges, icons | 80-200ms | 5-15% | Responsive |
+
+---
+
+## Quality Rules
+
+### CRITICAL — never break
+1. **Never linear for spatial movement** — always use easing curves (linear only for spinners, progress bars)
+2. **Never opacity-only** for important state changes — combine with position or scale
+3. **Never exceed 1/3 screen** without intermediate keyframe
+4. **Always three motion layers** — primary + secondary + ambient
+
+### HIGH — strongly follow
+1. Match duration to element type (see tables)
+2. Use directional easing (ease-out entrance, ease-in exit)
+3. Apply Disney principles (especially anticipation, follow-through)
+4. Maintain consistent personality across scene
+
+> Full checklist: [reference/quality-checklist.md](references/reference/quality-checklist.md)
+
+---
+
+## Troubleshooting Quick Reference
+
+| Problem | Likely Cause | Fix |
+|---------|-------------|-----|
+| Looks robotic | Linear easing or no arcs | Add easing curves + arc paths |
+| Feels too slow | Duration too long for element type | Check duration table, use ease-out |
+| Feels cheap/flat | Missing secondary + ambient | Add shadow motion + background life |
+| Too distracting | Too many elements moving | Apply 1/3 rule, reduce amplitude |
+| No personality | Generic easing everywhere | Apply personality archetype consistently |
+
+> Deep dive: [reference/troubleshooting.md](references/reference/troubleshooting.md)
+
+---
+
+## File Reference
+
+**Philosophy** (director/):
+- [core-philosophy.md](references/director/core-philosophy.md) — Three Pillars deep dive
+- [decision-framework.md](references/director/decision-framework.md) — Full decision pipeline
+- [disney-principles.md](references/director/disney-principles.md) — 12 principles, UI-adapted
+- [motion-personality.md](references/director/motion-personality.md) — 4 archetypes + brand identity
+- [emotion-mapping.md](references/director/emotion-mapping.md) — Emotion → motion + color psychology
+- [choreography.md](references/director/choreography.md) — Multi-element coordination
+- [narrative-structure.md](references/director/narrative-structure.md) — Micro-story framework
+- [context-adaptation.md](references/director/context-adaptation.md) — Platform, a11y, performance
+
+**Reference** (reference/):
+- [timing-easing-tables.md](references/reference/timing-easing-tables.md) — Duration + easing lookups
+- [property-selection.md](references/reference/property-selection.md) — Property communication guide
+- [troubleshooting.md](references/reference/troubleshooting.md) — Animation smells + fixes
+- [quality-checklist.md](references/reference/quality-checklist.md) — Evaluation criteria
+
+**Patterns** (patterns/):
+- [entrance-exit.md](references/patterns/entrance-exit.md) — Entrance/exit recipes
+- [state-feedback.md](references/patterns/state-feedback.md) — Success, error, loading, hover
+- [ambient-continuous.md](references/patterns/ambient-continuous.md) — Looping, breathing, parallax
+- [multi-element.md](references/patterns/multi-element.md) — Stagger + choreography recipes
+
+## Output
+
+A motion direction the build squads execute without interpretation: the
+emotional target and personality archetype, per-element property/duration/
+easing choices from the tables, the choreography order with stagger
+values, and the quality checklist run — plus which implementation skill
+(dev/css-native, dev/framer-motion, dev/canvas-generative or dev/threejs)
+each piece hands to.

package/departments/brand/skills/motion-design/references/director/choreography.md

@@ -0,0 +1,93 @@
+# Choreography
+
+## Coordinated Entry Rules
+
+### 1. Lead with the Hero
+- Hero gets largest displacement and most attention-grabbing easing
+- Supporting elements are subtler in every dimension
+
+### 2. Spatial Origin Consistency
+All elements enter from same direction or shared origin. Mixed directions = chaos.
+
+### 3. Counter-Motion
+
+| Hero Motion | Counter-Motion | Speed Ratio |
+|-------------|---------------|-------------|
+| Enters left | Background shifts right | 20-30% |
+| Scales up | Shadow scales down | 10-20% |
+| Rotates CW | Ambient drifts CCW | 15-25% |
+| Lifts (Y up) | Shadow spreads + softens | 20-30% |
+
+## Sequence Structure
+
+| Phase | Duration Share | What Happens |
+|-------|--------------|-------------|
+| Setup | 20-30% | Elements enter, scene establishes |
+| Action | 30-40% | Primary motion, hero moment |
+| Resolution | 30-40% | Settle, secondary reactions, breathing |
+
+Leave 100-200ms stillness after resolution before new motion.
+
+## The 1/3 Rules
+
+**Distance**: No motion travels >1/3 screen without intermediate keyframe. Break with direction changes, speed variations, or arc adjustments.
+
+**Elements**: With 3+ animated elements, max 1/3 active simultaneously. Stagger so element 1 settles as element 3 starts.
+
+## Stagger Patterns
+
+| Pattern | Description | Best For |
+|---------|------------|----------|
+| Sequential | Reading order | Lists, grids |
+| Center-out | Radiating from center | Hero content, ripples |
+| Random | Varied timing | Organic, particle-like |
+| Wave | Sine-based | Data bars, continuous |
+| Reverse | Bottom-to-top | Exits, backward nav |
+
+- All staggered elements use same easing family
+- Vary only start time, not curve
+- Optional: last element gets slight overshoot (punctuation)
+
+## Shared Motion Events
+
+When multiple elements react to one trigger:
+- All start within 50ms of each other
+- Can arrive at different times (staggered landing)
+- Same easing family; motion originates from trigger point
+
+## Attention Direction
+
+| Technique | Implementation |
+|-----------|---------------|
+| Leading motion | Animate target before context |
+| Following motion | Settle on focal point |
+| Ambient motion | Subtle continuous in periphery |
+| Pointing motion | Directional toward CTA |
+
+### Depth Through Speed
+
+| Layer | Displacement | Speed |
+|-------|-------------|-------|
+| Foreground | 1.0x | Fastest |
+| Midground | 0.5x | Medium |
+| Background | 0.2x | Slowest |
+
+## Common Recipes
+
+### Dashboard Load
+1. Skeletons fade in (100ms)
+2. Hero metric (250ms, ease-out, 100ms delay)
+3. Supporting cards stagger (50ms between, 200ms each)
+4. Chart data draws in (300ms, starts with cards)
+5. Ambient pulse on primary metric
+
+### Modal Open
+1. Background dims (200ms)
+2. Modal scales 95%→100% + fades (300ms, 50ms delay)
+3. Content fades in (200ms, 100ms after modal)
+4. Close button last (150ms)
+
+### List Update (item added)
+1. Existing items shift down (200ms, ease-in-out)
+2. New item fades+slides from top (250ms, ease-out, 50ms delay)
+3. Subtle scale overshoot on land (3-5%)

package/departments/brand/skills/motion-design/references/director/context-adaptation.md

@@ -0,0 +1,83 @@
+# Context Adaptation
+
+## Platform Scaling
+
+| Platform | Duration Modifier | Complexity | Physics |
+|----------|------------------|------------|---------|
+| Desktop | 1.0x (baseline) | Full | All types |
+| Tablet | 0.9x | Standard | Most types |
+| Mobile | 0.8x | Reduced (1-2 properties) | Snappy only |
+| Watch | 0.6x | Minimal (1 property) | None |
+| TV/Kiosk | 1.3x | Full | All types |
+
+**Mobile rules**: prefer opacity + transform; touch feedback <100ms; reduce stagger budgets by 30%; avoid parallax
+**Desktop opportunities**: hover states, cursor tracking, multi-column stagger, spatial choreography
+
+## Accessibility
+
+### prefers-reduced-motion
+
+| Original Motion | Reduced Alternative |
+|----------------|-------------------|
+| Slide entrance | Opacity fade only |
+| Bounce/spring | Instant or simple ease-out |
+| Parallax | Static positioning |
+| Auto-playing | Paused, user-initiated |
+| Complex choreography | Single fade |
+| Continuous ambient | Static or subtle opacity pulse |
+
+Reduced motion means: remove spatial movement, keep opacity, remove spring easing, reduce duration 50%+, never auto-play loops.
+
+### Vestibular Triggers (avoid or provide alternatives)
+- Large-scale zoom, full-screen position transitions
+- Spinning elements >100px, parallax >2 layers, rapid direction changes
+
+### Cognitive Accessibility
+- Same interaction = same animation every time
+- Pause controls for animations >5 seconds
+- Don't convey critical info through motion alone
+
+## Performance Budgets
+
+| Tier | Properties | Max Elements |
+|------|-----------|-------------|
+| Optimal | transform, opacity | Unlimited (GPU) |
+| Good | + color, clip-path | 10-15 |
+| Acceptable | + width, height, margin | 5-8 |
+| Avoid | box-shadow, border-radius, filter | 1-3 |
+
+- Target 60fps (16.67ms/frame); animation logic <10ms/frame
+- will-change sparingly; keep animated elements <20 per viewport
+- Stagger reduces peak load vs simultaneous
+- Fallback: 30fps acceptable for ambient
+
+## Content Type Adaptation
+
+| Content Type | Personality | Duration | Motion Density |
+|-------------|-------------|----------|---------------|
+| Financial | Corporate/Premium | 250-500ms | Low |
+| Social media | Playful | 150-300ms | Medium |
+| Enterprise SaaS | Corporate | 200-400ms | Low |
+| Gaming | Energetic | 100-250ms | High |
+| Healthcare | Corporate/Calm | 300-600ms | Very low |
+| E-commerce | Varies | 200-400ms | Medium |
+| Editorial | Premium | 350-600ms | Low |
+| Children's apps | Playful | 150-300ms | High |
+
+## Responsive Motion
+
+| Container Width | Max Displacement | Duration |
+|----------------|-----------------|----------|
+| <400px | 20% of width | 0.8x |
+| 400-800px | 25% of width | 1.0x |
+| 800-1200px | 20% of width | 1.0x |
+| >1200px | 15% of width | 1.1x |
+
+- Small viewport: sequential, one element at a time
+- Medium: standard stagger, 2-3 columns
+- Large: full choreography, center-out stagger, parallax
+
+## Dark Mode
+- Reduce motion intensity 10-20% (bright on dark = more impact)
+- Subtler ambient motion; careful with opacity values
+- Avoid pure white flashes