@utilitywarehouse/hearth-react 0.28.7 → 0.29.1

package/public/llms/components/body-text.md

@@ -0,0 +1,200 @@
+# BodyText
+
+```tsx
+<Flex direction="column" gap="100">
+  {sizes.map(size =>
+    weights.map(weight => (
+      <BodyText key={`${size}${weight}`} size={size} weight={weight}>
+        Hamburgefons ({size}, {weight})
+      </BodyText>
+    ))
+  )}
+</Flex>
+```
+
+```tsx
+<BodyText size="md">The five boxing wizards jump quickly.</BodyText>
+```
+
+## Alternatives
+
+- DetailText - For detail text
+- Heading - For heading-level text
+- Strong - For strong importance
+- Em - For emphasis
+
+## Semantic HTML
+
+By default `BodyText` renders a `p` element, this can be customised using the
+`as` prop, to render a `span` or a `div`.
+
+```tsx
+<BodyText as="span">...</Box>
+```
+
+To render any other valid HTML element, you can use the `asChild` prop.
+
+```tsx
+<BodyText asChild>
+  <label>...</label>
+</Box>
+```
+
+This will render the child element, with all the styles declared on the `Box`
+component passed down to it as well.
+
+## Size
+
+The size prop is responsive, so you can render different sizes at different breakpoints.
+
+```tsx
+<BodyText size={{ mobile: 'sm', tablet: 'md', desktop: 'lg'}}>{...}</BodyText>
+```
+
+```tsx
+<Flex direction="column" gap="100">
+  {sizes.map(size => (
+    <BodyText key={size} size={size}>
+      {size}
+    </BodyText>
+  ))}
+  <BodyText size={{ mobile: 'sm', tablet: 'md', desktop: 'lg' }}>Responsive size</BodyText>
+</Flex>
+```
+
+## Weight
+
+The weight prop is responsive, so you can render different weights at different breakpoints.
+
+```tsx
+<BodyText weight={{ mobile: 'bold', tablet: 'regular'}}>{...}</BodyText>
+```
+
+```tsx
+<Flex direction="column" gap="100">
+  {weights.map(weight => (
+    <BodyText key={weight} weight={weight}>
+      {weight}
+    </BodyText>
+  ))}
+  <BodyText weight={{ mobile: 'bold', tablet: 'regular' }}>Responsive weight</BodyText>
+</Flex>
+```
+
+## Colour
+
+You can use the `color` prop to set a semantic text colour.
+
+```tsx
+<BodyText color="primary" />
+<BodyText color="secondary" />
+<BodyText color="brand" />
+<BodyText color="affirmative" />
+<BodyText color="inverted" />
+```
+
+```tsx
+<Flex direction="column" width="fit-content">
+  <Flex direction="column" backgroundColor="secondary" padding="400" gap="400">
+    <BodyText color="primary">Primary</BodyText>
+    <BodyText color="secondary">Secondary</BodyText>
+    <BodyText color="brand">Brand</BodyText>
+    <BodyText color="affirmative">Affirmative</BodyText>
+  </Flex>
+  <Box backgroundColor="brand" padding="400">
+    <BodyText color="inverted">Inverted</BodyText>
+  </Box>
+</Flex>
+```
+
+## Inverted
+
+When using `BodyText` on a brand background you can set the `color` prop to
+inverted to ensure proper colour contrast.
+
+```tsx
+<Flex direction="column">
+  <Box backgroundColor="brand" padding="400">
+    <BodyText {...args}>Inverted text</BodyText>
+  </Box>
+</Flex>
+```
+
+## Text truncate
+
+Use the `truncate` prop to set the text to truncate, instead of wrapping, with a
+text overflow ellipsis. Note that text overflow can only happen with block or
+inline-block level elements (the element needs to have a width in order to
+overflow).
+
+```tsx
+<Flex direction="column" gap="100" width="200px">
+  {sizes.map(size => (
+    <BodyText key={size} {...args} size={size}>
+      the quick brown fox jumped over the lazy dog.
+    </BodyText>
+  ))}
+</Flex>
+```
+
+## Paragraph Spacing
+
+The `paragraphSpacing` prop aligns with the auto spacing between paragraphs in
+Figma designs. While layout components are preferred for managing layouts, and
+applying spacing between elements, sometimes multiple paragraphs can be stacked
+without a parent layout component. When this happens in a design there is no
+indication what the spacing is between these stacked paragraphs. You can use
+`paragraphSpacing` on these `BodyText` elements to apply a predefined bottom
+gutter.
+
+```tsx
+<Flex gap="500">
+  {sizes.map(size => (
+    <Flex key={size} direction="column" width="360px">
+      <BodyText paragraphSpacing size={size}>
+        EV tariffs offer fantastic value if your driving patterns mean you can regularly charge your
+        car at home - and can schedule your vehicle to charge while you sleep.
+      </BodyText>
+      <BodyText paragraphSpacing size={size}>
+        You’ll get the most value out of our EV tariff by consistently charging your car off-peak
+        between midnight and 5am in the morning
+      </BodyText>
+      <BodyText size={size}>
+        And don&apos;t forget, any domestic usage (e.g. washing machines) in that off-peak window
+        will also be charged at the reduced rate.
+      </BodyText>
+    </Flex>
+  ))}
+</Flex>
+```
+
+## API
+
+This component is based on the `p` element and supports the following common props:
+
+- Margin
+- Color
+- Text align
+- Text wrap
+- Text transform
+
+| Prop               | Type                                                                                                                                                                                                       | Default   | Description                                                                                                                                                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `as`               | `"span" \| "div" \| "label" \| "p"`                                                                                                                                                                        | `p`       | Shorthand for changing the default rendered element into a semantically appropriate alternative. Cannot be used in combination with `asChild`.                                                                                        |
+| `asChild`          | `boolean`                                                                                                                                                                                                  | —         | Change the default rendered element for the one passed as a child, merging their props and behavior.                                                                                                                                  |
+| `size`             | `Responsive<"sm" \| "md" \| "lg">`                                                                                                                                                                         | `md`      | Set the text size styles.                                                                                                                                                                                                             |
+| `weight`           | `Responsive<"regular" \| "semibold" \| "bold">`                                                                                                                                                            | `regular` | Set the font-weight                                                                                                                                                                                                                   |
+| `truncate`         | `boolean`                                                                                                                                                                                                  | —         | If true, the text will not wrap, but instead will truncate with a text overflow ellipsis. Note that text overflow can only happen with block or inline-block level elements (the element needs to have a width in order to overflow). |
+| `paragraphSpacing` | `boolean`                                                                                                                                                                                                  | —         | If true, the text will have a bottom margin.                                                                                                                                                                                          |
+| `color`            | `"primary" \| "secondary" \| "brand" \| "affirmative" \| "inverted" \| `var(--h-${string})``                                                                                                               | —         |                                                                                                                                                                                                                                       |
+| `textAlign`        | `Responsive<"center" \| "left" \| "right">`                                                                                                                                                                | —         |                                                                                                                                                                                                                                       |
+| `textTransform`    | `"none" \| "uppercase" \| "lowercase" \| "capitalize"`                                                                                                                                                     | —         | Set the text-transform on the component.                                                                                                                                                                                              |
+| `wrap`             | `Responsive<"wrap" \| "nowrap" \| "balance" \| "pretty">`                                                                                                                                                  | —         | DEPRECATED: use `textWrap` instead of `wrap` @deprecated Use `textWrap` instead of `wrap`                                                                                                                                             |
+| `textWrap`         | `Responsive<"wrap" \| "nowrap" \| "balance" \| "pretty">`                                                                                                                                                  | —         |                                                                                                                                                                                                                                       |
+| `margin`           | `Responsive<`var(--h-${string})` \| "auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —         |                                                                                                                                                                                                                                       |
+| `marginTop`        | `Responsive<`var(--h-${string})` \| "auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —         |                                                                                                                                                                                                                                       |
+| `marginRight`      | `Responsive<`var(--h-${string})` \| "auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —         |                                                                                                                                                                                                                                       |
+| `marginBottom`     | `Responsive<`var(--h-${string})` \| "auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —         |                                                                                                                                                                                                                                       |
+| `marginLeft`       | `Responsive<`var(--h-${string})` \| "auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —         |                                                                                                                                                                                                                                       |
+| `marginX`          | `Responsive<`var(--h-${string})` \| "auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —         |                                                                                                                                                                                                                                       |
+| `marginY`          | `Responsive<`var(--h-${string})` \| "auto" \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —         |                                                                                                                                                                                                                                       |

package/public/llms/components/box.md

@@ -0,0 +1,148 @@
+# Box
+
+```tsx
+<Box {...args} />
+```
+
+## Alternatives
+
+- Container - For page content, with default
+  responsive padding & gutters
+- Grid - For grid layouts
+- Flex - For stacked, inline or flexbox based
+  layouts
+
+## Semantic HTML
+
+By default `Box` renders a `div` element, this can be customised using the
+`as` prop, to render a `span`.
+
+```tsx
+<Box as="span">...</Box>
+```
+
+To render any other valid HTML element, you can use the `asChild` prop.
+
+```tsx
+<Box asChild>
+  <main>...</main>
+</Box>
+```
+
+This will render the child element, with all the styles declared on the `Box`
+component passed down to it as well.
+
+### Accessibility
+
+The `Box` component is an all purpose component. By default, it has no
+accessibility concerns. If you use the `Box` as a custom element, it is up to
+you to manage the resulting accessibility implications.
+
+## Show/hide content
+
+The `display` prop is responsive, you can use this to show or hide content responsively.
+
+```tsx
+<Box display={{ mobile: 'none', tablet: 'block' }}>hide on mobile screens</Box>
+```
+
+## API
+
+This component is based on the `div` element and supports the following common props:
+
+- AlignSelf
+- Padding
+- Margin
+- Position
+- Size
+- Colour
+- Background colour
+- Border colour
+- Border
+- Flex item
+- Grid item
+- Text align
+- Text transform
+- Z-Index
+- Overflow
+- Opacity
+- Order
+
+| Prop                          | Type                                                                                                                                                                                                       | Default | Description                              |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------- |
+| `asChild`                     | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `display`                     | `Responsive<"none" \| "inline" \| "inline-block" \| "block">`                                                                                                                                              | —       |                                          |
+| `alignSelf`                   | `Responsive<"center" \| "start" \| "end" \| "stretch">`                                                                                                                                                    | —       |                                          |
+| `backgroundColor`             | `"primary" \| "secondary" \| "brand" \| `var(--h-${string})``                                                                                                                                              | —       |                                          |
+| `borderColor`                 | `"strong" \| `var(--h-${string})` \| "subtle"`                                                                                                                                                             | —       |                                          |
+| `borderTopColor`              | `"strong" \| `var(--h-${string})` \| "subtle"`                                                                                                                                                             | —       |                                          |
+| `borderRightColor`            | `"strong" \| `var(--h-${string})` \| "subtle"`                                                                                                                                                             | —       |                                          |
+| `borderBottomColor`           | `"strong" \| `var(--h-${string})` \| "subtle"`                                                                                                                                                             | —       |                                          |
+| `borderLeftColor`             | `"strong" \| `var(--h-${string})` \| "subtle"`                                                                                                                                                             | —       |                                          |
+| `borderRadius`                | `Responsive<"none" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "full" \| "inherit">`                                                                                                                        | —       |                                          |
+| `borderRadiusTopLeftNone`     | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderRadiusTopRightNone`    | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderRadiusBottomLeftNone`  | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderRadiusBottomRightNone` | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderRadiusTopNone`         | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderRadiusRightNone`       | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderRadiusBottomNone`      | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderRadiusLeftNone`        | `boolean`                                                                                                                                                                                                  | —       |                                          |
+| `borderStyle`                 | `Responsive<"none" \| "solid">`                                                                                                                                                                            | —       |                                          |
+| `borderTopStyle`              | `Responsive<"none" \| "solid">`                                                                                                                                                                            | —       |                                          |
+| `borderRightStyle`            | `Responsive<"none" \| "solid">`                                                                                                                                                                            | —       |                                          |
+| `borderBottomStyle`           | `Responsive<"none" \| "solid">`                                                                                                                                                                            | —       |                                          |
+| `borderLeftStyle`             | `Responsive<"none" \| "solid">`                                                                                                                                                                            | —       |                                          |
+| `borderWidth`                 | `Responsive<"0" \| "1" \| "2">`                                                                                                                                                                            | —       |                                          |
+| `borderTopWidth`              | `Responsive<"0" \| "1" \| "2">`                                                                                                                                                                            | —       |                                          |
+| `borderRightWidth`            | `Responsive<"0" \| "1" \| "2">`                                                                                                                                                                            | —       |                                          |
+| `borderBottomWidth`           | `Responsive<"0" \| "1" \| "2">`                                                                                                                                                                            | —       |                                          |
+| `borderLeftWidth`             | `Responsive<"0" \| "1" \| "2">`                                                                                                                                                                            | —       |                                          |
+| `color`                       | `"primary" \| "secondary" \| "brand" \| "affirmative" \| "inverted" \| `var(--h-${string})``                                                                                                               | —       |                                          |
+| `flex`                        | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `flexBasis`                   | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `flexShrink`                  | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `flexGrow`                    | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `gridColumnSpan`              | `Responsive<Union<string, "1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "8" \| "9" \| "10" \| "11" \| "12">>`                                                                                           | —       |                                          |
+| `gridArea`                    | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `gridColumn`                  | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `gridColumnStart`             | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `gridColumnEnd`               | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `gridRow`                     | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `gridRowStart`                | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `gridRowEnd`                  | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `margin`                      | `Responsive<`var(--h-${string})` \| "0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —       |                                          |
+| `marginTop`                   | `Responsive<`var(--h-${string})` \| "0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —       |                                          |
+| `marginRight`                 | `Responsive<`var(--h-${string})` \| "0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —       |                                          |
+| `marginBottom`                | `Responsive<`var(--h-${string})` \| "0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —       |                                          |
+| `marginLeft`                  | `Responsive<`var(--h-${string})` \| "0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —       |                                          |
+| `marginX`                     | `Responsive<`var(--h-${string})` \| "0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —       |                                          |
+| `marginY`                     | `Responsive<`var(--h-${string})` \| "0" \| "auto" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">` | —       |                                          |
+| `opacity`                     | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `order`                       | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `overflow`                    | `Responsive<"hidden" \| "auto" \| "visible" \| "clip" \| "scroll">`                                                                                                                                        | —       |                                          |
+| `overflowX`                   | `Responsive<"hidden" \| "auto" \| "visible" \| "clip" \| "scroll">`                                                                                                                                        | —       |                                          |
+| `overflowY`                   | `Responsive<"hidden" \| "auto" \| "visible" \| "clip" \| "scroll">`                                                                                                                                        | —       |                                          |
+| `padding`                     | `Responsive<`var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">`           | —       |                                          |
+| `paddingTop`                  | `Responsive<`var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">`           | —       |                                          |
+| `paddingRight`                | `Responsive<`var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">`           | —       |                                          |
+| `paddingBottom`               | `Responsive<`var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">`           | —       |                                          |
+| `paddingLeft`                 | `Responsive<`var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">`           | —       |                                          |
+| `paddingX`                    | `Responsive<`var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">`           | —       |                                          |
+| `paddingY`                    | `Responsive<`var(--h-${string})` \| "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">`           | —       |                                          |
+| `position`                    | `Responsive<"fixed" \| "static" \| "relative" \| "absolute" \| "sticky">`                                                                                                                                  | —       |                                          |
+| `inset`                       | `Responsive<Union<string, "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">>`                    | —       |                                          |
+| `top`                         | `Responsive<Union<string, "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">>`                    | —       |                                          |
+| `right`                       | `Responsive<Union<string, "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">>`                    | —       |                                          |
+| `bottom`                      | `Responsive<Union<string, "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">>`                    | —       |                                          |
+| `left`                        | `Responsive<Union<string, "0" \| "25" \| "50" \| "75" \| "100" \| "150" \| "175" \| "200" \| "250" \| "300" \| "350" \| "400" \| "500" \| "600" \| "700" \| "800" \| "900" \| "1000">>`                    | —       |                                          |
+| `width`                       | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `maxWidth`                    | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `minWidth`                    | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `height`                      | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `maxHeight`                   | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `minHeight`                   | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `textAlign`                   | `Responsive<"center" \| "right" \| "left">`                                                                                                                                                                | —       |                                          |
+| `textTransform`               | `"none" \| "uppercase" \| "lowercase" \| "capitalize"`                                                                                                                                                     | —       | Set the text-transform on the component. |
+| `zIndex`                      | `Responsive<string>`                                                                                                                                                                                       | —       |                                          |
+| `as`                          | `"div" \| "span"`                                                                                                                                                                                          | —       |                                          |

