website: Buttons documentation update

apps/website/src/examples/Button.borderless.tsx

@@ -0,0 +1,24 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Button, Flex } from '@itwin/itwinui-react';
+import { SvgAdd, SvgCheckmarkSmall } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <Flex>
+      <Button styleType='borderless'>Default</Button>
+      <Button styleType='borderless' disabled>
+        Disabled
+      </Button>
+      <Button styleType='borderless' startIcon={<SvgAdd />}>
+        With startIcon
+      </Button>
+      <Button styleType='borderless' endIcon={<SvgCheckmarkSmall />}>
+        With endIcon
+      </Button>
+    </Flex>
+  );
+};

apps/website/src/examples/Button.cta.tsx

@@ -0,0 +1,24 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Button, Flex } from '@itwin/itwinui-react';
+import { SvgAdd, SvgCheckmarkSmall } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <Flex>
+      <Button styleType='cta'>Default</Button>
+      <Button styleType='cta' disabled>
+        Disabled
+      </Button>
+      <Button styleType='cta' startIcon={<SvgAdd />}>
+        With startIcon
+      </Button>
+      <Button styleType='cta' endIcon={<SvgCheckmarkSmall />}>
+        With endIcon
+      </Button>
+    </Flex>
+  );
+};

apps/website/src/examples/Button.default.tsx

@@ -4,13 +4,15 @@
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
 import { Button, Flex } from '@itwin/itwinui-react';
+import { SvgAdd, SvgCheckmarkSmall } from '@itwin/itwinui-icons-react';
 
 export default () => {
   return (
     <Flex>
-      <Button size='small'>Small</Button>
       <Button>Default</Button>
-      <Button size='large'>Large</Button>
+      <Button disabled>Disabled</Button>
+      <Button startIcon={<SvgAdd />}>With startIcon</Button>
+      <Button endIcon={<SvgCheckmarkSmall />}>With endIcon</Button>
     </Flex>
   );
 };

apps/website/src/examples/Button.highvisibility.tsx

@@ -0,0 +1,24 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Button, Flex } from '@itwin/itwinui-react';
+import { SvgAdd, SvgCheckmarkSmall } from '@itwin/itwinui-icons-react';
+
+export default () => {
+  return (
+    <Flex>
+      <Button styleType='high-visibility'>Default</Button>
+      <Button styleType='high-visibility' disabled>
+        Disabled
+      </Button>
+      <Button styleType='high-visibility' startIcon={<SvgAdd />}>
+        With startIcon
+      </Button>
+      <Button styleType='high-visibility' endIcon={<SvgCheckmarkSmall />}>
+        With endIcon
+      </Button>
+    </Flex>
+  );
+};

apps/website/src/examples/Button.size.tsx

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Button, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex>
+      <Button size='small'>Small</Button>
+      <Button>Medium</Button>
+      <Button size='large'>Large</Button>
+    </Flex>
+  );
+};

apps/website/src/examples/IconButton.main.tsx

@@ -3,13 +3,18 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-import { IconButton } from '@itwin/itwinui-react';
-import { SvgAdd } from '@itwin/itwinui-icons-react';
+import { IconButton, Flex } from '@itwin/itwinui-react';
+import { SvgAdd, SvgClose } from '@itwin/itwinui-icons-react';
 
 export default () => {
   return (
-    <IconButton onClick={() => {}}>
-      <SvgAdd />
-    </IconButton>
+    <Flex>
+      <IconButton>
+        <SvgAdd />
+      </IconButton>
+      <IconButton styleType='borderless'>
+        <SvgClose />
+      </IconButton>
+    </Flex>
   );
 };

apps/website/src/examples/index.tsx

@@ -38,7 +38,11 @@ export { default as BreadcrumbsMainExample } from './Breadcrumbs.main';
 export { default as BreadcrumbsTruncationExample } from './Breadcrumbs.truncation';
 export { default as BreadcrumbsCustomOverflowDropdownExample } from './Breadcrumbs.customOverflowDropdown';
 
+export { default as ButtonSizeExample } from './Button.size';
 export { default as ButtonDefaultExample } from './Button.default';
+export { default as ButtonHighVisibilityExample } from './Button.highvisibility';
+export { default as ButtonBorderlessExample } from './Button.borderless';
+export { default as ButtonCTAExample } from './Button.cta';
 export { default as ButtonMainExample } from './Button.main';
 export { default as IconButtonMainExample } from './IconButton.main';
 export { default as IdeasButtonMainExample } from './IdeasButton.main';

apps/website/src/pages/docs/button.mdx

@@ -18,21 +18,61 @@ import * as AllExamples from '~/examples';
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='buttons-button' />
-
-<LiveExample src='Button.main.tsx' truncate={false}>
+<LiveExample src='Button.main.tsx'>
   <AllExamples.ButtonMainExample client:load />
 </LiveExample>
 
