Spinner

Map variant color to the underlying operation's intent.

Use neutral variants for generic background loading.

Avoid color semantics that conflict with surrounding alerts or messages.

Document variant palette so consumers can choose consistent intent across components.

Maintain contrast against the host surface.

Avoid red unless signaling error-state recovery.

Provide tokenized color fallbacks for consumer themes that override core palettes.

Test spinner visibility across density and scale settings in OS accessibility panels.

Use smaller sizes inline with text or icons.

Use large/x-large for blocking overlays or empty states.

Prefer size tokens aligned to component density metrics to ensure cohesive scaling.

Use larger spinners for empty-state placeholders to center user attention.

Keep spinner size proportional to containing control.

Avoid oversized loaders that shift layout.

Expose size props rather than hard-coded CSS so consumers can adapt programmatically.

Validate spinner sizing on retina and high-DPI displays to prevent pixelation.

Use simple types for inline indicators; complex for standalone loaders.

Prefer non-blocking spinners within content regions.

Choose duo/gradient types for brand-centric hero loaders where motion complements identity.

Use pulse types sparingly in high-density pages to avoid visual fatigue.

Avoid overly decorative types in enterprise workflows.

Ensure animation performance stays under 60fps budget.

Fallback to static indicators in reduced-motion user settings.

Keep DOM footprint minimal for spinner variants used frequently in lists.