@primer/react-brand 0.69.1-rc.0a4e5ff5 → 0.70.0-rc.138127ad

package/docs/components/Button/index.md

@@ -0,0 +1,133 @@
+---
+title: Button
+description: Use the button component for the main actions on a page or form.
+keywords: ['action', 'cta', 'control', 'interactive', 'click']
+---
+
+## Usage
+
+Buttons allow users to initiate an action or command when clicked. The button's label or text description indicates the purpose of the action to the user. Most of the time, we use the "Default" button type, but other types of buttons may be used to indicate something special about the button's hierarchy or functionality.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/83f703f5-d02c-45f1-82d2-e819613a6638)
+
+_Keep button labels succinct with no line breaks._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/e0b67dea-712b-4483-9222-0b499e539415)
+
+_Buttons should never contain line breaks and lose their button shape._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/96da1bd5-d537-40c1-9103-96254813648f)
+
+_Show focus styles on keyboard :focus_
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/edc931cf-06ed-4814-8ad0-24a8344902c0)
+
+_Don't remove default button :focus styles._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/56824212-3622-4546-b437-53dbced734a6)
+
+_Use sentence case for labels._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/515e833e-fad2-44fd-aae8-fae6301974c1)
+
+_Don't use all-caps or other text formats._
+
+## Anatomy
+
+![An image showing the different parts of a button with annotations.](https://github.com/primer/brand/assets/6951037/ef74e834-2650-424e-b382-bdcd4a09c113)
+
+## Options
+
+### Variants
+
+#### Primary
+
+Primary buttons have top priority in visual hierarchy, and using too many of them on a single view dilutes their effectiveness. We recommend to limit the primary button to one button per view, and place it in the visible section, whenever possible, to indicate its emphasis relative to other actions. Use multiple primary buttons only when the action is repeated in multiple places of the same page. E,g a "Log in" button in the header and in the footer area.
+
+![An image showing all primary states.](https://github.com/primer/brand/assets/6951037/dfad0124-4cdc-4230-b442-4ee9c747d0f0)
+
+#### Secondary
+
+Secondary buttons are the default button type. Use them for the main actions on a page or form. Secondary buttons are the most common button type and should be used in most cases. They can be paired with a primary button to perform a secondary action, or used on their own.
+
+![An image showing all secondary states.](https://github.com/primer/brand/assets/6951037/71f5a85d-4e63-4a3b-b7fc-2492ceae2b30)
+
+#### Subtle
+
+Subtle buttons have a transparent background with translucent hover and active states, making them useful for compound components like [Button Group](../ButtonGroup/index.md) when paired with secondary or primary variants.
+
+![An image showing all subtle states.](https://github.com/primer/brand/assets/912236/7420969a-e561-4fd6-9bef-7340e2b0a7e8)
+
+#### Block
+
+Turning on the block option for button allows the button to span the full width of its container. This feature can be particularly useful when you want the button to occupy more space. Block button can continue to pair with secondary or primary variants.
+
+![An image showing block button with all subtle states.](https://github.com/primer/brand/assets/6951037/2fe48284-7c3d-4262-9992-3fc029237fe6)
+
+### Trailing and leading icons
+
+You can place an icon inside the button in either the leading or the trailing position to enhance the visual context. It is recommended to use an use an [Octicon](https://primer.style/octicons) here.
+
+Use a trailing visual if the button action involves selecting items (dropdown, select, filter, etc), and a leading visual to provide visual context to the adjacent label. E.g. Use a search icon for a search field submit action.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/558dd2c0-22b9-4e0b-aa0d-6394eae29e6c)
+
+_Use a leading icon that provides context and reinforces the label._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/2b4b06e5-5e54-4d8d-885a-b0d3faaa1298)
+
+_Don't use a trailing icons to add a visual cue to the label. Use the leading icon for better scanability._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/5e534c85-0dcd-44b2-8c21-f80f2f14a4d0)
+
+_Use a trailing icon for select, dropdown, or filter actions to reinforce its direction._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/2b3ad072-d3dd-4b34-b7fa-a915fd84d03d)
+
+_Don't use a leading icon or the arrow for select, dropdown, or filter actions._
+
+### Size
+
+Button default to a medium size. Medium is suitable for most interfaces and is considered the preferred size.
+
+Large buttons increase the significance of an action and should be used sparingly. Use the large option when you need to emphasize the button on a big sized heading, for example in a [Hero](../Hero/index.md) component.
+
+Small buttons are meant to be used sparingly. Some use cases can be:
+
+- Contained inside other components like dropdowns or small popups.
+- Areas where very low priority information might display a CTA.
+- Brand presence inside products where information is compact. For example for in-product banner.
+
+## Accessibility
+
+### Descriptive buttons
+
+Labeling buttons properly lets users know what will happen when they activate the control, lessens errors, and increases confidence.
+
+Read more about [descriptive buttons](https://primer.style/design/guides/accessibility/descriptive-buttons/).
+
+## Related components
+
+- [ButtonGroup](../ButtonGroup/index.md): To display a group of related buttons.
+- Link: To display a link that navigates to another page.
+- [Hero](../Hero/index.md): To display a large heading and a description with a ButtonGroup.

package/docs/components/Button/react.md

@@ -0,0 +1,94 @@
+---
+title: Button
+description: Use the button component for the main actions on a page or form.
+keywords: ['action', 'cta', 'control', 'interactive', 'click']
+ready: true
+a11yReviewed: true
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=2931%3A30104'
+source: https://github.com/primer/brand/blob/main/packages/react/src/Button/Button.tsx
+storybook: '/brand/storybook/?path=/story/components-button--playground'
+---
+
+```js
+import {Button} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+This is the default variant for the Button component. It corresponds to the `secondary` variant appearance.
+
+```jsx
+<Button>Default</Button>
+```
+
+### Primary
+
+The `primary` variant of `Button` indicates that the action is of high priority, and should be used sparingly.
+
+```jsx
+<Button variant="primary">Primary</Button>
+```
+
+### Subtle
+
+The `subtle` variant of Button indicates that the action is a low priority one.
+
+```jsx
+<Button variant="subtle">Subtle</Button>
+```
+
+### Sizes
+
+```jsx
+<Stack direction="vertical" alignItems="flex-start">
+  <Button size="small">Register now</Button>
+  <Button size="medium">Register now</Button>
+  <Button size="large">Register now</Button>
+</Stack>
+```
+
+### Block
+
+```jsx
+<Button block>Full-width button</Button>
+```
+
+### Using an icon
+
+You can place an icon inside the `Button` in either the leading or the trailing position to enhance the visual context. It is recommended to use an [Octicon](https://primer.style/octicons) here.
+
+```jsx
+<Stack direction="vertical" alignItems="flex-start">
+  <Button leadingVisual={<SearchIcon />}>Search</Button>
+  <Button trailingVisual={<ChevronDownIcon />}>Select</Button>
+  <Button leadingVisual={<FilterIcon />} trailingVisual={<ChevronDownIcon />}>
+    Filter
+  </Button>
+</Stack>
+```
+
+### Polymorphism
+
+The `Button` component can render as a `button` or `a` HTML element. By default, it will render as a `button`.
+
+```jsx
+<Button as="a" href="https://github.com">
+  Register now
+</Button>
+```
+
+## Component props
+
+### Button
+
+| Name             | Type                                   |    Default    | Description                                                                                             |
+| :--------------- | :------------------------------------- | :-----------: | :------------------------------------------------------------------------------------------------------ |
+| `leadingVisual`  | `ReactElement`                         |  `undefined`  | The leading visual appears before the button content                                                    |
+| `trailingVisual` | `ReactElement`                         |  `undefined`  | The trailing visual appears after the button content                                                    |
+| `variants`       | `'primary' \| 'secondary' \| 'subtle'` | `'secondary'` | The styling variations available in Button                                                              |
+| `size`           | `'small' \| 'medium' \| 'large'`       |   `'medium'`  | The size variations available in Button                                                                 |
+| `block`          | `boolean`                              |    `false`    | The full-width option available in Button                                                               |
+| `hasArrow`       | `boolean`                              |    `false`    | Deprecated. The `hasArrow` prop will be removed in a future release.                                    |
+| `disabled`       | `boolean`                              |    `false`    | Disables the rendered element using `disabled` or `aria-disabled` attributes based on the element type. |

package/docs/components/ButtonGroup/index.md

@@ -0,0 +1,62 @@
+---
+title: Button group
+description: Use the button group component to group related buttons together.
+keywords: ['buttons', 'control', 'action', 'group', 'paired']
+---
+
+![An image showing a button group with a primary and a secondary button.](https://github.com/primer/brand/assets/6951037/3b8d5346-31d5-4820-baaf-056d9063f203)
+
+## Usage
+
+Use button group to group a set of actions that are related between them or to a single application. E,g, "Log in" and "Sign up" or "Try it out" and "Learn more".
+
+Use button group to display a pair of primary and a secondary actions. The primary button is used for the main call to action while the secondary button is a related, less important action.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/c69ae38e-819b-4e03-9b92-665a479f188a)
+
+_Use a primary button with a secondary button._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/c4c5c0de-2a46-4dbb-802a-0a6739d31d3a)
+
+_Don’t place multiple primary buttons together._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/9918ba9b-57ea-4a32-b51b-2460554900a9)
+
+_Place the primary button at the beginning of a button group._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/cb151d26-2597-45e7-b271-62d64c3c292d)
+
+_Don't place the primary button at the end of a button group._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/97f95652-8802-418a-bf4b-7d9800c038fc)
+
+_Stack the buttons vertically when there's not enough horizontal space._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/ef165552-94e1-4377-a9db-d8e9355af4eb)
+
+_Don't stack the buttons horizontally when there's not enough space to avoid text wrapping._
+
+## Options
+
+### Size
+
+The button group component has two sizes: `medium` and `large`. The `medium` size should be used for most cases. The `large` size should be used when the button group is used in large headings that introduces a page, as in the [Hero](../Hero/index.md) component.
+
+## Related components
+
+- [Button](../Button/index.md): To display a button that performs an action.
+- Link: To display a link that navigates to another page.
+- [Hero](../Hero/index.md): To display a large heading and a description with a button group.
+- [CTA banner](../CTABanner/index.md): To draw attention to or create urgency around a user action.

package/docs/components/ButtonGroup/react.md

@@ -0,0 +1,60 @@
+---
+title: Button group
+description: Use the button group component to group related buttons together.
+keywords: ['buttons', 'control', 'action', 'group', 'paired']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/ButtonGroup/ButtonGroup.tsx
+storybook: '/brand/storybook/?path=/story/components-buttongroup--playground'
+---
+
+```js
+import {ButtonGroup, Button} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+This is the default variant for the ButtonGroup component. The first button in the group is the primary button and the second button is the secondary button.
+
+```jsx
+<ButtonGroup>
+  <Button>This is one button</Button>
+  <Button>This is another button</Button>
+</ButtonGroup>
+```
+
+### Sizes
+
+The ButtonGroup component can be rendered in different sizes in `medium` and `large` sizes. The default size is `medium`.
+
+```jsx
+<ButtonGroup buttonSize="large">
+  <Button>This is one large button</Button>
+  <Button>This is another large button</Button>
+</ButtonGroup>
+```
+
+### Polymorphism
+
+The `Button` component can render as a `button` or `a` HTML element. By default, it will render as a `button`.
+
+```jsx
+<ButtonGroup>
+  <Button as="a" href="#">
+    This is one link
+  </Button>
+  <Button as="a" href="#">
+    This is another link
+  </Button>
+</ButtonGroup>
+```
+
+## Component props
+
+### ButtonGroup
+
+| Name         | Type                  |   Default  | Description                             |
+| :----------- | :-------------------- | :--------: | :-------------------------------------- |
+| `buttonSize` | `'medium' \| 'large'` | `'medium'` | The size variations available in Button |
+| `buttonsAs`  | `'button' \| 'a'`     | `'button'` | The HTML variations available in Button |

package/docs/components/CTABanner/index.md

@@ -0,0 +1,114 @@
+---
+title: CTA banner
+description: Use the CTA banner component to highlight and create urgency around user actions.
+keywords: ['call to action', 'banner', 'conversion', 'highlight', 'urgent']
+---
+
+## Anatomy
+
+![An image showing the CTA banner anatomy with a heading, a description and a button group.](https://github.com/primer/brand/assets/6951037/a33f3b89-1a4d-4bd3-8533-99b0cd2275e8)
+
+- Heading: The main title of the CTA banner. It should be short and concise.
+- Description: Short text that extends the information provided by the heading.
+- Button group: The call to actions available to users
+
+## Usage
+
+Use the CTA banner to draw attention around the main user actions. The CTA banner should be used sparingly and is typically placed at the bottom of the page to close the user journey,
+make a short summary of the page, and to persist the main actions. The CTA banner can also be used between other sections on lengthy pages.
+
+The CTA banner can include primary and secondary actions. These actions are rendered as a [button group](../ButtonGroup/index.md) and follow the same guidelines as the button group component.
+
+The actions used in a CTA banner are normally the same as the ones used on the [hero](../Hero/index.md) component on the top of the page. This repetition provides consistency and helps the user to remember what the main actions are.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/89acfdad-c39f-4613-9555-6a9661c53845)
+
+_Use the CTA banner on the bottom of the page to close the user journey and reinforce the main actions._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/f1bec42f-dad0-4eb2-80f9-83ef0a1310ad)
+
+_Don't use the CTA early on in the user journey, use a hero or a section intro component instead._
+
+## Options
+
+### Align
+
+The CTA banner elements can be aligned to the start or center of the page. By default, the CTA banner is aligned to the start of the page. Use the center alignment if context calls for it. E.g. Use the left alignment if there's a background image on the right side of the page or center align if the CTA banner is placed between two sections that are centered aligned to not break the visual flow.
+
+### Styles
+
+#### Background
+
+The CTA banner uses a solid background color by default. This is the recommended style for most cases. However, the background can be removed to allow the content to blend with the background of the page.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/036f540a-b8f6-4ccb-8a1a-b3a27c265308)
+
+_Use the background by default to ensure that the content is legible._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/8bcc95cc-4d3b-49f5-a74d-f46062f690b5)
+
+_Don't remove the background and keep the shadow, it will make the content hard to read._
+
+Avoid using noisy or textured images that will make the content hard to read. Make sure that the combination of background and foreground guarantees compliance with WCAG contrast guidelines. Use an [online contrast checker](https://webaim.org/resources/contrastchecker/) or a [Figma plugin](https://primer.style/accessibility/tools-and-resources/#contrast-plugin) to test your contrast.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/db46a0b4-5bf9-4024-8788-6227762510a9)
+
+_Use background images or colors that guarantee optimal contrast between the background and the foreground._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/dfc50baa-9b2a-4dc5-8412-20548cf2e7ed)
+
+_Don't use images that interfere with the legibility of the content._
+
+#### Shadow
+
+The CTA banner has a shadow around the component to give it a sense of depth and separation from the background.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/798a3355-252c-4745-8692-267c9a16d45f)
+
+_Remove the shadow and the background to diminish the sense of depth and separation from the background or to allow
+the content to blend with the background of the page._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/336f8e27-44e9-48a5-b308-a9686aa03484)
+
+_Don't use the shadow and the background together if you want the content to blend with the background and the
+sections that surround the CTA banner._
+
+#### Border
+
+The CTA banner can render a border around the component giving further separation between the foreground and background. This is especially useful when there is no shadow present on the background.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/583528ad-e3ab-4bf1-a34a-e0f9bf17d0a1)
+
+_Use the border only when there is no shadow present on the background._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/845ee118-3575-4db8-b7ea-1ac248678005)
+
+_Don't use the border when there is a shadow present on the background. The shadow will provide enough separation
+between the foreground and background._
+
+## Related components
+
+- [BreakoutBanner](../BreakoutBanner/index.md): To break up content on longer pages and highlight important information.
+- [Hero](../Hero/index.md): To display a large heading and a description with a button group.
+- [Section intro](../SectionIntro/index.md): To provide a title, description and a link to a new section in the page.
+- [River](../River/index.md): To display a list of content items with a visual asset.