# Button component specification The `Button` component allows users to commit a change or trigger an action via a single click or tap and is often found inside forms, dialogs, panels and/or pages. ## Related variant considerations The following section documents variants of the component that currently exist in Fabric and identifies variants that exist in other component libraries but don't currently exist in Fabric, documenting which component libraries have those variants. ### Variants existing in Fabric today #### Styling related The following are variants that don't affect the functionality of the `Button`, but that have a visually distinct representation. A discussion needs to happen about how we support each of these variants and the effect of our theming story in that decision (separate components, via props, etc). - `Action/Link button` - `Circular button` - `Compound button` - `Icon button` - `Primary button` - `Secondary/Default button` #### Functionality related The following are variants that are functionally different from the base `Button` variant. A discussion needs to happen about how much of this functionality belongs to base versus a different variant and about the need of maybe having a different spec for these variants if they are significantly different from the base `Button`. - `Menu button` - `Pressable` - `Split button` - `Toogle button` - > TODO - Need to discuss if functionality belongs to base button or separate variant. #### Tied to other components The following are variants that exist because of the need of `Buttons` to reside inside other components and, while functionally the same, the styling of these `Buttons` is tightly coupled with the styling of these other components. - `Command bar button` - `Message bar button` ### Variants not in Fabric but that exist in other component libraries - `Animated button` - In Semantic UI - `Block/Fluid button` - In Ant Design - In Semantic UI - In Shards React - In Stardust UI - `Button group/set` - In Ant Design - In Atlaskit - In Base Web - In Carbon Design - In Elemental UI - In Material-UI - In React Bootstrap - In Semantic UI - In Shards React - In Stardust UI - `Conditional button` - In Semantic UI - `Floating action/Raised button` - In Material-UI - In PrimeReact - `Labelled button` - In Semantic UI - `Outlined/Ghost button` - In Ant Design - In Carbon Design - In Chakra UI - In Elemental UI - In FastDNA - In Material-UI - In Shards React - `Pill/Round button` - In Ant Design - In Base Web - In PrimeReact - In Shards React - `Tertiary button` - In Base Web - In Carbon Design - In React Bootstrap ## Reference implementations The following section documents links to different UI libraries implementations of Buttons, while also providing a code sandbox with a side by side implementation of them for comparison. - [Side-by-side implementations](https://codesandbox.io/s/button-implementations-93x8z) - [Ant Design Button docs](https://ant.design/components/button/) - [Atlaskit Button docs](https://atlaskit.atlassian.com/packages/core/button) - [Base Web Button docs](https://baseweb.design/components/button/) - [Carbon Design Button docs](https://www.carbondesignsystem.com/components/button/code) - [Chakra UI Button docs](https://chakra-ui.com/button) - [Elemental UI Button docs](http://elemental-ui.com/buttons) - [Fabric Button docs](https://developer.microsoft.com/en-us/fabric#/controls/web/button) - FastDNA Button - [Docs](https://github.com/microsoft/fast-dna/tree/master/packages/fast-components-react-base/src/button) - [Example](https://explore.fast.design/components/button) - [Gestalt Button docs](https://pinterest.github.io/gestalt/?ref=designrevision.com#/Button) - [Grommet Button docs](https://v2.grommet.io/button) - [Material-UI Button docs](https://material-ui.com/components/buttons/) - [Prime React Button docs](https://www.primefaces.org/primereact/#/button) - [React Bootstrap Button docs](https://react-bootstrap.github.io/components/buttons/) - [Semantic UI Button docs](https://react.semantic-ui.com/elements/button/) - [Shards React Button docs](https://designrevision.com/docs/shards-react/component/button) - [Stardust Button docs](https://microsoft.github.io/fluent-ui-react/components/button/definition) ## Props The following section documents the properties that will become part of the new component, as well as the process for mitigating all changes when moving from Fabric and Stardust to Fluent UI. > TODO: Consult the prop wizard to derive consistently defined props. | Name | Type | Default value | Description | | ---- | ---- | ------------- | ----------- | ### Recommended component props The `Button` component should inherit the HTML props of the web `button` so that props like `onClick` and `aria` have the same typings as the native web counterparts. | Name | Type | Default value | Description | | ----------- | :-------: | :-----------: | -------------------------------------------------------------------------------------- | | `as` | `string` | | Defines a component that should be used as the root element of the `Button`. | | `className` | `string` | | Defines an additional classname to provide on the root of the `Button`. | | `disabled` | `boolean` | `false` | Defines whether the `Button` is in an enabled or disabled state. | | `href` | `string` | | Defines an href that, if provided, will make the `Button` render as an anchor. | | `primary` | `boolean` | `false` | Defines whether the visual representation of the `Button` should be emphasized or not. | > TODO: Talk about the inheritance of native props, what should we do about them? `Pick`, `Omit`, get all of them? What do we do about slots? Do we defect to `any`? ### Recommended interface props | Name | Type | Default value | Description | | ------- | :----------: | ------------- | --------------------------- | | `focus` | `() => void` | | Sets focus on the `Button`. | ### Props to be discussed | Name | Description | Concern | | -------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `allowDisabledFocus` | Defines whether disabled `Buttons` should be tabbable via keyboard navigation or not. | Should we really redefine standard behavior here? | | `checked` | Defines whether the `Button` is in a checked state. | Does this belong to the base or to a variant `ToggleButton`? | | `circular` | Defines whether the `Button` should be rendered as a circle instead of as a rectangle. | Should we still have this prop or should we generate a `CircularButton` variant via recomposition of styles? | | `primary` | Defines whether the visual representation of the `Button` should be emphasized or not. | Should we still have this prop or should we generate a `PrimaryButton` variant via recomposition of styles? | ### Fabric Button props https://developer.microsoft.com/en-us/fabric#/controls/web/button #### IButton interface | Name | Type | Notes | | ------------- | :------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------ | | `dismissMenu` | `() => void` | Should not be part of the base `Button`. Should be considered for `MenuButton`. Maybe just bring it from the `Menu` interface. | | `focus` | `() => void` | | | `openMenu` | `(shouldFocusOnContainer?: boolean, shouldFocusOnMount?: boolean) => void` | Should not be part of the base `Button`. Should be considered for `MenuButton`. Maybe just bring it from the `Menu` interface. | #### IButtonProps interface | Name | Type | Notes | | ---------------------------------- | :--------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------- | | `allowDisabledFocus` | `boolean` | Should we really redefine standard behavior here? | | `ariaDescription` | `string` | What purpose does this serve? If anything, belongs to `CompoundButton` and not to base. | | `ariaHidden` | `boolean` | Should use native `aria-hidden` instead. | | `ariaLabel` | `string` | Should use native `aria-label` instead. | | `buttonType` | `ButtonType` | Already deprecated. | | `checked` | `boolean` | Does this belong to the base or to a variant `ToggleButton`? | | `className` | `string` | | | `componentRef` | `IRefObject` | | | `data` | `any` | What purpose does this serve? Maybe remove? | | `defaultRender` | `any` | What purpose does this serve? Maybe remove? | | `description` | `string` | Already deprecated in favor of `secondaryText`. | | `disabled` | `boolean` | | | `getClassNames` | `(props) => IButtonClassNames` | Should be deprecated in favor of new composition approach. | | `getSplitButtonClassNames` | `(props) => IButtonClassNames` | Should not be part of the base `Button`. Should be considered for `SplitButton`. Should be deprecated in favor of new composition approach. | | `href` | `string` | | | `iconProps` | `IIconProps` | Should be replaced by `slotProps`. | | `keytipProps` | `IKeytipProps` | Should be removed until we add `Keytips` in Fluent UI. | | `menuAs` | `IComponentAs` | Should be deprecated in favor of slot overrides. | | `menuIconProps` | `IIconProps` | Should not be part of the base `Button` and should be replaced by `slotProps` in `MenuButton`. | | `menuProps` | `IContextualMenuProps` | Should not be part of the base `Button` and should be replaced by `slotProps` in `MenuButton`. | | `menuTriggerKeyCode` | `KeyCodes \| null` | Should not be part of the base `Button`. Should be considered for `MenuButton`. | | `onAfterMenuDismiss` | `() => void` | Should not be part of the base `Button`. Should be considered for `MenuButton`. Maybe rename to `onDismiss`? | | `onMenuClick` | `(ev?: React.MouseEvent \| React.KeyboardEvent, button?: IButtonProps) => void;` | Should not be part of the base `Button`. Should be considered for `MenuButton`. | | `onRenderAriaDescription` | `IRenderFunction` | Only keep if we are keeping `ariaDescription`. If keeping it, deprecate in favor of slot overrides. | | `onRenderChildren` | `IRenderFunction` | Should be removed or deprecated in favor of slot overrides. | | `onRenderDescription` | `IRenderFunction` | Should not be part of base `Button`. Could be considered for `CompoundButton`. In that case, deprecate in favor of slot overrides. | | `onRenderIcon` | `IRenderFunction` | Should be deprecated in favor of slot overrides. | | `onRenderMenuIcon` | `IRenderFunction` | Should not be part of the base `Button`. Should be considered for `MenuButton`. Should be deprecated in favor of slot overrides. | | `onRenderMenu` | `IRenderFunction` | Should not be part of the base `Button`. Should be considered for `MenuButton`. Should be deprecated in favor of slot overrides. | | `onRenderText` | `IRenderFunction` | Should be deprecated in favor of slot overrides. | | `persistMenu` | `boolean` | Should this be handled as part of the menu `slotProps` instead of being a separate prop altogether? | | `primary` | `boolean` | | | `primaryActionButtonProps` | `IButtonProps` | Should not be part of the base `Button`. Should be replaced by a slot in `SplitButton`. | | `primaryDisabled` | `boolean` | Should not be part of the base `Button`. Should be considered for `SplitButton`. | | `renderPersistedMenuHiddenOnMount` | `boolean` | Already deprecated. | | `rootProps` | `React.ButtonHTMLAttributes \| React.AnchorHTMLAttributes` | Already deprecated. Should use `slotProps` instead. | | `secondaryText` | `string` | Should not be part of the base `Button`. Should be replaced by a slot in `CompoundButton`. | | `split` | `boolean` | Should be deprecated in favor of a `SplitButton` variant. | | `splitButtonAriaLabel` | `string` | Should not be part of the base `Button`. Should be considered for `SplitButton`. Maybe rename to `secondaryActionAriaLabel`? | | `splitButtonMenuProps` | `IButtonProps` | Should not be part of the base `Button`. Should be replaced by a slot in `SplitButton`. | | `styles` | `IButtonStyles` | Should be deprecated in favor of recomposition. | | `theme` | `ITheme` | Should not show up in the public props contract. | | `text` | `string` | Should be replaced by a slot. | | `toggle` | `boolean` | Does this belong to the base or to a variant `ToggleButton`? | | `toggled` | `boolean` | Already deprecated in favor of `checked`. | | `uniqueId` | `string \| number` | This is used for keytip support in Fabric. Maybe remove it until we add `Keytips` in Fluent UI? | ### Stardust Button props #### ButtonProps interface | Name | Type | Notes | | --------------- | :----------------------------------: | --------------------------------------------------------------------------------------------------------------------------------- | | `accessibility` | `Accessibility` | Why would a user need this as a prop? | | `circular` | `boolean` | | | `disabled` | `boolean` | | | `fluid` | `boolean` | Should this be a prop or should the library have a separate `BlockButton` variant? | | `icon` | `ShorthandValue` | Should be replaced by a slot. | | `iconOnly` | `boolean` | Should this be a prop or should the library have a separate `IconButton` variant? | | `iconPosition` | `'before' \| 'after'` | Should be deprecated in favor of view recomposition. | | `loader` | `ShorthandValue` | What's the use case for this? | | `loading` | `boolean` | Should be deprecated in favor of recomposition. | | `onClick` | `ComponentEventHandler` | Should be replaced by the native event signature from which we extend. | | `onFocus` | `ComponentEventHandler` | Should be replaced by the native event signature from which we extend. | | `primary` | `boolean` | | | `secondary` | `boolean` | Does this change styling or is this just the default? | | `size` | `SizeValue` | Should this prop be provided or is this just a matter that could be solved via styling and recomposition? | | `text` | `boolean` | Should this be a prop or should the library have a separate `GhostButton` variant? If a prop, should it be named `ghost` instead? | ### Conversion process from Fabric 7 to Fluent UI Button #### IButton interface | Name | Action to take/taken | Property transitioned? | Breaking change? | Codemod/Shim created? | | ------------- | -------------------- | :--------------------: | :--------------: | :-------------------: | | `dismissMenu` | TBD | ❌ | ❌ | ❌ | | `focus` | TBD | ❌ | ❌ | ❌ | | `openMenu` | TBD | ❌ | ❌ | ❌ | #### IButtonProps interface | Name | Action to take/taken | Property transitioned? | Breaking change? | Codemod/Shim created? | | ---------------------------------- | ------------------------------------- | :--------------------: | :-------------------------------------: | :-------------------: | | `allowDisabledFocus` | TBD | ❌ | ❌ | ❌ | | `ariaDescription` | TBD | ❌ | ❌ | ❌ | | `ariaHidden` | TBD | ❌ | ❌ | ❌ | | `ariaLabel` | TBD | ❌ | ❌ | ❌ | | `buttonType` | Removing as it is already deprecated. | ☑ | No, because prop is already deprecated. | ❌ | | `checked` | TBD | ❌ | ❌ | ❌ | | `className` | TBD | ❌ | ❌ | ❌ | | `componentRef` | TBD | ❌ | ❌ | ❌ | | `data` | TBD | ❌ | ❌ | ❌ | | `defaultRender` | TBD | ❌ | ❌ | ❌ | | `description` | Removing as it is already deprecated. | ☑ | No, because prop is already deprecated. | ❌ | | `disabled` | TBD | ❌ | ❌ | ❌ | | `getClassNames` | TBD | ❌ | ❌ | ❌ | | `getSplitButtonClassNames` | TBD | ❌ | ❌ | ❌ | | `href` | TBD | ❌ | ❌ | ❌ | | `iconProps` | TBD | ❌ | ❌ | ❌ | | `keytipProps` | TBD | ❌ | ❌ | ❌ | | `menuAs` | TBD | ❌ | ❌ | ❌ | | `menuIconProps` | TBD | ❌ | ❌ | ❌ | | `menuProps` | TBD | ❌ | ❌ | ❌ | | `menuTriggerKeyCode` | TBD | ❌ | ❌ | ❌ | | `onAfterMenuDismiss` | TBD | ❌ | ❌ | ❌ | | `onMenuClick` | TBD | ❌ | ❌ | ❌ | | `onRenderAriaDescription` | TBD | ❌ | ❌ | ❌ | | `onRenderChildren` | TBD | ❌ | ❌ | ❌ | | `onRenderDescription` | TBD | ❌ | ❌ | ❌ | | `onRenderIcon` | TBD | ❌ | ❌ | ❌ | | `onRenderMenuIcon` | TBD | ❌ | ❌ | ❌ | | `onRenderMenu` | TBD | ❌ | ❌ | ❌ | | `onRenderText` | TBD | ❌ | ❌ | ❌ | | `persistMenu` | TBD | ❌ | ❌ | ❌ | | `primary` | TBD | ❌ | ❌ | ❌ | | `primaryActionButtonProps` | TBD | ❌ | ❌ | ❌ | | `primaryDisabled` | TBD | ❌ | ❌ | ❌ | | `renderPersistedMenuHiddenOnMount` | Removing as it is already deprecated. | ☑ | No, because prop is already deprecated. | ❌ | | `rootProps` | Removing as it is already deprecated. | ☑ | No, because prop is already deprecated. | ❌ | | `secondaryText` | TBD | ❌ | ❌ | ❌ | | `split` | TBD | ❌ | ❌ | ❌ | | `splitButtonAriaLabel` | TBD | ❌ | ❌ | ❌ | | `splitButtonMenuProps` | TBD | ❌ | ❌ | ❌ | | `styles` | TBD | ❌ | ❌ | ❌ | | `theme` | TBD | ❌ | ❌ | ❌ | | `text` | TBD | ❌ | ❌ | ❌ | | `toggle` | TBD | ❌ | ❌ | ❌ | | `toggled` | Removing as it is already deprecated. | ☑ | No, because prop is already deprecated. | ❌ | | `uniqueId` | TBD | ❌ | ❌ | ❌ | ### Conversion process from Stardust to Fluent UI Button #### ButtonProps interface | Name | Action to take/taken | Property transitioned? | Breaking change? | Codemod/Shim created? | | --------------- | -------------------- | :--------------------: | :--------------: | :-------------------: | | `accessibility` | TBD | ❌ | ❌ | ❌ | | `circular` | TBD | ❌ | ❌ | ❌ | | `disabled` | TBD | ❌ | ❌ | ❌ | | `fluid` | TBD | ❌ | ❌ | ❌ | | `icon` | TBD | ❌ | ❌ | ❌ | | `iconOnly` | TBD | ❌ | ❌ | ❌ | | `iconPosition` | TBD | ❌ | ❌ | ❌ | | `loader` | TBD | ❌ | ❌ | ❌ | | `loading` | TBD | ❌ | ❌ | ❌ | | `onClick` | TBD | ❌ | ❌ | ❌ | | `onFocus` | TBD | ❌ | ❌ | ❌ | | `primary` | TBD | ❌ | ❌ | ❌ | | `secondary` | TBD | ❌ | ❌ | ❌ | | `size` | TBD | ❌ | ❌ | ❌ | | `text` | TBD | ❌ | ❌ | ❌ | ## DOM Structure The following section documents the DOM structure for the component from different component library examples and then suggests a recommended DOM taking into consideration common patterns between the libraries reviewed. ### Ant Design Button #### Example DOM ```html ``` #### Considerations - `Children` of `Button` components are rendered inside a `span`. ### Atlaskit Button #### Example DOM ```html ``` #### Considerations - Icons can go before and/or after the `children` via the `iconBefore` and `iconAfter` props. - Uneeded extra `span` wrapper inside of `button` tag. - Both `icons` and `children` are wrapped in styled `spans`. ### Base Web Button #### Example DOM ```html ``` #### Considerations - The concept of icon does not exist here, instead you can add _enhancers_ which are effectively a `React.Node` that are placed behind or after the `children` under a styled `div`. ### Carbon Design Button #### Example DOM ```html ``` #### Considerations None. ### Chakra UI Button #### Example DOM ```html ``` #### Considerations - Icons can go before and/or after the `children` via the `leftIcon` and `rightIcon` props. ### Elemental UI Button #### Example DOM ```html ``` #### Considerations - Has no built-in support for icons via props. ### Fabric Button #### Example DOM ```html ``` #### Considerations - Icons via props are only supported on the left of the `children` inside the `Button`. - Text can be provided via a `text` prop and via `children`. - If both are provided, only the one provided via the `text` prop is rendered. - If `children` is not a `string`, then both are rendered. - Text provided via the `text` prop is rendered inside two nested styled `spans`, one for the text container and one for the actual text. ### FastDNA Button #### Example DOM ```html ``` #### Considerations - Has no built-in support for icons via props. - Extra styled `span` wraps `children` inside of the `Button`. ### Gestalt Button #### Example DOM ```html ``` #### Considerations - Has no built-in support for icons via props. - Extends to container's width by default. - Text has to be provided via a `text` prop as `children` are not rendered. ### Grommet Button #### Example DOM ```html ``` #### Considerations - Icons via props are only supported on the left of the `children` inside the `Button`. - Text has to be provided via the `label` prop as `children` are not rendered. - A styled `div` is added in-between the icon and the text to add a _gap_ between them. - Uneeded extra `div` wrapper inside of `button` tag. ### Material-UI Button #### Example DOM ```html ``` #### Considerations - Icons can go before and/or after the `children` via the `startIcon` and `endIcon` props. - Both `children` and icons are wrapped inside of a `styled` span. - An extra `span` is added inside of the `Button` for styling the _ripple effect_ in Material-UI. ### Prime React Button #### Example DOM ```html ``` #### Considerations - Icons can go before and/or after the `children` via the `iconPos` prop. - Icons are rendered via the `:before` and `content` css props. ### React Bootstrap Button #### Example DOM ```html ``` #### Considerations - Has no built-in support for icons via props. ### Semantic UI Button #### Example DOM ```html ``` #### Considerations - Icons via props are only supported if `children` are not being rendered. - Icons are rendered via the `:before` and `content` css props. ### Shard React Button #### Example DOM ```html ``` #### Considerations - Has no built-in support for icons via props. ### Stardust Button #### Example DOM ```html ``` #### Considerations - Icons via props are only supported if `children` are not being rendered. - The icon is rendered inside of a styled `span`. - Text can be provided via both the `content` prop and `children`. - Text provided via the `content` prop is rendered inside of a styled `span`. ### Recommended DOM After looking at all the component libraries above and taking into consideration common patterns the following DOM is recommended. #### Regular buttons ```html ``` #### Buttons rendered as links ```html {children} ``` ### Slots From the recommended DOM above we can indicate which slots are going to be required: | Name | Considerations | | ----------- | -------------- | | `root` | | | `startIcon` | | | `endIcon` | | ### Considerations that need discussion - Do we provide both a `startIcon` and `endIcon` as recommended above? - Alternatively we could provide just an `icon` slot that is always on the left and provide a _"button with icon on the right"_ variant via view recomposition. - Previously we had a `text` prop. Our recommended DOM above is taking that out in favor of just having `children`. - Do we want to still have a `text` or `content` prop/slot? - If we do, where do we place `children` in relation to it? ## Behaviors Aria spec: https://www.w3.org/TR/wai-aria-1.1/#button https://www.w3.org/TR/wai-aria-practices/#button Fluent UI HIG: https://microsoft.sharepoint-df.com/:w:/r/teams/OPGUXLeads/_layouts/15/Doc.aspx?sourcedoc=%7B150DD97E-0ECE-460D-B868-8BCB91FCB4BA%7D&file=Buttons.docx&action=default&mobileredirect=true ### States The following section describes the different states in which a `Button` can be throughout the course of interaction with it. #### Enabled state An enabled `Button` communicates interaction by having styling that invite the user to click/tap on it to trigger an action. #### Disabled state A disabled `Button` is non-interactive, disallowing the user to click/tap on it to trigger an action. Typically disabled browser elements do now allow focus. This makes the control difficult for a blind user to know about it, or why it's disabled, without scanning the entire page. Therefore it is recommended to allow focus on disabled components and to make them readonly. This means we use `aria-disabled` attributes, and not `disabled` attributes, for defining a disabled state. This may sometimes require special attention to ignoring input events in the case a browser element might do something. In the past we've introduced an `allowDisabledFocus` prop for component users to control this behavior. #### Hovered state A hovered `Button` changes styling to communicate that the user has placed a cursor above it. #### Focused state A focused `Button` changes styling to communicate that the user has placed keyboard focus on it. This styling is usually the same to the one in the hovered state. #### Pressed state A pressed `Button` changes styling to communicate that the user has clicked/tapped on it. #### States that need discussion - Checked state in `Toggle buttons`, `Menu buttons` and `Split buttons`. ### Keyboard interaction The following is a set of keys that interact with the `Button` component: | Key | Description | | ------- | ------------------------------- | | `Space` | Triggers the `Button's` action. | | `Enter` | Triggers the `Button's` action. | ### Cursor interaction Test: Possible to use this to capture mouse, though Safari does not have compatibility: https://developer.mozilla.org/en-US/docs/Web/API/Element/setPointerCapture - `mouseenter`: Should immediately change the styling of the `Button` so that it appears to be hovered. - `mouseleave`: Should immediately remove the hovered styling of the `Button`. - `mousedown`: Should immediately change the styling of the `Button` so that it appears to be pressed. - `mouseup`: - If triggered while cursor is still inside of the `Button's` boundaries, then it should trigger the `Button's` action and immediately remove the pressed styling of the `Button`. - If triggered outside of the `Button's` boundaries, then it should immmediately remove the pressed styling of the `Button` without triggering the `Button's` action. ### Touch interaction The same behavior as above translated for touch events. This means that there is no equivalent for `mouseenter` and `mouseleave`, which makes it so that the hovered state cannot be accessed. ### Screen reader accessibility #### `root`: - Should render the native element using the `as` prop, defaulting to a native `button` element, or a native `a` element if the `href` prop has been set. - Should mix in the native props expected for the `button` or `a` native elements depending on if the `href` prop has been set. - Should be keyboard tabbable and focusable. #### Accessibility concerns for the user. The `aria-label`, `aria-labelledby` and `aria-describedby` properties are surfaced to the component interface but are required to be set by the component user to meet accessibility requirements. ## Themability and customization ### Composition The `Button` component uses `react-texture` to provide a recomposable implementation that has no runtime performance penalties. The `BaseButton` implementation can be used to provide new `slots` and default `props` without the application of additional styling: ```tsx const FooButton = BaseButton.compose({ tokens: {}, styles: {}, slots: {} }); const onClickAlert = () => { alert('Clicked'); }; render() { Click me! } ``` ## Class names 1 per slot 1 per state, tagged on root ### Component design tokens > Tokens represent the general look and feel of the various visual slots. Tokens feed into the styling at the right times in the right slot. > > Regarding naming conventions, use a camelCased name following this format: > `{slot}{property}{state (or none for default)}`. For example: `thumbSizeHovered`. > > Common property names: `size`, `background`, `color`, `borderRadius` > > Common states: `hovered`, `pressed`, `focused`, `checked`, `checkedHovered`, `disabled` #### Button tokens: | Name | Considerations | | ------------------------ | -------------- | | `background` | | | `backgroundDisabled` | | | `backgroundHovered` | | | `backgroundPressed` | | | `borderColor` | | | `borderColorDisabled` | | | `borderColorHovered` | | | `borderColorPressed` | | | `borderRadius` | | | `borderStyle` | | | `borderWidth` | | | `boxShadow` | | | `boxShadowDisabled` | | | `boxShadowHovered` | | | `boxShadowPressed` | | | `color` | | | `colorDisabled` | | | `colorHovered` | | | `colorPressed` | | | `fontFamily` | | | `fontSize` | | | `fontWeight` | | | `height` | | | `lineHeight` | | | `margin` | | | `maxHeight` | | | `maxWidth` | | | `minHeight` | | | `minWidth` | | | `outlineWidth` | | | `padding` | | | `width` | | | `startIconColor` | | | `startIconColorDisabled` | | | `startIconColorHovered` | | | `startIconColorPressed` | | | `startIconFontSize` | | | `startIconFontWeight` | | | `endIconColor` | | | `endIconColorDisabled` | | | `endIconColorHovered` | | | `endIconColorPressed` | | | `endIconFontSize` | | | `endIconFontWeight` | | #### Primary Button specific tokens: | Name | Considerations | | ------------------------------- | -------------- | | `backgroundPrimary` | | | `backgroundPrimaryDisabled` | | | `backgroundPrimaryHovered` | | | `backgroundPrimaryPressed` | | | `borderColorPrimary` | | | `borderColorPrimaryDisabled` | | | `borderColorPrimaryHovered` | | | `borderColorPrimaryPressed` | | | `colorPrimary` | | | `colorPrimaryDisabled` | | | `colorPrimaryHovered` | | | `colorPrimaryPressed` | | | `startIconColorPrimary` | | | `startIconColorPrimaryDisabled` | | | `startIconColorPrimaryHovered` | | | `startIconColorPrimaryPressed` | | | `endIconColorPrimary` | | | `endIconColorPrimaryDisabled` | | | `endIconColorPrimaryHovered` | | | `endIconColorPrimaryPressed` | | NOTE! Stardust does not follow this convention. Their `Button` currently uses these tokens: ``` backgroundColor: string backgroundColorActive: string backgroundColorDisabled: string backgroundColorFocus: string backgroundColorHover: string borderColor: string borderColorDisabled: string borderColorHover: string borderRadius: string boxShadow: string circularBackgroundColor: string circularBackgroundColorActive: string circularBackgroundColorFocus: string circularBackgroundColorHover: string circularBorderColor: string circularBorderColorFocus: string circularBorderColorHover: string circularBorderRadius: string circularColor: string circularColorActive: string color: string colorDisabled: string colorFocus: string colorHover: string contentFontSize: string contentFontWeight: FontWeightProperty contentLineHeight: string height: string loaderBorderSize: string loaderSize: string loaderSvgAnimationHeight: string loaderSvgHeight: string loadingMinWidth: string maxWidth: string minWidth: string padding: string sizeSmallContentFontSize: string sizeSmallContentLineHeight: string sizeSmallHeight: string sizeSmallLoaderBorderSize: string sizeSmallLoaderSvgAnimationHeight: string sizeSmallLoaderSvgHeight: string sizeSmallMinWidth: string sizeSmallPadding: string textColor: string textColorDisabled: string textColorHover: string textPrimaryColor: string textPrimaryColorHover: string ``` ### To be discussed - What do we do about high contrast? Do we provide additional tokens? ## Use cases > TODO: Example use cases ## Compatibility with other libraries > TODO: If this component represents a selected value, how will that be used in an HTML form? Is there a code example to illustrate? > TODO: Is it possible this component could be rendered in a focus zone? If so, should the focus model change in that case?