
I'm working on a theme/token generating library based on [theme-ui](https://theme-ui.com/) and [emotion](https://emotion.sh/docs/introduction). I've found myself using some variation of the same theme object across projects, but as I iterate on that object either improving it or tweaking it, I find it increasingly difficult to keep different versions up to parity. An example: I update how I'm using breakpoints in one so I need to go through each project and update the breakpoints there.

One solution would be to publish the theme object as an npm package, but I wanted something a little more dynamic. [speculative fabulation (or sf)](https://github.com/inadeqtfuturs/if-sf) generates theme tokens (ex. colors, typography, buttons) as well as theme objects (ex. an object comprised of theme tokens). These can be passed into `emotion`'s or `styled-components`'s theme provider. `sf` operates on the idea that objects go in, objects come out -- you can extend, merge, or override theme defaults, allowing granular control over the theme you generate:

``` js
const defaultTheme = genTheme();
const defaultThemeWithNewColor = genTheme({ colors: { newColor: '#333' } });
```

Both functions return a full theme object, but you can drill down and update the specific tokens you need.

### token generators

`genTheme()` is broken down into a series of token generators -- functions that return a token object, like colors or styles for a button. In working on these token generators, I set up a few parameters for how they should behave:

0. generator files export a token object
1. generators return a token object
2. generators don't require arguments to return the token object
3. generators merge and extend the token object by default
4. generators can wholesale override the token object

For something like colors, this is simple enough:

``` js
import { merge } from 'theme-ui';

const defaultColors = {
  text: '#111827',
  background: '#F9FAFB',
  primary: '#2563EB',
  secondary: '#DE7283',
  accent: '#7C3AED',
  muted: '#88d1FF'
};

export function genColors({ override, ...restColors } = {}) {
  if (override) {
    return override;
  }
  if (!restColors) {
    return defaultColors;
  }
  return merge(defaultColors, restColors);
}

export default defaultColors;
```

By default, `genColors()` returns `defaultColors`. If we pass an `override` argument, it will return that object instead. Any other key/value pair we pass gets merged into default colors.

### token generators -- deep and defaults

Things became slightly more complicated as I began working with typography. In the past, I've defined a default text base that includes things like font size, line height, and font family, spreading that object into each typographical element (i.e. p, ul, blockquote, etc.) (I'm ultimately leveraging the `theme.styles` object from [theme-ui](https://theme-ui.com/styling-mdx)). This works for the first two generator requirements -- have a base set of styles; spread them into each element, return that:

``` js
export const defaultTextBase = {
  fontFamily: 'body',
  fontSize: ['sm', 'md'],
  lineHeight: 1.5,
  margin: 0,
  padding: 0,
  marginBottom: 4
};

const defaultText = {
  p: {
    ...defaultTextBase
  },
  ul: {
    ...defaultTextBase,
    paddingLeft: 8,
    ul: {
      margin: 0
    }
  },
  ...
}
```

The problem starts when I want to extend or merge styles into the base: if we're just spreading `defaultTextBase` into these elements, at what point do we actually merge or extend the base? One way to solve this would be to iterate through the keys in `defaultText`, spreading the base as we went, but this would prevent us from exporting an object from the generator file. Another way to handle this would be to get a diff between the new base and default base -- after all, we're just extending or merging into it. However, this presents an immediate problem if we're going to wholesale override the base at some point. So I ended up writing a utility that removes the default values (if present) from each element.

``` js
function removeDefaults(obj, defaultObj) {
  const defaultKeys = Object.keys(defaultObj);

  // mapObject does what it sounds like: allows us to map the key/value pairs in an object
  // mapObject = (obj, func) => Object.fromEntries(Object.entries(obj).map(func));
  return mapObject(obj, ([key, value]) => {
    const remainingValues = Object.keys(value).reduce((acc, curr) => {
      if (defaultKeys.includes(curr) && defaultObj[curr] === value[curr]) {
        return { ...acc };
      }
      return { [curr]: value[curr], ...acc };
    }, {});
    return [
      key,
      {
        ...remainingValues
      }
    ];
  });
}
```

Once the default values are removed, we can determine the new base (overriding, merging into, or extending the default base) and use the above `mapObject` function to pass that base into each key. You can see the full implementation [here](https://github.com/inadeqtfuturs/if-sf/blob/main/src/theme/tokens/text/index.js)

### spread defaults // remove defaults

Something about this pattern seems useful, though I'm not entirely sure where. It goes something like this:

1. Have a default base
2. Spread that default base into each key of a token object. Export that object.
3. If you need to extend or override that base, use the above function to remove those defaults
4. Return new object using new base

I like this pattern, though I think it fits a specific use case. I do think it could be used in a more generalized way, and I'd be interested to hear alternative approaches to the above problem.


site refresh

markdown, dynamic routes, next.js

generating theme tokens

[Styled System](https://styled-system.com/) offers some robust tools to build out a themeable component library based on design tokens simply by using a unified theme object. In this post, I want to think about how to set up reusable component variants -- components that are functionally the same but visually different -- and how to override these default values when necessary.

### styled system and design tokens

One reason to use something like Styled System is an adherence to design tokens. A design token is a value that's used to construct components. It can be a color (primary, secondary, light), a size (small, medium, large), or an array of values for spacing (2px, 4px, 8px, etc.). Using design tokens makes building out a component library or design system easy and consistent because it reduces the number of variables you _could_ use (an infinite number) to a limited set that you _can_ use. This constraint leads to consistency in design.

Styled System, and other packages floating in this ecosystem, use a [theme spec](https://system-ui.com/theme/) for consistency across projects. It's just an object with values that can be used to build out components.

```js
theme = {
  colors: {
    text: '#f7f7f7',
    background: '#464452',
    primary: '#28B4AD',
    secondary: '#4926F6'
  },
  space: [0, 0.25, 0.5, 1, 2, 4, 8]
}
```

We can grab our hex values from the `theme.colors` object, or use the `theme.space` array to get a `rem` value for defining padding or margin.

With these values, it's easy enough to go out and build a simple component by importing the theme object. But we can also use [Styled Component's Theme Provider](https://styled-components.com/docs/advanced#theming) to give use access to these variables within our styled components

```js
import React from 'react';
import styled, { css, ThemeProvider } from 'styled-components';
import theme from './theme';

const StyledButton = styled.button`
  ${({ theme }) => css`
    background-color: ${theme.colors.primary};
    padding: ${theme.space[2]}rem ${theme.space[3]}rem;
  `}
`;

function Button() {
  return (
    <ThemeProvider theme={theme}>
      <StyledButton>Styled</StyledButton>
    </ThemeProvider>
  )
}
```

In a real world use case, you'd hoist the `ThemeProvider` up to whatever the app's entry point is, allowing all styled components access to the theme variables. This eliminates the need to import the theme object into every component and allows for on the fly theme switching based on what you pass to the `ThemeProvider`.

### building a variant

Buttons ask us to think in variants. The difference between a submit and a cancel button on a form is largely about design rather than functionality. What I ultimately want is to be able to abstract that visual difference away by just passing a prop to change the color.

```js
<Button>Submit</Button>
<Button type='outline' color='secondary'>Cancel</Button>
```

Styled System has a built in [variant function](https://styled-system.com/variants/) that makes this abstraction really easy. Here's an example:

```js
import React from 'react';
import PropTypes from 'prop-types';
import styled from 'styled-components';
import { variant } from 'styled-system';
import { alpha, darken } from '@theme-ui/color';

const StyledButton = styled.button`
  ${({ theme, color }) =>
    variant({
      prop: 'type',
      variants: {
        default {
          color: 'background',
          bg: color,
          '&:hover': {
            bg: darken(color, theme.opacity.hover)
          }
        },
        outline: {
          color,
          border: `${theme.borders[1]} ${theme.colors[color]}`,
          bg: 'transparent',
          '&:hover': {
            bg: alpha(color, 0.1)
          }
        }
      }
    })
  }
`;

function Button({ children, color, type, ...props }) {
  return (
    <StyledButton
      color={color}
      type={type}
      {...props}
    >
      {children}
    <StyledButton>
  );
}

Button.propTypes = {
  /**
   * content of button
   */
  children: PropTypes.string,
  /**
   * takes one of 'primary', 'secondary', 'accent', 'muted'. corresponds
   * to theme colors
   */
  color: PropTypes.oneOf(['primary', 'secondary', 'accent', 'muted']),
  /**
   * takes one of 'default', 'outline'
   */
  type: PropTypes.oneOf(['default', 'outline'])
}

Button.defaultProps = {
  children: null,
  color: 'primary',
  type: 'default'
};

export default Button;

```

At the top of the styled component, we're deconstructing the `props` object to get access to the `theme` that is passed down from `ThemeProvider` and the button's props, specifically `color`. We then use the `variant` function by providing a prop string of 'type', so they styling will depend on the `type` we pass to the button. These are two basic examples, and your milage may vary, but `type` will determine the text color, the background color, and how to handle the hover state. In both cases, we use the button's color prop to determine which color variable to use for the different css properties.

Because our color variables line up with the variables in our theme object, the `variant` function takes care of assigning the variables for us. With the outline variant, we can even use `color` as a shorthand for explicitly defining `color: color`. This eliminates additional theme destructuring, taking the color prop and finding the corresponding value in the theme object, which we have to do for the outline's border.

### overriding a variant

At some point, you're going to want to override these variants -- the design might call for it or you need something like a one-off CTA button. Without a token in the theme object that matches what you need, you'll need a little more granular control over how to style the thing. In this example, we can pass props into the styled button and override default values by using a styled component. The above button could be overridden like this:

```js
const RedButton = styled.Button`
  color: red;
`;

function Page() {
  return (
    <RedButton>I'm red now</RedButton>
  );
}
```

Rather than getting a button with the default `primary` color, we'll get a red button. This is a basic example, but you could use the same principle to do more complicated overrides.

### further thinking

In general, I like this pattern/system because it's, on the one hand, rigid and tied to the design tokens and, on the other, extendable beyond those values if you're in a pinch. Continuing to work some of this out for an in-house design system, my next thoughts would be about extending the above -- what other props would I want the component to take? What other states would be useful here? Additionally, I want to think about what other helper or getting functions might make defining css properties that aren't explicitly in the theme object -- what's the best way to programmatically generate borders or box shadows? The color functions I'm using could be extended to do more, but there are surely other ways to make syntax a little legible and friendlier.

An additional problem to consider is what overriding values this way gets you beyond an easy one-off: this won't generate a new hover state -- I'd have to do that myself. What becomes important, I think, is thinking about the theming system a bit more holistically or systemically in the way I'm asking in the questions above.

### further reading

- [styled system props](https://github.com/styled-system/styled-system/blob/master/docs/table.md#core)
- [chakra ui](https://chakra-ui.com/style-props)
- [primer](https://primer.style/components/system-props)
- [sprout social](https://seeds.sproutsocial.com/components/system-props)
- [design tokens](https://www.erikverweij.dev/blog/manage-design-tokens-with-typescript-and-styled-components/)


design-system