@primer/react-brand 0.69.1-rc.0a4e5ff5 → 0.70.0-rc.11ae3568

package/docs/components/Pillar/index.md

@@ -0,0 +1,114 @@
+---
+title: Pillar
+description: Use the pillar component to group related content together.
+keywords: ['feature', 'benefit', 'icon']
+---
+
+## Anatomy
+
+![An image showing the Pillar anatomy with an icon, a heading and a description in a vertical order.](https://github.com/primer/brand/assets/912236/785baf0f-4800-476e-8f90-b032851714c4)
+
+- Icon: An optional visual cue related to the content of the Pillar.
+- Heading: The main title of the Pillar. It should be short and concise.
+- Description: Short text that extends the information provided by the heading.
+- Link: An optional link to extended the information.
+
+## Usage
+
+Use pillars to display a collection of features or benefits, making them easier to scan and read. Pillars present content in a familiar and recognizable style.
+
+### Stacked
+
+Stack multiple pillars to create a collection of items. Ensure that all the items in a group have consistent content lengths so that their width and height match, making the content more visually appealing. When displaying a visual, create a balanced layout by using the same type for each pillar, either an icon or an image.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/cd9679ab-cfa0-4c6d-8a55-21d16668f1ca)
+
+_Use similar character counts to achieve a visually balanced layout._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/cd6e471f-98cf-4c70-801f-c0aeb4d2bdf5)
+
+_Avoid varying content lengths for the title and description._
+
+> Use pillars with images only for groups of a maximum of three to six items. Avoid stacking multiple sections that each
+> contain groups of six pillars.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/cdceda67-a911-40a0-839a-4620c83fe510)
+
+_When using icons, add them to all pillars to create a visually balanced layout._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/20955ac2-6aee-40ee-bcdf-605bc07f9b1d)
+
+_Don't use icons sparingly._
+
+**✅ Do**
+
+_When using images, add them to all pillars to create a visually balanced layout._
+
+**❌ Don't**
+
+_Don't use images with different aspect ratios._
+
+When presenting more than four pillars, we recommend displaying them in multiple rows. You can use the [Grid](../../layout/Grid/index.md) or the [Stack](../../layout/Stack/index.md) component to achieve this. We recommend using a grid with three or four columns and balancing the number of pillars on each row.
+
+![An image showing a group of numerous Pillars stacked in a three column grid.](https://github.com/primer/brand/assets/912236/350c5eab-bd21-450c-a7a3-60e29c828a3f)
+
+### Pillar and Card
+
+Pillar and Card are both components that are used to present related and/or condensed information. They have distinct use-cases however, with the main differences between them being:
+
+#### Interaction
+
+Pillars are used mainly for non-interactive content and might include an optional link for extended information. On the other hand, Cards are primarily navigational elements.
+
+#### Hierarchy
+
+Cards should be used for noteworthy information to immediately draw user attention. Pillars, on the other hand, should be used for lower priority information compared to Cards.
+
+#### Group size
+
+Cards should be used in small groups of three to five items, while Pillars can accommodate larger groups of up to nine items, or six if using images. The more items in a group, the less distinctive each individual element becomes.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/bc33c846-71c2-4af6-a3ac-f886bad71995)
+
+_Pillars are suitable for groups of up to six items._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/302dbc4d-6199-4c0c-96d5-76ac2e35fdea)
+
+_Don't use Cards for groups of five or more items. Use them sparingly in groups of three or four._
+
+## Options
+
+### Align
+
+Pillars can be aligned to the start or center of the container. Aligning to the start is the default and recommended behavior. Use center alignment only when displaying a maximum of 4 pillars and the overall page design calls for this alignment, so that the content is visually balanced and easy to scan.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/8762f31e-d39d-458f-b016-85b450251685)
+
+_Center align pillars when in groups of 3 or 4 and if their title and descriptions are short._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/87eb975f-b165-49ad-82bf-2f1e329c46bf)
+
+_Don't use center alignment when in groups of 5 or more._
+
+## 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.
+- [CTABanner](../CTABanner/index.md): To display a single block of content to draw attention or create urgency around a user action.
+- [UnorderedList](../UnorderedList/index.md) or the [OrderedList](../OrderedList/index.md): To display a list of plain content items.

package/docs/components/Pillar/react.md

