Keyframes

What you can do

You already opened Maya's homepage hero from Widgets and started composing. The headline on that hero should fade in — animate-fade-in, the same utility her product stylesheet already compiles. A class that only says animation: fade-in 200ms ease is a pointer. Those frames never lived in Class Definitions.

Two everyday jobs:

• Register fade-in once for the next widget. Add the name and the frame blocks here. A widget she creates after that starts with the animation already filled in.
• Leave inclusion off when the host already ships fade-in. Her product Tailwind can own the frames. The hero still points at fade-in. RuleCMS does not ship a second copy.

That same pattern covers a copied animate-enter, a bounce she already uses on sale badges, and a custom name the host never compiled. Authors stay in the catalog form. Engineers keep one vocabulary.

How a keyframes catalog thinks

A class can store animation-name: fade-in. Someone still has to define the frames. The host stylesheet can do that — Maya's product already does, in the compiled Tailwind sheet. RuleCMS can do it too, in a catalog of animation name → frame blocks.

A class body cannot hold the at-rule. Class bodies wrap as a descendant rule, so a pasted @keyframes is ignored. A token cannot hold the block either — @ and braces are rejected. That is why this catalog exists: RuleCMS emits @keyframes fade-in so Preview and the published embed match.

This catalog is the template for the next widget, not a live link to widgets that already exist. When Maya creates a widget, RuleCMS copies these animations onto it — including the inclusion radios. After that the widget owns the copy. Composer, Preview, and the published embed read that widget, not this page. The Projects guide already draws that line. This page is the keyframes catalog itself.

Here is the case that surprises people. Maya copies animate-fade-in onto the hero and expects the headline to fade. If fade-in is missing, the class is present and nothing moves. The utility is only a pointer. This catalog is the frames.

A second surprise: she edits fade-in on the project and expects the Production Default Widget — the hero she already built — to pick up the frames. It does not. Existing widgets stay on the snapshot they received at create until someone opens that widget's CSS Settings and clicks Sync from Project.

A third surprise: @keyframes is document-global. The name is not prefixed, and the rule is not scoped to the published-key span. Two embeds that define different frames for fade-in will race — same name, last widget wins. Use the same frames, or turn inclusion off on the host that already owns the name. RuleCMS does not rename animations per published key.

The renderer does not read this catalog. Composer, Preview, and the published widget GET read the widget's own catalog. This project catalog is copied onto a widget only when that widget is created.

A new widget receives a snapshot of this catalog, including the inclusion flags. Widgets that already exist are not updated automatically. Existing widgets can pull those updates later from the widget's own CSS Settings page. Copy, promote, and restore copy the source widget's catalog, not this one.

Give fade-in frames on the hero

You do this on environment home. The Default Widget in Production already exists — it will not pick up a new animation until someone syncs. A widget she creates after this save starts with fade-in already there.

1. Open the organization → team → project → environment you want to work in.
2. Under CSS catalog, click Keyframes. You land on this project page — Development, Staging, and Production share it.
3. Open Edit. Click Add keyframe. Name: fade-in. Frames: from { opacity: 0 } and to { opacity: 1 } — not @keyframes fade-in { … }. RuleCMS emits the at-rule. Save Changes.
4. Create a new widget from the orange Widgets card — that widget receives a snapshot of this catalog. Or open a widget that already exists, go to CSS Settings, and click Sync from Project so the hero picks up fade-in.

That is a safe stop. The next widget starts with frames for animate-fade-in instead of a still headline. Come back here when the next widget should start from a richer set of animations, or open that widget's catalog when only the hero should change.

Name and frames

Edit is a name plus a textarea for the frame blocks — not a pasted @keyframes wrapper. Reach for each field when the job matches:

The project catalog

Open an environment, then Keyframes. That page is the catalog for the project, not for one environment: Development, Staging, and Production share it.

To change one widget, open its CSS Settings — that guide is the override for this type.

Every new widget in the project can start from the same frames.

• Preview dumps the catalog as emitted @keyframes blocks — not a :root listing. That listing is for authors. Published widgets do not dump a global stylesheet onto your page beyond those unscoped at-rules.
• Edit is a name plus a textarea for the frames. Add keyframe starts a row. Invalid names and bodies are refused per row. Save Changes stays disabled until the catalog is clean.

Each entry is one animation:

@keyframes fade-in {
  from { opacity: 0 }
  to { opacity: 1 }
}

