# Text

The system’s paragraph, on the second rung of the ink ladder.

- Group: Display
- Import: `import { Text } from '@misoto22/design'`
- Page: https://ui.misoto22.com/components/text/
- Related: heading, article, markdown

## When to reach for it

One paragraph, or one run of text, outside a reading column. A whole column of prose is an Article.

## Anatomy

- **Box** (required) — The element `as` names — a <p> unless told otherwise. It carries the size, the tone and margin: 0, so the spacing between blocks belongs to the surface rather than to the paragraph.
- **Type step** (required) — size, one of four: xs, sm, base and lead. lead is --fs-item, the bottom rung of the heading ladder, and is the standfirst that carries a piece.
- **Ink step** (required) — tone, one of three, because the ink ladder has three rungs: body is --ink-2, strong is --ink, muted is --ink-3-aa.

## Best practices

### Do

- Leave tone alone for body copy. The default is --ink-2 on purpose: a page whose paragraphs are all full-strength ink has spent the top of the ladder on its body text and has nothing left for the headings.
- Use as="span" for a run inside a sentence. A <p> nested inside a <p> is not nesting — the HTML parser closes the outer one and you get two paragraphs and a broken layout.
- Reach for size="lead" for the standfirst under a title, and stop there. It is --fs-item, the same step an in-card title uses; anything larger is a heading that has not admitted it.

### Don’t

- Do not set spacing on it. Every Text is margin: 0, so a stack of them inside a plain <div> has no rhythm by design — put them in an Article or give the container the gap, or every surface ends up with its own idea of what a paragraph gap is.
- tone="muted" is --ink-3-aa, never --ink-3. The two look identical on paper and are not the same token: --ink-3 is a translucent tint that takes on whatever is under it, so it clears AA on the page ground and quietly fails on a card or a code plate.
- Do not use it as a heading with a bigger size. The element is what a screen reader navigates by, and a <p> at --fs-item is invisible to a heading list.

## Accessibility

- as changes the element and nothing else, so the markup can say what the content is without the look changing under it.
- Every tone is an AA-safe rung; the muted step is --ink-3-aa rather than the translucent --ink-3.

## Text

A paragraph, or a run of text that wants the system's voice. The step between `Article` and raw JSX. `Article` styles a whole reading column from element selectors and is the right answer for a post; this is for the single paragraph that is NOT in a column — a card's description, a dialog's explanation, the line under an empty state. The default tone is `body` (`--ink-2`), not `--ink`. A page whose paragraphs are all full-strength ink has spent the top of the ladder on its body copy and has nothing left for the headings, which is the single most common way a monochrome page loses its hierarchy.

### Props

- `children` — `ReactNode`.
- `size` — `TextSize` default `'base'`. Which rung of the type scale. See TextSize.
- `tone` — `TextTone` default `'body'`. Which rung of the ink ladder. See TextTone.
- `as` — `TextElement` default `'p'`. The element, and ONLY the element. Changing it changes what the markup means — a `span` inside a sentence, an `li` inside a list someone else opened — and changes nothing about the look. That separation is the whole point: the alternative is a `<p>` nested inside a `<p>`, which the HTML parser silently splits into two, or a paragraph faked out of a `<div>` because the real element brought a size with it.

Also accepts: `HTMLAttributes<HTMLElement>`.

## Example — sizes and tones

```tsx
import { Text } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-4">
  <Text size="lead" tone="strong">
    A monochrome system for software and writing.
  </Text>
  <Text>
    Body copy at the base step, on the second rung of the ink ladder. Use{' '}
    <Text as="span" tone="strong">
      strong
    </Text>{' '}
    for a run that has to carry, and nothing above lead.
  </Text>
  <Text size="sm" tone="muted">
    Updated just now — the muted rung is --ink-3-aa, which clears AA on any
    ground in the system.
  </Text>
</div>
```

## Example — a run inside a sentence

```tsx
import { Text } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-4">
  <Text>
    The release went out at 09:14.{' '}
    <Text as="span" tone="strong">Twelve deploys</Text> since the rewrite, and{' '}
    <Text as="span" tone="muted">no rollbacks</Text>.
  </Text>
  <ul className="m-0 flex list-none flex-col gap-1 ps-0">
    <Text as="li" size="sm">Tokens rebuilt from the CSS source</Text>
    <Text as="li" size="sm">Every example carries the sentence that explains it</Text>
    <Text as="li" size="sm">Chinese copy still owed for the newest five</Text>
  </ul>
</div>
```

## Example — a standfirst under a title

```tsx
import { Heading, Text } from '@misoto22/design'

<div className="flex max-w-prose flex-col gap-3">
  <Heading level={2}>The White Reset</Heading>
  <Text size="lead">
    A monochrome system for software and writing, published as one package
    and one stylesheet.
  </Text>
  <Text>
    Structure is carried by weight, rules and space rather than by colour,
    which leaves the two status hues free to mean something when they appear.
  </Text>
  <Text size="sm" tone="muted">Updated this morning</Text>
</div>
```