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

Feature Demo — Before → Action → After. Shows a single feature transformation (e.g., clicking "Optimize" and watching seats rearrange).
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

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

Step 2: Navigate and explore

Navigate to the target app URL
If auth is required, ask the user to log in manually, then resume
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.
Navigate to the specific feature/page to animate
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.

css-animation