@kaizen/components 1.70.20 → 1.70.22

package/dist/cjs/Filter/FilterBar/subcomponents/FilterBarButton/FilterBarButton.cjs

@@ -4,6 +4,7 @@ var tslib = require('tslib');
 var React = require('react');
 var classnames = require('classnames');
 var FilterBarContext = require('../../context/FilterBarContext.cjs');
+require('../../../FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.cjs');
 var FilterButton = require('../../../FilterButton/FilterButton/FilterButton.cjs');
 var FilterButtonRemovable = require('../../../FilterButton/FilterButtonRemovable/FilterButtonRemovable.cjs');
 var isRefObject = require('../../../../utils/isRefObject.cjs');

package/dist/cjs/Filter/FilterMultiSelect/subcomponents/Trigger/FilterTriggerButton/FilterTriggerButton.cjs

@@ -2,6 +2,7 @@
 
 var tslib = require('tslib');
 var React = require('react');
+require('../../../../FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.cjs');
 var FilterButton = require('../../../../FilterButton/FilterButton/FilterButton.cjs');
 require('../../../../FilterButton/FilterButtonRemovable/FilterButtonRemovable.cjs');
 var MenuTriggerProvider = require('../../../context/MenuTriggerProvider/MenuTriggerProvider.cjs');

package/dist/cjs/Filter/FilterMultiSelect/subcomponents/Trigger/RemovableFilterTrigger/RemovableFilterTrigger.cjs

@@ -3,6 +3,7 @@
 var tslib = require('tslib');
 var React = require('react');
 var classnames = require('classnames');
+require('../../../../FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.cjs');
 require('../../../../FilterButton/FilterButton/FilterButton.cjs');
 var FilterButtonRemovable = require('../../../../FilterButton/FilterButtonRemovable/FilterButtonRemovable.cjs');
 var MenuTriggerProvider = require('../../../context/MenuTriggerProvider/MenuTriggerProvider.cjs');

package/dist/cjs/RichTextEditor/RichTextEditor/utils/controlmap.cjs

@@ -3,6 +3,7 @@
 var tslib = require('tslib');
 var React = require('react');
 var Icon = require('../../../__rc__/Icon/Icon.cjs');
+require('vitest');
 var listIsActive = require('../../utils/commands/listIsActive.cjs');
 var markIsActive = require('../../utils/commands/markIsActive.cjs');
 require('prosemirror-transform');

package/dist/cjs/RichTextEditor/utils/commands/fixtures/mockRangeForBoundingRect.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+var vitest = require('vitest');
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+/*
+ ** This is used handle the JSDom type error issue you may encounter in testing
+ ** See https://github.com/jsdom/jsdom/issues/3002
+ */
+var mockRangeForBoundingRect = function () {
+  vitest.vi.spyOn(document, 'createRange').mockImplementation(function () {
+    var range = new Range();
+    range.getBoundingClientRect = function () {
+      return {
+        x: 0,
+        y: 0,
+        bottom: 0,
+        height: 0,
+        left: 0,
+        right: 0,
+        top: 0,
+        width: 0,
+        toJSON: function () {
+          return undefined;
+        }
+      };
+    };
+    range.getClientRects = function () {
+      var _a;
+      return _a = {
+        item: function () {
+          return null;
+        },
+        length: 0
+      }, _a[Symbol.iterator] = vitest.vi.fn(), _a;
+    };
+    return range;
+  });
+};
+exports.mockRangeForBoundingRect = mockRangeForBoundingRect;

package/dist/cjs/RichTextEditor/utils/plugins/LinkManager/LinkManager.cjs

@@ -2,6 +2,7 @@
 
 var debounce = require('lodash.debounce');
 var ProseMirrorState = require('prosemirror-state');
+require('vitest');
 var getMarkAttrs = require('../../commands/getMarkAttrs.cjs');
 var getMarkRange = require('../../commands/getMarkRange.cjs');
 require('prosemirror-utils');

package/dist/cjs/index.cjs

@@ -47,6 +47,7 @@ var Filter = require('./Filter/Filter/Filter.cjs');
 var FilterContents = require('./Filter/Filter/subcomponents/FilterContents/FilterContents.cjs');
 var FilterBar = require('./Filter/FilterBar/FilterBar.cjs');
 var FilterBarContext = require('./Filter/FilterBar/context/FilterBarContext.cjs');
