Xin An中文

An Atomic CSS System for Icon Motion

Date
2026.05.31

An icon motion system made up of a pure CSS motion utility library, an editor designers use to build motion, and a Skill that generates motion in batches. It is used on the Tencent Cloud website and in the console sidebar, so designers and AI can make more than a thousand icons with the same motion vocabulary.

Replay

Background

In 2026 Tencent Cloud refreshed the look of its platform, including the console home page and the console framework. The main part of the framework is the left navigation bar, and one part of the refresh was redrawing the navigation icons and adding hover motion to them.

The navigation bar covers about 200 cloud products and more than 2,000 icons. Making them one at a time in After Effects, Lottie, or Rive would mean designing and exporting each icon separately, which is expensive and makes it hard to keep timing and amplitude consistent when several people are working on them.

The system therefore had to meet three conditions: AI could generate motion in batches, every icon followed the same constraints, and designers could check and adjust each icon individually. AI could assist with generation, but it needed a stable motion system underneath it.

Technical Approach

I compared three common ways of delivering icon motion:

SolutionProsCons
GIFGood compatibility, WYSIWYGLarge file size, fixed resolution, difficult dark-mode adaptation, no interactive control of playback
LottieHighly expressive, supports complex path animationEach icon needs a JSON file and a player of about 60KB, hard for AI to generate or edit directly
CSSVector lossless, small footprint, no JS player, inherits colorHard to express complex path morphing

Lottie is the most expressive, but navigation icon motion usually needs only translation, scaling, rotation, fading, and stroke drawing, all of which CSS covers. GIF cannot change color with dark mode and blurs easily on high-density screens. CSS animation is written directly on the SVG, the icon's color still inherits through currentColor, and it is one of the formats AI knows best, so I chose CSS.

Motion Vocabulary

Atomization

Choosing CSS did not solve the volume problem. Writing keyframes (@keyframes) for 2,000 icons one by one would be no less work, and AI starting from scratch each time would struggle to stay consistent.

Tailwind CSS provides another model. It divides styles into small units such as p-4 and text-sm, and interfaces are composed from those units. Motion can be divided the same way: “scale up from 75% to original size” and “rotate 12° and back” each become a class name, and an icon's motion is a combination of a few class names. To a designer, a class name is the equivalent of one animation property. For AI, selecting and combining from a limited vocabulary is far more stable than writing keyframes from scratch.

I used the open-source library tailwindcss-motion as the starting point. It already has a complete motion taxonomy and set of preset values, but its Tailwind v3 JS plugin architecture cannot be used directly in Tailwind v4. I used Claude Code to rewrite it with Tailwind v4 @utility rules and CSS variables, then trimmed and extended it for SVG icons. The rewritten library is named tailwindcss-icon-motion.

Class Name Rules

Each class name has three parts, type, phase, and value: motion-{type}-{phase}-{value}. Take a bell as an example:

<svg data-motion-icon viewBox="0 0 24 24" fill="none" stroke="currentColor">
  <path class="motion-shake-loop-12 origin-top" d="…" />
  <path class="motion-draw-in-100 motion-delay-75" pathLength="1" d="…" />
</svg>

The first class name makes the bell body swing 12° around its top. The second draws the clapper's line from nothing, starting after a 75ms delay. The three phases mean:

  • in (enter): goes from the given value back to the element's original state, and plays once.
  • out (exit): goes from the original state to the given value, and plays once.
  • loop (round trip): goes from the original state to the given value and back. It plays once by default and can be set to loop infinitely when needed.

A - before a class name reverses the direction: -motion-draw-in-100, for example, draws from the other end of the path. The supported effects are:

EffectEnterExitLoopNotes
TranslateMove in from top/bottom/left/rightMove out to top/bottom/left/rightFloat up/down/left/rightSupports reverse
ScaleAppear from small to largeDisappear from large to smallHeartbeat, breathingSupports single-axis
RotateRotate inRotate outRotate back and forthSupports reverse
ShakeShake inShake outDamped swingSupports reverse
FadeFade inFade outBlink—
Stroke DrawLine drawing inLine erasingLine draws and returnsSupports reverse

