@primer/react-brand 0.69.1-rc.9dc041db → 0.70.0-rc.4599efb5

package/docs/components/Hero/index.md

@@ -0,0 +1,65 @@
+---
+title: Hero
+description: Use the hero component to render a full-width banner at the top of a page.
+keywords: ['heading', 'intro', 'cta', 'banner']
+---
+
+## Anatomy
+
+![An image displaying a hero with a heading, description, primary and secondary actions.](https://github.com/primer/brand/assets/6951037/14759331-3908-4eaf-9d67-db594b2407f0)
+
+- Label: an optional label to provide leading context to the hero.
+- Heading: the main title of the hero.
+- Description: a short description of the hero.
+- Actions: the main and secondary actions the user should take on the page.
+- Image: an optional foreground image that appears adjacent to the text
+
+## Usage
+
+Use the hero component to provide a title, description and action that introduces the main content of a page. The hero component is designed to be positioned at the top of a page and spans the full width of the viewport. Consider using the [CTA banner](../CTABanner/index.md) to replicate the content and actions in other parts of the page.
+
+Both the heading and description of the hero should be concise and descriptive. The heading should not exceed two lines, and the description should be limited to 3–4 lines.
+
+The description must maintain a minimum contrast ratio of 4.5:1 at all times. Since it may appear in either the `default` or `muted` text colors, ensure the `muted` variant is used only when contrast is sufficient and no background imagery is present.
+
+The hero component is not designed to provide a lot of information to the user. Consider using other components, such as the [section intro](../SectionIntro/index.md) or the [river](../River/index.md) component instead.
+
+The hero heading is rendered as an `h1` element by default. You can modify the heading level but be aware that this will affect the page's heading structure and may impact accessibility. [See heading accessibility](../../typography/Heading/index.md#accessibility) for more information.
+
+The hero can optionally 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.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/7ea1041a-6b3e-4a7c-a7da-a889ee642023)
+
+_Use the hero component to introduce the page with short, descriptive text._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/ed440ce6-a708-4196-b40b-30a2b6f03c13)
+
+_Don't use long, complex text in the hero. Consider splitting the content using other components._
+
+## Options
+
+### Alignment
+
+Hero elements can be aligned to the start or center of the page. By default, the hero is aligned to the start of the page to allow for an image or a visual asset to be positioned on the right of the hero. Use the center alignment if the asset is centered or not present, or the scenario calls for it.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/d3ce9fb3-e455-4535-8613-72d52d8961dc)
+
+_Use left alignment if the hero includes an image or visual asset on the right._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/4e3db6e1-cdb8-4a1e-a81c-b22f431b0738)
+
+_Don't use center alignment if the background interfere with the legibility of the content._
+
+## Related components
+
+- [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.
+- [CTABanner](../CTABanner/index.md): To draw attention to or create urgency around a user action.

package/docs/components/Hero/react.md

@@ -0,0 +1,215 @@
+---
+title: Hero
+description: Use the hero component to render a full-width banner at the top of a page.
+keywords: ['heading', 'intro', 'cta', 'banner']
+ready: true
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=431%3A8481
+source: https://github.com/primer/brand/blob/main/packages/react/src/Hero/Hero.tsx
+storybook: '/brand/storybook/?path=/story/components-hero--default'
+---
+
+```js
+import {Hero} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Hero>
+  <Hero.Label>Label</Hero.Label>
+  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
+  <Hero.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </Hero.Description>
+  <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
+  <Hero.SecondaryAction href="#">Secondary action</Hero.SecondaryAction>
+</Hero>
+```
+
+### Images
+
+`Hero` can display an optional foreground image. Use `position` to alternate between various layouts.
+
+```jsx
+<Stack>
+  <Hero>
+    <Hero.Label>Actions</Hero.Label>
+    <Hero.Heading>Automate your workflow from idea to production</Hero.Heading>
+    <Hero.PrimaryAction href="#">Get started with Actions</Hero.PrimaryAction>
+    <Hero.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+  </Hero>
+  <br />
+  <Hero align="center">
+    <Hero.Label>Actions</Hero.Label>
+    <Hero.Heading size="2">Automate your workflow from idea to production</Hero.Heading>
+    <Hero.PrimaryAction href="#">Get started with Actions</Hero.PrimaryAction>
+    <Hero.Image
+      position="inline-end"
+      src="/images/placeholder.png"
+      alt="placeholder, blank area with a gray background color"
+      style={{height: '100%'}}
+    />
+  </Hero>
+</Stack>
+```
+
+### GridLine variant
+
+Use `variant="gridline"` to display the Hero with a contained image, subtle background color, and borders.
+
+The `GridLine` variants all feature a trailing border by default. Use `Box` if you need to add one to the top also.
+
+```jsx
+<Hero variant="gridline" align="center">
+  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
+  <Hero.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </Hero.Description>
+  <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
+  <Hero.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+</Hero>
+```
+
+### GridLine "Expressive" variant
+
+Use `variant="gridline-expressive"` for an alternative split-content layout.
+
+The `GridLine` variants all feature a trailing border by default. Use `Box` if you need to add one to the top also.
+
+```jsx
+<Hero variant="gridline-expressive">
+  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
+  <Hero.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </Hero.Description>
+  <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
+  <Hero.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+</Hero>
+```
+
+### Video
+
+`Hero` includes support for inserting videos.
+
+Use [VideoPlayer](../VideoPlayer/index.md), a native `<video>` element or a YouTube embed as valid `children`. Similarly to `Hero.Image`, use the `position` prop to alternate between various layouts.
+
+```jsx
+<Hero>
+  <Hero.Label>Label</Hero.Label>
+  <Hero.Heading>This is my super sweet hero heading</Hero.Heading>
+  <Hero.Description>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+    felis nam pulvinar risus elementum.
+  </Hero.Description>
+  <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
+  <Hero.Video>
+    <iframe
+      src="https://www.youtube.com/embed/fHwtrOcLAnI"
+      title="YouTube video player"
+      frameBorder="0"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+      referrerPolicy="strict-origin-when-cross-origin"
+      allowFullScreen
+      style={{width: '100%', height: 'auto', aspectRatio: '16/10'}}
+    ></iframe>
+  </Hero.Video>
+</Hero>
+```
+
+### Alignment
+
+`Hero` text alignment can be adjusted by changing the `align` prop.
+
+```jsx
+<Hero align="center">
+  <Hero.Label>Label</Hero.Label>
+  <Hero.Heading>
+    Blazing fast cloud
+    <br />
+    developer environments
+  </Hero.Heading>
+  <Hero.PrimaryAction href="#">Primary action</Hero.PrimaryAction>
+</Hero>
+```
+
+## Component props
+
+### Hero
+
+| Name              | Type                      |   Default   | Description                                                     |
+| :---------------- | :------------------------ | :---------: | :-------------------------------------------------------------- |
+| `align`           | `'center'`, `'start'`     |  `'start'`  | Optional text alignment                                         |
+| `variant`         | `'default' \| 'gridline'` | `'default'` | Visual variants to the Hero.                                    |
+| `enableAnimation` | `boolean`                 |   `false`   | Enables animations for variants and children that support them. |
+| `className`       | `string`                  |             | Sets a custom class on the root element                         |
+| `ref`             | `React.RefObject`         |             | Forward a Ref to the underlying DOM node                        |
+
+### Hero.Label
+
+| name        | type              | default   | description                                  |
+| ----------- | ----------------- | --------- | -------------------------------------------- |
+| `variant`   | `TextVariants`    | `'muted'` | Specify alternative text appearance          |
+| `className` | `string`          |           | Sets a custom class on the root of the label |
+| `id`        | `string`          |           | Sets a custom id on the root of the label    |
+| `ref`       | `React.RefObject` |           | Forward a Ref to the underlying DOM node     |
+
+### Hero.Heading
+
+| name        | type              | default | description                              |
+| ----------- | ----------------- | ------- | ---------------------------------------- |
+| `className` | `string`          |         | Sets a custom class on the root element  |
+| `id`        | `string`          |         | Sets a custom id                         |
+| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node |
+
+Forwards all props from the [Heading component](../../typography/Heading/index.md), including `as`, `size`, and `weight`.
+
+### Hero.Description
+
+| name        | type           | default              | description                         |
+| ----------- | -------------- | -------------------- | ----------------------------------- |
+| `className` | `string`       |                      | Sets a custom CSS class             |
+| `variant`   | `TextVariants` | `defaultTextVariant` | Specify alternative text appearance |
+
+Forwards `size` and `weight` props from the [Text component](../../typography/Text/index.md).
+
+### Hero.PrimaryAction
+
+| name        | type          | default | description                         |
+| ----------- | ------------- | ------- | ----------------------------------- |
+| `className` | `string`      |         | Primary link custom class           |
+| `href`      | `string`      |         | `href` for primary link             |
+| `as`        | `a`, `button` | `a`     | Applies the underlying HTML element |
+
+Forwards all props from the [Button component](../Button/index.md).
+
+### Hero.SecondaryAction
+
+| name        | type          | default | description                         |
+| ----------- | ------------- | ------- | ----------------------------------- |
+| `className` | `string`      |         | Secondary link custom class         |
+| `href`      | `string`      |         | `href` for secondary link           |
+| `as`        | `a`, `button` | `a`     | Applies the underlying HTML element |
+
+Forwards all props from the [Button component](../Button/index.md).
+
+### Hero.Image
+
+| name       | type                                                                                                                  | default       | description                                  |
+| ---------- | --------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------- |
+| `position` | `'block-end' \| 'block-end-padded' \| 'inline-end' \| 'inline-end-padded' \| 'inline-start' \| 'inline-start-padded'` | `'block-end'` | Controls positioning of the foreground image |
+
+Forwards all props from the [Image component](../Image/index.md), including `src`, `alt`, and `aspectRatio`.
+
+### Hero.Video
+
+| name            | type                                                                                                                  | default       | description                                                                                                     |
+| --------------- | --------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
+| `position`      | `'block-end' \| 'block-end-padded' \| 'inline-end' \| 'inline-end-padded' \| 'inline-start' \| 'inline-start-padded'` | `'block-end'` | Controls positioning of the child video element                                                                 |
+| `poster`        | `string`                                                                                                              |               | URL of the poster image to display before video plays. When set, `posterAltText` and `posterTitle` are required |
+| `posterAltText` | `string`                                                                                                              |               | Alt text for the poster image. Required when `poster` is set                                                    |
+| `posterTitle`   | `string`                                                                                                              |               | Title text displayed on the poster overlay. Required when `poster` is set                                       |

package/docs/components/IDE/index.md

@@ -0,0 +1,278 @@
+---
+title: IDE
+description: Use the IDE to showcase a simulated integrated developer environment, complete with a code editor and AI chat that's intended to enhance code representation in marketing contexts.
+keywords: ['code', 'editor', 'chat', 'suggestions', 'AI']
+source: https://github.com/primer/brand/blob/main/packages/react/src/IDE/IDE.tsx
+storybook: '/brand/storybook/?path=/story/components-ide--playground'
+---
+
+> This component is deprecated and will be removed in a future release. No further updates will be made to it. This page is
+> preserved for reference only.
+
+```js
+import {IDE} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+> The `IDE` does not automatically apply syntax highlighting to code snippets. Usage of this component in GitHub.com is expected to use the proprietary tokenizer and highlighter, the output of which can be passed directly into `IDE` as a parameter.
+
+```jsx
+<IDE height={500}>
+  <IDE.Editor
+    files={[
+      {
+        name: 'index.js',
+        alternativeText: 'TypeScript sentiment analysis function with D3.js visualization.',
+        code: `import { fetch } from "fetch-h2";
+
+async function isPositive(text: string): Promise<boolean> {
+  const response = await fetch(...)
+  const drawScatterplot = (data, height, width) => {
+    const svg = d3.select("#scatterplot")
+      .data(data)
+      .attr("cx", d => d.x)
+      .attr("cy", d => d.y)
+      .attr("r", 5)
+  }
+  const json = await response.json();
+  return json.label === "pos";
+}`,
+      },
+      {
+        name: 'parse_expenses.py',
+        alternativeText:
+          'Python function that converts financial transaction strings into structured data, parsing dates, amounts, and currencies while skipping comments',
+        code: `import datetime
+
+def parse_expenses(expenses_string):
+Ignore lines starting with #.
+Parse the date using datetime.
+Example expenses_string:
+2016-01-02 -34.01 USD
+2016-01-03 2.59 DKK
+2016-01-03 -2.72 EUR
+"""
+expenses = []
+for line in expenses_string.splitlines():
+if line.startswith("#"):
+continue
+date, value, currency = line.split(" ")
+expenses.append((datetime.datetime.strptime(date, "%Y-%m-%d"),
+          float(value),
+          currency))
+return expenses`,
+      },
+    ]}
+  />
+</IDE>
+```
+
+### Animations
+
+Line-by-line animations can be enabled using pre-formatted prop values. A replay button is enabled by default.
+
+```jsx
+<IDE height={500}>
+  <IDE.Editor
+    files={[
+      {
+        name: 'index.js',
+        alternativeText: 'TypeScript sentiment analysis function with D3.js visualization.',
+
+        code: `import { fetch } from "fetch-h2";
+
+async function isPositive(text: string): Promise<boolean> {
+  const response = await fetch(...)
+  const drawScatterplot = (data, height, width) => {
+    const svg = d3.select("#scatterplot")
+      .data(data)
+      .attr("cx", d => d.x)
+      .attr("cy", d => d.y)
+      .attr("r", 5)
+  }
+  const json = await response.json();
+  return json.label === "pos";
+}`
+          .split('\n')
+          .map(line => line || ' '),
+      },
+    ]}
+  />
+</IDE>
+```
+
+### GitHub Copilot suggestions
+
+Simulate GitHub Copilot suggestions using the `suggestedLineStart` property.
+
+```jsx
+<IDE height={500}>
+  <IDE.Editor
+    files={[
+      {
+        name: 'index.js',
+        // Line number at which the suggestion will apply
+        suggestedLineStart: 6,
+        alternativeText:
+          'TypeScript sentiment analysis function with D3.js visualization. Copilot suggests completing the scatterplot with SVG creation and circle attributes.',
+
+        code: `import { fetch } from "fetch-h2";
+
+async function isPositive(text: string): Promise<boolean> {
+  const response = await fetch(...)
+  const drawScatterplot = (data, height, width) => {
+    const svg = d3.select("#scatterplot")
+      .data(data)
+      .attr("cx", d => d.x)
+      .attr("cy", d => d.y)
+      .attr("r", 5)
+  }
+  const json = await response.json();
+  return json.label === "pos";
+}`
+          .split('\n')
+          .map(line => line || ' '),
+      },
+    ]}
+  />
+</IDE>
+```
+
+### GitHub Copilot chat
+
+Simulate GitHub Copilot Chat using the `IDE.Chat` sub-component. The script is fully customizable, and code snippets will require pre-formatting to enable syntax highlighting.
+
+> See Storybook for a comprehensive example of the Chat feature, inclusive of syntax highlighting.
+>
+> See Chat example in Storybook
+
+```jsx
+<IDE height={700}>
+  <IDE.Chat
+    alternativeText="A user asks how to concatenate arrays in JavaScript, Copilot demonstrates using the concat method, and the user confirms it worked."
+    script={[
+      {
+        role: 'user',
+        handle: 'monalisa',
+        avatar: '/images/avatar-mona.png',
+        message: 'How do I concatenate two arrays in JavaScript?',
+      },
+      {
+        role: 'assistant',
+        handle: 'GitHub Copilot',
+        message: "To concatenate two arrays in JavaScript, you can use the `concat` method. Here's an example:",
+        codeSnippet: `const array1 = [1, 2, 3];\nconst array2 = [4, 5, 6];\nconst resultArray = array1.concat(array2);\nconsole.log(resultArray); // Output: [1, 2, 3, 4, 5, 6]`,
+      },
+      {
+        role: 'user',
+        handle: 'monalisa',
+        avatar: '/images/avatar-mona.png',
+        message: 'It worked!',
+      },
+    ]}
+  />
+</IDE>
+```
+
+### Glass variant
+
+A `glass` variant is available to simplify placement of the `IDE` on background images. This variant adds alpha transparency and background blurring.
+
+When using the `glass` variant, pay close attention to the background image behind the tabs of the `IDE.Editor`. Ensure there is sufficient contrast between the text and the background on inactive tabs.
+
+```jsx
+<Box
+  padding={48}
+  borderRadius="large"
+  style={{
+    backgroundImage: `url(https://github.com/primer/brand/assets/13340707/7fe496dc-f6e0-417e-9453-32cec638ca68)`,
+    backgroundRepeat: 'no-repeat',
+    backgroundSize: 'cover',
+    backgroundPosition: 'center',
+  }}
+>
+  <IDE height={400} variant="glass">
+    <IDE.Editor
+      files={[
+        {
+          name: 'index.js',
+          alternativeText: 'TypeScript sentiment analysis function with D3.js visualization.',
+          code: `import { fetch } from "fetch-h2";
+
+async function isPositive(text: string): Promise<boolean> {
+  const response = await fetch(...)
+  const drawScatterplot = (data, height, width) => {
+    const svg = d3.select("#scatterplot")
+      .data(data)
+      .attr("cx", d => d.x)
+      .attr("cy", d => d.y)
+      .attr("r", 5)
+  }
+  const json = await response.json();
+  return json.label === "pos";
+}`,
+        },
+        {
+          name: 'parse_expenses.py',
+          alternativeText:
+            'Python function description and docstring showing how to parse financial transactions with example date, amount, and currency formats.',
+
+          code: `import datetime
+
+def parse_expenses(expenses_string):
+Ignore lines starting with #.
+Parse the date using datetime.
+Example expenses_string:
+2016-01-02 -34.01 USD
+2016-01-03 2.59 DKK
+2016-01-03 -2.72 EUR
+"""`,
+        },
+      ]}
+    />
+  </IDE>
+</Box>
+```
+
+## Accessibility
+
+The full contents of `IDE.Chat` and `IDE.Editor` are intentionally not made available to users of assistive technologies. Summaries of the content — which must be provided using the `alternativeText` prop — are made available instead.
+
+When writing `alternativeText`, consider the following:
+
+- The `IDE.Chat` script should be summarized in a way that conveys the essential information of the conversation.
+- The `IDE.Editor` code should be summarized in a way that conveys the essential information of the code snippet, specifically noting any suggestions made by Copilot.
+
+In both cases, the goal is to provide a meaningful summary of the content that will allow users of assistive technologies to understand the purpose and scope of the conversation or code snippet, without needing to understand the full content.
+
+## Component props
+
+### IDE `Required`
+
+| name      | type                   | default   | required | description                                   |
+| --------- | ---------------------- | --------- | -------- | --------------------------------------------- |
+| `height`  | `number`               | `800`     | `false`  | The optionally configurable height of the IDE |
+| `variant` | `'default' \| 'glass'` | `default` | `false`  | Alternative presentation of the IDE           |
+
+### IDE.Editor
+
+| name               | type                             | default | required | description                     |
+| ------------------ | -------------------------------- | ------- | -------- | ------------------------------- |
+| `activeTab`        | `number`                         |         | `false`  | Active tab index                |
+| `files`            | [`IDEEditorFile[]`](#)           |         | `true`   | Array of editor files           |
+| `showLineNumbers`  | `boolean`                        |         | `false`  | Show line numbers in the editor |
+| `size`             | `'small' \| 'medium' \| 'large'` |         | `false`  | Controls editor text size       |
+| `triggerAnimation` | `boolean`                        |         | `false`  | Trigger animation externally    |
+
+Supported file extensions in the editor include:&#x20;
+
+### IDE.Chat
+
+| name              | type                    | default | required | description                                                                    |
+| ----------------- | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------ |
+| `script`          | [`IDEChatMessage[]`](#) |         | `true`   | Array of chat messages                                                         |
+| `alternativeText` | `string`                |         | `true`   | Alternative description of the chat script for users of assistive technologies |
+| `animationDelay`  | `number`                | `3000`  | `false`  | Delay for the chat animation                                                   |

package/docs/components/Icon/index.md

@@ -0,0 +1,87 @@
+---
+title: Icon
+description: Use the icon component to display Octicons with an optional background
+keywords: ['Octicon', 'symbol']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Icon/Icon.tsx
+storybook: '/brand/storybook/?path=/story/components-icon--playground'
+figma: https://www.figma.com/design/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=15397-35
+---
+
+```js
+import {Icon} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Icon icon={ZapIcon} />
+```
+
+### Colors
+
+```jsx
+<Stack direction="horizontal" gap={16} flexWrap="wrap" padding="none">
+  <Icon icon={RocketIcon} color="default" />
+  <Icon icon={RocketIcon} color="blue" />
+  <Icon icon={RocketIcon} color="coral" />
+  <Icon icon={RocketIcon} color="green" />
+  <Icon icon={RocketIcon} color="gray" />
+  <Icon icon={RocketIcon} color="indigo" />
+  <Icon icon={RocketIcon} color="lemon" />
+  <Icon icon={RocketIcon} color="lime" />
+  <Icon icon={RocketIcon} color="orange" />
+  <Icon icon={RocketIcon} color="pink" />
+  <Icon icon={RocketIcon} color="purple" />
+  <Icon icon={RocketIcon} color="red" />
+  <Icon icon={RocketIcon} color="teal" />
+  <Icon icon={RocketIcon} color="yellow" />
+</Stack>
+```
+
+### With background
+
+```jsx
+<Stack direction="horizontal" gap={16} flexWrap="wrap" padding="none">
+  <Icon icon={RocketIcon} hasBackground color="default" />
+  <Icon icon={RocketIcon} hasBackground color="blue" />
+  <Icon icon={RocketIcon} hasBackground color="coral" />
+  <Icon icon={RocketIcon} hasBackground color="green" />
+  <Icon icon={RocketIcon} hasBackground color="gray" />
+  <Icon icon={RocketIcon} hasBackground color="indigo" />
+  <Icon icon={RocketIcon} hasBackground color="lemon" />
+  <Icon icon={RocketIcon} hasBackground color="lime" />
+  <Icon icon={RocketIcon} hasBackground color="orange" />
+  <Icon icon={RocketIcon} hasBackground color="pink" />
+  <Icon icon={RocketIcon} hasBackground color="purple" />
+  <Icon icon={RocketIcon} hasBackground color="red" />
+  <Icon icon={RocketIcon} hasBackground color="teal" />
+  <Icon icon={RocketIcon} hasBackground color="yellow" />
+</Stack>
+```
+
+### Sizes
+
+```jsx
+<Stack direction="vertical">
+  <Icon icon={CopilotIcon} size="small" />
+  <Icon icon={CopilotIcon} size="medium" />
+  <Icon icon={CopilotIcon} size="large" />
+</Stack>
+```
+
+## Component props
+
+### Icon
+
+| Name            | Type                                                 | Default     | Description                                  |
+| :-------------- | :--------------------------------------------------- | :---------- | :------------------------------------------- |
+| `icon`          | `OcticonProps` \| `React.ReactElement<OcticonProps>` |             | The Octicon component to render              |
+| `color`         | `iconColors`                                         | `'default'` | The color of the icon                        |
+| `size`          | `namedIconSizes \| numericIconSizes`                 | `'small'`   | The size of the icon                         |
+| `hasBackground` | `boolean`                                            | `false`     | Whether to show a background behind the icon |
+| `className`     | `string`                                             |             | Additional CSS class for the icon            |
+
+All other props are forwarded to the underlying SVG element.