Primitives

146 named, searchable animation units — each carrying usage rules, personality affinity, composability flags, and AI guidance — that the toolchain selects, validates, and compiles into production CSS on your behalf.

What are primitives?

A primitive is the smallest named unit of motion in Animatic. It describes a single animation behavior — a fade entrance, a blur reveal, a typewriter text effect, a camera truck — with enough metadata that an AI assistant can select, validate, and compile it without ambiguity.

Primitives are not CSS snippets you copy-paste. They are structured definitions that carry intent: when to use them, when to avoid them, which personalities they work with, and how they compose with other primitives. The AI reads this metadata to make informed decisions about your animation.

Every primitive has:

• A name and slug for identification
• A category that describes its role (entrance, exit, emphasis, etc.)
• Timing and easing defaults calibrated to its personality
• CSS output — keyframes and/or transition properties
• Personality affinity — which personalities approve this primitive
• AI guidance — natural-language instructions for the AI on how to use it correctly

Anatomy of a primitive

Here is the full definition of the ed-slide-stagger primitive — the editorial personality's signature entrance:

{
  "name": "Slide + Fade Stagger",
  "slug": "ed-slide-stagger",
  "category": "entrance",
  "description": "Elements slide up 10px while fading in, with 120ms stagger intervals between siblings. The editorial signature entrance.",
  "default_duration": "400ms",
  "default_easing": "cubic-bezier(0.25, 0.46, 0.45, 0.94)",
  "composable": true,
  "stagger_compatible": true,
  "stagger_offset": "120ms",
  "css_class": "anim-ed-slide-stagger",
  "keyframes": {
    "slide-fade-in": {
      "0%": { "opacity": "0", "transform": "translateY(10px)" },
      "100%": { "opacity": "1", "transform": "translateY(0)" }
    }
  },
  "css_properties": {
    "initial": "opacity: 0; transform: translateY(10px)",
    "visible": "opacity: 1; transform: translateY(0)"
  },
  "when_to_use": ["Content item entrances", "List reveals", "Card grid staggers", "Feature showcases"],
  "when_to_avoid": ["Hero moments (use blur-reveal)", "Phase transitions (use crossfade)"],
  "ai_guidance": "Default editorial entrance. Use with data-stagger-group attribute and engine.runSlideStagger(). Stagger timing: 80-150ms between siblings, 400-600ms per element. No blur, no 3D — just translateY + opacity.",
  "personality_affinity": ["editorial"],
  "source": "engine"
}

Field reference

Categories

Each primitive belongs to one category that describes its role in an animation sequence.

Categories map directly to choreography phases. When you describe a sequence beat like "hero section enters," the AI searches the entrance category. When you say "transition to the next section," it searches transition. This mapping is automatic — you describe intent, not categories.

Try asking your AI

"Show me all entrance primitives compatible with cinematic-dark"

"What emphasis primitives work for editorial personality?"

"Find attention primitives for a tutorial walkthrough"

Sources

Primitives come from four distinct sources. Each source contributes different kinds of motion knowledge.

engine (31 primitives)

Built-in primitives that ship with each personality. These are the core motion vocabulary — every personality's signature entrance, default transition, and standard interactions. Engine primitives are the most thoroughly tested and carry the most detailed AI guidance.

Examples: cd-focus-stagger (cinematic-dark's signature entrance), ed-slide-stagger (editorial's default), nl-cursor-to (neutral-light's cursor simulation), ed-content-cycle (editorial's content cycling).

research (50 primitives)

Derived from cinematic camera and motion techniques adapted for UI. These translate film language — dolly shots, truck moves, crane lifts, rack focus — into CSS transforms and transitions. Research primitives tend to be higher-complexity and are concentrated in the transition category.

Examples: ct-camera-truck (horizontal dolly slide), ct-camera-crane (vertical lift), ct-rack-focus (blur shift between depth layers).