Duration, delay, loop count, easing curve, and transform origin are also class names, added to the same class. There are 22 easing curves, covering standard curves, back, spring, and bounce. When preset values aren't enough, you can write an arbitrary value, such as motion-rotate-in-[30deg].

Composition

Class names must not override one another when combined. This is the core technical problem atomization has to solve.

In CSS, playing two animations on one element requires writing both in the same animation declaration:

.element {
  animation:
    scale-in 0.3s,
    rotate-in 0.3s;
}

If the two animations are split into two class names, the later class name's animation replaces the earlier one as a whole, and only one animation takes effect.

tailwindcss-motion solves this with animation slots, a design I kept. All class names share the same animation declaration, which reserves one position for each property in each phase, with a default value of none. Each class name writes an animation only to its own position and leaves the others unchanged:

@utility motion-translate-x-in-* {
  --motion-translate-in-animation: motion-translate-in 300ms ease both;
  animation:
    var(--motion-scale-in-animation), var(--motion-translate-in-animation),
    var(--motion-rotate-in-animation),
    /* ...slots for the remaining properties and phases, none when unused */;
}

Each phase has five slots: scale, translate, rotate, opacity, and stroke draw. So motion-scale-in-75 motion-translate-x-loop-25 can take effect at the same time. Shake and rotate share a slot, so an element can use only one of the two.

The loop slots use animation-composition: accumulate, which adds them on top of the result of the entrance animation. An element can move in first, then continue floating from its current position.

translate-x
translate-y
scale
scale-x
scale-y
rotate
shake
opacity
draw
translate-x translate-y
translate-x opacity
translate-y opacity
scale opacity
rotate scale
rotate opacity
shake scale
draw scale
draw opacity

Single atomic animations above, pairwise combinations below; move the pointer over a card to play it

Adjustments for Icons

tailwindcss-motion targets general web elements. To suit SVG icons, I made the following changes:

  • Added stroke animation. Line drawing is done through stroke-dashoffset and requires the path to set pathLength="1", which normalizes a path of any length to 1. stroke-dasharray is set to 1.1 rather than 1, with a starting offset of 0.05, because when the value exactly equals the path length, the browser's subpixel rendering can flicker at the endpoints.
  • Added shake animation. The keyframes have a built-in, stepwise decaying swing, with amplitudes of -0.5, 0.25, and -0.1 times the original value in turn, close to the damped swing of a bell or a hanging ornament.
  • Fixed the SVG transform origin. Elements inside an SVG rotate and scale around the top-left corner of the canvas by default, while HTML elements use their own center. With data-motion-icon on the <svg>, inner elements all use their own center. Radially symmetric icons such as gears and fans can use motion-origin-viewbox to pivot around the center of the canvas instead.
  • Removed more than 30 preset combinations (such as motion-preset-fade). AI does the composing based on the icon's semantics, and presets would only limit its choices. I also removed filter, text-color, and background-color animations, which icon motion doesn't need.
  • Reduced the default duration from 700ms to 300ms, better suited to micro-interactions such as hover. Loop animations play once by default rather than infinitely, because navigation icon motion only needs to finish once on hover.
  • Added spring easing based on linear(), with curves from kvin.me/css-springs.
  • All keyframes are wrapped in @media (prefers-reduced-motion: no-preference), so animations don't run when users turn on “Reduce Motion” in their system settings.

Trigger Methods

By default, motion plays once when the icon appears. The navigation bar needs it to play on interaction, so a trigger mechanism is required. My principle was not to use JS for anything CSS can do: the browser handles pausing and playing animations without triggering React re-renders, so there is no extra runtime cost even with more than 2,000 icons present at once.

Set data-motion-trigger on a container, and animations inside it are completely suppressed by animation-name: none !important until triggered. Three triggers are currently supported:

TriggerPlays whenResets whenNeeds JS
hoverPointer is over the containerPointer leavesNo
stateContainer is in the open stateContainer closesNo
clickOn every clickStays on the last frameYes

hover is used for navigation items: the trigger sits on the whole list item, so hovering anywhere on the item plays the icon inside it.

state is used for controls with an on/off state, such as sidebar toggles, menus, and favorite buttons. “Open” is determined by attributes the component already sets for accessibility, such as aria-expanded="true" and aria-pressed="true", or data-state="open" set by component libraries such as Radix. Developers don't need to write any extra state logic for motion.

