react-doctor/no-excessive-motion-stagger

Review stagger spacing above 80ms in the context of item count, total tail, frequency, and product intent

Creative-direction review: This rule is explicitly classified as a preference. Review it against the product brief, rendered context, brand system, and user needs. Keeping an intentional choice with evidence is a successful outcome.

Validation prompt

Review the reported pattern in context before deciding whether an edit is warranted.

For react-doctor/no-excessive-motion-stagger, the detector inspects resolved Motion transition objects. It reports staggerChildren above 0.08 seconds or delayChildren: stagger(<literal>) above 0.08 when stagger comes from framer-motion or motion/react. It does not know the rendered child count, total tail, first-item timing, content availability, or replay frequency. Suppress a rare narrative group when its delay is bounded, interaction remains available, order is meaningful, and reduced motion is handled. Judge the rendered sequence rather than treating 80ms as a universal threshold. The Before example is representative, not exhaustive.

Evidence boundary

The diagnostic proves only that the detector’s modeled source pattern matched. It does not prove runtime impact, product intent, rendered failure, or that one remediation is correct.

Establish the environment, repository policy, exceptions, and required rendered or runtime evidence before deciding the occurrence.

The design tag controls activation and discovery. It does not determine the rule’s proof class.

Record one outcome:

• Confirmed failure: The required evidence establishes the violation.
• Rejected: A documented exception or false-positive predicate applies.
• Needs evidence: Named evidence can still be collected.
• Unavailable: Required evidence cannot be collected in this run.
• Waived with evidence: An authorized, scoped exception applies to an established failure.
• Observation: The review records an optional tradeoff without claiming a defect.

A waiver records its scope, authority, evidence, and review condition. It is not a pass or false positive.

Default severity is registry metadata. Use the occurrence’s JSON severity after repository configuration when ordering real findings.

Review the pattern

This revision is illustrative, not proof that the reported pattern is wrong. Keep intentional choices that fit the product brief and design system.

Reported pattern

import { motion } from "motion/react";

const Demo = () => (
  <motion.ul transition={{ staggerChildren: 0.2 }}>
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
  </motion.ul>
);

One possible revision

import { motion } from "motion/react";

const Demo = () => (
  <motion.ul transition={{ staggerChildren: 0.05 }}>
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
  </motion.ul>
);

Fix prompt

Treat this as review guidance, not a required correction. Preserve an intentional choice when the brief, design system, and rendered evidence support it.

Adjust stagger only when the rendered tail materially delays content or repeatedly disrupts the interaction. Reuse the project's choreography token when available. Otherwise reduce the interval, item count, or staggered subset until the total tail fits the interaction. Preserve item order, the first-item timing, transition type, interruption, and reduced-motion behavior. Do not force every sequence to 50ms or remove an intentional rare narrative sequence only to silence the heuristic.

Repository-wide copy prompt

Use this repository-wide prompt only after validating each occurrence. For one occurrence, use the guidance above.

import { motion } from "motion/react";

const Demo = () => (
  <motion.ul transition={{ staggerChildren: 0.2 }}>
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
  </motion.ul>
);

import { motion } from "motion/react";

const Demo = () => (
  <motion.ul transition={{ staggerChildren: 0.05 }}>
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
    <motion.li />
  </motion.ul>
);