Reduce and Simplify Type Variants

[alanbsmith]

Overview

We've done a bit of research for our new type hierarchy and tested out a few component API prototypes, but there wasn't much exploration into our type variants. I'd like to discuss our variants today and whether we'd like to update them along with our type hierarchy. I believe some of the new patterns in canvas-kit may be able to reduce and simplify our type variants making choices more straight-forward for consumers and reducing the cost and complexity for maintainers.

TLDR: Simplify type variants to error, hint, and inverse, and support other variants through style props, separate components, or both. (Though I believe it's plausible for us to remove all of our current variants if we wanted).

I'd like to review each of these variants in turn and propose updates. I believe these changes will make our type components more consistent with our other components, reduce maintenance, and more straightforward for consumers to use in their applications. Below is a list of our current variants and usage guidelines from our design docs.

• label
  • Used for field labels (Body 1/2 and SMALL)
• button
  • Used for button text, headings, subheadings, and emphasis on paragraph text
• caps
  • Used for Android buttons and uppercase text
• mono
  • Used for any monospace content (code, preformatted, etc.)
• hint
  • Used for help text and secondary content
• error
  • Used for making errors more visible (usually smaller sizes)
• inverse
  • Used for any text on a dark or colored background
• link
  • Used for any link (regardless of size)

Label

The label variant is a bit odd as the name maps to a particular HTML element, not a particular state or variation such as error or inverse. And the only actual style modification is fontWeight: 500, though it's described usage is for "body 1/2 and small."

Suggested Update

We could better support this usage with the fontWeight style prop on our new Typography components. Here's an example:

<Type as="label" fontWeight="medium" htmlFor="input-id">Field Label</Type>

We could also provide a Label component on top of Type that would set these values by default at a fairly low maintenance cost.

<Label htmlFor="input-id">Field Label</Label>

Button

Similarly, the button variant also feels misplaced as it describes an HTML element. And also like label it sets fontWeight to 500. I'm uncertain why the usage guidelines state that it's also used for "headings, subheadings, and emphasis on paragraph text."

Suggested Update

Along with label, we could better support this usage with the fontWeight style prop. Should we decide to make our Buttons composable, we could create a Button.Text as a convenient wrapper for this default, or we could hide it within the Button itself.

Caps

The caps variant mostly does what you would expect by setting the textTransform to uppercase. But it also sets the fontWeight to 700 (I presume for improved readability).

Suggested Update

I would recommend we use two style props to accomplish this: textTransform and fontWeight. Below is an example:

<Type fontWeight="bold" textTransform="uppercase">heads up!</Type>

If we wanted, we could button this up into a Caps component, though it feels less necessary than

<Caps>important</Caps>

Mono

The mono variant only sets fontFamily to monoFontFamily, and while this feels like somewhat like a variation, it seems less clear than others.

Suggested Update

Similar to caps I would rather support this with a style prop.

// Here `mono` would map to `Roboto Mono`
<Type fontFamily="mono">const numArr = [1,2,3,4,5];</Type>

And / or we could provide a simple wrapper component:

<Mono>const numArr = [1,2,3,4,5];</Mono>

Hint

The hint variant feels like a better fit than the former variants overall. Its only modification is setting color to typeColors.hint, but it seems to be communicating a true variation in usage. `Hint is also the variant most missed by developers in our research. They often chose to modify the color directly instead of applying the variant.

Suggested Update

Because the only modification is color, you could make a case for supporting hint with a color style prop instead, and I think that's an option worth considering:

<Type size="small" color="hint">your username must be at least eight characters</Type>

But if we wanted to use a variant, I think that would work as well:

<Type size="small" variant="hint">your username must be at least eight characters</Type>

And, as previously suggested, if we wanted to add a Hint component, it would be a fairly low-maintenance abstraction.

<Hint size="small">your username must be at least eight characters</Hint>

Error

Similarly error only modifies the text color to statusColors.error. It does feel like a true type variant.

Suggested Update

Identical to hint, we could support error in the same three ways:

With the color prop:

<Type color="error">Please complete the required fields</Type>

Or with the variant prop:

<Type variant="error">Please complete the required fields</Type>

And / or with an Error component:

<Error>Please complete the required fields</Error>

Inverse

The inverse variant follows the same patttern as hint and error. It only modifies color to typeColors.inverse and feels like a valid type variant.

Suggested Update

We can follow the same patterns for hint and error for inverse.

With the color prop:

<Type color="inverse">Light type on a dark background</Type>

Or with the variant prop:

<Type variant="inverse">Light type on a dark background</Type>

And / or with an Inverse component:

<Inverse>Light type on a dark background</Inverse>

Link

The link variant is by far the most complex. And it's worth noting that we have a Hyperlink component that uses variant styles directly (in addition to inverse variant) and then adds its own styles on top.

Suggested Update

I understand the value of having this variant so that it could be applied to many different types of text (headings, standalone links, inline with text, et al). However, now that Hyperlink uses createComponent and properly supports as, I feel the link variant is obsolete and is better served by the component directly. When our other Type components are added, Hyperlink can be built on top and use those to support any use case.

Here's an example in body text:

<Body>
  Please refer to the <Hyperlink href="/link/to/doc.pdf">following document</Hyperlink>
</Body>

Or in a heading:

<Heading as="h3">
  <Hyperlink href="/link/to/repo">canvas-kit</Hyperlink>
</Heading>

[alanbsmith]

Also worth noting for folks who would prefer to use object styles, they could still interact with our type tokens like this:

import { type, typeColors } from '@workday/canvas-kit-labs-react/tokens';

...
<p css={{ ...type.body.small, ...type.variant.hint, fontWeight: type.fontWeights.bold  }}>Small, bold hint text</p>

[alanbsmith]

Update: The labs caps variant adds letterSpacing: 0.5 and button sets the font-weight to 600, which is odd because that's not one of our standard font weights.

[anicholls]

TL;DR

• Let's drop label, button, and caps.
• Let's use fontFamily={monoFontFamily} for mono since it's not used very often.
• Let's use variant for hint, error and inverse.
• Let's force the Hyperlink component.

One consideration: Due to the limitations of Figma, making these changes will cause some drift between CK and our Figma libraries. We should discuss with Sean.

---

Reasoning

Label, Button & Caps

For some history/context, our original Canvas type hierarchy explicitly specified the font weight for each level of the hierarchy. Variants were added for agreed upon "divergences" that didn't fit within the hierarchy (e.g. labels, buttons, caps). buttons is out of date (our buttons use bold text now), and our new hierarchy no longer forces ties weights to sizes. This means we can probably drop all of the variants that are weight-based (label, button, and maybe caps). I'm fine with your suggested approach for label and caps. Let's skip the special Caps component. Consumers should avoid changing the weight of our buttons.

Mono

Using fontFamily="mono" is a bit unclear IMO. I think this will receive a similar response to your question in the CK slack a few weeks ago. It feels too black boxy. Mono could work, I think a lot of people would prefer fontFamily={monoFontFamily} (exported from the tokens module)

Hint

Same thing goes for color="hint". I think a lot of people would prefer color={colors.typeColors.hint}. I don't like a Hint component because it mixes components for various sizes of the hierarchy, with a component for less typographic styling. It just makes the type components feel a bit watered down.

Error

Same here color={colors.statusColors.error}, or variant="error". Note: if we go with the semantic variable approach, we should audit what's in design assets, because I noticed a few outdated values the other day.

Inverse

Same here!

Link

While I agree with your reasoning, this locks people in to using the utility components rather than an object spread, which I don't know will be popular. Probably not the worst thing in the world though - you have to draw a line somewhere.

[alanbsmith]

Due to the limitations of Figma, making these changes will cause some drift between CK and our Figma libraries.

This is one of the questions / concerns I had. Thanks for bringing that up.

[alanbsmith]

Re: Link

this locks people in to using the utility components rather than an object spread, which I don't know will be popular.

I understand that concern, but I think the tradeoff is valuable for two reasons:

1. One of the main issues with styled components is that they obfuscate the semantic element (e.g. Wrapper, Container, etc), but Hyperlink doesn't really do that. It renders a semantic a tag.

2. The link styles contain far more styling than our other variants (below for reference). This level of detail feels similar to our Button component or any other mid-level component in canvas-kit.

  link: {
    textDecoration: 'underline',
    color: colors.blueberry400,
    cursor: 'pointer',
    borderRadius: borderRadius.s,
    display: 'inline-block',
    padding: '0 2px',
    margin: '0 -2px',
    transition: 'color 0.15s,background-color 0.15s',
    '&:hover': {
      color: colors.blueberry500,
      background: colors.soap200,
    },
    '&:focus': {
      boxShadow: `0 0 0 2px ${colors.blueberry400}`,
      outline: 'none',
    },
    '&:active': {
      color: colors.blueberry600,
      background: colors.soap300,
    },
  },