Button

Primary for highest-priority, single action per view.

Secondary/tertiary for less prominent alternatives.

Use neutral variants for contextual actions that should not compete visually with CTAs.

Reserve error and warning variants for flows that require explicit user acknowledgement.

Do not stack multiple primaries together.

Use destructive (error) variant only for irreversible ops.

Instrument variant usage to track UX patterns and detect misuse across large apps.

Provide clear migration notes when changing the default variant mapping in a major release.

Use solid for CTAs; outline for secondary/inverse surfaces.

Use dashed/ghost patterns for low-emphasis utilities.

Prefer no-outline when embedding buttons into dense UI panels to minimize stroke noise.

Use glowing sparingly and reserve for micro-interactions or marketing surfaces only.

Avoid glowing for critical or enterprise contexts.

Maintain sufficient hit affordance with no-outline.

Avoid heavy box-shadow/glow on many elements simultaneously to keep paint budgets reasonable.

Provide CSS-only fallbacks for appearance options to support environments without full JS hydration.

Use smaller sizes for dense toolbars and compact UIs.

Use larger sizes for primary CTAs and mobile ergonomics.

Prefer consistent padding tokens across sizes to maintain rhythm across components.

Scale icons and spinner assets proportionally when changing size to avoid visual imbalance.

Keep size consistent within the same context/surface.

Respect minimum hit area (~44×44px) for touch targets.

Provide clear size mapping in component docs so consumers can programmatically choose sizes.

Avoid hard-coded font sizes inside buttons; derive from typography tokens for theme compliance.

Gate actions during async processing or unmet prerequisites.

Prevent destructive ops when user lacks authorization.

Disable during automatic retries or pending network reconciliation to avoid duplicate side-effects.

Conditionally disable when dependent form fields are invalid or validation is in-flight.

Pair with tooltip or helper text to explain why it's disabled.

Maintain focus order; use aria-disabled for non-native buttons.

Expose semantic attributes (data-disable-reason) for telemetry and test automation.

Ensure disabled visuals are covered by unit/integration tests to prevent regressions.

Align radius with product-wide shape semantics.

Use sharper corners for enterprise-dense layouts.

Use tokenized radius values to preserve cross-component consistency.

Consider platform affordances (iOS vs Android metaphors) when choosing extreme radii for mobile surfaces.

Avoid mixing multiple radii in one action cluster.

Maintain consistent radius across button + dropdown combos.

When theming, provide a clear override strategy to prevent accidental radius fragmentation.

Verify radius rendering at scale with visual regression snapshots to catch clipping issues.

Use icons to reinforce meaning, not replace labels.

Icon-only buttons require accessible labels (aria-label).

Prefer a single icon library for consistency in stroke/weight across the UI.

Align icon metrics to text baseline to avoid optical misalignment in mixed-size buttons.

Keep icon size aligned with text height.

Ensure consistent spacing between icon and label.

Provide accessible name via aria-label when children are omitted.

Avoid animating icon layout shifts during label/content changes to prevent reflow.

Apply for async tasks expected to exceed ~500ms.

Lock repetitive triggers to prevent duplicate requests.

Use loading states for multi-step workflows where intermediate state persists across screens.

Prefer inline loaders rather than full-overlay loaders for non-blocking operations.

Swap label to progress-friendly copy (e.g., “Saving…”).

Restore focus to the button on completion for continuity.

Provide ARIA live updates where appropriate to announce completion to assistive tech.

Ensure spinner animation is paused or simplified in low-power modes.

Cluster mutually related actions (e.g., formatting).

Use for mode-switching or segmented controls.

Apply for quick-action rows where grouping reduces cognitive load.

Use grouped buttons for responsive toolbars that collapse into menus on narrow viewports.

Preserve logical order and consistent sizes.

Support arrow-key navigation for accessibility.

Ensure focus ring and selected-state visuals are propagated consistently.

Do not mix unrelated actions inside a single group; prefer contextual separation.

Apply one coherent variant per group.

Use neutral/default for mixed-importance utilities.

Avoid variant inheritance ambiguity; document precedence rules for group vs child.

Use variant mapping to align with product-level semantic tokens for analytics consistency.

Avoid mixing semantic variants within one group.

Ensure contrast remains accessible on all states.

Add visual badges or separators when groups contain a mix of semantic importance to avoid misclicks.

Provide clear migration guidance if variant palettes change between versions.

Sync size with nearby inputs and controls.

Use larger sizes for touch-first contexts.

Use group sizes to enforce visual parity across dynamic button sets.

Prefer size tokens that map directly to spacing and typography scales.

Do not mix sizes inside the same group.

Respect vertical rhythm across stacked groups.

Expose size-related CSS variables for consumer overrides when necessary.

Document responsive size behavior (e.g., auto-scaling on smaller viewports).

Match group radius to global container shape tokens.

Use full for pill-style segmented controls.

Apply appropriate clipping rules to avoid adjacent element overlap when using large radii.

Ensure consistent radius behavior for first/last children when dynamic children are added/removed.

Avoid mixed radii within a single group.

Ensure first/last items visually cap the group correctly.

Provide utilities to normalize border-radius when combining with external wrappers.

Validate radius combinations visually in both LTR and RTL contexts.

Horizontal for toolbar-like interactions.

Vertical for narrow columns and mobile stacks.

Switch alignment responsively for smaller breakpoints to preserve touch targets.

Consider grouping alignment with adjacent layout components (inputs, labels) for visual coherence.

Mirror alignment with surrounding layout flow.

Maintain consistent spacing between grouped items.

When stacking vertically, ensure accessible hit area and consistent vertical rhythm.

Support reverse ordering for RTL locales and document expected behavior.

Disable an entire cluster when upstream state blocks all.

Use to prevent partial interaction in multi-step flows.

Use group-level disabling for transactional flows awaiting backend confirmation.

Leverage disabled groups during role-based access reviews to reduce per-button overrides.

Communicate why the group is disabled (tooltip/helper).

Allow granular overrides only when explicitly required.

Expose a single override API for exceptions to avoid prop explosion.

Document precedence rules when child-level disables differ from group-level.