## Feature Examples

### Size
- description: Control the size of the text with the `size` prop. It supports 3 sizes: - `medium` is the default for all common cases of running text. - `small` is for field labels and secondary content. - `tiny` is for short messages of minor importance. Note: Use `tiny` in exceptional cases only, as it's hard to read, and not recommended for accessibility.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text size="medium">
    Medium size is a default size that's used most of the time.
  </Text>
  <Text size="small">
    Small size is used where medium doesn't fit or content is less important.
  </Text>
  <Text size="tiny">
    Tiny size is used when there's no space or it's the last thing users need to
    see.
  </Text>
</StorybookComponents.Stack>;
```

### Weight
- description: Control the weight of the text with the `weight` prop. It supports 3 weights: - `bold` emphasizes running text. - `normal` is for form field values and button labels. - `thin` is the default for all regular paragraphs.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text weight="bold">Bold weight is meant to emphasize running text.</Text>
  <Text weight="normal">
    Normal weight is for form field values and buttons.
  </Text>
  <Text weight="thin">
    Thin weight is for running text. Use it for all regular paragraphs.
  </Text>
</StorybookComponents.Stack>;
```

### Skin
- description: Control the color of text with the `skin` prop. It supports 6 skins: - `standard` - `premium` - `success` - `error` - `disabled` - `primary` `standard` skin can be placed on backgrounds with color. All other skins can be used only on white or gray backgrounds.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text skin="standard">Standard skin appears in all regular texts.</Text>
  <Text skin="premium">
    Premium skin calls users to upgrade to get unlimited features.
  </Text>
  <Text skin="success">
    Success skin indicates that everything went smooth.
  </Text>
  <Text skin="error">Error skin alerts users that something went wrong.</Text>
  <Text skin="disabled">
    Disabled skin indicates that something cannot be accessed.
  </Text>
  <Text skin="primary">Primary skin is for inline links.</Text>
</StorybookComponents.Stack>;
```

### Light
- description: Invert text color so it can be used on a dark background with the `light` prop. It affects standard and disabled skins only.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text>Dark text is used on light backgrounds.</Text>
  <Box backgroundColor="D10">
    <Text light>Light text is used on dark backgrounds.</Text>
  </Box>
</StorybookComponents.Stack>;
```

### Secondary
- description: Emphasize content hierarchy by setting running text priority to `secondary`. It applies lower contrast font color for standard skin text only.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text skin="standard" secondary>
    Dark secondary text is used where it's less important than standard text.
  </Text>
  <Box backgroundColor="D10">
    <Text light secondary>
      Light secondary text also serves as neutral content just on a dark
      background.
    </Text>
  </Box>
</StorybookComponents.Stack>;
```

### Unordered list
- description: Use a standard `<ul>` HTML tag to build an unordered list. Control its style with the `listStyle` prop. It supports 2 styles: - `checkmark` - `circle`
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text listStyle="checkmark">
    The list below is built using standard "ul" and "li" HTML tags.
    <ul>
      <li>First statement</li>
      <li>
        Second statement
        <ul>
          <li>Subitem</li>
          <li>Subitem</li>
        </ul>
      </li>
      <li>Third statement</li>
    </ul>
  </Text>
  <Text listStyle="circle">
    The list below is built using standard "ul" and "li" HTML tags.
    <ul>
      <li>First statement</li>
      <li>
        Second statement
        <ul>
          <li>Subitem</li>
          <li>Subitem</li>
        </ul>
      </li>
      <li>Third statement</li>
    </ul>
  </Text>
</StorybookComponents.Stack>;
```

