Proposal: Consolidate minimal and outlined props on Button components

[ggdouglas]

Problem

The current Button components offer three stylistic options: "default," "minimal," and "outlined." Although these styles are mutually exclusive, their corresponding props, minimal and outlined, can both be applied simultaneously. This results in an overly complex API and can cause confusion and unintended styling conflicts. For instance, setting both minimal={true} and outlined={true} leads to the "outlined" styles overriding the "minimal" styles, which can be unintuitive for developers.

Proposal

We propose consolidating the minimal and outlined boolean props into a single enum prop named variant. The variant prop will accept the following values: "solid" (the default), "minimal", and "outlined".

type ButtonVariant = "solid" | "minimal" | "outlined";

To implement this change:

• Deprecate the minimal and outlined props, indicating their removal in a future major version.
• Provide migration instructions and codemods to assist developers in updating their codebases.
• Internally, the <Button> component will continue to use the same Classes.MINIMAL and Classes.OUTLINED classes, applied through the variant prop.

blueprint/packages/core/src/components/button/buttons.tsx

Lines 97 to 98 in 5d092cd

	[Classes.MINIMAL]: minimal,
	[Classes.OUTLINED]: outlined,

Examples:

// Before
<Button minimal={true} />

// After
<Button variant="minimal" />

// Before
<Button outlined={true} />

// After
<Button variant="outlined" />

Benefits

By unifying these styling options under the variant prop, we simplify the API and eliminate the possibility of mutually exclusive props being applied simultaneously. Setting "solid" as the default variant minimizes migration efforts, as existing buttons without the variant prop will maintain their current styling.

Affected Components

• <AnchorButton>
• <Button>
• <ButtonGroup>

Addendum

The following components also utilize the minimal prop. We need to determine whether these components should be updated for consistency with the proposed changes to the Button component, or if their minimal prop should remain unchanged:

• <Callout>
• <DialogFooter>
• <HTMLSelect>
• <Popover>
• <Tag> / <CompoundTag>

[ggdouglas]

#7197

[nerdstep]

This could be solved partly without a breaking change by using a discriminated union type, i.e.

type ButtonProps =
  | { minimal?: true; outlined?: never }
  | { minimal?: never; outlined?: true }

Of course that would only help TypeScript consumers. 🤷‍♂

To help non-TS consumers, a warning could be output to the console (when in development environment).