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>Default</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

@@ -37,7 +37,11 @@ export { default as BreadcrumbsLinkExample } from './Breadcrumbs.link';
 export { default as BreadcrumbsMainExample } from './Breadcrumbs.main';
 export { default as BreadcrumbsTruncationExample } from './Breadcrumbs.truncation';
 
+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,51 +18,92 @@ 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.
+## Appearance
+
+### Default
 
-## Button
+The default button should be used in most circumstances. If you are unsure as to what button to use, use this button!
 
 <LiveExample src='Button.default.tsx'>
   <AllExamples.ButtonDefaultExample client:load />
 </LiveExample>
 
-### Props
+### High visibility
+
+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.
+
+<LiveExample src='Button.highvisibility.tsx'>
+  <AllExamples.ButtonHighVisibilityExample client:load />
+</LiveExample>
+
+### Call to action
+
+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-like interactions). This is the biggest and most noticeable button.
+One CTA button per visible page is the rule. Treat it as a large, “CLICK HERE” guide for the user.
+
+<LiveExample src='Button.cta.tsx'>
+  <AllExamples.ButtonCTAExample client:load />
+</LiveExample>
+
+### Borderless
+
+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. A good example would be the close icon within a modal, toast notification, or alert.
+
+<LiveExample src='Button.borderless.tsx'>
+  <AllExamples.ButtonBorderlessExample client:load />
+</LiveExample>
+
+### Size
+
+There are 3 different sizes available, which can be applied to any button.
+
+The medium size should always be the first choice, unless there are good reasons to use the small or large version.
+
+<LiveExample src='Button.size.tsx'>
+  <AllExamples.ButtonSizeExample client:load />
+</LiveExample>
+
+## Button props
 
 <PropsTable path={frontmatter.propsPathDefault} />
 
 ## Split button
 
+Pressing this left side of the button will commit the action. Pressing the right side of the button will open a menu.
+
 <LiveExample src='SplitButton.main.tsx'>
   <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.
-
 ### Props
 
 <PropsTable path={frontmatter.propsPathSplitButton} />
 
 ## Dropdown button
 
+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.
+
 <LiveExample src='DropdownButton.main.tsx'>
   <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.
-
 ### Props
 
 <PropsTable path={frontmatter.propsPathDropdownButton} />
 
 ## Icon button
 
-<LiveExample src='IconButton.main.tsx' truncate={false}>
+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.
+
+<LiveExample src='IconButton.main.tsx'>
   <AllExamples.IconButtonMainExample client:load />
 </LiveExample>
 
@@ -72,10 +113,32 @@ Pressing this button will always open a menu. Upon selecting an option from the
 
 ## Ideas button
 
+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.
+
 <LiveExample src='IdeasButton.main.tsx'>
   <AllExamples.IdeasButtonMainExample client:load />
 </LiveExample>
 
 ### Props
 
 <PropsTable path={frontmatter.propsPathIdeasButton} />
+
+## Usage
+
+### Style types
+
+- Use default button just about everywhere. The default button can display a text label, an icon, or a text label & icon in combination.
+
+- Use high visibility Button when you want to draw the user’s attention to a specific action applicable to a section of a UI or “Page”. Remember, there should be only 1 high visibility button per section (e.g. in a modal dialog, or above the table). The high visibility button can display a text label, or a text label & icon in combination. Icon buttons should not have this styletype.
+
+- The call to action button is the primary function on the page. There should only ever be one CTA on a page at a time. The call to action always appears within a dedicated page footer so as to make it very clear that the application is awaiting this main input before it can switch modes or views. The call to action button can display a text label, or a text label & icon in combination. Icon buttons should not have this styletype.
+
+### Labels
+
+Strive for a single action word with a well-understood meaning. Verbs do the best. The button should describe what it is going to do and nothing else. 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.