neonwatty/css-animation

CSS Animation Walkthrough Skill

You create polished, self-contained HTML/CSS animations that mimic real app features. These are used for walkthroughs, onboarding demos, and marketing. They are NOT GIFs — they are resolution-independent, tiny file size, and easy to iterate on.

Two Animation Styles

1. Feature Demo — Before → Action → After. Shows a single feature transformation (e.g., clicking "Optimize" and watching seats rearrange).
2. Carousel — Multi-view. Cycles through several app screens with cross-fade transitions (e.g., Dashboard → Guest List → Canvas → RSVPs).

Determine which style the user needs during the Interview phase.

Phases

Phase 1: Research → Phase 2: Interview → Phase 3: Generate → Phase 4: Review Loop

---

Phase 1: Research

Before generating anything, deeply understand the target app's visual system by navigating it in Chrome.

Prerequisites

• Claude-in-Chrome MCP tools must be available
• The target app must be accessible in a browser (running locally or deployed)

Step 1: Set up Chrome

1. Call tabs_context_mcp to check existing tabs
2. Create a new dedicated tab: tabs_create_mcp
3. Store this tab ID — use it exclusively for all subsequent browser operations

Step 2: Navigate and explore

1. Navigate to the target app URL
2. If auth is required, ask the user to log in manually, then resume
3. If targeting mobile or both: Resize the browser to mobile viewport (390×844px) using resize_window before navigating to the feature. This ensures you research the app's actual mobile layout, not the desktop version squeezed down. If targeting both, research desktop first at full size, then resize to mobile and re-extract the mobile layout.
4. Navigate to the specific feature/page to animate
5. Take exploratory screenshots to understand the layout

Step 3: Extract design language

Use read_page, find, and javascript_tool to extract:

• Colors: background, surface, border, accent/primary, text, text-dim

  // Example: extract computed styles
  const body = getComputedStyle(document.body);
  JSON.stringify({
    bg: body.backgroundColor,
    color: body.color,
    fontFamily: body.fontFamily
  })
  

• Fonts: heading font-family, body font-family, font weights used
• Spacing: padding, margins, border-radius values
• Component styles: buttons, cards, badges, avatars, sidebar panels

