• v0.3.0
  • MIT license
  • A Claude Code skill

Polish you can prove.

kymo opens your web app in a real browser and uses it the way a person would. It times every press, watches every frame, and points each slow or jumpy moment at the line of code behind it. Claude makes the fix. kymo measures again and keeps it only if it helped.

Install kymo Read the code
The recorderPress a button. kymo times it from your press to the first frame that shows a change.
recording

The first pulses are real measurements from the jank zoo. Yours join them as you press.

It catches what reading the code misses.

Each pair is a real kymo rule. Press Before to feel the problem and After to feel the fix. kymo flags the Before version on its own and stays quiet about the After.

MOT-09

Teleport

A panel that moves should travel, so the eye can follow it.

MOT-09

Pop-in

The toast lands here.

New surfaces should arrive, not appear from nowhere.

MOT-10

Blink-out

Your trial ends in 3 days. Add a card to keep this workspace.

Things that leave should exit, shorter than they entered.

STAB-02

Hover reflow

FollowMessage

Pointing at a control should never move its neighbours.

WAIT-01

Silent wait

Save profile

A slow request should say it is working, right away.

CRAFT-02

Invisible focus

Keyboard users need to see where focus is.

Measure, fix, verify, keep.

Claude does the part a measurement can't: writing the change. Everything else is measured, before and after.

  1. 1

    Measure

    kymo finds every control, field and route, then presses, types, tabs, hovers and scrolls through them in Chromium, on desktop and a phone.

    kymo
  2. 2

    Point

    Each finding names the CSS rule, event handler or script behind it, with a timeline of what happened.

    kymo
  3. 3

    Fix

    Claude makes the smallest change the rule asks for, on a branch, one finding at a time.

    Claude
  4. 4

    Verify

    kymo replays exactly the same interactions. Anything new, or anything slower, counts against the fix.

    kymo
  5. 5

    Keep or revert

    A fix that resolves its finding and breaks nothing is committed. Anything else is rolled back.

    kymo and git

The loop has its own test in the repo. A quick fix for a teleporting panel, transition: left, removes the jump but animates a layout property, so it is reverted. The transform version is kept.

Every finding points at a line.

The report shows what happened over time, where to look, and how to check the fix. This finding is real, from the jank zoo.

WarningFEEL-01slow-ack, on /

Slow feedback after a click

Clicking button "Like 0" took 619 ms to show any change, with no pressed state while held.

100 ms budgetscreen changed 619 ms after the releasepressrelease500
  • zoo.js:6:45its click handler
  • zoo.css:89.btn:hover
  • zoo.css:77.btn

Acknowledge the click in the next frame: a pressed style on :active, an optimistic update, or a pending state that appears immediately. Keep the slow work, but stop making the user wait to see that the click landed.

Replay it

Only the interactions you touched, so checking a fix takes seconds.

kymo audit --trace .kymo/trace.json --only slow-ack

Keep or revert

Exit 0 keeps the fix. Exit 3 means put it back.

kymo verify --before before.json --after after.json --target FEEL-01-5c130

Not a fix?

For a new feature or a redesign, check that nothing got worse instead.

kymo verify --before before.json --after after.json --change

22 rules, each with a source.

Severity follows the evidence. Standards and studies can raise errors and warnings. Taste only ever suggests.

Feedback and waiting

  • FEEL-01Slow feedback after a clickStudy
  • FEEL-03Dead clickPractitioner
  • FEEL-04Long frame blocks the pageStandard
  • FEEL-05Typing lagsStudy
  • WAIT-01No pending state on a slow requestPractitioner + Study
  • CRAFT-07Failure is silent or blankStandard (AA) + Practitioner

Motion

  • MOT-01Animation runs too longStandard + Practitioner
  • MOT-03Easing does not fit the motionStudy + Standard
  • MOT-06Movement ignores reduced motionStandard
  • MOT-08Animating layout propertiesStandard
  • MOT-09Teleport or pop with no transitionStudy (design paper) + proposal
  • MOT-10Disappears with no exitStandard + Practitioner
  • VIS-08Motion token sprawlPractitioner

Layout, focus and input

  • STAB-01Layout shifts while loading or scrollingStandard
  • STAB-02Hover shifts the layoutStandard + Practitioner
  • CRAFT-02Focus is invisible or hiddenStandard
  • CRAFT-03Dialog breaks keyboard focusStandard
  • CRAFT-04Target too small and crowdedStandard
  • CRAFT-05Hover content cannot be reached or dismissedStandard
  • CRAFT-08Validation complains too earlyStudy
  • CRAFT-09Touch target under 44 pxStandard

Look

  • AI-01Reads as a templatePractitioner

Tested on planted jank. Then on this page.

The numbers come from runs you can repeat with kymo eval and from the write-up of two real sites in the repo.

31 of 31

planted problems found in the jank zoo, with no false alarms on its 13 clean twins.

9 of 15

findings on a real app, Fallow, confirmed line by line in its source. The rest are listed with why.

5 to 0

findings on this page before launch. Three were the page's, two were kymo's own. All fixed and checked with kymo verify.

We ran kymo on this page before shipping it

Desktop and phone, 35 interactions, about two minutes. kymo verify kept every fix: 3 resolved, nothing new, nothing slower. Then came a motion pass: 61 scroll entrances per viewport, all under 500 ms and decelerating, and kymo verify --change found no regressions across all 33 interactions.

  • Dead click (FEEL-03). The Archive button in the focus demo did nothing when pressed. It now answers with "Archived".
  • Teleport (MOT-09). The Copy button jumped 25 px sideways when its label grew to "Selected". It now has a fixed width.
  • Small touch targets (CRAFT-09). On a phone, six controls were under 44 px, the smallest 48 by 24. The Copy buttons and footer links now reach 44.
  • kymo's own mistake (FEEL-01, FEEL-03). It clicked the skip link, which sits above the page until it has focus, so no mouse can reach it. kymo now leaves off-page controls to its keyboard pass.

Two minutes to the first report.

kymo runs on Node 20 or newer with Playwright's Chromium. It is not on npm yet, so it installs from GitHub.

Run it on your app

Start your dev server, then point kymo at it.

terminal
# once
git clone https://github.com/shourya0mehta/kymo
cd kymo && npm install
npx playwright install chromium

# every time
node dist/cli.js audit http://localhost:5173 \
  --viewports desktop,mobile
open .kymo/report.html

Hand it to Claude

The skill walks Claude through the loop: baseline, one fix at a time, verify, commit or revert.

terminal
cp -r skills/kymo ~/.claude/skills/

# then, in Claude Code
Polish my app with kymo.

Gate pull requests

Fails only on findings your saved baseline doesn't already have, and annotates the lines in the diff.

.github/workflows/feel.yml
- uses: shourya0mehta/kymo@main
  with:
    url: http://localhost:4173
    viewports: desktop,mobile