feat(button): aligns Button with the new DS styling and functionality

[damienrobson-sage]

Proposed behaviour

• Introduce the "next" version of Button that consumers can start to import and use in place of the existing Button implementation
• Deprecate darkBackground, gradient-grey and gradient-white ButtonType from current button implementation
• Deprecate isWhite prop from current button implementation
• Deprecate destructive prop from current button implementation
• Deprecate subtext prop from current button implementation
• Deprecate buttonType prop from current button implementation

Current behaviour

The Button component is not aligned with the latest DS requirements.

Checklist

• Commits follow our style guide
• Related issues linked in commit messages if required
• Screenshots are included in the PR if useful
• All themes are supported if required
• Unit tests added or updated if required
• Playwright automation tests added or updated if required
• Storybook added or updated if required
• Translations added or updated (including creating or amending translation keys table in storybook) if required
• Typescript d.ts file added or updated if required
• Related docs have been updated if required

QA

• Tested in provided StackBlitz sandbox/Storybook
• Add new Playwright test coverage if required
• Carbon implementation matches Design System/designs
• UI Tests GitHub check reviewed if required

Additional context

• The existing Button component's documentation has been moved to the Deprecated section of Storybook and points users towards the newer documentation
• The newer documentation references the older documentation for consumers that still require it.

Testing instructions

Use the new Storybook documentation to check the new functionality

[nuria1110]

Looks pretty good, just a couple suggestions from me.

Also looks like there is a small issue with the height of the button not adjusting when text wraps:

[edleeks87]

Nice work @damienrobson-sage, I think we need to look into the fallbacks it's a bit up in the air right now we're trying to decide if we need them at all and if we do should they just fallback to the legacy ones, to me hardcoding them feels redundant as it negates the point of the tokens and the wrapper. I'll let you know where we get with that so I've not commented on them specifically for now.

I also think the commit message could do with some tweaks, currently the release note will just say aligns Button with the new DS styling and functionality. I think it's worth being a bit more descriptive in of what's changed, that may well need to be in a commit message comment that we copy into the release notes but I think it will be more helpful than the current. It also might be worth splitting the adding of the new and deprecating the old into separate commits.

[ljemmo]

Hey @edleeks87 - left a couple of comments inline where layout spacing tokens were used inline instead of comp spacing tokens.

Additionally, i found these other elements to consider:

1. When a button is composed with an icon, it appears we are consuming old tokens instead of new:

2. Icon only button example is not a circle, it should have the same width as height. Figma link here.

3. Inverse only has 1 example (primary button). For completeness it might be useful to show all the other inverse options in Storybook for devs to understand what they would look like:

4. I would expect the cursor: not-allowed; treatment to be applied to disabled button but currently there's no cursor change.

[ljemmo]

@edleeks87 the spacing token consumed here says layout. These are reserved for layout stacks such as groups of tiles or buttons. Instead the token consumed should be --global-space-comp-L for 16px left and right padding.

[ljemmo]

@edleeks87 Large size should consume --global-space-comp-L also

[clairedenning]

I've reviewed Luke's requests and the subsequent changes, and everything looks good to me!