+var FilterButtonBase = require('./Filter/FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.cjs');
 var FilterButton = require('./Filter/FilterButton/FilterButton/FilterButton.cjs');
 var FilterButtonRemovable = require('./Filter/FilterButton/FilterButtonRemovable/FilterButtonRemovable.cjs');
 var FilterDatePicker = require('./Filter/FilterDatePicker/FilterDatePicker.cjs');
@@ -354,6 +355,7 @@ var RichTextEditor = require('./RichTextEditor/RichTextEditor/RichTextEditor.cjs
 var ToggleIconButton = require('./RichTextEditor/RichTextEditor/subcomponents/ToggleIconButton/ToggleIconButton.cjs');
 var Toolbar = require('./RichTextEditor/RichTextEditor/subcomponents/Toolbar/Toolbar.cjs');
 var ToolbarSection = require('./RichTextEditor/RichTextEditor/subcomponents/ToolbarSection/ToolbarSection.cjs');
+var mockRangeForBoundingRect = require('./RichTextEditor/utils/commands/fixtures/mockRangeForBoundingRect.cjs');
 var addMark = require('./RichTextEditor/utils/commands/addMark.cjs');
 var getMarkAttrs = require('./RichTextEditor/utils/commands/getMarkAttrs.cjs');
 var getMarkRange = require('./RichTextEditor/utils/commands/getMarkRange.cjs');
@@ -488,6 +490,7 @@ exports.FilterContents = FilterContents.FilterContents;
 exports.FilterBar = FilterBar.FilterBar;
 exports.FilterBarProvider = FilterBarContext.FilterBarProvider;
 exports.useFilterBarContext = FilterBarContext.useFilterBarContext;
+exports.FilterButtonBase = FilterButtonBase.FilterButtonBase;
 exports.FilterButton = FilterButton.FilterButton;
 exports.FilterButtonRemovable = FilterButtonRemovable.FilterButtonRemovable;
 exports.FilterDatePicker = FilterDatePicker.FilterDatePicker;
@@ -979,6 +982,7 @@ exports.RichTextEditor = RichTextEditor.RichTextEditor;
 exports.ToggleIconButton = ToggleIconButton.ToggleIconButton;
 exports.Toolbar = Toolbar.Toolbar;
 exports.ToolbarSection = ToolbarSection.ToolbarSection;
+exports.mockRangeForBoundingRect = mockRangeForBoundingRect.mockRangeForBoundingRect;
 exports.addMark = addMark.addMark;
 exports.getMarkAttrs = getMarkAttrs.getMarkAttrs;
 exports.getMarkRange = getMarkRange.getMarkRange;

package/dist/esm/Filter/FilterBar/subcomponents/FilterBarButton/FilterBarButton.mjs

@@ -2,6 +2,7 @@ import { __rest, __assign } from 'tslib';
 import React, { forwardRef, useEffect } from 'react';
 import classnames from 'classnames';
 import { useFilterBarContext } from '../../context/FilterBarContext.mjs';
+import '../../../FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.mjs';
 import { FilterButton } from '../../../FilterButton/FilterButton/FilterButton.mjs';
 import { FilterButtonRemovable } from '../../../FilterButton/FilterButtonRemovable/FilterButtonRemovable.mjs';
 import { isRefObject } from '../../../../utils/isRefObject.mjs';

package/dist/esm/Filter/FilterMultiSelect/subcomponents/Trigger/FilterTriggerButton/FilterTriggerButton.mjs

@@ -1,5 +1,6 @@
 import { __assign } from 'tslib';
 import React, { useRef } from 'react';
+import '../../../../FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.mjs';
 import { FilterButton } from '../../../../FilterButton/FilterButton/FilterButton.mjs';
 import '../../../../FilterButton/FilterButtonRemovable/FilterButtonRemovable.mjs';
 import { useMenuTriggerContext } from '../../../context/MenuTriggerProvider/MenuTriggerProvider.mjs';

package/dist/esm/Filter/FilterMultiSelect/subcomponents/Trigger/RemovableFilterTrigger/RemovableFilterTrigger.mjs

@@ -1,6 +1,7 @@
 import { __assign } from 'tslib';
 import React, { useRef } from 'react';
 import classnames from 'classnames';
+import '../../../../FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.mjs';
 import '../../../../FilterButton/FilterButton/FilterButton.mjs';
 import { FilterButtonRemovable } from '../../../../FilterButton/FilterButtonRemovable/FilterButtonRemovable.mjs';
 import { useMenuTriggerContext } from '../../../context/MenuTriggerProvider/MenuTriggerProvider.mjs';

package/dist/esm/RichTextEditor/RichTextEditor/utils/controlmap.mjs

@@ -1,6 +1,7 @@
 import { __assign } from 'tslib';
 import React from 'react';
 import { Icon } from '../../../__rc__/Icon/Icon.mjs';
+import 'vitest';
 import { listIsActive } from '../../utils/commands/listIsActive.mjs';
 import { markIsActive } from '../../utils/commands/markIsActive.mjs';
 import 'prosemirror-transform';

package/dist/esm/RichTextEditor/utils/commands/fixtures/mockRangeForBoundingRect.mjs

@@ -0,0 +1,38 @@
+import { vi } from 'vitest';
+
+// eslint-disable-next-line import/no-extraneous-dependencies
+/*
+ ** This is used handle the JSDom type error issue you may encounter in testing
+ ** See https://github.com/jsdom/jsdom/issues/3002
+ */
+var mockRangeForBoundingRect = function () {
+  vi.spyOn(document, 'createRange').mockImplementation(function () {
+    var range = new Range();
+    range.getBoundingClientRect = function () {
+      return {
+        x: 0,
+        y: 0,
+        bottom: 0,
+        height: 0,
+        left: 0,
+        right: 0,
+        top: 0,
+        width: 0,
+        toJSON: function () {
+          return undefined;
+        }
+      };
+    };
+    range.getClientRects = function () {
+      var _a;
+      return _a = {
+        item: function () {
+          return null;
+        },
+        length: 0
+      }, _a[Symbol.iterator] = vi.fn(), _a;
+    };
+    return range;
+  });
+};
+export { mockRangeForBoundingRect };

package/dist/esm/RichTextEditor/utils/plugins/LinkManager/LinkManager.mjs

@@ -1,5 +1,6 @@
 import debounce from 'lodash.debounce';
 import { Plugin } from 'prosemirror-state';
+import 'vitest';
 import { getMarkAttrs } from '../../commands/getMarkAttrs.mjs';
 import { getMarkRange } from '../../commands/getMarkRange.mjs';
 import 'prosemirror-utils';

package/dist/esm/index.mjs

@@ -45,6 +45,7 @@ export { Filter } from './Filter/Filter/Filter.mjs';
 export { FilterContents } from './Filter/Filter/subcomponents/FilterContents/FilterContents.mjs';
 export { FilterBar } from './Filter/FilterBar/FilterBar.mjs';
 export { FilterBarProvider, useFilterBarContext } from './Filter/FilterBar/context/FilterBarContext.mjs';
+export { FilterButtonBase } from './Filter/FilterButton/subcomponents/FilterButtonBase/FilterButtonBase.mjs';
 export { FilterButton } from './Filter/FilterButton/FilterButton/FilterButton.mjs';
 export { FilterButtonRemovable } from './Filter/FilterButton/FilterButtonRemovable/FilterButtonRemovable.mjs';
 export { FilterDatePicker } from './Filter/FilterDatePicker/FilterDatePicker.mjs';
@@ -352,6 +353,7 @@ export { RichTextEditor } from './RichTextEditor/RichTextEditor/RichTextEditor.m
 export { ToggleIconButton } from './RichTextEditor/RichTextEditor/subcomponents/ToggleIconButton/ToggleIconButton.mjs';
 export { Toolbar } from './RichTextEditor/RichTextEditor/subcomponents/Toolbar/Toolbar.mjs';
 export { ToolbarSection } from './RichTextEditor/RichTextEditor/subcomponents/ToolbarSection/ToolbarSection.mjs';
+export { mockRangeForBoundingRect } from './RichTextEditor/utils/commands/fixtures/mockRangeForBoundingRect.mjs';
 export { addMark } from './RichTextEditor/utils/commands/addMark.mjs';
 export { getMarkAttrs } from './RichTextEditor/utils/commands/getMarkAttrs.mjs';
 export { getMarkRange } from './RichTextEditor/utils/commands/getMarkRange.mjs';

package/dist/types/Filter/FilterBar/subcomponents/FilterBarButton/FilterBarButton.d.ts

@@ -9,7 +9,7 @@ export declare const FilterBarButton: React.ForwardRefExoticComponent<{
     label: string;
     selectedValue?: string | JSX.Element;
     isOpen?: boolean;
-} & Omit<import("../../../FilterButton/subcomponents/FilterButtonBase").FilterButtonBaseProps, "children"> & {
+} & Omit<import("../../../FilterButton").FilterButtonBaseProps, "children"> & {
     filterId: string;
     isRemovable: boolean | undefined;
 } & React.RefAttributes<FilterTriggerRef>>;

package/dist/types/Filter/FilterButton/index.d.ts

@@ -1,2 +1,3 @@
+export * from './subcomponents/FilterButtonBase';
 export * from './FilterButton';
 export * from './FilterButtonRemovable';

package/dist/types/RichTextEditor/utils/commands/fixtures/helpers.d.ts

@@ -1,6 +1,5 @@
 import { type EditorState, type Transaction } from 'prosemirror-state';
 import { type ProseMirrorModel } from '../../prosemirror';
-export declare const mockRangeForBoundingRect: () => void;
 export declare const simulateRangeSelection: (anchorPositionStart?: number, anchorPositionEnd?: number) => (state: EditorState, dispatch?: (tx: Transaction) => void) => boolean;
 export declare const getStartNode: (state: EditorState) => ReturnType<ProseMirrorModel.Node["childAfter"]>;
 export declare const simulateSelectionOfCurrentElement: (selectEntireElement?: boolean) => (state: EditorState, dispatch: (tx: Transaction) => void) => boolean;

package/dist/types/RichTextEditor/utils/commands/fixtures/index.d.ts

@@ -0,0 +1,2 @@
+export * from './mockRangeForBoundingRect';
+export * from './helpers';

package/dist/types/RichTextEditor/utils/commands/fixtures/mockRangeForBoundingRect.d.ts

@@ -0,0 +1 @@
+export declare const mockRangeForBoundingRect: () => void;

package/dist/types/RichTextEditor/utils/commands/index.d.ts

@@ -1,3 +1,4 @@
+export * from './fixtures/mockRangeForBoundingRect';
 export * from './addMark';
 export * from './getMarkAttrs';
 export * from './getMarkRange';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.70.20",
+  "version": "1.70.22",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",

package/src/Filter/FilterButton/index.ts

@@ -1,2 +1,3 @@
+export * from './subcomponents/FilterButtonBase'
 export * from './FilterButton'
 export * from './FilterButtonRemovable'

package/src/RichTextEditor/utils/commands/addMark.spec.ts

@@ -2,11 +2,7 @@ import { findByText, waitFor } from '@testing-library/dom'
 import { vi } from 'vitest'
 import { createRichTextEditor } from '../core'
 import { addMark } from './addMark'
-import {
-  mockRangeForBoundingRect,
-  simulateSelectionByText,
-  simulateTextInsert,
-} from './fixtures/helpers'
+import { mockRangeForBoundingRect, simulateSelectionByText, simulateTextInsert } from './fixtures/'
 import { testEditorState, testSchema } from './fixtures/test-state'
 describe('addMark()', () => {
   const onChange = vi.fn()

package/src/RichTextEditor/utils/commands/fixtures/helpers.ts

@@ -5,38 +5,7 @@ import {
   type Transaction,
 } from 'prosemirror-state'
 import { findChildrenByType } from 'prosemirror-utils'
-//  eslint-disable-next-line import/no-extraneous-dependencies
-import { vi } from 'vitest'
 import { type ProseMirrorModel } from '../../prosemirror'
-/*
- ** This is used handle the JSDom type error issue you may encounter in testing
- ** See https://github.com/jsdom/jsdom/issues/3002
- */
-export const mockRangeForBoundingRect = (): void => {
-  vi.spyOn(document, 'createRange').mockImplementation(() => {
-    const range = new Range()
-
-    range.getBoundingClientRect = () => ({
-      x: 0,
-      y: 0,
-      bottom: 0,
-      height: 0,
-      left: 0,
-      right: 0,
-      top: 0,
-      width: 0,
-      toJSON: () => undefined,
-    })
-
-    range.getClientRects = () => ({
-      item: () => null,
-      length: 0,
-      [Symbol.iterator]: vi.fn(),
-    })
-
-    return range
-  })
-}
 
 /*
  ** Prosemirror cannot intuit a real `Selection` of content injected into the base test.

package/src/RichTextEditor/utils/commands/fixtures/index.ts

@@ -0,0 +1,2 @@
+export * from './mockRangeForBoundingRect'
+export * from './helpers'

package/src/RichTextEditor/utils/commands/fixtures/mockRangeForBoundingRect.ts

@@ -0,0 +1,32 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { vi } from 'vitest'
+
+/*
+ ** This is used handle the JSDom type error issue you may encounter in testing
+ ** See https://github.com/jsdom/jsdom/issues/3002
+ */
+export const mockRangeForBoundingRect = (): void => {
+  vi.spyOn(document, 'createRange').mockImplementation(() => {
+    const range = new Range()
+
+    range.getBoundingClientRect = () => ({
+      x: 0,
+      y: 0,
+      bottom: 0,
+      height: 0,
+      left: 0,
+      right: 0,
+      top: 0,
+      width: 0,
+      toJSON: () => undefined,
+    })
+
+    range.getClientRects = () => ({
+      item: () => null,
+      length: 0,
+      [Symbol.iterator]: vi.fn(),
+    })
+
+    return range
+  })
+}

package/src/RichTextEditor/utils/commands/index.ts

@@ -1,3 +1,4 @@
+export * from './fixtures/mockRangeForBoundingRect'
 export * from './addMark'
 export * from './getMarkAttrs'
 export * from './getMarkRange'

package/src/__rc__/Button/_docs/Button--usage-guidelines.mdx

@@ -1,6 +1,10 @@
 import { Canvas, Meta, Controls } from '@storybook/blocks'
-import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import { ResourceLinks, KAIOInstallation, DosAndDonts, DoOrDont } from '~storybook/components'
 import * as Button from './Button.docs.stories'
+import ButtonIconOnlySpec from './assets/button_icon_only_spec.png'
+import ButtonIconSpec from './assets/button_icon_spec.png'
+import ButtonSpec from './assets/button_spec.png'
+import ButtonAnatomy from './assets/button_anatomy.png'
 
 <Meta title="Components/Button/Button (v3)/Usage Guidelines" />
 
@@ -27,3 +31,168 @@ Buttons allow users to perform an action. They have multiple styles for various
   include={['children', 'variant', 'size', 'isDisabled', 'icon', 'iconPosition']}
   className="mb-64"
 />
+
+## Anatomy
+
+<img
+  src={ButtonAnatomy}
+  alt="Indicates the anatomy of an Button component with text"
+  className="my-auto"
+/>
+
+### When to use
+
+Use buttons to communicate actions users can take. Each page should have only one primary button, and any remaining calls to action should use lower emphasis buttons.
+
+### When not to use
+
+Do not use buttons as navigational elements. Instead, use links when the desired action is to take the user to a new page.
+
+## Specs
+
+<img
+  src={ButtonSpec}
+  alt="Indicates the spacing specifications of a Button component with text"
+  className="my-auto"
+/>
+
+<img
+  src={ButtonIconSpec}
+  alt="Indicates the spacing specifications of a Button component with text and an icon"
+  className="my-auto"
+/>
+
+<img
+  src={ButtonIconOnlySpec}
+  alt="Indicates the spacing specifications of an icon-only Button"
+  className="my-auto"
+/>
+
+### Dos and don'ts
+
+#### Use primary buttons to highlight a single, important action
+
+Reserve the primary button for actions that are essential to an experience. Usually, use only one primary button on a page or section. These buttons give extra prominence and help establish a clear hierarchy.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExamplePrimaryAndSecondary} />
+  <DoOrDont story={Button.DontExamplePrimaryAndSecondary} isDont />
+</DosAndDonts>
+
+#### Use secondary buttons for medium emphasis actions
+
+Use secondary buttons when the action requires less prominence, or if there are multiple actions with the same importance on a page or section.
+
+#### Use tertiary buttons to communicate action hierarchy
+
+Use tertiary buttons for less important actions within a group or section to help establish a clear hierarchy. Don't use tertiary buttons in isolation.
+
+#### Use large buttons for high emphasis
+
+Use large buttons sparingly within pages or sections where you need a high emphasis and prominent button to provide balance with other large elements. This might be on a landing page or a CTA in proximity to large headings.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleCta} />
+</DosAndDonts>
+
+#### Use medium buttons most of the time
+
+Medium buttons are appropriate in most common contexts such as pairing with input fields.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleDefaultToMediumSize} />
+  <DoOrDont story={Button.DontExampleDefaultToMediumSize} isDont />
+</DosAndDonts>
+
+#### Use small buttons in information rich contexts
+
+Use small buttons when space is limited, such as inside or adjacent to lists, tables, or data visualizations.
+
+Ensure clarity by prioritizing the most important actions. Think about how many buttons you use and where you put them. Don't overload your interface with too many buttons, as clustering buttons can confuse people.
+
+#### Use icons in Primary and Secondary buttons sparingly and consistently
+
+Overusing icons can create visual clutter and overwhelm users. Use them sparingly to highlight common and recognizable actions.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleUseIconsSparingly} />
+  <DoOrDont story={Button.DontExampleUseIconsSparingly} isDont />
+</DosAndDonts>
+
+#### Always use icons in Tertiary buttons
+
+Without icons, tertiary buttons can look like plain text. Tertiary buttons must always use icons to support a button affordance and meet accessibility standards.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleTertiaryButtonWithIcons} />
+  <DoOrDont story={Button.DontExampleTertiaryButtonWithIcons} isDont />
+</DosAndDonts>
+
+#### Use tooltips when the label is hidden
+
+When a button label is hidden and only an icon is used, show a tooltip on hover that displays the label text.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleUseTooltips} />
+  <DoOrDont story={Button.DontExampleUseTooltips} isDont />
+</DosAndDonts>
+
+#### Use a menu button when all actions are equally important
+
+Group related actions in a menu. The action options should be closely related and make sense as a group. You can use any type or size of button based on the context.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleMenuButton} />
+</DosAndDonts>
+
+#### Use a button and an overflow button when there is a most common or distinct action
+
+Highlight the most important, common, or a distinct action by using a button with text. Group related, less important actions in an overflow button. The action options should be closely related and make sense as a group. You can use any type or size of button based on the context. This pattern replaces Split Buttons.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleKebabMenuButton} />
+</DosAndDonts>
+
+#### Write clear, action-oriented button labels
+
+Write button labels as concise verbs that clearly state the action and its outcome. Always align the button label with the language used elsewhere in the Platform to maintain consistency and clarity.
+Make sure that all your buttons begin with a strong verb (something that elicits an action from the user). Verbs indicate to a user what they’re about to see or do next.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleClearAndConciseLabels} />
+  <DoOrDont story={Button.DontExampleClearAndConciseLabels} isDont />
+</DosAndDonts>
+
+A verb and noun combination gives users more context and can help guide them when the action they’re about to perform isn’t commonplace.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleDeclareContext} />
+  <DoOrDont story={Button.DontExampleDeclareContext} isDont />
+</DosAndDonts>
+
+#### Write in sentence case with minimal punctuation
+
+All buttons should be in sentence case i.e. the first letter of the first word is capitalized and everything else is in lower case unless it’s a proper noun or feature name. Always err on the side of minimal punctuation, so leave out full stops and commas where possible.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleMinimalPunctuation} />
+  <DoOrDont story={Button.DontExampleMinimalPunctuation} isDont />
+</DosAndDonts>
+
+#### Use second person
+
+Any buttons that include a personal pronoun should be written in the second person. Keep in mind that you shouldn’t use personal pronouns unless you’re asking the user to filter something. For example, “View your reports” vs “View all reports.”
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleSecondPerson} />
+  <DoOrDont story={Button.DontExampleSecondPerson} isDont />
+</DosAndDonts>
+
+#### Button labels should make sense in isolation
+
+If buttons on a page have the same label repeated multiple times, they should have distinct, accessible names that add context for users. This ensures better accessibility for screen reader users, who rely on descriptive labels to distinguish between actions.
+
+<DosAndDonts>
+  <DoOrDont story={Button.DoExampleFunctionalLabels} />
+  <DoOrDont story={Button.DontExampleFunctionalLabels} isDont />
+</DosAndDonts>