click is the only trigger that needs JS, because CSS can't restart an animation on every click. For this I wrote a script of about 60 lines that listens for clicks on document, finds the clicked container, and replays the icon animations inside it. It depends on no framework and also works for elements added dynamically later.

Controls with an on/off state also need two playback modifiers:

  • motion-hold-start: before the trigger, holds the entrance animation on its first frame. The rectangle representing the panel in a sidebar icon, for example, stays collapsed in the closed state.
  • motion-leave-reverse: when the trigger ends, plays smoothly backward from the current frame instead of jumping back to the original state. A keyframe animation canceled midway can't play in reverse, so this modifier replaces the keyframe animation with a CSS transition, and the browser interpolates back from the current position.
<button data-motion-trigger="state" aria-expanded="false">
  <svg data-motion-icon viewBox="0 0 24 24" fill="none" stroke="currentColor">
    <rect class="motion-scale-x-in-0 origin-left motion-hold-start motion-leave-reverse" … />
    <rect x="3" y="3" width="18" height="18" rx="2" />
    <path d="M9 3v18" />
    <path class="motion-rotate-in-180 motion-hold-start motion-leave-reverse" d="m16 15-3-3 3-3" />
  </svg>
</button>

When this sidebar toggle expands, the panel opens from the left and the arrow flips 180°. When it collapses, both return the way they came.

Workflow

With the motion vocabulary settled, the remaining problem was letting designers use it efficiently. I provided two entry points that use the same class names: the Studio editor for fine-tuning icons one at a time, and a Skill for batch generation.

Studio

Studio is an editor in the browser with a layout modeled on Figma: layers on the left, canvas in the middle, properties on the right.

  1. Import SVG. SVGO automatically removes redundant nodes and adds pathLength="1" to paths so they can use stroke animation.
  2. Group. Motion usually applies to an icon's semantic parts rather than individual paths. Designers can drag to group, or have AI suggest groups based on the SVG source and rendered image, for example dividing a gear into “outer teeth” and “center hole”.
  3. Set motion. Add one or more animations to each group, choosing type, phase, value, direction, delay, loop count, and transform origin. Duration and easing can be set for all at once. motion-hold-start and motion-leave-reverse appear in the panel as two options, “Initial state” and “When trigger ends”, so designers don't need to remember the class names.

Each property maps to a class name: type, phase, and value form motion-rotate-loop-90, and choosing the icon center for “Transform reference” gives motion-origin-viewbox

  1. Export. You can export a standalone SVG with embedded CSS that plays when opened directly in a browser, or export only the SVG with class names and have the project bring in the CSS. The export panel also provides the container markup and usage notes for the selected trigger.

The export is an SVG rather than a component for a particular framework, so pages that don't use React can reference it directly

Step 3 can also be handed to AI. AI generates three plans at once, each with a different choreography strategy: semantic (choosing actions from the icon's meaning, so a refresh icon rotates and a bell shakes), rhythmic (parts enter one after another in spatial order), and minimal (only the most expressive part moves). After selecting a plan, the designer can still adjust it property by property in the properties panel.

The reference material AI receives is the complete CSS source of the motion library, and it is told to use only the class names defined there. With a limited vocabulary, AI's output is predictable. Because the output is ordinary class names, designers can read and edit it. This is the main reason I chose atomization.

Icons and editing progress are saved locally in the browser, and exported SVGs can be re-imported to continue editing. AI features are called through OpenRouter, with an API key supplied by the user and stored only in the local browser.

Skill

The same workflow is also packaged as a Claude Code Skill. After the user provides an SVG, the agent picks combinations from the class name list based on the icon's semantics, writes them back to the SVG, and generates a preview page for the user to view in the browser. The preview script validates the output against a snapshot of all valid class names and reports an error for any class name that doesn't exist, which keeps AI from inventing them. Multiple icons can be handed to sub-agents to process in parallel.

Results

The system is now used on the Tencent Cloud website and in the sidebars of some products. An experienced designer can complete motion for about 15 sidebar icons in one day, approximately 20 times faster than the previous workflow.

Acknowledgments

Thanks to romboHQ for tailwindcss-motion, the source of this system's slot design and most of its preset values, and to Tailwind CSS for the atomic model.