package/public/llms/components/breadcrumbs.md

@@ -0,0 +1,97 @@
+# Breadcrumbs
+
+Use the `Breadcrumbs` component when you need to help users understand and move between multiple levels of a website.
+
+- [Current page](#current-page)
+- [Inverted](#inverted)
+- [Usage with Next.js](#usage-with-nextjs)
+- [API](#api)
+
+```tsx
+<Flex direction="column">
+  <Flex padding="400">
+    <Breadcrumbs>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#" currentPage>
+        Current page
+      </BreadcrumbItem>
+    </Breadcrumbs>
+  </Flex>
+  <Flex backgroundColor="brand" padding="400">
+    <Breadcrumbs inverted>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#">Page</BreadcrumbItem>
+      <BreadcrumbItem href="#" currentPage>
+        Current page
+      </BreadcrumbItem>
+    </Breadcrumbs>
+  </Flex>
+</Flex>
+```
+
+## Current page
+
+Use the `currentPage` prop to indicate the current page.
+
+## Inverted
+
+Use the `inverted` prop to adjust colours for use on darker brand backgrounds.
+
+## Usage with Next.js
+
+When using `Breadcrumbs` with Next.js v13 and above, use the `asChild` prop on
+`BreadcrumbItem` to render it as a Next.js `Link` component.
+
+Make sure you only do this with `BreadcrumbItem` components that are not the
+current page.
+
+```tsx
+import { Breadcrumbs, BreadcrumbItem } from '@utilitywarehouse/hearth-react';
+import NextLink from 'next/link';
+
+[...]
+
+<Breadcrumbs margin="400">
+  <BreadcrumbItem asChild>
+    <NextLink href="/one">
+      One
+    </NextLink>
+  </BreadcrumbItem>
+  <BreadcrumbItem asChild>
+    <NextLink href="/two">
+      Two
+    </NextLink>
+  </BreadcrumbItem>
+  <BreadcrumbItem asChild>
+    <NextLink href="/three">
+      Three
+    </NextLink>
+  </BreadcrumbItem>
+  <BreadcrumbItem currentPage>
+    Home
+  </BreadcrumbItem>
+</Breadcrumbs>
+```
+
+## API
+
+This component is based on the `nav` element and supports the following common props:
+
+- Margin
+
+## BreadcrumbItem API
+
+This component is based on the `Link` component.
+
+| Prop            | Type                                                   | Default | Description                                                                                          |
+| --------------- | ------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
+| `asChild`       | `boolean`                                              | —       | Change the default rendered element for the one passed as a child, merging their props and behavior. |
+| `inverted`      | `boolean`                                              | —       | Inverts the component colours, for use on darker surface colours.                                    |
+| `hideOpenIcon`  | `boolean`                                              | —       | Hides the "open in new tab" icon when `target="_blank"` is set.                                      |
+| `textTransform` | `"none" \| "uppercase" \| "lowercase" \| "capitalize"` | —       | Set the text-transform on the component.                                                             |
+| `currentPage`   | `boolean`                                              | —       |                                                                                                      |