# Amevia brand motion — Ribbon Flow

Presentation-only animation for the approved Amevia icon. The light travels **across the icon itself**,
clipped to its exact geometry — never as a circular orbit or spinner. The official static SVG
(`/brand/source/amevia-logo.svg`) is never modified.

## Approach

A **broad elliptical light travels the ribbon** and is clipped to the exact icon silhouette, so the whole
ribbon width beneath it is illuminated — never a stroked line or a circular orbit:

1. **Base** — the approved SVG rendered as-is, sharp and readable.
2. **Illumination** — a broad radial/elliptical gradient blob rides an invisible guide path via CSS Motion
   Path (`offset-path` + `offset-distance`). The layer is `mask-image` = the icon and `mix-blend-mode: screen`,
   so wherever the light passes, the full ribbon width under it brightens while the material is preserved.
3. **Trailing tail** — a second, dimmer, phase-shifted blob just behind the main light for directional flow.
4. **Local bloom** — a broad, softly blurred blob on a separate masked layer that hugs the icon (no large halo).
5. **Inner glow** — a static/pulsing centered glow used by `none`, `soft-pulse`, and reduced motion.

The guide path is authored in the icon's viewBox units and mapped onto the rendered box with a
`translateY() scale()` bridge, so the light always follows the real geometry. It is **never stroked** in
production — it only positions the light. Breathing scale lives on an inner wrapper; pointer tilt/parallax on
an outer wrapper, so the two transforms never conflict.

## Components

| Component | Purpose |
|-----------|---------|
| `AnimatedAmeviaIcon` | Core effect switcher |
| `AmeviaHeroMark` | Homepage-ready hero (ribbon-flow + bloom + breathe) |
| `AmeviaLoadingMark` | Loading / idle (soft-pulse, 48–96 px) |
| `AmeviaAgentMark` | Chat launcher / agent header (static, optional one-time sweep) |

## Effects

- **ribbon-flow** — Flagship. A broad light illuminates the full width of each ribbon section in sequence (lower-left → left leg → top fold → right leg → lower-right fold → center crossing → back) + breathing scale. Seamless loop, no visible line.
- **ribbon-sweep** — One soft pass through the ribbon, long pause. Login / launch.
- **soft-pulse** — Internal brightness pulse, no traveling light. Loading / idle.
- **reveal** — One-time entrance (fade + scale 0.94→1.00 + one sweep).
- **none** — Static approved icon with faint inner glow (also the reduced-motion look).

## Intensity presets

`subtle` · `standard` · `hero` — each controls illumination opacity, bloom, moving-light size, breathing
scale, and the material edge response.

| Preset | Illumination | Bloom | Light size | Scale |
|--------|------|------|-------|-------|
| subtle | 55% | 16% | 0.9× | 1.012 |
| standard | 82% | 28% | 1.0× | 1.014 |
| hero | 100% | 44% | 1.14× | 1.015 |

Speeds (via `speedMultiplier`): slow ≈ 12 s, standard = 8 s, fast ≈ 5.5 s.

## Component API

```tsx
<AnimatedAmeviaIcon
  size={220}
  effect="ribbon-flow"      // none | ribbon-flow | ribbon-sweep | soft-pulse | reveal
  intensity="hero"          // subtle | standard | hero
  background="dark"         // transparent | light | dark
  interactive               // desktop pointer parallax (≤2px shift, ≤1.8° tilt)
  autoPlay                  // pause offscreen / tab hidden
  paused={false}
  speedMultiplier={1}       // 0.67 (slow) · 1 (standard) · 1.45 (fast)
  debug={false}             // dev-only: draw the invisible guide path + moving light center
/>
```

## When to use

| Context | Recommended |
|---------|-------------|
| Homepage hero | `ribbon-flow` / `AmeviaHeroMark` |
| Loading / idle | `soft-pulse` / `AmeviaLoadingMark` |
| Login / launch | `ribbon-sweep` |
| Chat launcher | `AmeviaAgentMark` (static + one-time sweep) |
| Navigation | `none` (static glow) |
| Favicon | Never animated |

## Reduced motion

Under `@media (prefers-reduced-motion: reduce)` (or the playground simulation toggle):

- Continuous flow, sweep, pulse, and pointer parallax stop
- The static approved icon is shown with a faint inner glow
- Visual hierarchy is preserved

## Performance safeguards

- Animates `offset-distance`, `transform`, and `opacity` only (moves a small light, not large regions)
- No continuously animated large blur radii
- `IntersectionObserver` pauses offscreen; pauses when the tab is hidden
- Minimal DOM: base + two masked light layers + inner glow

## Example

```tsx
import { AnimatedAmeviaIcon, AmeviaHeroMark, AmeviaLoadingMark, AmeviaAgentMark } from "@/components/brand-motion";

<AmeviaHeroMark size={220} theme="dark" />
<AnimatedAmeviaIcon effect="ribbon-flow" size={200} intensity="hero" background="dark" interactive />
<AmeviaLoadingMark size={64} />
<AmeviaAgentMark size={48} sweepOnMount />
```

Styles: `styles/amevia-motion.css` (imported in `app/globals.css`).