{
  "name": "Camera Truck",
  "slug": "ct-camera-truck",
  "category": "transition",
  "description": "Horizontal camera slide left or right, simulating a truck move on a dolly track.",
  "default_duration": "1200ms",
  "default_easing": "cubic-bezier(0.16, 1, 0.3, 1)",
  "css_properties": {
    "rig": "perspective: 600px; perspective-origin: 50% 40%",
    "scene": "transform-style: preserve-3d; transition: transform 1.2s cubic-bezier(0.16, 1, 0.3, 1)"
  },
  "personality_affinity": ["cinematic-dark"],
  "source": "research"
}

animate.style (17 primitives)

Curated selections from Animate.css, adapted to work within Animatic's personality system. These are familiar effects — bounce, flash, rubber band, swing — that have been re-timed and re-eased to match personality constraints. Not every Animate.css effect is included; only those that pass personality validation.

Examples: as-bounce-in, as-fade-in-up, as-zoom-in, as-swing.

breakdown (48 primitives)

Extracted from the 20 reference breakdowns — detailed analyses of exemplary animations from Linear, Notion, Vercel, and other sources. When a breakdown identifies a novel motion pattern, that pattern gets formalized as a primitive. Breakdown primitives tend to be the most specific and contextual.

Examples: Metaball merge effects from the liquid-metaball-merge breakdown, dot-grid breathing from the sparse-dot-breathing analysis, isometric card flips from the 3d-card-cascade study.

Source distribution

Personality affinity

Every primitive declares which personalities it works with via the personality_affinity array. This is not a suggestion — it is an enforcement boundary.

When you (or your AI) select a personality, all primitive searches are automatically filtered to show only compatible primitives. A cinematic-dark session will never surface nl-spotlight or ed-content-cycle. An editorial session will never surface cd-focus-stagger or camera truck moves.

How filtering works

1. You set a personality (explicitly or via the brief)
2. The AI calls search_primitives with your query
3. Results are filtered to primitives where personality_affinity includes your active personality
4. The AI selects from the filtered set
5. Choreography validation double-checks personality compatibility before compilation

This two-layer check — filter at search time, validate at compile time — prevents personality drift even when the AI improvises.

Affinity distribution

Some primitives have multiple affinities. The ed-count-up number animation works in both editorial and neutral-light. The typewriter reveal works in cinematic-dark and editorial. These cross-personality primitives tend to be functional rather than stylistic.

Try asking your AI

"List all primitives shared between editorial and neutral-light"

"Which cinematic-dark primitives are exclusive — not available in any other personality?"

"How many entrance primitives does montage have?"

Searching and filtering

The search_primitives MCP tool searches the full 146-primitive catalog by name, category, personality, source, tags, or natural-language description.

Search strategies

Try asking your AI

"Search for blur-related primitives in cinematic-dark"

"Find stagger-compatible entrance primitives for editorial"

"Show me all primitives extracted from the Linear homepage breakdown"

"What ambient/continuous primitives are available for cinematic-dark backgrounds?"

"Find composable primitives I can layer on top of a slide-fade entrance"

Using primitives in choreography

Primitives are building blocks. On their own, they define a single motion. Combined into a choreography, they define a complete animated sequence.

The typical flow:

1. Search — Find primitives that match your intent and personality
2. Recommend — Use recommend_choreography to get an AI-composed sequence of primitives with timing
3. Validate — The choreography is checked against personality constraints, primitive compatibility, and timing guardrails
4. Compile — Use compile_motion to generate production CSS from the validated choreography

At each step, the primitive's metadata does the work. The AI reads when_to_use and when_to_avoid to select. It reads composable and stagger_compatible to plan layering. It reads default_duration and default_easing as starting points, then adjusts based on the personality's timing tiers. It reads ai_guidance for implementation specifics.

You do not need to memorize primitives. Describe what you want, name your personality, and the tools handle selection.

Try asking your AI

"I need a 5-phase product demo using cinematic-dark. Recommend choreography with focus-pull entrances, a camera orbit in the middle, and a blur-reveal hero moment."

"Build an editorial feature showcase: slide-fade stagger for the list items, content cycling for the benefits section, count-up for the stats."

"Create a neutral-light onboarding tutorial with spotlight highlights, cursor simulation moving between three input fields, and step progress indicators."