# Copywriting

Text make up almost 70% of our products’ interfaces. The way we write and style it is as important as our user flows and UI components.

Text conveys the first impression users get of our software, it dictates whether we appear as professional, friendly, knowledgeable, and even more importantly: trustworthy.

Just as we make sure not to detach instances from components and to use the correct colour tokens, let's strive for that same level of attention when it comes to the words we choose across our products.

## Language

### British English

Volue's company standard is British English, as set out in the Volue Brand Strategy. Use it consistently for all UI copy, from headings and button labels to error messages and documentation.

This applies to spelling (_colour_, _organisation_, _centre_, _analyse_, _behaviour_, _licence_ as a noun) as well as terminology. Never mix British and American English within a product.

<Grid columns={{ '@initial': '1', '@mqLargeAndUp': '2' }} columnGap="spacingL">
  <GridItem>
    <Tip variant="good">Do's</Tip>
    <ul>
      <li iconName="check">
        <em>Customise the colour of the chart.</em>
      </li>
      <li iconName="check">
        <em>Analyse the behaviour of your portfolio.</em>
      </li>
    </ul>
  </GridItem>
  <GridItem>
    <Tip variant="bad">Don'ts</Tip>
    <ul>
      <li iconName="close">
        <em>Customize the color of the chart.</em>
      </li>
      <li iconName="close">
        <em>Analyze the behavior of your portfolio.</em>
      </li>
    </ul>
  </GridItem>
</Grid>

Consider automating this in your project with a spell checker configured for British English, such as [cspell](https://cspell.org/).

## Use of sentence case

### When to use

Our UIs are text-dense and should be easy to parse through. Therefore, sentence case is the default for every UI element, body text, and headings.

Only the first word of a sentence (and proper nouns) are capitalised, while all other words remain lowercase, just like a normal sentence.
Example: "The quick brown fox jumps over the lazy dog."

### The exception

Proper nouns such as product names: PowerBot, Nimbus, Data & Forecasts, SmartPulse, etc.

### Examples

Here is what sentence case use looks like in practice.

In a blog post:

![Blog post](https://wave.volue.com/_next/static/chunks/images/blog-post-c34984cde65bdc6d3386daca760a4533.png)

In a widget element:

![Widget element](https://wave.volue.com/_next/static/chunks/images/widget-element-c1ea37b025bb559b445d2582a2394589.png)

## Grammar and punctuation

### Active and passive voice

Active voice is when the subject performs the action. Passive voice is when the subject receives the action. Use the former as much as possible to avoid confusion.

<Grid columns={{ '@initial': '1', '@mqLargeAndUp': '2' }} columnGap="spacingL">
  <GridItem>
    <Tip variant="good">Do's</Tip>
    <ul>
      <li iconName="check">
        <em>Schedule imbalance detected. Please review your positions.</em>
      </li>
      <li iconName="check">
        <em>Enter the amount below.</em>
      </li>
    </ul>
  </GridItem>
  <GridItem>
    <Tip variant="bad">Don'ts</Tip>
    <ul>
      <li iconName="close">
        <em>Schedule imbalance detected. Positions should be reviewed.</em>
      </li>
      <li iconName="close">
        <em>Amount should be entered below.</em>
      </li>
    </ul>
  </GridItem>
</Grid>

### Calls to action

Make sure the label on call to action buttons are clear, contextual, and action-oriented. Avoid vague labels such as “Okay” or “Continue”, as well as labels containing multiple actions in one button.

<Grid columns={{ '@initial': '1', '@mqLargeAndUp': '2' }} columnGap="spacingL">
  <GridItem>
    <Tip variant="good">Do's</Tip>
    <Flex gap="spacingS" marginTop="spacingM" flow="column" cross="start">
      <Button size="small">Confirm trade</Button>
      <Button size="small">View pricing details</Button>
      <Button size="small">Save changes</Button>
    </Flex>
  </GridItem>
  <GridItem>
    <Tip variant="bad">Don'ts</Tip>
    <Flex gap="spacingS" marginTop="spacingM" flow="column" cross="start">
      <Button size="small">Confirm</Button>
      <Button size="small">Learn more</Button>
      <Button size="small">Save</Button>
    </Flex>
  </GridItem>
</Grid>

### Be precise and write like you speak

When writing copy, read it out loud first to see if it conveys the information needed to make a decision. Avoid overly technical language. You can ask yourself: is this phrasing influenced by internal jargon used by the engineering teams? Is it intelligible outside of the office?

<Grid columns={{ '@initial': '1', '@mqLargeAndUp': '2' }} columnGap="spacingL">
  <GridItem>
    <Tip variant="good">Do's</Tip>
    <ul>
      <li iconName="check">
        <em>Overview of the results</em>
      </li>
      <li iconName="check">
        <em>You’ve been logged out due to inactivity.</em>
      </li>
      <li iconName="check">
        <em>Incorrect email or password.</em>
      </li>
    </ul>
  </GridItem>
  <GridItem>
    <Tip variant="bad">Don'ts</Tip>
    <ul>
      <li iconName="close">
        <em>Result overview</em>
      </li>
      <li iconName="close">
        <em>Session expired</em>
      </li>
      <li iconName="close">
        <em>Invalid credentials</em>
      </li>
    </ul>
  </GridItem>
</Grid>

### Punctuation

Use regular punctuation for the body/main content, but skip end punctuation (period, question mark and exclamation mark) for titles, headings, subheadings, and items in a list that are 3 or fewer words.

<Grid columns={{ '@initial': '1', '@mqLargeAndUp': '2' }} columnGap="spacingL">
  <GridItem>
    <Tip variant="good">Do's</Tip>
    <Card.Root marginTop="spacingM" size="small">
      <Card.Header>Position limit exceeded</Card.Header>
      <Card.Body>Review your exposure before placing new orders.</Card.Body>
      <Card.Footer>
        <Button size="small" variant="outline">
          Dismiss
        </Button>
      </Card.Footer>
    </Card.Root>
  </GridItem>
  <GridItem>
    <Tip variant="bad">Don'ts</Tip>
    <Card.Root marginTop="spacingM" size="small">
      <Card.Header>Position limit exceeded!</Card.Header>
      <Card.Body>Review your exposure before placing new orders</Card.Body>
      <Card.Footer>
        <Button size="small" variant="outline">
          Dismiss
        </Button>
      </Card.Footer>
    </Card.Root>
  </GridItem>
</Grid>