vcc-ui/_src/components/text/README.md

VCC UI is a collection of React UI Components that can be used for developing front-end applications at Volvo Car Corporation.

We provide a Volvo type scale for use across Volvo's digital ecosystem. It contains several distinct styles, some of which have sub-styles to portray more specific intentions:

<Spacer size={4} />
<ReadMeDivider />
<Spacer size={4} />

<Flex extend={{ textAlign: 'center', width: 375, margin: '0 auto' }}>

<Text variant="ootah">Standard set</Text>
<Spacer size={1} />
<Text variant="bates">Harmonious type styles most commonly used</Text>
<Spacer size={2} />

<ReadMeTypeCard title="Headings" subTitle="3 separate styles, no sub-styles">
<Text variant="peary">Peary</Text>
<Text variant="cook">Cook</Text>
<Text variant="ootah">Ootah</Text>
</ReadMeTypeCard>

<ReadMeTypeCard title="Sub-heading" subTitle="1 style, 2 sub-styles">
<Text variant="hillary">Hillary - Standard</Text>
<Text variant="hillary" subStyle="inline-link" href="#">Hillary - Inline Link</Text>
<Text variant="hillary" subStyle="emphasis">Hillary - Emphasis</Text>
</ReadMeTypeCard>

<ReadMeTypeCard title="Body copy" subTitle="1 style, 2 sub-styles">
<Text variant="columbus">Columbus - Standard</Text>
<Text variant="columbus" subStyle="inline-link" href="#">Columbus - Inline Link</Text>
<Text variant="columbus" subStyle="emphasis">Columbus - Emphasis</Text>
</ReadMeTypeCard>

<ReadMeTypeCard title="Micro copy" subTitle="1 style, 2 sub-styles">
<Text variant="bates">Bates - Standard</Text>
<Text variant="bates" subStyle="inline-link" href="#">Bates - Inline Link</Text>
<Text variant="bates" subStyle="emphasis">Bates - Emphasis</Text>
</ReadMeTypeCard>

<ReadMeTypeCard title="Button" subTitle="1 style, no sub-styles">
<Text variant="amundsen">Amundsen</Text>
</ReadMeTypeCard>

<Spacer size={4} />

<Text variant="ootah">Outliers</Text>
<Spacer size={1} />
<Text variant="bates">Useful type styles that sit outside the standard set</Text>

<Spacer size={2} />

<ReadMeTypeCard title="Quote" subTitle="3 separate styles, no sub-styles">
<Text variant="armstrong">Armstrong</Text>
<Text variant="jemison">Jemison</Text>
<Text variant="ride">Ride</Text>
</ReadMeTypeCard>

</Flex>

<Spacer size={4} />
<ReadMeDivider />
<Spacer size={4} />

## Variants

The variant prop defines the type style used, with Columbus being the default:

```jsx live=true
<Block extend={{textAlign: "center"}}>
  <Text>Hello world!</Text>
  <Text variant="bates">Nice to meet you :)</Text>
</Block>
```

## Markup

Each variant comes with its own sensible default HTML element, which can be overridden using the `as` prop to fit your needs:

```jsx live=true
<Block extend={{textAlign: "center"}}>
  <Text variant="hillary">The Hillary variant is a &lt;p&gt; by default,</Text>
  <Text variant="hillary" as="h2">but it can also be rendered as an H2.</Text>
</Block>
```

<Spacer size={2} />

## Sub-Styles

Some variants have their own sub-styles. These are for use cases where you may need to render a link, or emphasise a portion of text. You can set them with the `subStyle` prop, for example:

```jsx live=true
<Block extend={{textAlign: "center"}}>
  <Text subStyle="inline-link">This is a link</Text>
  <Text subStyle="emphasis">This is emphasised text</Text>
</Block>
```

The above examples use the default Columbus variant, but sub-styles are available for Hillary and Bates too:

```jsx live=true
<Block extend={{textAlign: "center"}}>
  <Text variant="bates" subStyle="inline-link">A small Bates link</Text>
  <Text variant="hillary" subStyle="emphasis">Hillary with emphasis</Text>
</Block>
```