### Ordered list
- description: Use a standard `<ol>` HTML tag to build an ordered list. It accepts all default HTML [types](https://www.w3schools.com/html/html_lists_ordered.asp).
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text>
    The list below is built using standard "ol" and "li" HTML tags.
    <ol type="1">
      <li>First statement</li>
      <li>
        Second statement
        <ol type="1">
          <li>Subitem</li>
          <li>Subitem</li>
        </ol>
      </li>
      <li>Third statement</li>
    </ol>
  </Text>
  <Text>
    The list below is built using standard "ol" and "li" HTML tags.
    <ol type="A">
      <li>First statement</li>
      <li>
        Second statement
        <ol type="a">
          <li>Subitem</li>
          <li>Subitem</li>
        </ol>
      </li>
      <li>Third statement</li>
    </ol>
  </Text>
  <Text>
    The list below is built using standard "ol" and "li" HTML tags.
    <ol type="I">
      <li>First statement</li>
      <li>
        Second statement
        <ol type="i">
          <li>Subitem</li>
          <li>Subitem</li>
        </ol>
      </li>
      <li>Third statement</li>
    </ol>
  </Text>
</StorybookComponents.Stack>;
```

### Text overflow
- description: Handle text overflow by wrapping text, truncating it or doing both. By default, text wraps into any number of lines. With `ellipsis` enabled, it will truncate to fit the width of the parent container. Specify `maxLines` to truncate text after a specified number of rows. Always provide full text content to view: - The most accessible pattern is to add a 'Show more' button which expands the full text. - Show full text on mouse hover with `showTooltip` prop. Control tooltip style by passing all default `<Tooltip/>` properties via `tooltipProps`.
- example:
```jsx
() => {
  const [open, setOpen] = React.useState(false);
  const suffixIcon = open ? <Icons.ChevronUp /> : <Icons.ChevronDown />;

  return (
    <StorybookComponents.Stack flexDirection="column" width="50%">
      <Text>Text that wraps forever. It doesn't show any ellipsis.</Text>
      <Box direction="vertical">
        <Text maxLines={open ? 4 : 2} ellipsis>
          Text that is truncated but has an accessible alternative to provide
          its full content. Click 'Show more' to expand full text. Full text is
          then revealed in the main layout.
        </Text>
        <TextButton onClick={() => setOpen(!open)} suffixIcon={suffixIcon}>
          {open ? 'Show less' : 'Show more'}
        </TextButton>
      </Box>
      <Text ellipsis maxLines={2}>
        Text with ellipsis. It can wrap until a specified number of lines. When
        the limit is reached it displays the 3 dot ellipsis. Full text is
        revealed on hover.
      </Text>
    </StorybookComponents.Stack>
  );
};
```

### Custom tag
- description: Render text as a custom HTML tag by using the `tagName` prop.
- example:
```jsx
<Text tagName="div">This text will be rendered as a "div" element.</Text>;
```

### Inline link
- description: Use a default `<a>` HTML tag to add an inline link to a sentence.
- example:
```jsx
<Text>
  Use a standard HTML 'a' tag to add <a>a text link</a> within the line.
</Text>;
```

## Common Use Case Examples

### Inline button
- description: Use inline `<Box/>` to place buttons or other elements inline to text.
- example:
```jsx
<Text>
  Set up subscriptions, memberships or package plans to sell on your site.
  <Box inline paddingLeft="SP1">
    <TextButton underline="always">Learn more about Pricing Plans</TextButton>
  </Box>
</Text>;
```

### Show more
- description: Toggle `maxLines` prop value to recreate 'Show more / Show less' behavior for text paragraphs. This is a more accessible way to handle text overflow than using a tooltip only, since keyboard users can't access the complete text inside the tooltip.
- example:
```jsx
() => {
  const [open, setOpen] = React.useState(false);
  const suffixIcon = open ? <Icons.ChevronUp /> : <Icons.ChevronDown />;

  return (
    <Box width="50%" direction="vertical">
      <Text maxLines={open ? 4 : 1} ellipsis>
        Click 'Show more' to display more than a single line of text. Toggling
        maxLines allows to recreate expand / collapse behaviour.
      </Text>
      <TextButton onClick={() => setOpen(!open)} suffixIcon={suffixIcon}>
        {open ? 'Show less' : 'Show more'}
      </TextButton>
    </Box>
  );
};
```

## Accessibility Examples

### Formatting
- description: For better readability and accessibility: - Use either `small` or `medium` text size for all running text. - Keep text left-aligned (avoid center alignment, or don't overuse it). - Avoid lines longer than 75 characters in any language. - Divide long text into lists or short paragraphs.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <Box gap="12px" direction="vertical">
    <Text weight="bold">Do:</Text>
    <Text>
      To ensure that text is easy to read:
      <ul>
        <li>Use font size that meets accessibility criteria.</li>
        <li>Divide text into shorter paragraphs or lists.</li>
        <li>Do not exceed 75 characters of line width in any language.</li>
        <li>Use left-alignment.</li>
      </ul>
    </Text>
  </Box>
  <Box gap="12px" direction="vertical">
    <Text weight="bold">Don't:</Text>
    <Text size="tiny">
      To ensure that text in a UI is easy to read, consider font size, paragraph
      length, line width, and text alignment. The font size should meet
      accessibility criteria, and the text should be divided into shorter
      paragraphs or lists. Line width should not exceed 75 characters in any
      language to enhance reading speed and comprehension. Lastly, text should
      be left-aligned, as center-aligned text is less readable.
    </Text>
  </Box>
</StorybookComponents.Stack>;
```

### Contrast
- description: All text should have a contrast ratio of at least 4.5:1, compared to its background. For default running text: - Use `standard` and `secondary` skins on white and light backgrounds. - Use `light` and `light` `secondary` on dark backgrounds.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column" gap="0px">
  <Box direction="vertical" padding="12px" backgroundColor="D80">
    <Text>Standard skin on white background.</Text>
    <Text secondary>Standard secondary skin on white background.</Text>
  </Box>
  <Box direction="vertical" padding="12px" backgroundColor="D10">
    <Text light>Light skin on dark background.</Text>
    <Text light secondary>
      Light secondary skin on dark background.
    </Text>
  </Box>
</StorybookComponents.Stack>;
```