react-doctor/no-permanent-will-change

Use will-change only after profiling shows a benefit; broad or long-lived hints can retain costly layers

Validation prompt

Confirm the detector match and collect the required evidence before deciding whether an edit is warranted.

The detector reports unvarianted static Tailwind will-change-* utilities except its auto and scroll-position forms. In an inline JSX style object it reports a willChange property unless the value is conditional/logical or the literal string 'scroll-position'; this means it incorrectly reports willChange: 'auto'. Suppress auto, a measured small element that changes continuously or very frequently, and deliberate pre-promotion such as a slide deck where applying the hint early is necessary and resource use is acceptable. Otherwise confirm the hint persists while the element is idle and that profiling shows retained layers or memory cost. will-change is a last-resort performance hint, not a required animation declaration.

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.

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.

Fix prompt

Apply this candidate correction only after the required evidence confirms the risk.

Remove will-change first and re-profile; browsers already promote many transform and opacity animations. If evidence shows the hint is needed, apply it shortly before the change so the browser has time to prepare, limit it to the exact property and smallest element, then restore auto after the transition/animation finishes or the interaction becomes idle. Do not universally put it inside :hover or keyframes: activation at the same moment as the animation can be too late, and keyframed properties already receive animation optimizations. Keep a static hint only for a documented, frequently changing element whose measured benefit outweighs layer memory. See https://developer.mozilla.org/en-US/docs/Web/CSS/will-change#using_will-change_responsibly

Repository-wide copy prompt

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