# Animations

The `theme.animations` block defines motion design tokens — named animations, reusable durations and easing curves, and `@keyframes` definitions. Tokens generate CSS that any component can reference through its `className`.

## `theme.animations`

`animations` is a map keyed by token name (alphanumeric, must start with a letter). Each value is one of four shapes, giving you a spectrum from a one-line toggle to a full keyframe definition.

| Value shape   | Use it for                                                                        |
| ------------- | --------------------------------------------------------------------------------- |
| Boolean       | Enable or disable a named animation: `fadeIn: true`.                              |
| String        | A raw CSS animation value or a utility class name: `slideUp: 'animate-slide-up'`. |
| Config object | Detailed control: `enabled`, `duration`, `easing`, `delay`, `keyframes`.          |
| Token map     | A nested map of named `duration`, `easing`, or `keyframes` design tokens.         |

### Boolean and string forms

The quickest way to switch a built-in animation on, or to alias a class name.

```yaml
theme:
  animations:
    fadeIn: true
    slideUp: 'animate-slide-up'
```

### Config-object form

A detailed animation with timing control.

| Property    | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `enabled`   | Boolean. Whether the animation is active.                               |
| `duration`  | CSS duration (e.g. `'300ms'`, `'0.5s'`).                                |
| `easing`    | CSS easing/timing function (e.g. `'ease-in-out'`, `cubic-bezier(...)`). |
| `delay`     | CSS duration to wait before starting (e.g. `'0ms'`).                    |
| `keyframes` | Inline keyframe definition map.                                         |

```yaml
theme:
  animations:
    modalOpen:
      enabled: true
      duration: '300ms'
      easing: 'ease-in-out'
      delay: '0ms'
```

### Nested token maps

For a reusable motion system, declare `duration`, `easing`, and `keyframes` as named token maps. Other animations and component classes can then reference these tokens instead of repeating raw values.

```yaml
theme:
  animations:
    duration:
      fast: '200ms'
      normal: '300ms'
      slow: '500ms'
    easing:
      smooth: 'cubic-bezier(0.4, 0, 0.2, 1)'
      bounce: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)'
    keyframes:
      fadeIn:
        from: { opacity: '0' }
        to: { opacity: '1' }
      colorPulse:
        '0%': { backgroundColor: '$colors.primary' }
        '50%': { backgroundColor: '$colors.accent' }
        '100%': { backgroundColor: '$colors.primary' }
```

| Token map   | Key rule                            | Value                                             |
| ----------- | ----------------------------------- | ------------------------------------------------- |
| `duration`  | Alphanumeric, starts with a letter. | CSS duration string.                              |
| `easing`    | Alphanumeric, starts with a letter. | CSS easing/timing function.                       |
| `keyframes` | Alphanumeric, starts with a letter. | A keyframe map (`from`/`to` or percentage stops). |

:::callout
**Reference theme colors in keyframes.** Keyframe values may reference other theme tokens with the `$colors.<name>` syntax (e.g. `backgroundColor: '$colors.primary'`), keeping motion in sync with your palette.
:::

## Ecoconception note

Motion is a footprint concern. Prefer short durations and avoid long-running infinite animations on first paint. Sovrium's eco posture is operator-controlled via environment variables, not theme schema — see the [Environment Variables](/en/docs/env-vars) reference for the `ECO_*` controls that govern client behavior.

## Next steps

- [Theme](/en/docs/theme) — the full theme token reference.
- [Responsive Design](/en/docs/responsive-design) — breakpoints and per-breakpoint overrides.
- [Pages Overview](/en/docs/pages-overview) — applying animation classes to components.