RFC: <Text> component

[SiAdcock]

The typography API provides a low level interface for generating CSS that complies with our typography usage guidelines.

However I've also been considering whether it would be useful to provide a component-based abstraction layer around this API. This would enable us to define text components directly in JSX:

import {Text} from '@guardian/src-text'

(
  <button>
    <Text family="sans" size="medium" weight="bold" element="span">
      Click me
    </Text>
  </button>
)

The prop names could potentially be aliased for brevity:

(
    <Text f="sans" s="medium" w="bold" el="span">
      Click me
    </Text>
)

The equivalent using the existing API and @emotion/core:

import {css} from '@emotion/core'
import {textSans} from '@guardian/src-foundations/typography'

const buttonStyles = css`
  ${textSans.medium({fontWeight: 'bold'})}
`

(
  <button css={buttonStyles}>Click me</button>
)

Advantages:

• provides a more declarative and arguably more readable interface
• ensures that high level styling information is kept close to the markup
• is more idiomatic to React applications
• is easier to refactor and control dynamically

Disadvantages:

• creates a new element in the DOM entirely for styling purposes
• we would need to provide a way for developers to specify the DOM element that gets created, making the API more verbose than the existing typography API

Discussion

• Are there any pain points of the typography API that this or some other implementation might solve?
• Would anyone find the component described above useful?

[sndrs]

Are there any pain points of the typography API that this or some other implementation might solve?

i guess this is the first thing that needs to be answered? I can't really offer much on that i'm afraid, but before adding anything to the api surface/maintenance costs, i think that would be important to understand

a couple of other thoughts:

1. my gut says that adding a new node for styling is something we should avoid. each one has a cost, but this wouldn't actually offer any new functionality to the page itself, just to developers

2. it puts presentation information in two places/contexts in a component (on a special, limited component and however else your app does it). it also makes it possible to do <Text family="sans" css={buttonCss} element="button">, which feels like a code smell to me

3. i think it would make it harder to move applications that use this from react in the future. currently, requiring components to use CSS (in some form) means that all that information is fairly portable. moving styling rules into component attributes would make moving that feature to another framework much harder

in terms of the api, i'd be wary of the shorthand props – would be quicker for people intimately familiar with it, but much harder for people not used to writing CSS or using the component to understand what someone else has done (plus autocomplete should make it fairly quick to use)

if you decide to go with it, i've seen as used a fair bit in these kind of components, in place of element, which i found felt quite natural to use

[SiAdcock]

Good points, thanks @sndrs. Point 1 is solid and makes me feel uneasy about this type of component. I think points 2 and 3 apply to all components, but I agree that adding a purely presentational component for DevX purposes exacerbates the problems.

I appreciate that this proposal might fall into the YAGNI file. If nobody has a problem with the typography API as it stands then it's a solution looking for a problem. However I have seen other design systems use this type of component, which made me think it might be worth exploring.

[JamieB-gu]

creates a new element in the DOM entirely for styling purposes

my gut says that adding a new node for styling is something we should avoid

I would agree with this concern; I'm also reluctant to introduce non-semantic additional elements if possible. I wonder if a HOC would solve this? It doesn't necessarily add any new elements, but extracts the CSS prop from an existing element and adds to it. The downside to this is that it might be brittle, I've had trouble getting HOCs to type-check the way I want in the past. That said it might solve: "we would need to provide a way for developers to specify the DOM element that gets created"

I would also say that I'm quite happy with the way the typography API currently works. It's lightweight and fairly flexible 🙂.

[SiAdcock]

I would also say that I'm quite happy with the way the typography API currently works. It's lightweight and fairly flexible 🙂.

Thanks @JamieB-gu

I wonder if a HOC would solve this?

I'm reluctant to add HOCs to the public API of Source because the brittleness you mentioned. I've also heard concerns from others that HOCs are hard to reason with. I'm not sure if that's a general view.

Thanks for your feedback 🙂

[gtrufitt]

Sorry, forgot to reply to this, but I echo the other comments. From my perspective, I don't think it brings enough value for the cognitive load it might bring. The current API works well IMO and I think keeps a nice understandable separation of concerns for styling on a className rather than prop styling.

[tompretty]

I like this proposal. It's pretty similar to the Typography component from Material UI. The less css the better imo (I'm actually really fond of utility css frameworks like tailwind which add all the styles to the markup). If I can just think in terms of React components and not stop to come up with class names like secondaryCtaSupportingText, I'm happy 😃.

we would need to provide a way for developers to specify the DOM element that gets created, making the API more verbose than the existing typography API

I guess this does make it a little more verbose. With a sensible default (I guess a p tag?) you might never have to touch this though.

Are there any pain points of the typography API that this or some other implementation might solve

I'd say my main pain point is looking up what font size e.g medium corresponds to for a given font. I suppose this doesn't address that though. Other than that, I think it would help reduce general css pain points - stopping to think of good (enough) class names, and context switching between css and react.

Would anyone find the component described above useful

For sure!

Overall, I'd definitely be happy to see this 👍.