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

package/docs/layout/Grid/react.md

@@ -0,0 +1,117 @@
+---
+title: Grid
+description: Use the grid component to create flexible and responsive grid-based layouts.
+keywords: ['layout', 'responsive', 'columns', 'rows', 'spacing']
+source: https://github.com/primer/brand/tree/main/packages/react/src/Grid/Grid.tsx
+storybook: '/brand/storybook/?path=/story/components-grid--playground'
+---
+
+```js
+import {Grid} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+The `Grid` component uses a 12-column layout system. Use `span` to control the number of columns that should be displayed.
+
+```jsx
+<Grid enableOverlay>
+  <Grid.Column span={1}></Grid.Column>
+  <Grid.Column span={11}></Grid.Column>
+  <Grid.Column span={2}></Grid.Column>
+  <Grid.Column span={10}></Grid.Column>
+  <Grid.Column span={3}></Grid.Column>
+  <Grid.Column span={9}></Grid.Column>
+  <Grid.Column span={4}></Grid.Column>
+  <Grid.Column span={8}></Grid.Column>
+  <Grid.Column span={5}></Grid.Column>
+  <Grid.Column span={7}></Grid.Column>
+  <Grid.Column span={6}></Grid.Column>
+  <Grid.Column span={6}></Grid.Column>
+  <Grid.Column span={7}></Grid.Column>
+  <Grid.Column span={5}></Grid.Column>
+  <Grid.Column span={8}></Grid.Column>
+  <Grid.Column span={4}></Grid.Column>
+  <Grid.Column span={9}></Grid.Column>
+  <Grid.Column span={3}></Grid.Column>
+  <Grid.Column span={10}></Grid.Column>
+  <Grid.Column span={2}></Grid.Column>
+</Grid>
+```
+
+### Nested grids
+
+```jsx
+<Grid enableOverlay>
+  <Grid.Column>
+    <Grid enableOverlay>
+      <Grid.Column span={4}></Grid.Column>
+      <Grid.Column span={4}></Grid.Column>
+      <Grid.Column span={4}></Grid.Column>
+    </Grid>
+  </Grid.Column>
+</Grid>
+```
+
+### Responsive behavior
+
+Use `span` with an `Object` of breakpoint-specific keys and `number` values to enable responsive behavior.
+
+Breakpoints use `min-width`, where it will also apply your chosen `span` value to all larger breakpoints.
+
+```jsx
+<Grid enableOverlay>
+  <Grid.Column span={{xsmall: 12, small: 12, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 12, small: 12, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 12, small: 12, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 12, small: 12, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+  <Grid.Column span={{xsmall: 6, small: 6, medium: 6, large: 4, xlarge: 3, xxlarge: 2}} />
+</Grid>
+```
+
+### Column offset
+
+Use `start` to provide a positioning offset.
+
+```jsx
+<Grid enableOverlay>
+  <Grid.Column span={3}></Grid.Column>
+  <Grid.Column span={5} start={8}></Grid.Column>
+</Grid>
+```
+
+## Component props
+
+### Grid `Required`
+
+| name            | type          | default     | required | description                               |
+| --------------- | ------------- | ----------- | -------- | ----------------------------------------- |
+| `as`            |               | `'div'`     | `false`  | The HTML element used to render the grid. |
+| `columnGap`     |               | `'default'` | `false`  | Defines the gap between columns.          |
+| `enableGutters` | `boolean`     | `true`      | `false`  | Enable or disable default gutters.        |
+| `enableOverlay` | `boolean`     | `false`     | `false`  | Visual aid to help with alignment.        |
+| `fullWidth`     | `boolean`     | `false`     | `false`  | Fills the width of the parent container   |
+| `rowGap`        |               | `'default'` | `false`  | Defines the gap between rows.             |
+| `className`     | `string`      |             | `false`  | Sets a custom class on the element.       |
+| `children`      | `Grid.Column` |             | `true`   |                                           |
+| `id`            | `string`      |             | `false`  | Sets a custom `id` attribute.             |
+
+### Grid.Column `Required`
+
+| name        | type                                                                             | default | required | description                                                        |
+| ----------- | -------------------------------------------------------------------------------- | ------- | -------- | ------------------------------------------------------------------ |
+| `as`        | `'div' \| 'section' \| 'span'`                                                   | `'div'` | `false`  | The HTML element used to render the column.                        |
+| `span`      | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 'ResponsiveMap'` | `12`    | `false`  | The number of columns the element should span or a responsive map. |
+| `start`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 \| 'ResponsiveMap'` |         | `false`  | The column index to start the element or a responsive map.         |
+| `className` | `string`                                                                         |         | `false`  | Sets a custom class on the element                                 |
+| `children`  | `ReactElement`                                                                   |         | `false`  |                                                                    |
+| `id`        | `string`                                                                         |         | `false`  | Sets a custom `id`                                                 |

package/docs/layout/Stack/index.md

@@ -0,0 +1,60 @@
+---
+title: Stack
+description: Use the stack component to create a layout for its immediate children along the vertical or horizontal axis.
+keywords: ['layout']
+---
+
+![](https://github.com/primer/brand/assets/912236/f04a87ce-a4ca-403b-8732-a8575a39437a)
+
+## Usage
+
+Use the stack component to distribute space and alignment between items in a vertical or horizontal direction (one-dimensional layout)[^1]. If you need both vertical and horizontal layout (two-dimensional layout), use the [grid](../Grid/index.md) component instead. When in doubt, we recommend reading the [grid vs stack](../Grid/index.md#grid-vs-stack) documentation.
+
+We recommend using the stack component for inline or text based elements. Stack enables items to scale, wrap, and shrink depending on each item's content and the available space.
+
+[^1]: The stack component is implemented using the [CSS Flexbox Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout) specification.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/3cfb1fc3-071c-478e-8104-543dcc823927)
+
+_Use the stack component for inline or text based elements. Like a navigational list or a button group._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/53436826-515f-49d6-b33c-d84124f29aa4)
+
+_Don't use the stack component to create a grid of items. Use the grid component instead._
+
+## Options
+
+### Gap
+
+Use the gap to change the space between items. Use small values when grouping closed related items, and larger values to separate sections or non-related items between them.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/dd508033-0435-48af-9b0b-ab1881608d8e)
+
+_Use large gap values to separate sections or non-related items._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/3e6974eb-2f80-4fee-9000-dc9fa31432a7)
+
+_Don't use large gap values for related items._
+
+### Direction, alignment, and justification
+
+Use the direction to control the rendering direction of items. The direction can be adjusted on different viewports. For example, an icon and a label might be rendered horizontally on large viewports, but vertically on small viewports for better readability and composition.
+
+Use the align and justify options for determining the rendering alignment on the cross-axis and main-axis respectively. Taking the example above, the icon and label might be aligned to the center on mobile viewports, but aligned to the start on large viewports.
+
+_Video demonstration — see the online docs._
+
+_Use vertical layout on small viewports to ensure that the content is readable. Combine it with center alignment if
+the text is short and the context calls for it._
+
+## Related components
+
+- [Grid](../Grid/index.md): Use the grid component to create flexible and responsive grid-based layouts.

package/docs/layout/Stack/react.md

@@ -0,0 +1,166 @@
+---
+title: Stack
+description: Use the stack component to create a layout for its immediate children along the vertical or horizontal axis.
+keywords: ['layout']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Stack/Stack.tsx
+storybook: '/brand/storybook/?path=/story/components-stack--default'
+---
+
+```js
+import {Stack} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+`Stack` is a layout helper component intended for rendering `children` in a single direction.
+
+Use the `direction` prop to alternate between `vertical` and `horizontal` directions.
+
+Many `Stack` props - including `direction` - accept both `string` and `Object` values. The former will apply the value across all viewports, while the latter will permit granular control at specific breakpoints. See [Responsive](#Responsive) below for more details.
+
+```jsx
+<Stack>
+  <Heading size="subhead-large">Code search & code view</Heading>
+  <Text as="p">Enables you to rapidly search, navigate, and understand code, right from GitHub.com.</Text>
+</Stack>
+```
+
+### Alignment
+
+`Stack` provides `alignItems` and `justifyContent` props for determining the rendering direction on the cross-axis and main-axis respectively.
+
+Use the playground below to experiment with the various options.
+
+```jsx filename="noinline"
+const App = () => {
+  const [alignItemsValue, setAlignItemsValue] = React.useState('center')
+  const [justifyContentValue, setJustifyContentValue] = React.useState('space-between')
+
+  const handleMainAxisChange = event => setJustifyContentValue(event.target.value)
+  const handleCrossAxisChange = event => setAlignItemsValue(event.target.value)
+
+  return (
+    <div style={{width: '100%'}}>
+      <Stack
+        direction="horizontal"
+        alignItems={alignItemsValue}
+        justifyContent={justifyContentValue}
+        style={{height: 400}}
+      >
+        <img
+          src="/images/placeholder.png"
+          alt="placeholder with gray background and no foreground text"
+          style={{width: 150, height: 75}}
+        />
+        <img
+          src="/images/placeholder.png"
+          alt="placeholder with gray background and no foreground text"
+          style={{width: 150, height: 75}}
+        />
+        <img
+          src="/images/placeholder.png"
+          alt="placeholder with gray background and no foreground text"
+          style={{width: 150, height: 75}}
+        />
+      </Stack>
+
+      <Stack direction="horizontal" gap="spacious" justifyContent="center">
+        <FormControl>
+          <FormControl.Label>Main axis</FormControl.Label>
+          <Select defaultValue={justifyContentValue} onChange={handleMainAxisChange}>
+            <Select.Option value="center">center</Select.Option>
+            <Select.Option value="flex-start">flex-start</Select.Option>
+            <Select.Option value="flex-end">flex-end</Select.Option>
+            <Select.Option value="space-between">space-between</Select.Option>
+            <Select.Option value="space-around">space-around</Select.Option>
+            <Select.Option value="space-evenly">space-evenly</Select.Option>
+          </Select>
+        </FormControl>
+
+        <FormControl>
+          <FormControl.Label>Cross axis</FormControl.Label>
+          <Select defaultValue={alignItemsValue} onChange={handleCrossAxisChange}>
+            <Select.Option value="center">center</Select.Option>
+            <Select.Option value="flex-start">flex-start</Select.Option>
+            <Select.Option value="flex-end">flex-end</Select.Option>
+          </Select>
+        </FormControl>
+      </Stack>
+    </div>
+  )
+}
+
+render(App)
+```
+
+### Responsive
+
+Passing an Object of a particular shape will allow granular control of `direction`, `gap`, `alignItems`, `justifyContent` and `padding` at various supported breakpoints.
+
+Supported breakpoints are `narrow`, `regular` and `wide`.
+
+The Object value does not require all properties be passed, but rather operates on the basis of `min-width`.
+
+E.g. Providing only `narrow` will apply that value to all larger breakpoints, but not the other way.
+
+```jsx
+<Stack
+  style={{height: 400}}
+  direction={{
+    narrow: 'vertical',
+    regular: 'vertical',
+    wide: 'horizontal',
+  }}
+  gap={{
+    narrow: 'condensed',
+    regular: 'normal',
+    wide: 'spacious',
+  }}
+  padding={{
+    narrow: 'condensed',
+    regular: 'normal',
+    wide: 'spacious',
+  }}
+  alignItems={{
+    narrow: 'flex-start',
+    regular: 'center',
+    wide: 'center',
+  }}
+  justifyContent={{
+    narrow: 'center',
+    regular: 'center',
+    wide: 'space-between',
+  }}
+>
+  <img
+    src="/images/placeholder.png"
+    alt="placeholder with gray background and no foreground text"
+    style={{width: 150, height: 75}}
+  />
+  <img
+    src="/images/placeholder.png"
+    alt="placeholder with gray background and no foreground text"
+    style={{width: 150, height: 75}}
+  />
+  <img
+    src="/images/placeholder.png"
+    alt="placeholder with gray background and no foreground text"
+    style={{width: 150, height: 75}}
+  />
+</Stack>
+```
+
+## Component props
+
+### Stack
+
+| Name             | Type                          | Default | Description                                |
+| :--------------- | :---------------------------- | :-----: | :----------------------------------------- |
+| `direction`      | `StackDirectionVariants`      |         | Determines layout direction                |
+| `gap`            | `StackSpacingVariants`        |         | Determines gap between items               |
+| `padding`        | `StackSpacingVariants`        |         | Determines padding applied to Stack parent |
+| `justifyContent` | `StackJustifyContentVariants` |         | Determines rendering on the main-axis      |
+| `alignItems`     | `StackAlignItemVariants`      |         | Determines rendering on the cross-axis     |

package/docs/layout/index.md

@@ -0,0 +1,9 @@
+---
+title: Layout
+---
+
+## In this section
+
+- [Box](Box/react.md): Use a box to simplify the process of applying one-off styles to an element
+- [Grid](Grid/react.md): Use the grid component to create flexible and responsive grid-based layouts.
+- [Stack](Stack/react.md): Use the stack component to create a layout for its immediate children along the vertical or horizontal axis.

package/docs/primitives/color.md

@@ -0,0 +1,6 @@
+---
+title: Color
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=387%3A8439'
+---
+
+This page is an interactive demo, so it has no static Markdown form. The primitives it showcases ship with this package: load `@primer/react-brand/lib/css/main.css` and read the design tokens bundled under `lib/design-tokens/`.

package/docs/primitives/index.md

@@ -0,0 +1,8 @@
+---
+title: Primitives
+description: Learn about Primer Brand Primitives
+---
+
+## In this section
+
+- [Color](color.md)

package/docs/typography/Heading/index.md

@@ -0,0 +1,53 @@
+---
+title: Heading
+description: Use the heading component to render title or subtitle text
+keywords: ['title', 'subtitle']
+---
+
+![An image displaying each header from h1 to h6.](https://github.com/primer/brand/assets/912236/9947878f-4d2f-439f-ab6e-8349115f6888)
+
+## Usage
+
+Headings are used to structure the content on the page, with each heading representing a different level of importance. It is recommended to use headings in a logical manner to create a clear hierarchy and improve accessibility.
+
+- Heading should be used to communicate page organization and hierarchy.
+- Use heading as the title that introduces a page, a section or an article.
+- The heading component will render an html h2 tag without any default styling.
+
+## Options
+
+### Scale and size
+
+The heading scale ranges from 1 to 6 and maps to the HTML heading elements h1 to h6 respectively. The size is determined by the type of HTML element specified, although you can override this when the scenario calls for it. E.g. use a `h2` heading size on a `<h3>` to highlight an article that might be relevant to the user.
+
+### Weight, stretch and letter spacing
+
+The heading component also supports the following options: `weight`, `stretch` and `letterSpacing`. Each of these options are determined by the heading scale and size, but can be overridden when the scenario calls for it.
+
+### Responsive
+
+The heading component is responsive by default and the size will scale down on smaller screens. Weight, stretch and letter spacing will remain the same across all screen sizes but can be overridden for each breakpoint.
+
+_Video demonstration — see the online docs._
+
+## Accessibility
+
+While sighted users rely on visual cues such as font size changes to determine what the heading is, assistive technology users rely on programatic cues that can be read out. When text on a page is visually implied to be a heading, ensure that it is coded as a heading. Additionally, visually implied heading level and coded heading level should be consistent. See [WCAG success criteria: 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html).
+
+Headings allow assistive technology users to quickly navigate around a page. Navigation as text that is not meant to be a heading can be a confusing experience. [Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/).
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/05b615e0-9f07-4718-8ce5-80109119b92a)
+
+_Use headings with a lower rank to start new subsections that are part of the higher ranked section._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/876097cc-27a9-41c4-adab-24db8a3c6432)
+
+_Don't skip heading ranks. Make sure that a h2 is not followed directly by an h4, for example._
+
+## Related components
+
+- [Text](../Text/index.md): to render body content

package/docs/typography/Heading/react.md

@@ -0,0 +1,182 @@
+---
+title: Heading
+description: Use the heading component to render title or subtitle text.
+keywords: ['title', 'subtitle']
+ready: true
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=354%3A8982'
+source: https://github.com/primer/brand/blob/main/packages/react/src/Heading/Heading.tsx
+storybook: '/brand/storybook/?path=/story/components-heading--playground'
+---
+
+```js
+import {Heading} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Heading>This is my super sweet heading</Heading>
+```
+
+### Scale
+
+```jsx
+<Stack gap="condensed" style={{width: '100%'}}>
+  <Heading size="display">Display: 96px</Heading>
+  <Heading size="1">1: 72px</Heading>
+  <Heading size="2">2: 64px</Heading>
+  <Heading size="3">3: 48px</Heading>
+  <Heading size="4">4: 40px</Heading>
+  <Heading size="5">5: 32px</Heading>
+  <Heading size="6">6: 24px</Heading>
+  <Heading size="subhead-large">subhead-large: 20px</Heading>
+  <Heading size="subhead-medium">subhead-medium: 16px</Heading>
+</Stack>
+```
+
+### Levels
+
+The `Heading` level can be assigned using the `as` prop, which accepts any valid HTML heading tag.
+
+Its visual appearance corresponds to the `1-6` scale values, but can be overridden using the `size` prop.
+
+```jsx
+<Stack gap="condensed" style={{width: '100%'}}>
+  <Heading as="h6">This is my super sweet heading as a h6</Heading>
+
+  <Heading as="h2" size="4">
+    This h2 will appear visually identical to a h4
+  </Heading>
+</Stack>
+```
+
+### Weight
+
+The recommended text weight is automatically applied to Headings based on their position on the type scale.
+
+Use the `weight` prop to override the default visual appearance if required.
+
+```jsx
+<Stack gap="condensed" style={{width: '100%'}}>
+  <Heading as="h3" weight="heavy">
+    heavy
+  </Heading>
+  <Heading as="h3" weight="extrabold">
+    extrabold
+  </Heading>
+  <Heading as="h3" weight="bold">
+    bold
+  </Heading>
+  <Heading as="h3" weight="semibold">
+    semibold
+  </Heading>
+  <Heading as="h3" weight="medium">
+    medium
+  </Heading>
+  <Heading as="h3" weight="normal">
+    normal
+  </Heading>
+  <Heading as="h3" weight="light">
+    light
+  </Heading>
+
+  {/* Responsive */}
+  <br />
+  <br />
+  <Heading
+    as="h4"
+    weight={{
+      narrow: 'heavy',
+      regular: 'semibold',
+      wide: 'light',
+    }}
+  >
+    Responsive
+  </Heading>
+</Stack>
+```
+
+### Width / Stretch
+
+The recommended text width value is automatically applied to Headings based on their position on the type scale.
+
+Use the `stretch` prop to override the default visual appearance if required.
+
+```jsx
+<Stack gap="condensed" style={{width: '100%'}}>
+  <Heading as="h3" stretch="condensed">
+    condensed
+  </Heading>
+  <Heading as="h3" stretch="normal">
+    normal
+  </Heading>
+  <Heading as="h3" stretch="expanded">
+    expanded
+  </Heading>
+
+  {/* Responsive */}
+  <br />
+  <br />
+  <Heading
+    as="h4"
+    stretch={{
+      narrow: 'condensed',
+      regular: 'normal',
+      wide: 'expanded',
+    }}
+  >
+    Responsive
+  </Heading>
+</Stack>
+```
+
+### Letter spacing
+
+The recommended character letter spacing is automatically applied to Headings based on their position on the type scale.
+
+Use the `letterSpacing` prop to override the default settings if required.
+
+```jsx
+<Stack gap="condensed" style={{width: '100%'}}>
+  <Heading as="h3" letterSpacing="condensed">
+    condensed
+  </Heading>
+  <Heading as="h3" letterSpacing="normal">
+    normal
+  </Heading>
+  <Heading as="h3" letterSpacing="none">
+    none
+  </Heading>
+
+  {/* Responsive */}
+  <br />
+  <br />
+  <Heading
+    as="h4"
+    letterSpacing={{
+      narrow: 'condensed',
+      regular: 'normal',
+      wide: 'none',
+    }}
+  >
+    Responsive
+  </Heading>
+</Stack>
+```
+
+## Component props
+
+### Heading
+
+| Name            | Type                                                    |       Default       | Description                                    |
+| :-------------- | :------------------------------------------------------ | :-----------------: | :--------------------------------------------- |
+| `as`            | `HeadingTags`                                           | `defaultHeadingTag` | Applies the underlying HTML element            |
+| `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       |
+| `size`          | `HeadingSizes`                                          |                     | Override the default visual text size          |
+| `weight`        | `HeadingWeights \| 'ResponsiveWeightMap'`               |                     | Override the default visual text weight        |
+| `stretch`       | `HeadingStretch \| 'ResponsiveStretchMap'`              |                     | Override the default visual text stretch value |
+| `letterSpacing` | `HeadingLetterSpacing \| 'ResponsiveLetterSpacingMap'`> |                     | Override the default visual character spacing  |

package/docs/typography/Text/index.md

@@ -0,0 +1,68 @@
+---
+title: Text
+description: Use the text component create a range of body text
+keywords: ['body', 'content', 'copy', 'paragraph']
+---
+
+![The text component has size ranges from 100 to 700 with 100 being the smallest, and 700 being the largest.](https://github.com/primer/brand/assets/912236/67d89861-7a1e-4df9-a801-01d11f4dfb17)
+
+## Usage
+
+Use the text component to provide content and a clear hierarchy structure. The text component renders an HTML `<span>` tag without any default styling. Use `<p>` for any text that is meant to be a paragraph of text. Use multiple text components to represent paragraphs as distinct blocks of text. This helps with readability and makes it easier for search engines and assistive technologies to understand the content.
+
+## Options
+
+### Variant
+
+The text component provides two variant options: `default` and `muted`. The `muted` variant is used to de-emphasize text or to provide visual contrast when paired with a title.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/b7fa8c0d-0877-4edd-a8b3-4eea2e16fe26)
+
+_Use muted text to de-emphasize text and provide additional context._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/01f1e3a8-5058-4a73-a69f-6f424382fb63)
+
+_Don't use standalone muted text. Muted text should always be paired with emphasized text or a title._
+
+### Size
+
+The text size ranges from 100 to 700, with 400 as the default size. This scale is built to provide hierarchy for all types of scenarios.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/e029b053-eab8-47a7-bd49-b6ce49ac8bdf)
+
+_Use a smaller size to provide visual hierarchy when the text is paired with a title. Use as many text components
+as needed to represent different blocks of content._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/bfc9aaba-5a48-4053-a4a0-2209a9d7f082)
+
+_When the text is paired with a title, use a smaller size to provide visual hierarchy._
+
+### Alignment
+
+Text alignment options offer a convenient way to control the positioning of content within block level elements.
+
+Available options include `start`, `center`, and `end`, which are recommended for supporting bidirectional reading.
+
+### Weight
+
+The text component also supports `weight` options. Weight is automatically determined by the text size, but can be overridden when the scenario calls for it.
+
+### Responsive
+
+The text component is responsive by default and the size will scale down on smaller screens. Weight options will remain the same across all screen sizes but can be overridden for each breakpoint.
+
+_Video demonstration — see the online docs._
+
+## Related components
+
+- [Heading](../Heading/index.md): to render headings.
+- [Ordered list](../../components/OrderedList/index.md): to render ordered lists.
+- [Unordered list](../../components/UnorderedList/index.md): to render unordered lists.