Switch

Use primary for high-visibility, core settings.

Use success/error for domain-specific semantics.

Map variants to backend meaning when toggles correspond to persistent feature flags.

Reserve warning colors for toggles that may cause visible UX changes or require confirmation.

Respect contrast and WCAG state colors.

Avoid alarming colors for benign toggles.

Ensure variant colors are still distinguishable for color-blind users (use shape + color).

Provide tokenized theming for variant overrides so clients can maintain high contrast.

Default to the most common safe option.

Reflect server-sourced defaults in settings pages.

Use checked to mirror persisted user preferences when rendering forms.

Avoid pre-checking toggles that result in billing or destructive behavior.

Avoid dark patterns; never pre-enable risky toggles.

Sync initial state with persisted user preferences.

Provide explicit documentation for initial checked semantics to prevent integration errors.

When migrating defaults, communicate breaking changes in release notes and deprecation paths.

Use labels to clarify domain meaning of the toggle.

Localize labels to match app language settings.

Prefer concise labels (2-4 words) that map directly to backend fields.

When space permits, include a short helper to explain complex toggle behavior.

Associate label via or aria-labelledby.

Keep label copy concise (2-4 words).

Ensure label changes are announced by screen readers when state toggles programmatically.

Provide test IDs for labels to support UI automation and telemetry correlation.

Horizontal for dense settings lists or tables.

Vertical for forms and stacked layouts.

Use responsive alignment to shift between horizontal/vertical based on available width.

Prefer vertical alignment for forms where label wrapping is likely to improve readability.

Ensure click target includes label and control.

Maintain consistent alignment across a section.

When aligning horizontally, ensure the label remains accessible via keyboard navigation.

Document expected layout fallback for third-party CSS resets that might alter alignment behavior.

Reflect permission gating or system-enforced states.

Use when prerequisites are unmet in forms.

Use disabled state to indicate server-derived read-only configuration in settings pages.

Apply disabled when dependent asynchronous validations are pending to avoid inconsistent toggles.

Explain disabled state with helper text or tooltip.

Avoid disabling core settings without rationale.

Prefer programmatic reasons (data-disable-reason) over visual-only indicators for maintainability.

Do not rely on visual disabled state for security — enforce permission checks server-side.

Use smaller sizes in dense data tables.

Use large/x-large on mobile-first screens.

Select sizes that maintain a minimum thumb grab area for touch devices.

Prefer consistent vertical metrics between switches and adjacent inputs for optical alignment.

Ensure thumb size remains easily grabbable.

Avoid resizing text without adjusting control size.

Document how size impacts layout and provide examples for responsive design.

Create snapshot tests for each size to catch visual regressions across themes.

Coordinate state with forms, stores, or URL params.

Drive from a single source of truth in complex UIs.

When integrating with form libraries, map onChange to library adapters to avoid duplicate renders.

Use controlled pattern for toggles that affect other components or persist to remote stores.

Debounce writes if persisting remotely.

Always implement onChange with idempotent handlers.

Consider optimistic UI updates with rollback paths for failed persistence.

Document expected event payload structure to ensure consistent consumer implementations.

Use icons to reinforce domain meaning (e.g., eye/eye-off).

Use sparingly to avoid visual noise.

Ensure icons are legible across sizes and themes; consider stroke weight consistency.

Prefer subtle icons that act as affordances rather than decorative elements.

Keep icons subtle and size-aligned to the track.

Ensure icons remain legible at all sizes.

Provide non-icon alternatives for assistive tech consumers (aria-label fallback).

Avoid adding heavy SVGs that increase bundle size for frequently-rendered switches.

Use for strong branding or explicit affordance.

Avoid when minimalism and clarity are preferred.

Use for clearly semantic controls like power toggles where icon adds immediate recognition.

Avoid for generic settings where icon could reduce readability.

Keep contrast sufficient against the thumb color.

Do not animate icons independently of the thumb.

Provide scalable vector icons to avoid pixelation at large sizes.

Document accessibility expectations when thumb icons replace textual cues.