From 00275979c386bd3d5761a4dab2d8d6bb92f03279 Mon Sep 17 00:00:00 2001
From: Josh Farrant <joshfarrant@github.com>
Date: Tue, 3 Dec 2024 11:52:29 +0000
Subject: [PATCH] export Icon component and add documentation (#844)

* export Icon component and add documentation

* add changeset

* explicitly name icon sizes

* update changeset

* add reference to Figma to Icon documentation
---
 .changeset/lovely-jobs-lay.md                 | 10 +++
 apps/docs/content/components/Icon.mdx         | 88 +++++++++++++++++++
 .../src/@primer/gatsby-theme-doctocat/nav.yml |  2 +
 packages/react/src/Bento/Bento.stories.tsx    |  3 +-
 packages/react/src/index.ts                   |  1 +
 5 files changed, 102 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/lovely-jobs-lay.md
 create mode 100644 apps/docs/content/components/Icon.mdx

diff --git a/.changeset/lovely-jobs-lay.md b/.changeset/lovely-jobs-lay.md
new file mode 100644
index 000000000..346034a61
--- /dev/null
+++ b/.changeset/lovely-jobs-lay.md
@@ -0,0 +1,10 @@
+---
+'@primer/react-brand': minor
+---
+
+New `Icon` component is generally available.
+
+Example:
+<Icon icon={ZapIcon} />
+
+🔗 [Read the documentation for more usage examples](https://primer.style/brand/components/Icon)
diff --git a/apps/docs/content/components/Icon.mdx b/apps/docs/content/components/Icon.mdx
new file mode 100644
index 000000000..3cd0a101e
--- /dev/null
+++ b/apps/docs/content/components/Icon.mdx
@@ -0,0 +1,88 @@
+---
+title: Icon
+source: https://github.com/primer/brand/tree/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
+description: Use the icon component to display Octicons with an optional background
+---
+
+import {PropTableValues} from '../../src/components'
+import {iconColors, namedIconSizes, numericIconSizes} from '@primer/react-brand'
+
+```js
+import {Icon} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx live
+<Icon icon={ZapIcon} />
+```
+
+### Colors
+
+```jsx live
+<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 live
+<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 live
+<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`         | <PropTableValues values={iconColors} commaSeparated />                               | `'default'` | The color of the icon                        |
+| `size`          | <PropTableValues values={[...namedIconSizes, ...numericIconSizes]} commaSeparated /> | `'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.
diff --git a/apps/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/apps/docs/src/@primer/gatsby-theme-doctocat/nav.yml
index f182eee83..6b3459ca8 100644
--- a/apps/docs/src/@primer/gatsby-theme-doctocat/nav.yml
+++ b/apps/docs/src/@primer/gatsby-theme-doctocat/nav.yml
@@ -62,6 +62,8 @@
       url: /components/Footnotes
     - title: Hero
       url: /components/Hero
+    - title: Icon
+      url: /components/Icon
     - title: IDE
       url: /components/IDE
     - title: Image
diff --git a/packages/react/src/Bento/Bento.stories.tsx b/packages/react/src/Bento/Bento.stories.tsx
index 8606d9555..77f3f28cb 100644
--- a/packages/react/src/Bento/Bento.stories.tsx
+++ b/packages/react/src/Bento/Bento.stories.tsx
@@ -2,8 +2,7 @@ import React from 'react'
 import {Meta} from '@storybook/react'
 import {CopilotIcon} from '@primer/octicons-react'
 import {Bento} from '.'
-import {Link} from '../'
-import {Icon} from '../Icon'
+import {Link, Icon} from '../'
 
 export default {
   title: 'Components/Bento',
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index e11602744..ba9bdcc7b 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -47,6 +47,7 @@ export * from './Section'
 export * from './Statistic'
 export * from './BreakoutBanner'
 export * from './Footnotes'
+export * from './Icon'
 
 // hooks
 export * from './hooks/useWindowSize'