agentleFS
neonwattyneonwatty/css-animation-skill/SKILL.md

css-animation

Skill18 starsChanged 9 months agoMITView on GitHub

Generates self-contained HTML/CSS animations of app features for walkthroughs, demos, and onboarding. Researches the target app via Chrome, interviews the user, generates a structured brief and animation HTML file, then enters an iterative freeze-inspect-feedback review loop until the user approves. Use when the user says "css animation", "animate this feature", "create a css walkthrough", "animation walkthrough", or wants to create a CSS-based visual demo of an app feature.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. keny4nn/claude-skills★ 0100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

Show its rules and text

We split this skill into the rules it gives an agent

41 rules. About 0 are common, 31 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈31

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 27
  2. Very specific:

    Call tabs_context_mcp to check existing tabs

    line 34
  3. Very specific:

    Create a new dedicated tab: tabs_create_mcp

    line 35
  4. Distinctive:

    If auth is required, ask the user to log in manually, then resume

    line 40
  5. Very specific:

    Use read_page, find, and javascript_tool to extract:

    line 46
  6. Very specific:

    Use javascript_tool to extract exact positions:

    line 73
  7. Distinctive:

    Ask the user focused questions to define what to animate.

    line 92
  8. Distinctive:

    When Mobile or Both is selected:

    line 109
  9. Distinctive:

    Prefer vertical stacking over horizontal layouts

    line 113
  10. Distinctive:

    Stop after 3-6 questions — when you have enough context to generate.

    line 147
  11. Very specific:

    Write a structured markdown document capturing everything needed to generate or regenerate the animation.

    line 157
  12. Distinctive:

    Show the brief to the user: before generating HTML:

    line 229
  13. Distinctive:

    NEVER eyeball positions on circles.

    line 271
  14. Very specific:

    3. Self-contained HTML: No external dependencies except Google Fonts @import.

    line 295
  15. Distinctive:

    Before state hold: 0.3–0.5s (just long enough to register)

    line 334
  16. Distinctive:

    After state hold: 2–3s

    line 336
  17. Distinctive:

    Always match the app's design language (dark/light theme, colors).

    line 347
  18. Distinctive:

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

    line 367
  19. Distinctive:

    If content overflows, compact spacing (reduce padding, margins, font sizes) or increase stage height before proceeding to review.

    line 373
  20. Very specific:

    Use @keyframes with percentage-based timing for scene visibility

    line 380
  21. Distinctive:

    Default CSS defines "before" positions for all elements

    line 385
  22. Very specific:

    After-state positions go under .stage.optimized .element { left: ....

    line 386
  23. Distinctive:

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

    line 394
  24. Distinctive:

    Single-column layouts: No sidebars. Stack content vertically.

    line 400
  25. Distinctive:

    When generating both variants from a single brief:

    line 404
  26. Distinctive:

    Check if a Python HTTP server is already running:

    line 419
  27. Distinctive:

    If not running, start one in the output directory:

    line 423
  28. Distinctive:

    Use the Chrome tab from Phase 1 (or create a new one)

    line 427
  29. Distinctive:

    BEFORE state: leave all classes removed (default CSS positions apply)

    line 458
  30. Distinctive:

    When the user reports an issue:

    line 493
  31. Distinctive:

    Update the brief: if the fix reveals a spec error

    line 503
  32. Distinctive:

    If Approved → done. Inform the user where files are saved (brief + HTML).

    line 525
  33. Distinctive:

    If Timing needs adjustment → enter the Timing Tuning Loop (below).

    line 526
  34. Distinctive:

    If other feedback → apply it, re-serve, re-ask.

    line 527
  35. Distinctive:

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

    line 533
  36. Distinctive:

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

    line 555
  37. Distinctive:

    If the user says "faster" without specifics, shorten the before-state hold and final hold first — the action stagger is usually fine

    line 559
  38. Distinctive:

    App requires login: Stop and ask the user to log in manually in the Chrome tab.

    line 573
  39. Very specific:

    Browser cache shows stale version: Always cache-bust with ?v=<timestamp>.

    line 576
  40. Very specific:

    User reports an issue you can't reproduce: Ask the user to describe it in detail.

    line 577
  41. Distinctive:

    Hold the payoff — but not too long: After the transformation, hold the final state for 2-3 seconds.

    line 590

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.