Sub-styles can also be set without needing to explicitly set their parent variant too, this can be useful for cases where you are dynamically rendering text:

```jsx live=true
<Block extend={{textAlign: "center"}}>
  <Text variant="bates">
    Small block of text with an
    <Text subStyle="inline-link">inline link</Text>
  </Text>
</Block>
```

<Spacer size={2} />

## Baselines

Due to the granualar nature of digital applications at Volvo Card, the Text component does not adhere to a traditional baseline calculated from the smallest or most common type scale variant; Instead, we align to the 4px micro-grid to maintain vertical rhythm.

<Flex extend={{width: 450, margin: "0 auto"}}>
<Spacer size={2} />
<Text variant="jemison" as="blockquote" extend={{border: "none", textAlign: "center"}}>“...a regular, consistent and predictable structure will, naturally, aid the legibility and cognitive interpretation of your design. Establishing a solid baseline grid is a great method to achieve just that”</Text>
<Spacer size={2} />
<Text variant="bates" extend={{textAlign:"center"}}>Excerpt from <Text href="https://www.smashingmagazine.com/2012/12/css-baseline-the-good-the-bad-and-the-ugly/" subStyle="inline-link">Smashing Magazine</Text></Text>
<Spacer size={6} />
</Flex>

The web is notoriously bad at vertical text alignment; in order to overcome this we have fine tuned each element of our type scale so that it will always adhere to our baseline. These adjustments are applied using padding and margin properties to the top and bottom of the element respectively. These adjustments can be disabled by setting `alignBaseline=false`, but then extra care should be taken to adhere to the baseline manually.

See below for a clearer visualisation of the baseline grid against our typescale:

<Block>
{(() => {
const [baselineOn, toggleBaseline] = React.useState(true);
return (
<Flex extend={{alignItems: "center"}}>

<Flex extend={{flexDirection: "row", justifyContent: "center"}}>
<Toggle checked={baselineOn} onChange={() =>toggleBaseline(!baselineOn)}/><Spacer size={2} /><Text as="label">Adjustments <Text subStyle="emphasis">{baselineOn ? "enabled" : "disabled"}</Text></Text>
</Flex>
<Spacer size={2} />

<ReadMeGrid extend={{maxWidth: 500}}>
<Flex extend={{flexDirection: "row"}}>

<Block extend={{flex: 1}}>
<Text alignBaseline={baselineOn} variant="peary">Lorem</Text>
<Text alignBaseline={baselineOn}>ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation</Text>
</Block>
<Flex extend={{flex: 1}}>
<Text alignBaseline={baselineOn}>ullamco laboris nisi ut aliquip ex ea commodo consequat.</Text>
<Spacer size={1} />
<Text alignBaseline={baselineOn} variant="jemison" extend={{textAlign: 'center'}}>“Finibus Bonorum”</Text>
<Spacer size={1.5} />
<Text alignBaseline={baselineOn}>Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.</Text>
</Flex>

</Flex>
</ReadMeGrid>
<Spacer size={10} />
</Flex>
)
})()}
</Block>

<Spacer size={2} />


## Extending the Type Scale

There may be occasions where you would like to use values from the existing type scale, or perhaps even make minor adjustments to the existing styles. For these cases, we provide two options:

### 1. The extend prop

As with many core components in VCC-UI, we have left the extend prop open on the Text component. Styles can be passed in as you would with a `<Block>` element or similar:

```jsx live=true
<Block extend={{textAlign: "center"}}>
  <Text extend={{ fontSize: "2rem", color: "navy" }}>Big Navy Columbus.</Text>
</Block>
```

### 2. Reusing the existing type scale styles

The styles for all of the type scales are written in a notation that can be directly applied to any extend property. These styles are packaged as part of the theme, and can be loaded in like so:

```jsx
const { typeScale } = useTheme();
const { peary } = typeScale; // Contains "standard", "inline-link" and "emphasis"

return (
  <Block
    as={peary.standard.element}
    extend={{
      ...peary.standard.styles,
      fontSize: "2rem",
      color: "teal"
    }}
  >This is a custom variation of Peary.</Block>
)
```