Using CSS Animations Inside Codex Themes

CSS animations inside a codex theme fail on restraint far more often than on syntax. Codex Skin Studio injects theme CSS into the renderer over local CDP, so your keyframes run on the same layer as the interface. A badly written animation slows down the input box and scrolling directly. Here is what is worth animating, what numbers to use, and how to tell when one starts costing you frames.

Which animations are worth it

One test decides it: does the effect help you read state? Panel slide-ins, a focus ring that breathes, and a crossfade when the theme changes all pass. An endlessly rotating wallpaper, floating particles across the whole window, or a permanent glow pulse do not. The second group looks good for the first minute and starts pulling attention by the third hour.

• Worth it: panel and sidebar entry offsets, focus ring and active-state transitions, a crossfade when switching themes, a soft breathing load state
• Use with care: wallpaper drift or zoom, a gradient that flows forever, anything layered over text
• Skip: an endlessly rotating background, particle fields, large cursor-following offsets

What numbers to use

Duration and easing carry the feel. Offset interface elements by 160 to 240 milliseconds, crossfade over 120 to 200 milliseconds, and run breathing loops for 2.4 to 4 seconds. Past roughly 300 milliseconds on a movement, the pointer has already moved on while the interface is still catching up, and what you perceive is lag.

• Movement: 160 to 240ms, ease-out
• Crossfade: 120 to 200ms, linear or ease
• Breathing loop: 2.4 to 4s, ease-in-out, alternate
• Easing: prefer cubic-bezier(0.2, 0, 0.2, 1), which reads cleaner than ease-in-out at short durations

Animate only the properties that skip layout

The performance split comes down to which properties you touch. transform and opacity run on the compositor, so the browser can hand them to the GPU and leave the main thread free for your input. width, height, top, left, box-shadow and filter force a layout and paint recalculation every frame, and you feel it the moment you type continuously into the input box.

• Safe: transform (translate, scale, rotate), opacity
• Use with care: box-shadow, filter: blur(), background-position
• Avoid: width and height, top and left, margin, border-width

Honour the reduced motion setting

Some users turn on reduced motion at the system level, either for vestibular reasons or simply because they do not want to be moved around. Wrapping your decorative animations in @media (prefers-reduced-motion: reduce) and dropping them to 0.01ms or switching them off takes a few lines, and it decides whether those users can work in your theme at all.

• Turn purely decorative animation off entirely
• Keep functional transitions, but compress them under 100ms
• After turning an animation off, confirm the static end state is correct so nothing simply vanishes

How to tell when an animation costs you frames

Do not judge by feel alone. Open Codex, scroll through a long session, type continuously into the input box, then switch between a few themes and watch for dropped frames. For something more objective, record five seconds in the DevTools Performance panel and check whether animation frames keep filling the main thread.

• Input lags while typing: something is animating a layout property
• Scrolling stutters: the wallpaper is running a blur or a large offset
• A hitch right after switching themes: several long loops start at once
• The fan spins up: an animation is holding the main thread continuously

A starting point you can paste

Begin with these four rules and adjust the numbers to your theme. They only touch transform and opacity, and they include the reduced motion branch.

• .panel { transition: transform 200ms cubic-bezier(0.2, 0, 0.2, 1), opacity 160ms linear; }
• @keyframes breathe { from { opacity: 0.55 } to { opacity: 0.85 } }
• .focus-ring { animation: breathe 3s ease-in-out infinite alternate; }
• @media (prefers-reduced-motion: reduce) { .focus-ring { animation: none } }

Animation is the tone of a theme, not its weight. Spend motion on state changes and leave the background still, and long sessions stay comfortable.

FAQ