At most 32 animations and 4000 characters per body. Nested at-rules, url(, and a pasted @keyframes wrapper are rejected.

A project has no keyframes row until someone saves for the first time. Until then, a new widget starts without RuleCMS-owned frames and relies on the host stylesheet — a still element if that host never registered the name.

Updates for existing widgets

Editing the project catalog never changes a widget by itself. A person must open the widget and click Sync from Project.

Widgets are per-environment (Development, Staging, Production), but the project catalog is shared across all three. Syncing a Production widget pulls from the same project values a Development widget would.

There is no project-side action that pushes settings to many widgets. Syncing is always started from a widget — one type from its feature page, or all nine from the hub.

Your site probably defines them too — and that is fine

The original animation model is still the right one for a product that already compiles Tailwind: the host stylesheet registers @keyframes fade-in, and RuleCMS widgets inherit it. A Next.js host that already ran its Tailwind build is one of those cases — not a requirement, and not something you configure inside RuleCMS.

Teams that also fill the RuleCMS catalog usually keep the same animation name in both places. By default RuleCMS still includes those frames on the published widget. The rest of your page is untouched: injection is the unscoped at-rule, not a rewritten class.

That default is the useful one when:

• The widget is on a page that never compiled those frames (a landing page, a partner site, an email-adjacent HTML shell).
• Editors need the published embed to match Preview even if the host forgot the name.
• You are still rolling the animation out on the host and the catalog is ahead of the stylesheet.

It is the wrong default when the host stylesheet is the only definition you want at runtime — especially if RuleCMS and the host might disagree for a while, or if two embeds would race on the same name.

Turn off inclusion on published widgets

On the project's Keyframes page, the Published widgets accordion holds two radios. These radios set the default copied onto new widgets. Changing them does not change widgets that already exist. Changing a radio saves immediately. Catalog Save is separate.

The first radio is selected by default:

• Include these keyframes when published widgets are rendered. A non-empty catalog is sent with the widget and the renderer defines the frames. This is how RuleCMS makes Preview and the live embed match.
• My apps already define these animations. Do not include them again when the widget is being rendered. Published widgets still carry class names that point at those animations, but RuleCMS does not ship the @keyframes blocks. Your host stylesheet must define them. Use this when the app already compiles fade-in.

How a published widget receives the catalog

Hosts already fetch the widget once. When inclusion is on and the catalog is not empty, RuleCMS hangs those frames on that same response as a sibling of the widget, its collections, CSS variables, class definitions, and fonts — not folded into itemList, not copied onto each collection. The field is keyframes so the renderer can emit the at-rule without guessing which list is type.

{
  "success": true,
  "data": {
    "widget": { "publishedKey": "…", "itemList": "…", "…": "…" },
    "childCollections": { },
    "keyframes": {
      "fade-in": "from { opacity: 0 }\nto { opacity: 1 }"
    }
  }
}

keyframes is omitted when the catalog is empty, when inclusion is off, or if the catalog cannot be read. When inclusion is off, the same response also sends includeKeyframes: false so renderers that still receive a map must not emit it. Missing on the payload means include (legacy clients). The widget still loads. You never lose a page because a frame row is missing.

The React renderer (@rulecms/widget-react) and the HTML custom element (which bundles that renderer) turn a non-empty catalog into one <style> of unscoped @keyframes rules, for example:

@keyframes fade-in {
  from { opacity: 0 }
  to { opacity: 1 }
}

Nested collections inherit. Other widgets on the same page keep their own catalogs — until two of them register the same name. Same name, last widget wins.

The Development draft fetch (Development Integration) reads the same fields from the draft widget row, so a dev. animation preview on your site matches composer.

After a widget is created, restyling an animation means editing that widget's catalog (or the host stylesheet). Editing this page does not change widgets that already exist.

If the catalog is empty, nothing extra is emitted. Host frames still work. Widgets that never used a RuleCMS animation are unchanged.

React and the HTML embed this pass. Other framework SDKs do not emit this catalog yet.

What to read next

This page is the story and the first walkthrough. The class that points at a name, the other catalogs, and the request your app already sends live on the pages below.

• Class Definitions — A class named animate-fade-in is only a pointer. The body still needs frames this catalog defined.
• Fonts — The typeface catalog; another unscoped at-rule.
• CSS Properties — Typed @property so token values in these frames (and in transitions) can interpolate. This page does not type those names.
• CSS Variables — The token catalog those interpolable names live in.
• widget Keyframes — This widget's live catalog, Sync from Project, and the inclusion radios that actually ship with the embed.
• Position try, Cascade layers, Themes, and Widget chrome — the rest of the project templates on the same home. Widget copies sit under Widgets in the sidebar.
• Generate Tailwind CSS — Compile the class names this widget already uses. That flow can add named frames here; it does not replace this catalog. It is not this page.
• Projects, Environments & Tokens — The pipeline, and project CSS as the template for the next widget.
• Development Integration — Preview the live Development draft with a dev. token.
• HTML Custom Element Embed — The script tag that mounts a widget in light DOM so host animations still reach it.
• API Reference — The public widget GET, including keyframes.
• MDN: @keyframes

How this fits

A widget is the content. This catalog gives copied animate-* utilities frames to run. It does not replace the widget, and it does not replace Maya's stylesheet. Publishing is how a draft catalog reaches a Staging or Production token. The Composer is where a class name stores the pointer at fade-in.

This catalog is the template for new widgets. It is shared across Development, Staging, and Production. The renderer reads the widget, not this page. Existing widgets are not updated automatically when you edit here; they can pull the new values from CSS Settings.

• Same name, last widget wins. @keyframes is document-global. Two embeds that define different frames for fade-in will race. Use the same frames, or turn inclusion off on the host that already owns the name. RuleCMS does not rename animations per published key.
• Leave the catalog empty if the host owns every animation. Class names on elements still work. Nothing extra is sent to the published page.
• Ask whoever owns the stylesheet which animation names are already compiled. A missing @keyframes fade-in on the live page paints as a still element. That is the surprising case, not a slower fade.