withTypeScale for ChakraUI

A theme extension for ChakraUI to generate a type scale for use with the Text and Heading components.

Any feedback and help to make the extension better is always welcome! 😁

Installation

npm i @tylerapfledderer/chakra-ui-typescale

or

yarn add @tylerapfledderer/chakra-ui-typescale

Usage

Because withTypeScale is a theme extension, it is included as an additional argument to the extendTheme, along with any other extension that may be used.

import { withTypeScale } from '@tylerapfledderer/chakra-ui-typescale';

const customTheme = extendTheme(
  {
    // default custom styles
  },
  withTypeScale({ scale: 1.25 }),
);

export default customTheme;

scale prop

It requires one prop, referred to as the scale. It is a unitless number value, with the lowest common value usually 1.067 (or the "Minor Second") up to 1.618 (the "Golden Ratio") and any other scale or custom value in between. There is a type-scale generator by Jeremy Church for reference. (Scroll down on the page to see his suggestions on picking a scale value!)

lineHeight prop (optional)

An optional prop is the lineHeight which is also passed as a unitless number value, but renders as a rem value. It needs to be unitless to allow for certain calculations on the return to the theme.

Why rem for the lineHeight value? This is to allow easier consistency with the different font sizes to stay within a "baseline" separation for vertical rhythm. In other words, if the line height in pixels for a 16px body copy is 24px, and the h1 is given a font size of 56px, then the lineHeight for the h1 should be 3 * 24 = 72px. This means the h1 takes up three "rows" in the base line height.

This lineHeight value is also used to generate a new set of space theme tokens specifically for the vertical rhythm in line with the type scale. This provides spacing consistency between text content, regardless of any other content that may not fit in the baseline.

To learn more on vertical rhythm check out the discussion from designer Matej Latin on his site BetterWebType.com

isClamped prop (optional)

Defaults to false

This prop toggles between the use of custom functionality with the CSS clamp() function, or Chakra's breakpoint array feature. This is applied to the Heading component font sizes and line heights generated in the sizes theme object.

• If true a custom function with clamp() is used so the font sizes and line heights are scaled gradually throughout screen sizes instead of breakpoints. By default, the minimum screen size set is 375px and the maximum screen size is 640px.
  • Instead of true, you can also define an object to set a minVW and/or maxVW in pixels.

withTypeScale({
  scale: 1.25,
  lineHeight: 1.45,
  isClamped: { minVW: 300, maxVW: 1200 },
});

• If false Chakra's breakpoint array is used to declare change of the font sizes and line heights via a sensible breakpoint. (breakpoint used is min-width 48em, aka md). For more information, see Chakra UI's page on Responsive Styles

Return Object

withTypeScale generates the following set of token values for sizing:

['sm', 'base', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl']

These are then paired with each value in the scale as font sizes, from a text used one smaller than the body copy up to a size that can be for the h1 tag. Since some projects may only require 3 of the six heading and/or of drastically varying sizes, any of the sizes in scales can certainly be used for any heading (give the h3 element a font size from the lg token, say, instead of 3xl).

The Text component gets a base style lineHeight of the base token line height value.

Both the Heading and Text components receive a base style marginBottom of the vertical.2 token denoting the line height value in rem. (See below) They also receive an object for its sizes group of fontSize / lineHeight array pairs which are also assigned the same token values. See the section in the ChakraUI docsite on Changing font size to get an idea on how withTypeScale returns a similar set.

This extension also generates a subset of tokens under the space theme object with the object name vertical. There are 13 whole-number tokens, with values equal to multiple of half the given lineHeight from the extension's props in rem.

Using whole numbers to prevent confusion and minimize complexity when calling the tokens. i.e. vertical.1, vertical.2 instead of vertical.1, vertical.1.5

// lineHeight value: 1.5
{
  space: {
    // Other values
    vertical: {
      1: "0.75rem",
      2: "1.5rem",
      3: "2.25rem"
      // etc. up to 13
    }
  }
}

So use the even token numbers if you want to use multiples of the line height!

Extended Theme Output

{
  fontSizes: fontSizesObj,
  space: {
    vertical,
  },
  components: {
    Heading: {
      baseStyle: {
        marginBottom: vertical[2],
      },
      sizes: sizesObj,
    },
    Text: {
      baseStyle: {
        lineHeight: sizesObj.base.lineHeight,
        marginBottom: vertical[2],
      },
      sizes: sizesObj,
    },
  },
}

Future Considerations

• As the extension gets used, there may be discovery of other ways to generate the values more efficiently or with more flexibility.

@tylerapfledderer/chakra-ui-typescale

1.4.0

Minor Changes

• 1ffd850: Add sizes theme object for Text component

  Takes the generated object of font size and line height token groups for the Heading component and applies them to the Text component.

Patch Changes

• a0e4a77: Add JSDoc for withTypeScale

  Provide detail about the extension for the IDE intellisense.

  Includes update to the JSDoc for the scale prop.

1.3.1

Patch Changes

• 4c13d66: Update README file

  • fixes outstanding typos in the file.
  • Clarifies the use of the minVW and maxVW props for isClamped.

• 063bb91: Refactor various minor syntax

  Simplify the sizesArr declaration using the map() function.

1.3.0

Minor Changes

• 415abb1: Add option to use clamp() functionality for Heading sizes via the prop isClamped.

  Defaults to false

  • Adds ability to toggle between the use of the CSS clamp() function or the use of Chakra's breakpoint array feature for the Heading component's sizes object. Affects both the font sizes and line heights generated.
  • Instead of true to enable clamp(), can accept an object to replace the default sizes (in pixels) with newly defined min and/or max screen sizes to clamp to.

  withTypeScale({
    scale: 1.25,
    lineHeight: 1.45,
    isClamped: { minW: 300, maxW: 1200 },
  });

  • The README file is updated to reflect the new functionality, along with other minor changes to the documentation.

  NOTE: This is not a breaking change, as the clamp functionality is not enabled by default, and will not affect current projects. Enabling the functionality, however, may require adjustments as it could unexpectedly break UI layouts.

1.2.1

Patch Changes

• ee6e63b: Update dependencies, import(s) and remove @chakra-ui/theme-tools dependency.

  • Dependecy versions have been bumped
  • Removed @chakra-ui/theme-tools dependency as it is no longer needed to import SystemStyleObject
  • SystemStyleObject is now imported from @chakra-ui/react

1.2.0

Minor Changes

• 1daaa73: Add tsup to build the package

Patch Changes

• 56e1f6c: Bump dependencies

1.1.2

Patch Changes

• e0e5407: Fix generated component base styles where the default values for marginBottom should come directly from the verticalSpace function return instead of calling the token strings.

1.1.1

Patch Changes

• ceaee99: Fix import for vertical-space into with-typescale

1.1.0

Minor Changes

• 0a6e762: Add generation of vertical spacing tokens

1.0.5

Patch Changes

• e3b880a: fix link for LGTM language grade badge

1.0.4

Patch Changes

• cb70fe4: Add README badges for license and language grade

1.0.3

Patch Changes

• adf9330: fix usage example in README

1.0.2

Patch Changes

• eb8d754: Add github action step to run build for release workflow