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

package/docs/components/EyebrowBanner/index.md

@@ -0,0 +1,153 @@
+---
+title: Eyebrow banner
+keywords: ['call to action', 'banner', 'highlight']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/EyebrowBanner/EyebrowBanner.tsx
+storybook: '/brand/storybook/?path=/story/components-eyebrowbanner--playground'
+description: Use the eyebrow banner to highlight important information at the top of a page.
+---
+
+```js
+import {EyebrowBanner} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+This is the default variant for the eyebrow banner component.
+
+```jsx
+<EyebrowBanner href="http://githubuniverse.com">
+  <EyebrowBanner.Visual>
+    <img
+      src="https://github.githubassets.com/assets/eyebrow-23@2x-563f292d9e30.png"
+      alt="Badge featuring a GitHub logo surrounded by Universe-themed shapes"
+    />
+  </EyebrowBanner.Visual>
+  <EyebrowBanner.Heading>GitHub Universe: Dive in to AI, security, and DevEx</EyebrowBanner.Heading>
+  <EyebrowBanner.SubHeading>Get your tickets now to join us on Nov. 8-9.</EyebrowBanner.SubHeading>
+</EyebrowBanner>
+```
+
+### Color modes
+
+Use `ThemeProvider` to automatically adjust the visual presentation of the component to light or dark variants.
+
+```jsx
+<Stack gap="none" padding="none">
+  <ThemeProvider colorMode="light">
+    <Box backgroundColor="default" padding="normal" borderWidth="thin" borderStyle="solid" borderColor="default">
+      <EyebrowBanner href="http://githubuniverse.com">
+        <EyebrowBanner.Visual>
+          <img
+            src="https://github.githubassets.com/assets/eyebrow-23@2x-563f292d9e30.png"
+            alt="Badge featuring a GitHub logo surrounded by Universe-themed shapes"
+          />
+        </EyebrowBanner.Visual>
+        <EyebrowBanner.Heading>GitHub Universe: Dive in to AI, security, and DevEx</EyebrowBanner.Heading>
+        <EyebrowBanner.SubHeading>Get your tickets now to join us on Nov. 8-9.</EyebrowBanner.SubHeading>
+      </EyebrowBanner>
+    </Box>
+  </ThemeProvider>
+  <ThemeProvider colorMode="dark">
+    <Box backgroundColor="default" padding="normal">
+      <EyebrowBanner href="http://githubuniverse.com">
+        <EyebrowBanner.Visual>
+          <img
+            src="https://github.githubassets.com/assets/eyebrow-23@2x-563f292d9e30.png"
+            alt="Badge featuring a GitHub logo surrounded by Universe-themed shapes"
+          />
+        </EyebrowBanner.Visual>
+        <EyebrowBanner.Heading>GitHub Universe: Dive in to AI, security, and DevEx</EyebrowBanner.Heading>
+        <EyebrowBanner.SubHeading>Get your tickets now to join us on Nov. 8-9.</EyebrowBanner.SubHeading>
+      </EyebrowBanner>
+    </Box>
+  </ThemeProvider>
+</Stack>
+```
+
+### Text labels
+
+Use `EyebrowBanner.Label` to display a leading text for additional context.
+
+A `color` prop is available to customise the color of the label.
+
+```jsx
+<Stack>
+  <EyebrowBanner href="http://githubuniverse.com">
+    <EyebrowBanner.Label>NEW</EyebrowBanner.Label>
+    <EyebrowBanner.Heading>GitHub Copilot now available for Business</EyebrowBanner.Heading>
+  </EyebrowBanner>
+  <EyebrowBanner href="http://githubuniverse.com">
+    <EyebrowBanner.Label color="blue-purple">NEW</EyebrowBanner.Label>
+    <EyebrowBanner.Heading>GitHub Copilot now available for Business</EyebrowBanner.Heading>
+  </EyebrowBanner>
+  <EyebrowBanner href="http://githubuniverse.com">
+    <EyebrowBanner.Label color="red">NEW</EyebrowBanner.Label>
+    <EyebrowBanner.Heading>GitHub Copilot now available for Business</EyebrowBanner.Heading>
+  </EyebrowBanner>
+</Stack>
+```
+
+### Icon visuals
+
+Use `EyebrowBanner.Visual` with an `icon` prop to display a leading icon for additional context.
+
+Icons can be SVGs or ideally Octicons. If using Octicons, import the icon from `@primer/octicons-react` and pass it as the `icon` prop.
+
+A `color` option is available to customise the color of the icon.
+
+An optional `hasBackground` prop can be used to fill the surrounding circle with the lighter hue of the selected color.
+
+```jsx
+<Stack>
+  <EyebrowBanner href="/">
+    <EyebrowBanner.Visual icon={<StarIcon />} color="blue" hasBackground />
+    <EyebrowBanner.Heading>GitHub Universe: Dive in to AI, security, and DevEx</EyebrowBanner.Heading>
+    <EyebrowBanner.SubHeading>Get your tickets now to join us on Nov. 8-9.</EyebrowBanner.SubHeading>
+  </EyebrowBanner>
+  <EyebrowBanner href="/">
+    <EyebrowBanner.Visual icon={<CopilotIcon />} color="blue" />
+    <EyebrowBanner.Heading>GitHub Copilot now available for Business</EyebrowBanner.Heading>
+  </EyebrowBanner>
+</Stack>
+```
+
+## Component props
+
+### EyebrowBanner `Required`
+
+| Name   | Type     |   Default   | required | Description                               |
+| :----- | :------- | :---------: | :------: | :---------------------------------------- |
+| `href` | `string` | `undefined` |  `true`  | The URL that the eyebrow banner points to |
+
+### EyebrowBanner.Heading `Required`
+
+Please note that this is not a HTML-based heading element.
+
+| Name       | Type        |   Default   | required | Description                                             |
+| :--------- | :---------- | :---------: | :------: | :------------------------------------------------------ |
+| `children` | `ReactNode` | `undefined` |  `true`  | The primary messaging that appears on the top-most line |
+
+### EyebrowBanner.SubHeading
+
+| Name       | Type        |   Default   | required | Description                                                   |
+| :--------- | :---------- | :---------: | :------: | :------------------------------------------------------------ |
+| `children` | `ReactNode` | `undefined` |  `false` | Optional secondary messaging that appears beneath the heading |
+
+### EyebrowBanner.Visual
+
+| Name            | Type                         |   Default   | required | Description                                 |
+| :-------------- | :--------------------------- | :---------: | :------: | :------------------------------------------ |
+| `icon`          | `'ReactNode' \| 'IconProps'` | `undefined` |  `false` | Optional icon. Accepts React-based Octicons |
+| `color`         | `EyebrowBannerIconColors`    | `undefined` |  `false` | Optional icon color.                        |
+| `hasBackground` | `boolean`                    | `undefined` |  `false` | Optional background color.                  |
+| `children`      | `ReactNode`                  | `undefined` |  `false` | Accepts `img`, `picture` or `svg` elements  |
+
+### EyebrowBanner.Label
+
+| Name       | Type                       |   Default   | required | Description                      |
+| :--------- | :------------------------- | :---------: | :------: | :------------------------------- |
+| `color`    | `EyebrowBannerLabelColors` | `undefined` |  `false` | Optional label color.            |
+| `children` | `ReactNode`                | `undefined` |  `false` | Text to appear in the label slot |

package/docs/components/FAQ/index.md

@@ -0,0 +1,66 @@
+---
+title: FAQ
+description: Use the FAQ component to display content in a Q&A format.
+keywords: ['content', 'questions', 'answers']
+---
+
+## Anatomy
+
+![The FAQ component has a heading, optional subheading, and a list of questions that are interactive to expand and display answers](https://github.com/primer/brand/assets/912236/cfc22774-7348-4e2b-9887-2157e1a17e16)
+
+- Heading: The main title of the FAQ.
+- Subheading: An optional short description that extends the information provided by the heading and helps group the items in the list.
+- Question: The question being answered.
+- Answer: The answer to the question.
+
+## Usage
+
+Use the FAQ to provide answers to common questions about a product or a feature presented on a page. The FAQ is a good way to provide additional information that may be beyond the scope of the main content of the page. We recommend placing the FAQ at the bottom of the page, after the main content. Avoid using the FAQ to provide information that is already available in the page.
+
+Answers should be clear and no longer than 2-3 paragraphs. If the answer is longer than the suggested, needs visual assets, or a specific layout treatment, consider using a different component. For instance, if the answer needs an image, we recommend using a list of [cards](../Card/index.md) or a [river](../River/index.md) component instead.
+
+For answers that need to provide a list of tasks, we recommend using an [ordered list](../OrderedList/index.md). To split the content into different items, we recommend using an [unordered list](../UnorderedList/index.md).
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/5566161b-439b-4e13-b41c-188723b0bae6)
+
+_Use the FAQ to provide clear answers to common questions. Link to other resources and use ordered/unordered lists
+if necessary._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/a42230be-ee4b-4905-885b-dab98f4889c9)
+
+_Don't use visual assets or other content-related components within the answers._
+
+## FAQ group
+
+When using long lists of questions and answers, consider using the FAQ group to organize items into content-related categories to make it easier for the user to scan the list.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/a659524d-4574-4880-8f00-c6846438492e)
+
+_Use the FAQ group for related questions and answers._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/315a9a4e-95de-4dc5-9129-ff31108d5dfd)
+
+_Don't use long lists of questions and answers. We recommend using FAQ groups to group them and to help the user
+scan the list._
+
+## Accessibility
+
+### Heading levels
+
+The `FAQ.Heading`, `FAQ.Subheading`, `FAQ.Question`, and `FAQGroup.Heading` components all support the `as` prop, allowing the underlying HTML element to be changed.
+
+When using these components, ensure that the heading levels are semantically correct and follow a logical hierarchy within the document, as the default heading levels for each component may not fit all use cases.
+
+## Related components
+
+- [Card](../Card/index.md): to display navigational related content with higher visual weight.
+- [River](../River/index.md): To display a list of content items with a visual asset.
+- [Pillar](../Pillar/index.md): To display related content with less visual emphasis.