# Prose

A container for long-form content, such as documentation, articles, and release notes. It switches the text inside to the prose style and spaces the blocks inside, so they need no margins of their own. For application UI, use [Stack](/components/stack.md) and the components' own spacing.

```tsx
// demo.tsx
import {
  Blockquote,
  CodeSnippet,
  Heading,
  InlineCode,
  Link,
  List,
  Prose,
  Strong,
  Text,
} from '@earendil-works/elanor-react';

export default function ProseDemo() {
  return (
    <Prose>
      <Heading level={2} size={2}>
        Deploy a project
      </Heading>
      <Text>
        Every project deploys from its default branch. Connect a repository first, then choose the
        branch in <Link href="#">project settings</Link>.
      </Text>
      <List.Root render={<ol />}>
        <List.Item>Install the command-line tool.</List.Item>
        <List.Item>
          Sign in with <InlineCode>acme login</InlineCode>.
        </List.Item>
        <List.Item>Run the deploy command from the project folder.</List.Item>
      </List.Root>
      <CodeSnippet>acme deploy --prod</CodeSnippet>
      <Heading level={3} size={3}>
        Rollbacks
      </Heading>
      <Text>
        A deploy that fails its checks <Strong>never replaces</Strong> the running version.
      </Text>
      <Blockquote>
        <Text>We roll back by deploying the previous commit again; nothing else changes.</Text>
      </Blockquote>
      <Text>Deploys keep their logs for 30 days.</Text>
    </Prose>
  );
}
```

## Usage

```tsx
import {Heading, Prose, Text} from '@earendil-works/elanor-react';

<Prose>
  <Heading level={2} size={2} />
  <Text />
</Prose>;
```

Prose renders a `div` with `data-text-context="prose"`, so `semantic.typography.primary` resolves to the prose style for [Text](/components/text.md), [Link](/components/link.md), [List](/components/list.md), and [Table](/components/table.md) inside. Use `render` for another element, such as `article`. Inside, an element with `data-text-context="ui"` switches back to the UI style and keeps Prose's spacing out of its lists and quotations, such as an interface example in an article.

## Spacing

Prose puts space above each block, from the `semantic.dimension.space.flow` tokens, also between the blocks inside list items and quotations:

| Between                                         | Space                                         |
| ----------------------------------------------- | --------------------------------------------- |
| Blocks, such as paragraphs and lists            | `flow.small` (16px)                           |
| A code block and its neighbors                  | `flow.medium` (24px)                          |
| A quotation, figure, or image and its neighbors | `flow.large` (32px)                           |
| A separator and its neighbors                   | `flow.xLarge` (48px)                          |
| Above and below an `h2`                         | `flow.xLarge` and `flow.medium` (48 and 24px) |
| Above and below an `h3`                         | `flow.large` and `flow.small` (32 and 16px)   |
| Above and below `h4` to `h6`                    | `flow.medium` and `flow.xSmall` (24 and 8px)  |

A heading stays closest to the content it introduces. Headings match directly or as the only heading inside a wrapper, such as a heading with a link button. Inline content in list items and quotations gets no space.

The spacing lives in the `elanor.prose` cascade layer, after the components, so it overrides their margin resets.

## API

### `Prose`

Renders `<div>`. Accepts its HTML attributes, `ref`, and `render`.