-Buttons are the recipients of a user onClick action (a mouse click for browsers and a finger press on touch-sensitive devices). Buttons have states and events and should be used when a form is submitted (post) or where the button represents a clear call to action on a page. In some cases, buttons can also be used in place of href links to draw special attention to that action.
+Buttons have states and events and should be used when a form is submitted or where the button represents a clear call to action on a page.
+In some cases, buttons can also be used in place of href links to draw special attention to that action.
+
+## Variants
 
-## Button
+### Default
 
 <LiveExample src='Button.default.tsx'>
   <AllExamples.ButtonDefaultExample client:load />
 </LiveExample>
 
-### Props
+The default button should be used in most circumstances. If you are unsure as to what button to use, use this button!
+
+### High visibility
+
+<LiveExample src='Button.highvisibility.tsx'>
+  <AllExamples.ButtonHighVisibilityExample client:load />
+</LiveExample>
+
+This is the button to emphasize an action applicable to an area of the page or a [dialog](dialog). High visibility buttons are used to draw the user’s attention to the main action of the page.
+There should only be one high visibility button per area of the user interface.
+
+### Call-to-action
+
+<LiveExample src='Button.cta.tsx'>
+  <AllExamples.ButtonCTAExample client:load />
+</LiveExample>
+
+The call-to-action button, also referred to as the CTA, is the button that is used for most full page layouts and whole-page overlays (think Next in [stepper](stepper) interactions). This is the biggest and most noticeable button.
+One call-to-action button per visible page is the rule. Treat it as a large, “CLICK HERE” guide for the user.
+
+### Borderless
+
+<LiveExample src='Button.borderless.tsx'>
+  <AllExamples.ButtonBorderlessExample client:load />
+</LiveExample>
+
+The borderless button is useful in tighter areas where using a default button would visibly cause too many boxes.
+
+The borderless button is often used by actionable icons in relation to another component.
+They are commonly used within [table](table) rows and widgets.
+
+### Size
+
+<LiveExample src='Button.size.tsx'>
+  <AllExamples.ButtonSizeExample client:load />
+</LiveExample>
+
+There are 3 different sizes available, which can be applied to any button. The medium size is a default and should always be the first choice, unless there are good reasons to use the small or large version.
+
+## Button props
 
 <PropsTable path={frontmatter.propsPathDefault} />
 
@@ -42,7 +82,7 @@ Buttons are the recipients of a user onClick action (a mouse click for browsers
   <AllExamples.SplitButtonMainExample client:load />
 </LiveExample>
 
-Pressing this left side of the button will commit the action. Pressing the right side of the button will open a menu. Upon selecting an option from the menu, the action immediately takes place, and the left side of the button’s label will change to match the recent selection.
+Pressing the left side of this button will commit the action. Pressing the right side of the button will open a menu.
 
 ### Props
 
@@ -54,18 +94,20 @@ Pressing this left side of the button will commit the action. Pressing the right
   <AllExamples.DropdownButtonMainExample client:load />
 </LiveExample>
 
-Pressing this button will always open a menu. Upon selecting an option from the menu, the action immediately takes place. The label of the button is not effected from your selection within the menu. The menu button can only be applied to default buttons and borderless buttons.
+Pressing this button will always open a menu. Upon selecting an option from the menu, the action immediately takes place. The menu button should only be styled as default buttons and borderless buttons.
 
 ### Props
 
 <PropsTable path={frontmatter.propsPathDropdownButton} />
 
 ## Icon button
 
-<LiveExample src='IconButton.main.tsx' truncate={false}>
+<LiveExample src='IconButton.main.tsx'>
   <AllExamples.IconButtonMainExample client:load />
 </LiveExample>
 
+Icon button gives the icon the correct styling as well as adds some clickable padding within the button, ensuring icons meet the necessary touch target size.
+
 ### Props
 
 <PropsTable path={frontmatter.propsPathIconButton} />
@@ -76,6 +118,28 @@ Pressing this button will always open a menu. Upon selecting an option from the
   <AllExamples.IdeasButtonMainExample client:load />
 </LiveExample>
 
+The Ideas button is unique and should only be used under certain circumstances. You will need to perform an audit of your application to ensure that the feedback button does not cover / obscure any tools.
+
+If the button does obscure anything important, we suggest adding empty space at the bottom of the page so the user can scroll far enough down that the button doesn’t overlap the underlying tools.
+
 ### Props
 
 <PropsTable path={frontmatter.propsPathIdeasButton} />
+
+## Usage
+
+### Style types
+
+- Use default button just about everywhere.
+- One high visibility button per section such as within a [dialog](dialog), or above a [table](table).
+- One call-to-action button on a page at a time, and it should always appear within a dedicated page footer.
+- Borderless buttons should be used in places where a default and icon button could cause too much visual clutter.
+- Icon buttons should not have high visibility or call-to-action styletypes.
+
+### Labels
+
+Strive for a single action word with a well-understood meaning such as a verb. Remember that all labels will need translation, so if the button absolutely requires a longer string, adhere to the _twentycharacterlimit_ rule.
+
+### Icon and label buttons
+
+To reinforce the meaning of a button it can be useful to display both an icon and a label. Use this option sparingly, and reserve if for the most important / frequently used buttons only. If you are unsure if an icon should be used, probably it shouldn’t.