Experience Engineering

Svelte-first patterns for interactive frontend experiences. Uses bun, not npm.

Before visual implementation: Aesthetic direction should be established. If unclear, invoke the artist agent to conduct discovery. The designer and architect need direction to work from.

Claims cite sources inline [Author Year] or in the Sources section.

Framework Decision

Tooling: Always bun, never npm.

Animation Decision Tree

Need animation?
├── Simple enter/exit → Svelte transition:fade, in:fly
├── State-driven values → Svelte spring(), tweened()
├── Complex timeline/sequence → GSAP timeline
├── Scroll-driven
│   ├── Simple triggers → Scrollama
│   └── Complex scrub/pin → GSAP ScrollTrigger + Lenis
├── 3D per-frame → Threlte useTask
└── 2D graphics → PixiJS ticker

Motion Library Landscape

What Claude doesn't know:

• •Lenis + ScrollTrigger is the Awwwards stack [Darkroom Engineering, Lusion SOTD]
• •GSAP Standard License prohibits "Competitive Products" — tools for visual animation building [GSAP 2025]
• •CSS animation-timeline: scroll() landed in Safari 26 [WebKit 2025]
• •View Transitions API became Baseline Oct 2025 [web.dev 2025]
• •linear() timing function enables CSS springs [Comeau 2024]

Performance Rules

GSAP cleanup is mandatory — memory leaks are common:

<script>
  import { onMount } from 'svelte';
  import gsap from 'gsap';

  onMount(() => {
    const tl = gsap.timeline();
    // ... animations
    return () => tl.kill(); // REQUIRED
  });
</script>

3D / WebGL Decision Tree

Need 3D?
├── Svelte app → Threlte 8
├── Vanilla/other → Three.js direct
├── Banner/tiny → Vanilla WebGL
└── Low-code → Spline (max 1-2 per page)

Need 2D graphics?
├── < 1,000 elements → SVG + GSAP
├── 1,000-10,000 → Canvas 2D
└── 10,000+ → PixiJS (WebGL)

See references/graphics-primitives.md for SVG, Canvas, PixiJS patterns.

Object Count Decision

Mobile Reality Check

Think 2015 mobile for draw call budget.

See references/3d-experiences.md for full patterns.

Scrollytelling Decision

What Claude doesn't know:

• •Locomotive Scroll breaks position: sticky [GitHub Issues #282, #30, #401]
• •scroll-snap-type: mandatory dangerous with tall content
• •Passive listeners are non-negotiable
• •NYT Snow Fall team "toned down" flashy transitions for reader focus [OpenNews 2012]

See references/scrollytelling.md for Sticky+Steps pattern, CSS scroll-driven examples, and award-winning implementations.

Typography

Use clamp() for fluid scaling (never pure vw — fails WCAG 1.4.4 [WCAG 2.1]).

See references/typography.md for fluid type patterns, system font stacks, and variable fonts.

Color Systems

OKLCH over HSL: Perceptually uniform, predictable contrast, P3 support [CSS Color Level 4 spec].

Dark mode: Deep grays (not pure black), off-white text, desaturated colors.

See references/color-systems.md for OKLCH syntax, dark mode patterns, and accessible palettes.

"Designed" vs "AI-Generated"

The gap: Technically correct but emotionally hollow. Visual equality ≠ mathematical equality.

Design System Tooling

See references/design-systems.md for design tokens (primitives → semantic → component slots) and production patterns.

Headless UI

Why headless: Behavior and accessibility are the hard parts. Styling is the easy part you want control over.

See references/headless-ui.md for Melt UI, Bits UI, shadcn-svelte patterns.

Component Patterns

See references/component-patterns.md for full patterns.

Cognitive Design

Attention & Load

Animation Psychology

Asymmetric timing: Enter slower than exit (300ms in, 200ms out).

Audience Targeting

What Claude gets wrong:

• •7±2 everywhere (it's recall, not recognition)
• •F-pattern as natural (it's a failure mode)
• •300ms for everything (different elements need different durations)
• •Western color meanings as universal

See references/cognitive-design.md for full research.

Microcopy & Interaction

Microcopy test: Can you remove a word without losing meaning? Remove it. ("copy" not "click to copy")

Focus states: Use :focus-visible (not :focus), add opacity: 0 transitions (not display: none).

Positioning: Absolute elements need containing blocks; test min AND max content lengths.

Pre-Ship Checklist

Animation: GSAP cleanup on unmount, SSR guards, prefers-reduced-motion, mobile test (iOS), passive listeners.

Design: Optical adjustments, personality, audience (age/culture).

Interaction: Minimal microcopy, visible focus states, edge-case content lengths.

Aesthetic Discovery (Non-Conformist by Design)

Categorical aesthetic agents converge output. Instead: help users discover and articulate their own visual voice.

The Collaboration Model

Discovering Your Aesthetic

The skill doesn't prescribe style. It helps users crystallize their own influences through a structured interview process (see assets/aesthetic-interview.md):

1. •Influences - Surface what has moved you (films, games, art, spaces)
2. •Qualities - Extract underlying patterns (density, temperature, precision, energy)
3. •Context - Ground in the specific project and constraints
4. •Synthesis - Build vocabulary and reference shorthand
5. •Crystallization - Optionally persist as personal skill using plugin-dev/extension-builder

Example influences (demonstration, not prescription):

• •Film: Blade Runner, Kubrick's geometric dread, Villeneuve's restrained atmosphere
• •Anime: Ghibli warmth → Death Note tension → Ghost in the Shell density
• •Games: BOTW's invitation vs Elden Ring's hostility (same openness, different emotional register)
• •Web: The Boat (SBS), Wix space exploration

Agents

Four collaborative agents - each with values-based construction and references to internalize:

The artist + human discover direction. The designer implements it. The architect structures it. The labcoat validates it.

References

Technical knowledge domains - agents internalize relevant references before working.

Fundamentals:

Svelte Ecosystem:

Visual Implementation:

Motion & Animation:

Graphics & 3D:

Components & UI:

Cognitive & Sources:

Assets: