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

package/docs/components/River/index.md

@@ -0,0 +1,190 @@
+---
+title: River
+description: Use the river component to introduce a feature using a type and media pairing.
+keywords: ['feature', 'showcase', 'highlight', 'story']
+---
+
+![A river component used to showcase a security feature. The title reads "Get security feedback with every git push" and it includes an image showing screenshots of of a CLI prompt with the git push command and a code scanning screenshot.](https://github.com/primer/brand/assets/912236/e01c2743-54cd-4ed0-9a6e-2afdadabb66e)
+
+## Usage
+
+Use rivers to showcase features and introduce topics. Rivers are composed of images or videos paired alongside text content like headings, paragraphs, and links.
+
+A river’s content should be short and concise, no longer than 3 or 4 sentences and in a single paragraph when possible.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/55e56aa1-2a04-4cc4-b708-08c480ba5943)
+
+_Write short and concise text content._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/bd3585bc-a79b-4ca2-bbc4-ff59bc8c75cf)
+
+_Don't overload the river with too much content._
+
+### Stacked
+
+Two or more rivers can be stacked to guide the user through a set of features. When stacking rivers, alternate between left and right alignments to create a more dynamic reading flow. When alternating alignments, use a `40:60` image to text ratio, otherwise keep the ratio to `50:50`.
+
+It is possible to use 2 or more following left or right river to create a simple alignment promoting easy scroll scan.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/a7f8bca8-78e6-4e29-a44b-5a305ffeeeae)
+
+_Alternate rivers with left and right alignments._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/169d5c19-67f4-4f15-8e3b-80c877b34af1)
+
+_Don't break the flow in a stack of rivers that would otherwise stay aligned._
+
+Note that too many rivers can make the design feel repetitive. In that situation, consider introducing a breakout section or break the content with a different component, such as [pillar](../Pillar/index.md) or [card](../Card/index.md) to provide a better visual hierarchy and experience. For example, use the river for the top features you want to highlight and then use pillars to showcase the rest.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/12739a14-1775-44ff-b5a5-d87a8820a29e)
+
+_Use pillars or cards to breakout a multiple river section and provide a better visual hierarchy._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/a2e43864-3cde-441e-b992-05e7c037e306)
+
+_Don't stack numerous rivers without breaking the content to avoid repetitive a layout that can make the design
+feel repetitive._
+
+### Sections with rivers
+
+A single river component acts as a section and it should not include any child sections within in. Multiple rivers can be used to conform a section. In that case, the section should include a [section intro](../SectionIntro/index.md) that introduces the main topic or features.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/67cd0c85-ab9a-4736-ae29-bcb4d2ec7845)
+
+_Use a section intro to introduce multiple rivers._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/7654c23c-8337-4ab1-af82-ec4b6934b3b7)
+
+_Don't add child sections or other components to the river body content._
+
+### River breakout
+
+A river breakout component has an image that fills the width of the container while providing more space for content such as text and lists.
+
+This is useful when you want to create a highlight which can be used to create more emphasis or simply break a monotonous vertical flow of left/right rivers. It can also be helpful on smaller viewports to avoid stacking two images or two chunks of text from adjacent river components.
+
+As its name suggest, a river breakout should not be the first in the stack, it should be positioned in-between two standard rivers.
+
+Some examples of when to use a river breakout:
+
+- Expand on more complex feature that require more room for content
+- Give designer a tool to emphasize the feature story
+- Use a branded wallpaper in a more cinematic way than the standard 50/50 or 60/40 text-to-image column ratios
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/6951037/409b7e4e-a7b4-4126-b1ff-91e038565bc3)
+
+_Use a river breakout to emphasize a part of the river or break up a series of river components._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/6951037/eda1e0fa-7424-4ad4-8484-7c89c9c09192)
+
+_Don't stack river breakouts on top of other river breakout components or center-aligned river components. These
+both show a full-width image. This diminishes the visual impact the river breakout is intended to provide._
+
+The leading content in a river breakout component must always be present, but the trailing content is optional.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/2313998/433b1fba-4505-452b-8f8c-7cda69cc316d)
+
+_Always provide leading content._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/2313998/62cf1c98-6b7d-46e9-a2d4-6d211a9103ad)
+
+_Don't exclude the leading content._
+
+Limit trailing content to a maximum of 500 characters (or two timeline items) to avoid overwhelming the user and disrupting the layout's balance.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/175638/c5879e94-09c3-4494-aa42-87543570dfb4)
+
+_Limit high character counts in trailing content to preserve visual balance._
+
+**❌ Don't**
+
+![](https://github.com/primer/design/assets/175638/8a083960-e12a-4f11-b282-45d663be2e28)
+
+_Avoid using high character counts in trailing content._
+
+### River story scroll
+
+A river story scroll component is used to compose rivers and create a dynamic, scroll-driven presentation. It's a great way to showcase a set of features or topics in an interactive and visually engaging way.
+
+#### Composition
+
+River story scroll functions as a self-contained unit and is often paired with a a section intro. To effectively leverage this pattern, use between three and six rivers. For other configurations, simply stack rivers in a standard layout.
+
+This component should be used sparingly, at most twice per page, and alternated with other content types rather than placed consecutively. This approach enhances user engagement and keeps the spotlight on key information while preventing user fatigue.
+
+#### Content alignment and visuals
+
+Content across the different rivers in a story scroll must share the same alignment; either start or end. This ensures that the content flows smoothly with predictable placement and transitions. Additionally, all visuals in a story should share the same aspect ratio to achieve a consistent effect.
+
+**✅ Do**
+
+_Ensure all visuals maintain a consistent aspect ratio._
+
+**❌ Don't**
+
+_Avoid using visuals with varying aspect ratios._
+
+## Anatomy
+
+![A river component used to showcase a security feature. The title reads "Get security feedback with every git push" and it includes an image showing screenshots of of a CLI prompt with the git push command and a code scanning screenshot.](https://github.com/primer/brand/assets/10632534/bf32364f-02b7-4f0d-8784-471eaf97b4bb)
+
+### Content
+
+River provides a heading as the main title and a body text as the main content that describes the adjacent visual. The heading should be short and concise and the body should describe the feature or topic in a short paragraph.
+
+### Visual
+
+A river can include either an image or video to illustrate the feature or topic. The media should be relevant to the content and should not be used as a decorative element.
+
+Always use high quality images and videos. Avoid using images with text or single logos. Ensure the image fills the provided container.
+
+The image is automatically styled to fit the width of the parent container. If you have bespoke styling requirements, you can disable the provided default styles and style the image manually.
+
+### Additional guidance
+
+- We recommend using a river left as the first river of the flow to start with a visual and avoid stacking text with above section on mobile
+- River components stacks create a unit, the set should be considered to be the main parent section. The parent section should be spaced as a regular section with the largest spacing while internal elements should use smaller spacing
+- If the image is critical for the user to understand the message, default to right aligned. If the text is critical for the user to understand the image, choose left aligned.
+
+### Link
+
+River can include an optional call to action to link to more detailed content about the feature or topic. Avoid using buttons to do so, instead use the regular link built into the component.
+
+**✅ Do**
+
+_Use the provided link component._
+
+**❌ Don't**
+
+_Avoid using buttons._
+
+## Related components
+
+- [Pillar](../Pillar/index.md): To display non-navigational related content in a compact way.
+- [Card](../Card/index.md): To display navigational related content in a compact way.

package/docs/components/River/react.md

@@ -0,0 +1,295 @@
+---
+title: River
+description: Use the river component to introduce a feature using a type and media pairing.
+keywords: ['feature', 'showcase', 'highlight', 'story']
+ready: true
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=418%3A8416
+source: https://github.com/primer/brand/blob/main/packages/react/src/river/River/River.tsx
+storybook: '/brand/storybook/?path=/story/components-river--default'
+---
+
+```js
+import {River, RiverBreakout} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Stack style={{width: '100%'}}>
+  <River>
+    <River.Visual>
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>Heading</Heading>
+      <Text>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+        felis nam pulvinar risus elementum.
+      </Text>
+      <Link href="#">Call to action</Link>
+    </River.Content>
+  </River>
+  <River align="end">
+    <River.Visual>
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>Heading</Heading>
+      <Text>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+        felis nam pulvinar risus elementum.
+      </Text>
+      <Link href="#">Call to action</Link>
+    </River.Content>
+  </River>
+  <River align="center">
+    <River.Visual>
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Label>Label</Label>
+      <Heading>Heading</Heading>
+      <Text>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sapien sit ullamcorper id. Aliquam luctus sed turpis
+        felis nam pulvinar risus elementum.
+      </Text>
+      <Link href="#">Call to action</Link>
+    </River.Content>
+  </River>
+</Stack>
+```
+
+### GridLine variant
+
+The `gridline` variant adds lateral padding to the River component, making it suitable for use within bordered grid layouts.
+
+```jsx
+<Stack style={{width: '100%'}}>
+  <River variant="gridline">
+    <River.Visual>
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>GridLine variant</Heading>
+      <Text>Use the gridline variant when the River needs lateral spacing to align with bordered grid layouts.</Text>
+      <Link href="#">Call to action</Link>
+    </River.Content>
+  </River>
+  <River variant="gridline" align="end">
+    <River.Visual>
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>GridLine variant</Heading>
+      <Text>The variant works with all alignment options.</Text>
+      <Link href="#">Call to action</Link>
+    </River.Content>
+  </River>
+</Stack>
+```
+
+### Visual with background
+
+Use the `imageBackgroundColor` prop on `River.Visual` to create a full-bleed container with a background color and the image/video centered inside with padding. This is intended for use with the `gridline` variant.
+
+```jsx
+<Stack style={{width: '100%'}}>
+  <River variant="gridline">
+    <River.Visual imageBackgroundColor="subtle">
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>Visual with background</Heading>
+      <Text>
+        The imageBackgroundColor prop creates a full-bleed container with a subtle background, centering the media with
+        padding around it.
+      </Text>
+      <Link href="#">Call to action</Link>
+    </River.Content>
+  </River>
+  <River variant="gridline" align="end">
+    <River.Visual imageBackgroundColor="subtle">
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>Visual with background (end)</Heading>
+      <Text>The imageBackgroundColor prop works with all alignment options.</Text>
+      <Link href="#">Call to action</Link>
+    </River.Content>
+  </River>
+</Stack>
+```
+
+### Image to text ratio
+
+```jsx
+<Stack style={{width: '100%'}}>
+  {/* 50/50 (default) example */}
+  <River>
+    <River.Visual>
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>50/50</Heading>
+      <Text>
+        <strong>By default</strong>, River applies a 50/50 image to text split.
+      </Text>
+    </River.Content>
+  </River>
+  {/* 60/40 example */}
+  <River imageTextRatio="60:40">
+    <River.Visual>
+      <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+    </River.Visual>
+    <River.Content>
+      <Heading>60/40</Heading>
+      <Text>This example applies an optional 60/40 image to text split.</Text>
+    </River.Content>
+  </River>
+</Stack>
+```
+
+### Video
+
+```jsx
+<River style={{width: '100%'}} imageTextRatio="60:40">
+  <River.Visual hasShadow={false}>
+    <video
+      loop
+      playsInline
+      autoPlay
+      muted
+      poster="https://github.githubassets.com/images/modules/site/issues/issue-tasks-progress-placeholder.png"
+    >
+      <source
+        type="video/mp4; codecs=hevc,mp4a.40.2"
+        src="https://github.githubassets.com/images/modules/site/issues/issue-tasks-progress.hevc.mp4"
+      />
+      <source
+        type="video/mp4; codecs=avc1.4D401E,mp4a.40.2"
+        src="https://github.githubassets.com/images/modules/site/issues/issue-tasks-progress.h264.mp4"
+      />
+    </video>
+  </River.Visual>
+  <River.Content>
+    <Heading>Break issues into actionable tasks</Heading>
+    <Text>
+      Tackle complex issues with task lists and track their status with new progress indicators. Convert tasks into
+      their own issues and navigate your work hierarchy.
+    </Text>
+  </River.Content>
+</River>
+```
+
+### Alternative heading levels
+
+```jsx
+<River style={{width: '100%'}} imageTextRatio="60:40">
+  <River.Visual>
+    <img src="/images/placeholder.png" alt="placeholder with a gray background color" />
+  </River.Visual>
+  <River.Content>
+    <Heading as="h1">Alternative heading levels</Heading>
+    <Text>Use the 'as' prop to specify alternative heading levels. The default is 'h3'.</Text>
+  </River.Content>
+</River>
+```
+
+### Duotone
+
+```jsx
+<River style={{width: '100%'}}>
+  <River.Visual>
+    <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+  </River.Visual>
+  <River.Content>
+    <Text size="300">
+      <b>This first sentence is highlighted</b> and here is where the body copy starts. Remember to keep this nice and
+      succinct.
+    </Text>
+    <Link href="#">Call to action</Link>
+  </River.Content>
+</River>
+```
+
+### River breakout
+
+```jsx
+<RiverBreakout style={{width: '100%'}}>
+  <RiverBreakout.A11yHeading>Accelerate workflows</RiverBreakout.A11yHeading>
+  <RiverBreakout.Visual>
+    <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
+  </RiverBreakout.Visual>
+  <RiverBreakout.Content
+    trailingComponent={() => (
+      <Timeline>
+        <Timeline.Item>
+          <b>GitHub Codespaces</b> offers a complete dev environment in seconds.
+        </Timeline.Item>
+        <Timeline.Item>
+          <b>GitHub Copilot</b> is your AI pair programmer that empowers you to complete tasks.
+        </Timeline.Item>
+      </Timeline>
+    )}
+  >
+    <Text>
+      <b>This first sentence is a river breakout headline.</b> And this is where the body copy starts. Remember to keep
+      these nice and succinct.
+    </Text>
+    <Link href="#">Call to action</Link>
+  </RiverBreakout.Content>
+</RiverBreakout>
+```
+
+## Component props
+
+### River `Required`
+
+| Name             | Type                           | Default | Description                                                                                                 |
+| :--------------- | :----------------------------- | :-----: | :---------------------------------------------------------------------------------------------------------- |
+| `align`          | `'start'`, `'end'`, `'center'` |         | Alignment of text content relative to the Visual position                                                   |
+| `imageTextRatio` | `'50:50'`, `'60:40'`           |         | The aspect ratio applied to the image in relation to the adjacent text. Affects overall layout proportions. |
+| `variant`        | `'default'`, `'gridline'`      |         | Visual variant. Use `gridline` to add lateral padding for bordered grid layouts.                            |
+| `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                                                                    |
+
+### River.Visual and RiverBreakout.Visual `Required`
+
+| Name                   | Type                    | Default | Description                                                                                                                                                                               |
+| :--------------------- | :---------------------- | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fillMedia`            | `boolean`               |   true  | Automatically styles images and video to fill and fit the width of the parent. Disable this setting if you have bespoke styling requirements.                                             |
+| `children`             | `ReactElement`          |         | Bring your own component (BYOC) `img` or `ReactElement` (E.g. Next.js `Image` component)                                                                                                  |
+| `imageBackgroundColor` | `'default'`, `'subtle'` |         | Applies a background color with padding around the media. Use `'subtle'` to create a full-bleed container with the image/video centered inside. Intended for use with `gridline` variant. |
+| `hasShadow`            | `boolean`               | `false` | Shadow applied to the `children`. Set be `false` when the child node has a transparent background.                                                                                        |
+| `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                                                                                                                                                  |
+| `rounded`              | `boolean`               |  `true` | Toggle visually rounded corners. Enabled by default.                                                                                                                                      |
+
+### River.Content and RiverBreakout.Content `Required`
+
+[`Label`](../Label/index.md), [`Text`](../../typography/Text/index.md),[`Heading`](../../typography/Heading/index.md), `Link` are the only `children` accepted. They can be composed in any order, but their rendered output will always be in a predetermined order.
+
+| Name        | Type                                                                                            | Default | Description                                      |
+| :---------- | :---------------------------------------------------------------------------------------------- | :-----: | :----------------------------------------------- |
+| `children`  | [`Text`](../../typography/Text/index.md),[`Heading`](../../typography/Heading/index.md), `Link` |         | Content that corresponds to the adjacent visual. |
+| `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         |
+
+### RiverBreakout
+
+| 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 |
+
+### RiverBreakout.A11yHeading `Required`
+
+| Name       | Type        | Default | Description                                                                         |
+| :--------- | :---------- | :-----: | :---------------------------------------------------------------------------------- |
+| `children` | `ReactNode` |         | The heading text that will be read aloud to screen readers, but is visually hidden. |