# Motion

> Foundations · Tetrifox Brand Book · https://design.tetrifox.com/foundations/motion

## Purpose

Motion is assembly: modular pieces arrive in order, become legible, and lock into place. The same discipline used to compose a Mino shapes how Tetrifox interfaces move — then they stay put.

## Rules

### Must

- **Make motion feel like assembly — deliberate, confident and mechanical. Never playful, bouncy or decorative.** Assemble. Reveal. Settle. echoes the modular pieces finding their place that underpin the brand: Minos, tetrominoes, the bordered grid. [Assemble. Reveal. Settle.](https://design.tetrifox.com/foundations/motion#assemble-reveal-settle) · `motion.assembly`
- **Use `motion/react` for entrances and CSS transitions for hover and focus only (colour and transform, about 200ms). No raw `@keyframes` and no second animation library.** One engine for entrances and one for micro-interactions keeps every timing traceable to the shared presets. Tokens: `transitions.fast`. [Assemble. Reveal. Settle.](https://design.tetrifox.com/foundations/motion#assemble-reveal-settle) · `motion.tooling`
- **Sequence groups with the exported stagger variants instead of local numeric delay ladders.** An existing stagger preset already expresses the order; a local ladder drifts from it. Tokens: `variants.staggerContainer`, `variants.staggerContainerSlow`, `variants.gridStagger`. [Presets](https://design.tetrifox.com/foundations/motion#presets) · `motion.stagger-presets`
- **Animate only `opacity` and `transform`. The `draw` preset, which animates SVG `pathLength` for instructional line work, is the one exception; never animate width, height, padding or layout.** Composited properties stay smooth and never shift the layout a reader is following. Tokens: `variants.draw`. [Presets](https://design.tetrifox.com/foundations/motion#presets) · `motion.opacity-transform`
- **Let the effective preference — system, reduced or full — govern Motion components, CSS micro-interactions, smooth anchor scrolling and the pattern field together.** Reduced motion changes presentation, not meaning; one switch must cover every moving surface. [Reduced motion](https://design.tetrifox.com/foundations/motion#reduced-motion) · `motion.effective-preference`
- **Give every moving surface a named reduced state: in reduced mode content renders settled, anchor links jump, and the pattern field paints one static lattice with no animation frame or pointer listener.** A surface without a named reduced state does not move at all. [Reduced motion](https://design.tetrifox.com/foundations/motion#reduced-motion) · `motion.reduced-settled`
- **Fire reveals once (`viewport once: true`): hero content on mount, section headers and grid content on first entry, illustrations after their text.** Re-triggering on scroll-back turns orientation into decoration. Tokens: `variants.fadeUp`, `variants.fadeIn`. [What moves](https://design.tetrifox.com/foundations/motion#what-moves) · `motion.once`
- **Keep the pattern field the only ambient motion: inside a contained cell, only while visible, and only when the effective preference allows it.** The drifting dots embody the assembly metaphor. Their physics live in the component; their colours are the field tokens. Tokens: `--field-dot`, `--field-glow`, `--field-bloom`. [What moves](https://design.tetrifox.com/foundations/motion#what-moves) · `motion.pattern-exception`

### Must not

- **Hardcode durations, easings, transitions or variant objects. Import them from `src/lib/motion.ts`.** If you catch yourself writing `transition={{ duration: 0.4, ease: [...] }}`, stop and import instead. Tokens: `transitions.default`, `variants.fadeUp`. [Presets](https://design.tetrifox.com/foundations/motion#presets) · `motion.import-presets`
- **Use parallax, scroll-linked effects or exit animations, or animate header and footer chrome, borders or grid lines.** Content assembles, reveals and settles. Then it stays put. [What moves](https://design.tetrifox.com/foundations/motion#what-moves) · `motion.never`

### Prefer

- **Use `transitions.reveal` (0.8s, easeOut) for scroll reveals and `transitions.fast` (0.2s, snappy) for hovers. Choose a preset by purpose, not taste.** Each pairing of duration and easing has one job. Tokens: `transitions.reveal`, `transitions.fast`, `easings.easeOut`, `easings.snappy`. [Presets](https://design.tetrifox.com/foundations/motion#presets) · `motion.reveal-and-hover`

## Tokens used

| Token | Dark (`:root`) | Light (`.light`) |
| --- | --- | --- |
| `--field-dot` | `#9aa5b1` | `#52606d` |
| `--field-glow` | `#408cb4` | `#0891b2` |
| `--field-bloom` | `#2bc4f0` | `#10add9` |

| Token | Value | Source |
| --- | --- | --- |
| `transitions.fast` | `{"duration":0.2,"ease":[0.4,0,0.2,1]}` | src/lib/motion.ts |
| `transitions.default` | `{"duration":0.4,"ease":[0.25,0.1,0.25,1]}` | src/lib/motion.ts |
| `variants.fadeUp` | `{"hidden":{"opacity":0,"y":24},"visible":{"opacity":1,"y":0}}` | src/lib/motion.ts |
| `variants.staggerContainer` | `{"hidden":{},"visible":{"transition":{"staggerChildren":0.12}}}` | src/lib/motion.ts |
| `variants.staggerContainerSlow` | `{"hidden":{},"visible":{"transition":{"staggerChildren":0.2,"delayChildren":0.1}}}` | src/lib/motion.ts |
| `variants.gridStagger` | `{"hidden":{},"visible":{"transition":{"staggerChildren":0.08}}}` | src/lib/motion.ts |
| `transitions.reveal` | `{"duration":0.8,"ease":[0,0,0.2,1]}` | src/lib/motion.ts |
| `easings.easeOut` | `[0,0,0.2,1]` | src/lib/motion.ts |
| `easings.snappy` | `[0.4,0,0.2,1]` | src/lib/motion.ts |
| `variants.draw` | `{"hidden":{"pathLength":0,"opacity":0},"visible":{"pathLength":1,"opacity":1}}` | src/lib/motion.ts |
| `variants.fadeIn` | `{"hidden":{"opacity":0},"visible":{"opacity":1}}` | src/lib/motion.ts |

## Do / Don't

- **Presets.** Do: `<motion.div variants={variants.fadeUp} transition={transitions.reveal} />` Don't: `<motion.div transition={{ duration: 0.4, ease: [0.25, 0.1, 0.25, 1] }} />`
- **Restraint.** Do: A section header fades up once and settles. Don't: A hero image drifts with scroll position and fades out on exit.

## Related chapters

- [Layout & grid](https://design.tetrifox.com/foundations/layout.md)
- [Components](https://design.tetrifox.com/expressions/components.md)
- [Minos & configurations](https://design.tetrifox.com/expressions/minos.md)