Record these as CSS custom properties (e.g., --bg: #0f0f0f).

Step 4: Map layout geometry

For the specific feature to animate:

• Container dimensions: width, height, position of major containers
• Element positions: absolute coordinates of key elements
• Relationships: which elements are inside which, z-index stacking
• Circular elements: center point and radius
• Rectangular elements: origin (top-left), width, height

Use javascript_tool to extract exact positions:

const el = document.querySelector('.selector');
const rect = el.getBoundingClientRect();
`${rect.left}, ${rect.top}, ${rect.width}, ${rect.height}`

Step 5: Screenshot key states

Take screenshots of:

• The feature in its default/initial state
• Any intermediate states (hover, loading, processing)
• The final/result state after the feature action completes

These screenshots serve as visual reference for generation.

---

Phase 2: Interview

Ask the user focused questions to define what to animate. Use AskUserQuestion for each — one at a time, with multiple choice options.

Question 1: Animation style

"What style of animation should this be?"
- Feature Demo (Recommended): Before → Action → After. Shows one feature transformation.
- Carousel: Cycles through multiple app views with cross-fade transitions.

Question 2: Target size

"What size should the animation target?"
- Desktop only (960×620px) — for landing pages, marketing, desktop walkthroughs
- Mobile only (360×640px) — for in-app tour tooltips, mobile onboarding
- Both — generates two files from the same brief, one per viewport

When Mobile or Both is selected:

• The mobile variant uses a 360×640px stage (portrait, matching common phone viewports)
• Simplify the layout: fewer elements (8–12 max), larger relative sizing, no sidebars
• Drop elements that don't translate to small screens (wide toolbars, multi-column layouts)
• Prefer vertical stacking over horizontal layouts
• Increase font sizes relative to stage (minimum 11px body, 14px headings)
• File naming: <app>-<feature>.html (desktop), <app>-<feature>-mobile.html (mobile)

Question 3: Feature identification

"What specific feature or flow should the animation show?"
- [Options based on research phase findings]
- Other (user describes)

Question 4: The payoff moment

"What's the key moment — the visual 'wow' of this animation?"
- [Options relevant to the chosen feature]
- Other

Question 5: Emphasis

"Is there anything specific to emphasize or avoid showing?"
- Show everything as-is
- Emphasize specific elements (user specifies)
- Hide certain elements (user specifies)

Question 6: Output location

"Where should I save the animation files?"
- Current directory: [show cwd path]
- Desktop
- Other (user specifies path)

Stop after 3-6 questions — when you have enough context to generate. Don't over-interview.

---

Phase 3: Generate

This phase produces two artifacts: a brief (markdown) and an HTML animation file.

3a: Generate the Brief

Write a structured markdown document capturing everything needed to generate or regenerate the animation. Save as <app>-<feature>-brief.md in the user's chosen directory.

Brief format:

---
app: <App Name>
feature: <Feature Name>
style: feature-demo | carousel
target: desktop | mobile | both
output_file: <app>-<feature>.html
output_file_mobile: <app>-<feature>-mobile.html  # only when target is mobile or both
---

# Design Language
- Background: <hex>
- Surface: <hex>
- Border: <hex>
- Accent: <hex> (<name>)
- Text: <hex>
- Text dim: <hex>
- Heading font: <font> (serif/sans-serif)
- Body font: <font> (sans-serif)
- Border radius: <N>px
- Additional colors: <name>: <hex> (for groups, statuses, categories, etc.)

# Layout (Desktop)
- Stage: 960x620px
- [Container hierarchy description]
- [Element positions with exact pixel coordinates]
- [Circular elements: center point (x,y), radius R]
- [Rectangular containers: origin (x,y), width, height]
- [Item sizing: WxH px]

# Layout (Mobile)  <!-- only when target is mobile or both -->
- Stage: 360x640px
- [Simplified container hierarchy — no sidebars, single-column]
- [Reduced element count: 8–12 elements max]
- [Element positions recalculated for smaller stage]
- [Larger relative element sizing: e.g., 36x36px avatars instead of 30x30px]
- [Elements or sections omitted from desktop version and why]

# Animation Plan

## Style: Before → Action → After
(or: ## Style: Carousel with N scenes)

### Before State
- [Element positions, visual state, text content]
- [For circular layouts: N items, angular spacing, starting angle]

### Action (feature-demo only)
- [User action: cursor movement, button click]
- [Intermediate states: loading, processing]

### After State
- [New positions, trigonometrically calculated for circles]
- [Visual changes: colors, borders, labels, badges]
- [Text content changes]

### Scene N (carousel only)
- [What's visible in this scene]
- [Entry animations for elements]
- [Duration and transition to next scene]

### Timing
- Total loop: <N>s
- [Phase-by-phase durations]
- Easing: cubic-bezier(0.34, 1.56, 0.64, 1) for spring motion
- Easing: ease-in-out for fades

Show the brief to the user before generating HTML:

"Does this brief capture the animation correctly?"
- Yes, generate the animation
- Needs adjustments (user specifies)

Iterate on the brief until the user approves it, then proceed to 3b.

3b: Generate the HTML/CSS Animation

Using the brief as your spec, generate a self-contained HTML file. Save as <app>-<feature>.html in the user's chosen directory.

File Structure

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title><App> – <Feature> Animation</title>
<style>
  @import url('https://fonts.googleapis.com/css2?family=...');
  /* ALL CSS here — no external stylesheets */
</style>
</head>
<body>
  <div class="stage" id="stage">
    <!-- All visual elements -->
  </div>
  <script>
    // Minimal JS: setTimeout loop controller + class toggling ONLY
  </script>
</body>
</html>

Technical Rules (MANDATORY)

1. Trigonometric positioning for circular layouts.

NEVER eyeball positions on circles. ALWAYS calculate:

left = centerX + R * cos(angle_radians) - (elementWidth / 2)
top  = centerY + R * sin(angle_radians) - (elementHeight / 2)

Where:

• R = visible radius of container + (elementSize / 2), so the element's inner edge touches the container perimeter
• For N items evenly spaced: angle_i = startAngle + i * (2 * PI / N), starting from -PI/2 (top center)
• Convert degrees to radians: radians = degrees * PI / 180

Example for 7 items on a circle with center (140, 160) and R=95, items are 30x30px:

Item 0: angle = -90°  → left = 140 + 95*cos(-90°) - 15 = 125,  top = 160 + 95*sin(-90°) - 15 = 50
Item 1: angle = -38.6° → left = 140 + 95*cos(-38.6°) - 15 = 199, top = 160 + 95*sin(-38.6°) - 15 = 86
...etc for all N items

2. Rectangular edge positioning.

For items along rectangle edges, distribute evenly:

• Top/bottom edges: vary X at equal intervals, Y at edge ± (elementHeight / 2)
• X spacing: containerLeft + containerWidth * (i + 1) / (numItemsOnEdge + 1)
• Left/right edges: same logic, varying Y

3. Self-contained HTML. No external dependencies except Google Fonts @import. All CSS in <style>, all JS in <script>. Zero build step.

4. CSS transitions for element movement.

.element {
  position: absolute;
  transition: left 1.2s cubic-bezier(0.34, 1.56, 0.64, 1),
              top 1.2s cubic-bezier(0.34, 1.56, 0.64, 1);
}

5. JS only for loop control and class toggling.

CRITICAL: Never use inline styles (element.style.opacity = '1') in JS reset/update functions. Inline styles override CSS class rules and cause state bugs (e.g., a "hidden" element that stays visible because an inline style trumps the CSS class). Use class toggling exclusively.

const stage = document.getElementById('stage');
function runCycle() {
  // Reset — class toggling only, no inline styles
  stage.classList.remove('clicking', 'processing', 'optimized', 'complete');
  // Reset text content to before-state values

  setTimeout(() => stage.classList.add('clicking'), 500);
  setTimeout(() => {
    stage.classList.remove('clicking');
    stage.classList.add('processing');
  }, 900);
  setTimeout(() => {
    stage.classList.remove('processing');
    stage.classList.add('optimized');
    // Update text content to after-state values
  }, 1500);
  setTimeout(() => stage.classList.add('complete'), 3000);
  setTimeout(runCycle, 6000); // Loop
}
setTimeout(runCycle, 300);

Default to fast timing. Users almost always want the animation faster than your first instinct. Start with snappy defaults:

• Before state hold: 0.3–0.5s (just long enough to register)
• Stagger between elements: 0.3–0.5s
• After state hold: 2–3s
• Total loop: 5–8s
• Timing will be tuned iteratively in Phase 4 — start fast and slow down only if asked.

6. CSS @keyframes for non-interactive animations — cursor movement, badge entrance, spinner rotation. Use the animation property on the relevant elements.

7. Stagger transitions with transition-delay on individual elements (0.04–0.08s apart) for sequential movement that feels natural.

8. Stage dimensions by target.

• Desktop: 960×620px, border-radius: 12px
• Mobile: 360×640px, border-radius: 16px (portrait orientation)
• Always match the app's design language (dark/light theme, colors). Adjust proportions based on the app's actual layout at that viewport.

9. Hidden elements must use visibility: hidden alongside opacity: 0. On dark backgrounds, JPEG screenshot compression creates visible artifacts for opacity-0 elements — they appear as faint ghosts. Always pair:

.element-hidden {
  opacity: 0;
  visibility: hidden;
  transition: opacity 0.5s ease-out, visibility 0s 0.5s; /* visibility delays on hide */
}
.element-hidden.visible {
  opacity: 1;
  visibility: visible;
  transition: opacity 0.5s ease-out, visibility 0s 0s; /* visibility instant on show */
}

For elements that should be completely removed from flow when hidden (like placeholder text), use display: none via a parent class toggle:

.stage.active .placeholder { display: none; }

10. Verify content fits the stage. After generating, inject JS to check that all content fits within the stage bounds before entering the review loop:

var content = document.querySelector('.content');
var stage = document.getElementById('stage');
JSON.stringify({ stageH: stage.offsetHeight, contentH: content.scrollHeight, fits: content.scrollHeight <= stage.offsetHeight - content.offsetTop })

If content overflows, compact spacing (reduce padding, margins, font sizes) or increase stage height before proceeding to review. Don't waste review cycles on overflow bugs.

Carousel-Specific Rules

• Each scene uses opacity keyframes to show/hide (fade in → hold → fade out)
• Child elements within each scene use animation-delay for staggered entry
• Total loop duration = sum of all scene durations + transition gaps
• Use @keyframes with percentage-based timing for scene visibility
• Each scene is a container div with position: absolute; inset: 0;

Feature-Demo-Specific Rules

• Default CSS defines "before" positions for all elements
• After-state positions go under .stage.optimized .element { left: ...; top: ...; }
• JS class toggling (stage.classList.add('optimized')) triggers CSS transitions
• Include: animated cursor (CSS keyframes), click flash effect, processing spinner overlay
• Include: completion badge that animates in after the transformation
• Include: text content updates (counters, labels) via JS in the setTimeout chain

Mobile-Specific Rules

When generating mobile animations (360×640px stage):

• Simplify aggressively. Show the essence of the feature, not every UI element. A desktop animation might show a full toolbar + sidebar + canvas; the mobile version shows just the core interaction.
• 8–12 elements max. Small stages get cluttered fast. Cut decorative elements first, then secondary UI.
• No animated cursor. Mobile is touch — replace cursor animations with a tap indicator (a brief circle pulse at the tap point).
• Larger relative sizing. Elements should be proportionally larger relative to the stage. If desktop uses 30×30px avatars on a 960px stage (3.1%), mobile should use 36×36px on 360px (10%).
• Single-column layouts. No sidebars. Stack content vertically.
• Bottom-anchored actions. Buttons and CTAs at the bottom of the stage, matching mobile app conventions.
• Skip nav bars if tight on space. The animation doesn't need to recreate the full app chrome — focus on the feature area.

When generating both variants from a single brief:

• Generate the desktop version first (<app>-<feature>.html)
• Then generate the mobile version (<app>-<feature>-mobile.html) as a separate file
• The mobile version is a purposeful redesign for the smaller stage, not a scaled-down copy
• Both files share the same design language (colors, fonts) but have independent layouts
• Review each variant independently in Phase 4

---

Phase 4: Review Loop

This is the core quality mechanism. After generating the animation HTML, enter an iterative review loop until the user approves.

Step 1: Serve the animation locally

1. Check if a Python HTTP server is already running:

   lsof -i :8765
   

2. If not running, start one in the output directory:

   python3 -m http.server 8765 --directory <output-directory> &
   

3. Use the Chrome tab from Phase 1 (or create a new one)
4. If reviewing a mobile animation: Resize the browser to mobile viewport (390×844px) using resize_window before navigating. This ensures you see the animation at the intended scale, not stretched across a desktop window.
5. Navigate to: http://localhost:8765/<filename>.html?v=<timestamp>

ALWAYS append ?v=<Date.now()> to bust the cache after every edit.

When reviewing both variants: Review the desktop animation first at full browser size, then resize to mobile and review the mobile variant. Keep reviews separate — don't mix feedback between variants.

Step 2: Freeze and inspect each key state

Inject JavaScript to stop the animation and set a specific state:

// Stop ALL pending timers
var id = window.setTimeout(function(){}, 0);
while (id--) { window.clearTimeout(id); }

// Reset stage
var stage = document.getElementById('stage');
stage.classList.remove('clicking', 'processing', 'optimized', 'complete');

// Hide cursor
var cursor = document.querySelector('.cursor');
if (cursor) { cursor.style.animation = 'none'; cursor.style.opacity = '0'; }

// Hide badges/overlays
var badge = document.querySelector('.optimized-badge');
if (badge) { badge.style.display = 'none'; }

Then set the target state:

• BEFORE state: leave all classes removed (default CSS positions apply)
• AFTER state: stage.classList.add('optimized'); and update text content
• COMPLETE state: stage.classList.add('optimized', 'complete'); and show badge

Take a screenshot after setting each state. Present to the user.

Key states to inspect

Feature Demo:

1. Before state — Are all elements visible? Positioned correctly on container perimeters? Colors match the app?
2. After state — Are elements on perimeters? Correct grouping? Labels and badges positioned correctly?
3. Badge/overlay — Does the completion badge obscure important elements?

Carousel:

1. Each scene — Layout matches the app? Elements properly styled? Text content correct?

Step 3: Collect feedback

For EACH inspected state, use AskUserQuestion:

"How does the [BEFORE / AFTER / Scene N] state look?"
Options:
- Looks good
- Element positions are off (not on perimeters, wrong placement)
- Colors or styling need adjustment
- Layout or spacing needs changes
- Text content is wrong
- [Other]

Enable multiSelect: true if multiple issues are likely.

Step 4: Fix and re-inspect

When the user reports an issue:

1. Read the current HTML to understand the CSS structure
2. Identify the root cause:
   • Positions off perimeter → recalculate with trig formulas
   • Colors wrong → update CSS custom properties
   • Layout shifted → check container positions and absolute coordinates
   • Text wrong → update HTML content
   • Badge obscuring elements → adjust badge position or z-index
3. Apply the fix using the Edit tool
4. Update the brief if the fix reveals a spec error
5. Re-serve with new cache-buster: ?v=<new-timestamp>
6. Re-freeze at the affected state using the same JS injection
7. Re-screenshot and ask the user again

Repeat Steps 3-4 until the user says "Looks good" for every state.

Step 5: Full playthrough and timing tuning

Once ALL frozen states are individually approved:

1. Reload the page (with cache-buster) to restart the animation loop
2. Let the user watch the full animation — do NOT freeze it
3. Ask:

   "How does the full animation look in motion?"
   Options:
   - Approved — looks great!
   - Timing needs adjustment
   - Transitions need work (easing feels wrong, stagger off)
   - Something else needs fixing
   

4. If Approved → done. Inform the user where files are saved (brief + HTML).
5. If Timing needs adjustment → enter the Timing Tuning Loop (below).
6. If other feedback → apply it, re-serve, re-ask.

Timing Tuning Loop

Timing is always iterative. Expect 2-4 rounds of timing adjustment — this is normal, not a sign of a bad first attempt. The goal is to converge quickly by asking specific questions.

When the user says timing needs adjustment, ask specifically which phases:

"What about the timing needs adjustment?"
Options (multiSelect: true):
- Initial state too long (before the action starts)
- Initial state too short (need more time to see the 'before')
- Action/stagger too slow (elements appear too slowly)
- Action/stagger too fast (can't follow what's happening)
- Final hold too long (loop feels sluggish)
- Final hold too short (not enough time to absorb the result)

Apply the changes, reload with cache-buster, and re-ask:

"How does the updated timing feel?"
Options:
- Approved — looks great!
- Still needs adjustment

If "Still needs adjustment" → ask the specific phase question again. Repeat until approved.

Timing tuning tips:

• Adjust in meaningful increments (halve or double, don't tweak by 50ms)
• If the user says "faster" without specifics, shorten the before-state hold and final hold first — the action stagger is usually fine
• Total loop under 6s feels snappy; over 12s feels sluggish
• The before-state rarely needs more than 0.5s — the viewer understands the "empty" state immediately

Review Loop Principle

Inspect static states first, then evaluate motion.

Positioning and layout bugs are much easier to see in frozen frames. Timing and easing bugs only appear during playback. Fix the visual bugs first, then tune the motion.

---

Error Handling

• App requires login: Stop and ask the user to log in manually in the Chrome tab. Resume research after they confirm.
• Chrome tools unavailable: Inform the user that Claude-in-Chrome is required for Phase 1 (Research). Offer to skip to Interview if they can describe the app verbally.
• HTTP server port in use: Try ports 8766, 8767, etc. Check with lsof -i :<port>.
• Browser cache shows stale version: Always cache-bust with ?v=<timestamp>. If still stale, try a new Chrome tab.
• User reports an issue you can't reproduce: Ask the user to describe it in detail. Use read_page or javascript_tool to inspect the live DOM and computed styles.
• Circular positioning looks wrong: Double-check the formula. Common mistakes:
  • Forgetting to convert degrees to radians
  • Wrong center point (remember: center = origin + half-dimension)
  • Wrong radius (should be container visible radius + half element size)
  • Forgetting to subtract half element size from the calculated position

Tips for High-Quality Animations

• Match the app's personality. Dark theme apps get dark animations. Playful apps get bouncy easing. Corporate apps get subtle transitions.
• Less is more. 14-20 moving elements is plenty. Don't try to recreate every pixel of the real app.
• Spring easing sells it. cubic-bezier(0.34, 1.56, 0.64, 1) makes elements feel physical and alive.
• Stagger everything. Sequential transition-delay (0.04–0.08s per element) looks far better than simultaneous movement.
• Hold the payoff — but not too long. After the transformation, hold the final state for 2-3 seconds. Longer than that and the loop feels sluggish. The viewer absorbs the result faster than you think.
• Labels and badges appear last. They narrate the result — let the visual change happen first.
• Design language is king. Getting the colors, fonts, and border-radius right makes a rough layout still feel "like the app." Getting the layout perfect with wrong colors feels off.