package/src/__rc__/Button/_docs/Button.docs.stories.tsx

@@ -2,7 +2,17 @@ import React from 'react'
 import { action } from '@storybook/addon-actions'
 import { type Meta, type StoryObj } from '@storybook/react'
 import { Badge } from '~components/Badge'
-import { Icon } from '~components/__rc__'
+import { EmptyState } from '~components/EmptyState'
+import {
+  Icon,
+  Menu,
+  MenuItem,
+  MenuPopover,
+  MenuTrigger,
+  Select,
+  Tooltip,
+  TooltipTrigger,
+} from '~components/__rc__'
 import { ReversedColors } from '~components/__utilities__/v3'
 import { Button } from '../index'
 
@@ -15,7 +25,7 @@ const meta = {
   },
   argTypes: {
     icon: {
-      options: ['delete', 'arrow', 'plus'],
+      options: ['delete', 'arrow', 'add'],
       mapping: {
         delete: <Icon isPresentational name="delete" />,
         arrow: <Icon isPresentational name="arrow_forward" />,
@@ -60,13 +70,6 @@ export const ButtonVariantsReversed: Story = {
     reverseColors: true,
     backgrounds: { default: 'Purple 700' },
   },
-  decorators: [
-    (Story) => (
-      <div className="flex gap-8">
-        <Story />
-      </div>
-    ),
-  ],
 }
 
 export const ButtonSizes: Story = {
@@ -136,3 +139,255 @@ export const ButtonWithBadge: Story = {
     ),
   },
 }
+
+// Dos and Donts
+
+export const DoExamplePrimaryAndSecondary: Story = {
+  render: () => {
+    return (
+      <>
+        <Button variant="primary" className="me-8">
+          Submit
+        </Button>
+        <Button variant="secondary">Cancel</Button>
+      </>
+    )
+  },
+  decorators: [
+    (Story) => (
+      <div className="flex gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const DontExamplePrimaryAndSecondary: Story = {
+  render: () => {
+    return (
+      <>
+        <Button variant="primary" className="me-8">
+          Submit
+        </Button>
+        <Button variant="primary">Cancel</Button>
+      </>
+    )
+  },
+  decorators: [
+    (Story) => (
+      <div className="flex gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const DoExampleCta: Story = {
+  render: () => {
+    return (
+      <>
+        <EmptyState
+          headingProps={{ children: 'Lorem', variant: 'heading-2', tag: 'span' }}
+          bodyText="Ipsum dolor sit amet consectetur adipisicing elit."
+        >
+          <Button size="large">Action</Button>
+        </EmptyState>
+      </>
+    )
+  },
+}
+
+export const DoExampleDefaultToMediumSize: Story = {
+  render: () => {
+    return (
+      <>
+        <Select items={[]} label="Choose country"></Select>
+        <Button className="mt-8">Save</Button>
+      </>
+    )
+  },
+}
+
+export const DontExampleDefaultToMediumSize: Story = {
+  render: () => {
+    return (
+      <>
+        <Select items={[]} label="Choose country"></Select>
+        <Button className="mt-8" variant="primary" size="small">
+          Save
+        </Button>
+      </>
+    )
+  },
+}
+
+export const DoExampleUseIconsSparingly: Story = {
+  args: {
+    children: 'Add user',
+    icon: <Icon isPresentational name="add" />,
+    iconPosition: 'end',
+  },
+}
+
+export const DontExampleUseIconsSparingly: Story = {
+  args: {
+    children: 'Add user',
+    icon: <Icon isPresentational name="star" />,
+    iconPosition: 'end',
+  },
+}
+
+export const DoExampleUseTooltips: Story = {
+  args: {
+    children: 'Delete',
+    icon: <Icon isPresentational name="delete" />,
+    hasHiddenLabel: true,
+    variant: 'tertiary',
+  },
+  render: (args) => (
+    <TooltipTrigger>
+      <Button {...args} />
+      <Tooltip>Delete content</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+export const DontExampleUseTooltips: Story = {
+  args: {
+    children: 'Delete',
+    icon: <Icon isPresentational name="delete" />,
+    hasHiddenLabel: true,
+    variant: 'tertiary',
+  },
+}
+
+export const DoExampleMenuButton: Story = {
+  render: () => (
+    <MenuTrigger defaultOpen={false}>
+      <Button
+        variant="secondary"
+        icon={<Icon name="keyboard_arrow_down" isPresentational />}
+        iconPosition="end"
+      >
+        Manage
+      </Button>
+      <MenuPopover>
+        <Menu>
+          <MenuItem icon={<Icon name="bookmark" isPresentational />}>Save</MenuItem>
+          <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>Edit</MenuItem>
+          <MenuItem icon={<Icon name="delete" isPresentational isFilled />}>Delete</MenuItem>
+        </Menu>
+      </MenuPopover>
+    </MenuTrigger>
+  ),
+}
+
+export const DoExampleKebabMenuButton: Story = {
+  render: () => (
+    <TooltipTrigger>
+      <MenuTrigger defaultOpen={false}>
+        <Button
+          variant="secondary"
+          icon={<Icon name="more_horiz" isPresentational />}
+          iconPosition="end"
+          hasHiddenLabel
+        >
+          Manage
+        </Button>
+        <MenuPopover>
+          <Menu>
+            <MenuItem icon={<Icon name="bookmark" isPresentational />}>Save</MenuItem>
+            <MenuItem icon={<Icon name="edit" isPresentational isFilled />}>Edit</MenuItem>
+            <MenuItem icon={<Icon name="delete" isPresentational isFilled />}>Delete</MenuItem>
+          </Menu>
+        </MenuPopover>
+      </MenuTrigger>
+      <Tooltip>Manage</Tooltip>
+    </TooltipTrigger>
+  ),
+}
+
+export const DoExampleMinimalPunctuation: Story = {
+  args: {
+    children: 'View tour',
+    variant: 'secondary',
+  },
+}
+
+export const DontExampleMinimalPunctuation: Story = {
+  args: {
+    children: "What's new?",
+    variant: 'secondary',
+  },
+}
+
+export const DoExampleSecondPerson: Story = {
+  args: {
+    children: 'View your reports',
+    variant: 'secondary',
+  },
+}
+
+export const DontExampleSecondPerson: Story = {
+  args: {
+    children: 'View my reports',
+    variant: 'secondary',
+  },
+}
+
+export const DoExampleFunctionalLabels: Story = {
+  args: {
+    children: 'Edit report',
+    variant: 'secondary',
+  },
+}
+
+export const DontExampleFunctionalLabels: Story = {
+  args: {
+    children: 'Edit',
+    variant: 'secondary',
+  },
+}
+
+export const DoExampleClearAndConciseLabels: Story = {
+  args: {
+    children: 'Save',
+    variant: 'secondary',
+  },
+}
+
+export const DontExampleClearAndConciseLabels: Story = {
+  args: {
+    children: 'Go to next step',
+    variant: 'secondary',
+  },
+}
+
+export const DoExampleDeclareContext: Story = {
+  args: {
+    children: 'Create survey',
+    variant: 'secondary',
+  },
+}
+
+export const DontExampleDeclareContext: Story = {
+  args: {
+    children: 'Create',
+    variant: 'secondary',
+  },
+}
+
+export const DoExampleTertiaryButtonWithIcons: Story = {
+  args: {
+    children: 'Edit cycle',
+    variant: 'tertiary',
+    icon: <Icon isPresentational name="edit" />,
+  },
+}
+
+export const DontExampleTertiaryButtonWithIcons: Story = {
+  args: {
+    children: 'Edit cycle',
+    variant: 'tertiary',
+  },
+}