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

package/docs/components/Image/index.md

@@ -0,0 +1,51 @@
+---
+title: Image
+description: Use the image component to display a graphical representation.
+keywords: ['illustration', 'picture', 'screenshot']
+---
+
+## Usage
+
+Use an image to display a graphical representation, such as a photograph or a visual illustration, on a web page. Use it in combination with text to provide context or additional information.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/3ffc80cb-4d7d-4ef4-b66f-10e902d8f17c)
+
+_Use an image to display a photograph in combination with descriptive text to provide context._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/6f29d849-9379-4327-a4aa-e1233e19861b)
+
+_Don't use an icon as an image or illustration._
+
+## Options
+
+### Size
+
+Choose the appropriate dimensions for the image to fit the desired layout using the `width/height` or the `aspect-ratio` properties. Avoid using images that are too large or too small for their intended display. When using images in a list, make sure they are all the same size to achieve a visually balanced layout.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/7e9cf19c-1545-4b47-9ac8-0442050eb509)
+
+_In a list or group, use images of the same size and aspect ratio._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/6efc49d3-f982-4f9f-9951-413a05f329cc)
+
+_Don't use images of different sizes in the same section._
+
+## Accessibility
+
+Use the `alt` attribute to provide alternative text that is displayed if the image cannot be loaded or for accessibility purposes. It is important to include descriptive alternative text that conveys the meaning or content of the image. For more info, see [alternative text for images](https://primer.style/design/guides/accessibility/alternative-text-for-images).
+
+Optimize your images to reduce file size without compromising quality. Smaller file sizes improve page loading speed.
+
+## 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.
+- [Avatar](../Avatar/index.md): Use avatar to display a thumbnail representation of a person.

package/docs/components/Image/react.md

@@ -0,0 +1,160 @@
+---
+title: Image
+description: Use the image component to display a graphical representation.
+keywords: ['illustration', 'picture', 'screenshot']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Image/Image.tsx
+storybook: '/brand/storybook/?path=/story/components-image--playground'
+---
+
+```js
+import {Image} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+This component uses the `img` element by default.
+
+```jsx
+<Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+```
+
+### Picture
+
+The `as` prop can be used to set the container of the image to use `picture`.
+
+```jsx
+<Image as="picture" src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+```
+
+### Picture with sources
+
+The `sources` prop can be used to set the source elements within the `picture` component. This can only be used when `as` is set to `picture`.
+
+```jsx
+<Image
+  as="picture"
+  src="/images/placeholder.png"
+  alt="placeholder, blank area with a gray background color"
+  sources={[
+    {
+      srcset: '/images/placeholder.png',
+      media: '(min-width: 600px)',
+    },
+    {
+      srcset: '/images/placeholder.png',
+      media: '(min-width: 900px)',
+    },
+  ]}
+/>
+```
+
+### Image with source set
+
+The `srcSet` prop can be used to set the srcSet of the image. This can only be used when `as` is set to `img`.
+
+```jsx
+<Image
+  src="/images/placeholder.png"
+  srcSet="/images/placeholder.png, /images/placeholder.png 1.5x"
+  alt="placeholder, blank area with a gray background color"
+/>
+```
+
+### Aspect ratio
+
+The `aspectRatio` prop can be used to set the aspect ratio of the image. This is useful when the image is not the same aspect ratio as the container.
+
+```jsx
+<Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" aspectRatio="16:9" />
+```
+
+### Height
+
+The `height` prop can be used to set the height of the image. This can be used along side the `aspectRatio` prop to create a responsive image the same size as other images.
+
+```jsx
+<Image
+  src="/images/placeholder.png"
+  alt="placeholder, blank area with a gray background color"
+  height={200}
+  aspectRatio="16:9"
+/>
+```
+
+### Border radius
+
+The `borderRadius` prop can be used to apply rounded corners to images using preset values.
+
+```jsx
+<Stack direction="horizontal">
+  <Image
+    src="/images/placeholder.png"
+    alt="placeholder, blank area with a gray background color"
+    height={100}
+    width={100}
+    borderRadius="small"
+  />
+  <Image
+    src="/images/placeholder.png"
+    alt="placeholder, blank area with a gray background color"
+    height={100}
+    width={100}
+    borderRadius="medium"
+  />
+  <Image
+    src="/images/placeholder.png"
+    alt="placeholder, blank area with a gray background color"
+    height={100}
+    width={100}
+    borderRadius="large"
+  />
+  <Image
+    src="/images/placeholder.png"
+    alt="placeholder, blank area with a gray background color"
+    height={100}
+    width={100}
+    borderRadius="xlarge"
+  />
+  <Image
+    src="/images/placeholder.png"
+    alt="placeholder, blank area with a gray background color"
+    height={100}
+    width={100}
+    borderRadius="full"
+  />
+</Stack>
+```
+
+### Width
+
+The `width` prop can be used to set the width of the image. This can be used along side the `aspectRatio` prop to create a responsive image the same size as other images.
+
+```jsx
+<Image
+  src="/images/placeholder.png"
+  alt="placeholder, blank area with a gray background color"
+  width={200}
+  aspectRatio="16:9"
+/>
+```
+
+## Component props
+
+### Image `Required`
+
+| name           | type                                              | default     | required | description                                                                                                                                                               |
+| -------------- | ------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`          | `string`                                          |             | `true`   | Specifies the path to the image                                                                                                                                           |
+| `alt`          | `string`                                          |             | `true`   | Specifies a text value explaining the nature of the image for users of assistive technology                                                                               |
+| `as`           | `img`, `picture`                                  | `img`       | `false`  | Specification to create a picture component                                                                                                                               |
+| `sources`      | `{srcset: string, media: string}[]`               |             | `false`  | When picture is specified in the `as` prop sources allows you to set the source elements.                                                                                 |
+| `aspectRatio`  | `'1:1'`, `'16:9'`, `'16:10'`, `'4:3'`, `'custom'` | `undefined` | `false`  | Sets the image aspect ratio. A custom ratio can be provided in the design tokens.                                                                                         |
+| `borderRadius` | `ImageBorderRadiusOptions`                        | `undefined` | `false`  | Applies a system-level border radius value to the Image.                                                                                                                  |
+| `height`       | `number`                                          |             | `false`  | The height of the image element or its container if it has an aspect ratio                                                                                                |
+| `width`        | `number`                                          |             | `false`  | The width of the image element or its container if it has an aspect ratio                                                                                                 |
+| `loading`      | `eager`, `lazy`                                   | `eager`     | `false`  | The loading attribute specifies whether a browser should load an image immediately or to defer loading of off-screen images until for example the user scrolls near them. |
+| `decoding`     | `sync`, `async`, `auto`                           | `sync`      | `false`  | Sets the image decoding strategy. Representing a hint given to the browser on how it should decode the image.                                                             |
+| `className`    | `string`                                          |             | `false`  | Sets a custom CSS class                                                                                                                                                   |

package/docs/components/Label/index.md

@@ -0,0 +1,86 @@
+---
+title: Label
+description: Use the label component to add metadata or indicate the status of items.
+keywords: ['badge', 'tag', 'metadata', 'status', 'indicator']
+---
+
+![An image showing a group of labels with different styles, colors, leading icons and content.](https://github.com/primer/brand/assets/6951037/1c9c6b81-0a2a-4a56-a9f5-a9608f89e220)
+
+## Usage
+
+Use labels to indicate the status of an item or to help oraganize and categorize them. E.g, using "New" or "Recommended". Labels aren't meant to be used as interactive elements. Instead use the [Button](../Button/index.md) component.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/5da25ec0-a780-4add-972a-246bf9462e07)
+
+_Use labels to categorize an item._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/976d645c-17ba-45ff-97ea-03c81a4c3b53)
+
+_Don't use labels as an interactive or navigational element. Use a button or a link component._
+
+Position the labels to clearly identify the object they’re informing.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/467449ad-013d-4b9c-9eec-a4655c4d13ec)
+
+_Give labels enough space to be clearly identified. Use size or color to differentiate them if needed._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/5a32b608-2bc7-417b-b064-42c2308075ea)
+
+_When used along with other items, don't place the label too close to them._
+
+### Content
+
+Use Label with with short, scannable text. If possible, use a single word to describe the status of an object. Use two or more words if you need to describe a complex state or category. For example, “Limited availability" or "Enterprise only".
+
+## Options
+
+### Size
+
+Labels come in two sizes: `medium`, and `large`.
+
+### Medium
+
+Use the `medium` size when paired with medium-sized headings or in components such as `Card`.
+
+![](https://github.com/primer/brand/assets/912236/2bca5ddd-2422-41a1-a32c-dc6be243f9ce)
+
+_The Card component allows for a medium label to provide extra meta data to the content. In a group of stacked cards,
+the label helps to quickly scan certain items._
+
+![](https://github.com/primer/brand/assets/6951037/c51e151c-d93a-42f8-bf73-6bd15b1c3781)
+
+_Medium labels are great for headings that introduce a section. They help categorize the main topic and provide a
+visual break._
+
+### Large
+
+Use the `large` size when paired with large headings, such as in the `Hero` component.
+
+![](https://github.com/primer/brand/assets/6951037/13f9debc-3b20-4f77-a509-b8291ca677ae)
+
+_Use large labels with headings that introduce a page. Use it to introduce the main topic or application._
+
+### Color
+
+The label offers color options from the [Primer Brand color palette](../../primitives/color.md). These color choices are carefully curated to ensure optimal contrast with the background or surrounding elements. Colors options doesn't follow a strict functional meaning. We recommend using the colors that best fit the context of your application. For example, blue and purple gradient for `Copilot` examples.
+
+![An image showing multiple label options with different colors.](https://github.com/primer/brand/assets/6951037/41817520-87bb-41bc-9586-95155604b83d)
+
+### Leading visual
+
+You can add a leading icon to enhance the visual context. It is recommended you use an [Octicon](https://primer.style/octicons). Use an icon that reinforces the meaning of the label. For example, a `StarIcon` for a "Starred" label.
+
+![An image showing multiple label options with different leading visuals.](https://github.com/primer/brand/assets/6951037/d5fdf463-f5ce-4806-886d-1b8f44278308)
+
+## Related components
+
+- [Button](../Button/index.md): To provide an action.
+- Link: To provide navigation.

package/docs/components/Label/react.md

@@ -0,0 +1,76 @@
+---
+title: Label
+description: Use the label component to add metadata or indicate the status of items.
+keywords: ['badge', 'tag', 'metadata', 'status', 'indicator']
+ready: true
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=6084-28401'
+source: https://github.com/primer/brand/blob/main/packages/react/src/Label/Label.tsx
+storybook: '/brand/storybook/?path=/story/components-label--playground'
+a11yReviewed: true
+---
+
+```js
+import {Label} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+This is the default variant for the `Label`component. It corresponds to the `medium` size and `default` color.
+
+```jsx
+<Label>Default</Label>
+```
+
+### Sizes
+
+Use the `size` prop to adjust the size of the `Label` component. The `small` size is ideal for body text. The `medium` size is recommended for small headings and `large` is suitable for large headings or section intros.
+
+```jsx
+<Stack direction="horizontal" alignItems="flex-start" padding="none">
+  <Label size="small">Small</Label>
+  <Label size="medium">Medium</Label>
+  <Label size="large">Large</Label>
+</Stack>
+```
+
+### Color
+
+Use the `color` prop to change the color of the `Label` component. The `default` color is recommended for use with neutral backgrounds.
+
+```jsx
+<Stack direction="horizontal" alignItems="flex-start" padding="none">
+  <Label color="blue">Blue</Label>
+  <Label color="red">Red</Label>
+  <Label color="green-blue">Green blue</Label>
+  <Label color="red">Red</Label>
+  <Label color="pink-blue">Pink blue</Label>
+  <Label color="orange">Orange</Label>
+</Stack>
+```
+
+### Leading visual
+
+You can add a leading icon to enhance the visual context. It is recommended you use an [Octicon](https://primer.style/octicons) here.
+
+```jsx
+<Stack direction="horizontal" alignItems="flex-start" padding="none">
+  <Label color="yellow" leadingVisual={<StarIcon />}>
+    Starred
+  </Label>
+  <Label color="blue-purple" leadingVisual={<CopilotIcon />}>
+    Copilot
+  </Label>
+</Stack>
+```
+
+## Component props
+
+### Label
+
+| Name            | Type           |   Default   | Description                                         |
+| :-------------- | :------------- | :---------: | :-------------------------------------------------- |
+| `leadingVisual` | `ReactElement` | `undefined` | The leading visual appears before the Label content |
+| `size`          | `LabelSizes`   |  `'medium'` | The size variations available in Label              |
+| `color`         | `LabelColors`  | `'default'` | The color variations available in Label             |

package/docs/components/LogoSuite/index.md

@@ -0,0 +1,93 @@
+---
+title: Logo suite
+description: Use a logo suite to present a list logos, such as sponsors or vendors.
+keywords: ['logos', 'sponsors', 'vendors', 'clients', 'enterprise', 'social proof']
+---
+
+## Anatomy
+
+![A complete logo suite component, featuring a heading, description and two rows of 6 vendor logos in their default muted colors](https://github.com/primer/brand/assets/13340707/1a5e494f-7bd3-497c-933c-6c809a78422c)
+
+- **Heading:** an optional main title of the logo suite.
+- **Description:** optional information that describes the logos shown.
+- **Logobar:** a space for a list of logos, with three appearance options.
+- **Divider:** an optional divider to separate the logo suite from following content.
+
+## Usage
+
+Use the logo suite component to showcase a list of logos, such as for clients, sponsors, or related enterprises.
+
+A logo suite is intended to build credibility, trust, and provide social proof by displaying consistent logos.
+
+Logo suite should be used for groups of logos more than 4 and less than 12. To create the best visual consistency and balance, rearrange and resize the logos when necessary to create similar area distribution and attention to each of the logos.
+
+### Arrangement
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/131988618/da2bd3f3-c7d8-4880-b30d-c05dd4897ba6)
+
+_Arrange the logos so that the sizes, heights, colors, and areas of the separate logos create consistency and
+balance._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/13340707/d7ac28ec-e341-4d77-8220-fd4197d5613b)
+
+_Don’t place logos without considering the spatial balance of the logo suite. Rearrange the logos to prevent using
+more than two rows or imbalance._
+
+### Color uniformity
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/13340707/b7126430-0d81-4fb6-bd7d-8f35cff923dd)
+
+_Ensure that the colors are consistent across the logos to match the logo bar option. Ensure spacing between logos
+are consistent._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/13340707/85f477d5-9c3d-4db3-847c-1bcf3539ab67)
+
+_Don’t use logos with inconsistent colors or don’t match the logo bar option. Don’t use inconsistent spacing._
+
+## Options
+
+### Logo bar appearance
+
+The logo suite offers three appearance options:
+
+- `muted`: The muted option is suitable for displaying 6+ logos and displays logos in a `secondary` color. It allows for two rows of logos, maintaining a clean and organized appearance.
+- `emphasis`: The emphasis option is designed for spotlighting 5 or fewer logos in the `primary` color. It displays logos larger, drawing more attention to the logos.
+- `marquee`: The marquee option provides a flowing logo animation and can accommodate up to 12 logos. It is ideal for scenarios with limited page real estate.
+
+The `muted` and `emphasis` variants will automatically be applied if they are not specified. The `muted` variant will be applied if there are 6 or more logos, and the `emphasis` variant will be applied if there are 5 or fewer logos.
+
+All three options on the logo bar contains an optional divider. This divider can serve as a visual separator. These three options can be used adjacently.
+
+![](https://github.com/primer/brand/assets/131988618/d525e6b1-bf67-4684-9300-401ef7686b47)
+
+_Use the muted option when displaying 6-12 logos across two rows. 2 rows (when using 6-12 logos)._
+
+![](https://github.com/primer/brand/assets/131988618/ce3e22f1-9852-4869-830b-5d54b6a1a039)
+
+_The emphasis option can be used to spotlight logos. It is best used with 5 or fewer logos to create 1 row\._
+
+![](https://github.com/primer/brand/assets/131988618/409d7a90-d086-438b-80ab-31350f6c42fa)
+
+_The marquee options allows for different speed options._
+
+### Alignment
+
+The logo suite comes with start and center align options. Only the heading and description will have visible changes to their alignment as logos will be consistently center aligned to create balance. By default, the logo suite is aligned to the start of the page.
+
+## Accessibility
+
+Always ensure that a heading is provided to the logo suite. Headings provide leading context to the logos shown, and serve as a navigation hook for assistive technologies. It can be visually hidden if needed.
+
+## Related components
+
+- [Image](../Image/index.md): to display a graphical representation.
+- [Ordered List](../OrderedList/index.md): to display a list of numbered items.
+- [Unordered List](../UnorderedList/index.md): to present a collection of items without specific ordering.