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
primer · Dec 3, 2024 · 0027597 · 0027597
1 parent 26f79f6
commit 0027597
Show file tree

Hide file tree

Showing 5 changed files with 102 additions and 2 deletions.
diff --git a/.changeset/lovely-jobs-lay.md 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
@@ -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
@@ -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
@@ -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
@@ -47,6 +47,7 @@ export * from './Section'
 export * from './Statistic'
 export * from './BreakoutBanner'
 export * from './Footnotes'
+export * from './Icon'
 
 // hooks
 export * from './hooks/useWindowSize'