# Motion

A strict, utilitarian timing language for feedback and transitions.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).



Motion in the **Monolith Design System** is the shared timing language of the interface. Our philosophy dictates that all interactions must be snappy, deliberate, and free of over-engineering.

Unlike other design systems that rely on complex spring physics or heavy libraries like Framer Motion, we strictly use **Native CSS Transitions** and **Vanilla JavaScript** (like `MutationObserver` for sliding highlights).

## Preview [#preview]



<ComponentPreview src="examples/motion-demo.tsx">
  <MotionDemo />
</ComponentPreview>

## Core Principles [#core-principles]

* **Utilitarian & Snappy**: Animations exist only to provide immediate user feedback, not for decoration.
* **Max Duration Limit (150ms)**: No animation or transition may exceed 150ms. Slower animations (like 300ms or 500ms) make the interface feel sluggish and are strictly banned.
* **No `scale` Transformations**: Hover and active states must never use `scale` (e.g., `active:scale-95`). All buttons and inputs must maintain their rigid geometry. Use opacity or background color changes instead.
* **Directional Micro-animations**: Lateral movement (e.g., a 2px horizontal slide) is allowed ONLY for semantic icons (like Chevrons or Arrows) on hover, to indicate directional flow.

## Presets [#presets]

Because we rely exclusively on native Tailwind CSS utilities, we do not need custom JavaScript configuration files for animation. Use the following standard Tailwind duration classes:

| Preset       | Duration | Utility Class      | Easing     | Use                                                    |
| ------------ | -------- | ------------------ | ---------- | ------------------------------------------------------ |
| **Fast**     | 75ms     | `duration-75`      | `ease-out` | Micro-interactions, hover backgrounds, opacity changes |
| **Standard** | 150ms    | `duration-[150ms]` | `ease-out` | Layout shifts, sliding indicators, Dialog/Sheet enter  |

> **Note:** There is no `slow` preset. Any interaction requiring more than 150ms violates the Monolith philosophy and will be rejected.

## Usage [#usage]

Use Tailwind's `duration-*` utility classes combined with our strict timing rules. Ensure you are not combining motion with banned transformations like `scale`.

### Incorrect (Anti-patterns) [#incorrect-anti-patterns]

```tsx
// Too slow (300ms violates the 150ms rule)
<div className="transition-all duration-300" />

// Uses banned scale transformation
<button className="transition-transform duration-150 active:scale-95">
  Submit
</button>
```

### Correct (Impeccable) [#correct-impeccable]

```tsx
// Fast, snappy hover state using opacity/background
<button className="transition-colors duration-[150ms] ease-out hover:bg-accent hover:text-accent-foreground">
  Submit
</button>

// Subtle 75ms opacity transition for micro-feedback
<span className="transition-opacity duration-75 hover:opacity-80">
  Icon
</span>
```

## Reduced Motion [#reduced-motion]

We respect user system preferences. Tailwind automatically provides the `motion-reduce:` modifier.
Ensure that critical information is never lost when a user has "Reduce Motion" enabled in their OS.

```tsx
<div className="transition-colors duration-150 motion-reduce:transition-none" />
```