@@ -0,0 +1,175 @@
+---
+title: Pillar
+description: Use the pillar component to group related content together.
+keywords: ['feature', 'benefit', 'icon']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Pillar/Pillar.tsx
+storybook: '/brand/storybook/?path=/story/components-pillar--playground'
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=6849-31364&mode=design
+---
+
+```js
+import {Pillar} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+The default Pillar displays a heading and description.
+
+```jsx
+<Pillar>
+  <Pillar.Heading>Collaboration is the key to DevOps success</Pillar.Heading>
+  <Pillar.Description>Everything you need to know about getting started with GitHub Actions.</Pillar.Description>
+</Pillar>
+```
+
+### Icon
+
+You can add an `icon` to enhance the visual context. We recommend using an [Octicon](https://primer.style/design/foundations/icons). The icon defaults to a green presentation and can be customized using the `size` and `hasBackground` props. For custom SVG artwork or logos, set `hasBackground` to `false` to render the icon without the shared square icon frame.
+
+```jsx
+<Pillar>
+  <Pillar.Icon icon={<CopilotIcon />} />
+  <Pillar.Heading>Code search & code view</Pillar.Heading>
+  <Pillar.Description>
+    Enables you to rapidly search, navigate, and understand code, right from GitHub.com.
+  </Pillar.Description>
+</Pillar>
+```
+
+### Image
+
+You can add an image to enhance the visual context.
+
+```jsx
+<Pillar>
+  <Pillar.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+  <Pillar.Heading>Code search & code view</Pillar.Heading>
+  <Pillar.Description>
+    Enables you to rapidly search, navigate, and understand code, right from GitHub.com.
+  </Pillar.Description>
+</Pillar>
+```
+
+### Full width
+
+Use the `fullWidth` prop to allow the Pillar to fill the width of its parent container. By default, pillar width is constrained.
+
+```jsx
+<Pillar fullWidth>
+  <Pillar.Image src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+  <Pillar.Heading>Code search & code view</Pillar.Heading>
+  <Pillar.Description>
+    Enables you to rapidly search, navigate, and understand code, right from GitHub.com.
+  </Pillar.Description>
+</Pillar>
+```
+
+### Link
+
+You can add an external link to the Pillar using the `Link` component.
+
+```jsx
+<Pillar>
+  <Pillar.Heading>Code search & code view</Pillar.Heading>
+  <Pillar.Description>
+    Enables you to rapidly search, navigate, and understand code, right from GitHub.com.
+  </Pillar.Description>
+  <Pillar.Link href="https://github.com">Learn more</Pillar.Link>
+</Pillar>
+```
+
+### Align
+
+The content alignment can be changed using the `align` prop on the root `Pillar`. This can be configured to either `start` or `center`.
+
+```jsx
+<Pillar align="center">
+  <Pillar.Icon icon={<CopilotIcon />} />
+  <Pillar.Heading>Code search & code view</Pillar.Heading>
+  <Pillar.Description>
+    Enables you to rapidly search, navigate, and understand code, right from GitHub.com.
+  </Pillar.Description>
+</Pillar>
+```
+
+### Stacked Pillars
+
+Use the `Stack` component to stack multiple Pillars horizontally or vertically.
+
+```jsx
+<Stack direction="horizontal" alignItems="center" justifyContent="center" gap="normal">
+  <Pillar>
+    <Pillar.Icon icon={<CopilotIcon />} />
+    <Pillar.Heading>Heading</Pillar.Heading>
+    <Pillar.Description>Everything you need to know about getting started with GitHub Actions.</Pillar.Description>
+  </Pillar>
+  <Pillar>
+    <Pillar.Icon icon={<RocketIcon />} />
+    <Pillar.Heading>Heading</Pillar.Heading>
+    <Pillar.Description>Everything you need to know about getting started with GitHub Actions.</Pillar.Description>
+  </Pillar>
+  <Pillar>
+    <Pillar.Icon icon={<GitBranchIcon />} />
+    <Pillar.Heading>Heading</Pillar.Heading>
+    <Pillar.Description>Everything you need to know about getting started with GitHub Actions.</Pillar.Description>
+  </Pillar>
+</Stack>
+```
+
+## Component props
+
+### Pillar
+
+| name        | type                 | default | required | description                                                  |
+| ----------- | -------------------- | ------- | -------- | ------------------------------------------------------------ |
+| `align`     | `start`, `center`    | `start` | `false`  | Aligns the pillar content                                    |
+| `as`        | `'div' \| 'article'` | `'div'` | `false`  | The HTML element used to render the pillar.                  |
+| `fullWidth` | `boolean`            | `false` | `false`  | Allows the pillar to fill the width of its parent container. |
+
+### Pillar.Icon
+
+| name            | type                                 | default | required | description                                                                                                                       |
+| --------------- | ------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `icon`          | `React.Node`                         |         | `true`   | Octicon                                                                                                                           |
+| `size`          | `namedIconSizes \| numericIconSizes` | `32`    | `false`  | The size of the icon                                                                                                              |
+| `hasBackground` | `boolean`                            | `true`  | `false`  | Adds a filled colored background to the icon. Set to `false` for custom artwork that should not use the shared square icon frame. |
+
+Supports the [Icon component](../Icon/index.md) props, excluding `color`.
+
+### Pillar.Image
+
+Forwards all the props from the [Image component](../Image/index.md), including `src`, `alt`, and `aspectRatio`.
+
+### Pillar.Heading
+
+| name        | type                         | default     | required | description                                           |
+| ----------- | ---------------------------- | ----------- | -------- | ----------------------------------------------------- |
+| `as`        | `h2`, `h3`, `h4`, `h5`, `h6` | `h3`        | `false`  |                                                       |
+| `className` | `string`                     |             | `false`  | Custom class name for the heading component           |
+| `children`  | `ReactNode`, `ReactNode[]`   | `undefined` | `true`   | Content to be displayed inside the heading component. |
+
+Forwards all the props from the [Heading component](../../typography/Heading/index.md), including `as`, `size`, and `weight`.
+
+### Pillar.Description
+
+Optional node that can be used to provide a description for the section.
+
+| name       | type                       | default     | required | description                                         |
+| ---------- | -------------------------- | ----------- | -------- | --------------------------------------------------- |
+| `children` | `ReactNode`, `ReactNode[]` | `undefined` | `true`   | Content to be displayed inside the pillar component |
+
+`id`, `className` and `ref` are forwarded by default to all children.
+
+### Pillar.Link
+
+Optional node that can be used to provide a link.
+
+| name        | type     | default     | required | description                               |
+| ----------- | -------- | ----------- | -------- | ----------------------------------------- |
+| `className` | `string` | `undefined` | `false`  | Sets a custom class on the root element   |
+| `href`      | `string` |             | `true`   | Local identifier for the anchored element |
+
+`id`, `className` and `ref` are forwarded by default to all children.