🧩 Button Widget

A customizable button widget that adapts its style, size, colors, and configuration based on parameters. It supports multiple priorities (primary, secondary, tertiary) and configurations (filled, fab, outlined, naked, glass, magic), and handles states like disabled, pressed, and hovered.

The Button widget is ideal for creating interactive actions in modals, sections, or as standalone components, especially when used with ActionWidget for grouped button layouts.

🧱 Parameters:

[label] – String? – Text displayed inside the button. Optional, but at least one of label, leadingIcon, or trailingIcon must be provided.

[leadingIcon] – IconData? – Icon displayed before the text. Optional.

[trailingIcon] – IconData? – Icon displayed after the text. Optional.

[onPressed] – VoidCallback? – Callback triggered when the button is pressed. If null or isDisabled is true, the button is disabled.

[isDisabled] – bool – Whether the button is disabled. Defaults to false.

[size] – ButtonSize – Size of the button (small, medium, large, xl). Defaults to ButtonSize.medium.

[priority] – ButtonPriority – Visual priority (primary, secondary, tertiary). Defaults to ButtonPriority.primary.

[config] – ButtonConfiguration – Appearance and behavior configuration (filled, fab, outlined, naked, glass, magic). Defaults to ButtonConfiguration.filled.

[backgroundColor] – Color? – Custom background color. Overrides the default color defined by priority and config.

[textColor] – Color? – Custom text color. Overrides the default text color.

[iconColor] – Color? – Custom icon color. Overrides the default icon color.

[borderColor] – Color? – Custom border color for outlined or glass configurations.

[width] – double? – Fixed width for the button. If null, the button sizes to its content.

[gap] – double – Spacing between the label and icons. Defaults to 8.0.

[borderRadius] – double? – Radius of the button corners. Defaults to Tokens.borderRadiusBase.

[fill] – bool – Expands the button to fill available space when used in a centered ActionWidget. Defaults to false.

🎨 Supported Configurations

• Configuration Description
• filled Full colored background.
• fab Floating Action Button style with elevated shape.
• outlined Transparent background with a border.
• naked Transparent background, no border.
• glass Semi-transparent background effect.
• magic (Reserved for future styles).

🎯 Behavior and States

• Icon-only buttons ➔ Use a circular shape (for non-fab) or a compact rounded rectangle (for fab), with no padding.
• Colors ➔ Background, text, and border colors adapt dynamically based on priority, config, and ButtonState (enabled, hovered, pressed, focused, disabled) using mix_tokens.dart.
• States ➔ Interactive states are fully supported:
• • enabled: Default appearance.
• • hovered: Subtle color change (e.g., Tokens.surfaceVariant for filled primary).
• • pressed: Distinct color (e.g., Tokens.primary for filled primary).
• • focused: Similar to hovered for accessibility.
• • disabled: Muted colors (e.g., Tokens.surfaceVariant).
• Overlay ➔ For filled with primary, an overlay effect is applied for hovered, pressed, and focused states.

🎯 Usage Example:

Button(
  label: "Save",
  leadingIcon: Icons.save,
  onPressed: () {
  // Perform save action
  },
  size: ButtonSize.large,
  priority: ButtonPriority.primary,
  config: ButtonConfiguration.filled,
  borderRadius: 16,
  )
  leadingIcon: Icons.add,
  onPressed: () {},
  size: ButtonSize.small,
  config: ButtonConfiguration.fab,
)

---

📌 Notes:

Responsive Padding: Padding is calculated based on Tokens.getPadding(screenWidth) with a clamp of 12–20, ensuring adaptive spacing across screen sizes. Centralized Styles: Colors, font sizes, and border radius are managed via mix_tokens.dart (e.g., Tokens.primary, Tokens.fontFamilyPrimary, Tokens.borderRadiusBase). ButtonSize: Affects height (36–60), font size (via Tokens.textSizes), and padding. ButtonPriority: Determines color schemes (e.g., Tokens.primary, Tokens.secondary). ButtonConfiguration: Defines the visual style and behavior (e.g., elevation for fab, transparency for naked). Fill: When fill = true in a centered ActionWidget, the button expands proportionally with spacers. Accessibility: Consider adding Semantics(button: true, label: label) for screen readers. Integration: Commonly used within ActionWidget for grouped actions in Section or modals.