[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/)


(re)thinking the digital garden

tangle frontend

styled system, variants, overrides


this post documents setting up the frontend portion of tangle.

This section covers the technical foundations including

- bootstrapping the lerna repo
- adding eslint and prettier
- setting up the frontend

### bootstrap lerna repo

``` bash
yarn init
yarn add lerna --dev
yarn lerna init
```

Add to package.json:

``` js
...
  'name': 'root',
  'private': true,
  'workspaces': [
    'packages/*'
  ]
...
```

Update lerna.json:

``` js
  'packages': ['packages/*'],
  'version': 'independent',
  'npmClient': 'yarn',
  'useWorkspaces': true
```

### gitignore

### eslint/prettier

Copy/paste eslint and prettier

``` bash
  yarn add babel-eslint eslint eslint-config-airbnb
  eslint-config-prettier eslint-plugin-import
  eslint-plugin-jsx-a11y eslint-plugin-prettier
  eslint-plugin-react prettier -W -D
```

`-W` for root flag

`-D` for dev dependencies

Add to package.json

``` js
    'lint': 'eslint --fix . && echo 'Lint complete.'',
```

Commit `[init]`.

## frontend / next.js

``` bash
  mkdir packages/web
  npx create-next-app packages/web
```

Select `Default starter app`

Update name of web app to `@tangle/web`

Add command to root package.json

```'web': 'lerna run --scope @tangle/web dev --stream'```

commit `[web] init`

We want to share react and next across the codebase. Add these as `devDependencies` to the root and add them as `peerDependencies` in whatever packages need them.

## component library

``` bash
  mkdir packages/components
  cd packages/components && yarn init -y
```

Name package `@tangle/components`.

Add peer dependencies

```js
  yarn workspace @tangle/components add -P react react-dom next
```

Add dependencies

```js
  yarn workspace @tangle/components add @emotion/styled @theme-ui/color styled-system theme-ui prop-types
```

Make a component

`packages/components/src/components/Button/Button.js`

``` js
  import React from 'react';
  import PropTypes from 'prop-types';
  import styled from '@emotion/styled';

  const StyledButton = styled.button`
    color: red;
    background-color: blue;
  `;

  function Button({ children }) {
    return <StyledButton>{children}</StyledButton>;
  }

  Button.propTypes = {
    /**
    * content of button
    */
    children: PropTypes.string
  };

  Button.defaultProps = {
    children: null
  };

  export default Button;

```

Add storybook

``` bash
  yarn add -W -D @storybook/react @storybook/addon-actions
  @storybook/addon-docs babel-loader @babel/core
```

Add `.storybook` directory w/ `config.js` and `main.js`

`config.js`

``` js
  import { configure, addDecorator } from '@storybook/react';

  addDecorator(storyFn => (storyFn()))

  configure(require.context('../packages/components/src', true, /\.stories\.js$/), module);
```

`main.js`

``` js
  module.exports = {
    stories: ['../packages/**/*.stories.js'],
    addons: ['@storybook/addon-docs']
  };
```

Add a story for the button

`Button.stories.js`

``` js
  import React from 'react';
  import { action } from '@storybook/addon-actions';
  import { storiesOf } from '@storybook/react';
  import Button from './Button';

  storiesOf('Button', module).add('default', () => (
    <Button onClick={action('clicked')}>test</Button>
  ));
```

update root `package.json`

``` js
  'stories': 'start-storybook'
```

Run storybook.

## clean up and code share

[babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver) helps us keep things looking clean.

``` bash
  yarn add -D -W babel-plugin-module-resolver eslint-plugin-import
  eslint-import-resolver-babel-module eslint-import-resolver-alias
```

add a `.babelrc` file

``` js
  {
    'plugins': [
      ['module-resolver', {
        'root': ['./'],
        'alias': {
          '@components': './packages/components/src',
          '@web': './packages/web'
        }
      }]
    ]
  }
```

add to `.eslintrc.js`

``` js
  settings: {
    'import/resolver': {
      'babel-module': {},
      alias: {
        map: [['@components', './packages/components/src']],
        extensions: ['.ts', '.js', '.jsx', '.json']
      }
    }
  }
```

add an `index.js` file to `components/src` and export the button component from there. Update the import in the `Button.stories.js` file to reflect the update

``` js
  import { Button } from '@components';
```

Run storybook to test.

Time to add the button to Next.js

Add a `babel.config.js` to the next app

``` js
  module.exports = {
    babelrcRoots: ['../packages/*'],
    presets: ['next/babel'],
    plugins: [
      [
        'module-resolver',
        {
          root: ['./'],
          alias: {
            '@components': '../components/src'
          }
        }
      ]
    ]
  };
```

We need to transpile the components as they come in:

`yarn workspaces @tangle/web next-transpile-modules`

Transpile components in the `next.config.js`

``` js
  const withTM = require('next-transpile-modules')([
    '../components/src'
  ]);

  module.exports = withTM();
```

Call the `Button` in your index to test. Run your next app.


tangle


This is the first in a series of posts documenting tangle, a fullstack monorepo that utilizes next.js and styled-system on the front end, with a graphql backend. The purpose of these posts is to, on the one hand, document the technical foundations of the repo and, on the other, act as an opening for thinking about the project more generally. Towards this end, I've split this post into two sections -- technical and theoretical.

### technical

tangle is an attempt to build a full stack monorepo boilerplate for quickly spinning up web apps. It's also an attempt to learn a bit more about full stack development -- I have a sense of how I want the codebase to work, but the solutions and integrations are not completely obvious from the outset. I do know that I want a few things:

- lerna monorepo to share code between projects
- shared tooling (eslint, prettier, jest, storybook)
- component library built on top of styled components and styled system
- web/front end built on next.js
- server/back end built on an apollo or express graphql server
- alternatively, serverless functions
- easy deployed to heroku/netlify/now

The directory structure is as follows:

``` bash
├── babel.config.js
├── lerna.json
├── package.json
├── packages
│   ├── api
│   ├── components
│   └── web
└── yarn.lock
```

Some of the motivating factors:

1. I find it easier to work in a codebase that's been bootstrap than bootstrapping the same project over and over. I want the ability to dive immediately into the code rather than fret over setup.
1. Because I'm pretty much only writing JS, shared tooling makes the most sense -- again: set and forget.
1. Splitting the frontend into a component library and web project allows the component library to grow organically (more in theoretical section) and isolates the dependencies the web project needs to deal with.
1. Additionally, splitting things up with way will eventually allow me to deploy just an api, or just a frontend app, or pull in just the component library.
1. Serverless functions are what I'd like to build into this, but there's some weirdness with where those functions should reside.
1. Someone else should be able to pick this up and deploy it eventually, so ideally it's easily deployed everywhere.

For MVP, I want to deploy the repo to Netlify, render a component from the component library, and display information by making a call to the server. This initial build (v 0.1.0) will also document the steps made to structure the codebase (i.e. an edited version of what I'll be doing here).

### theoretical

'Tangle' is a noun and a verb. To tangle is a process of becoming entangled; a tangle is the result. But tangles always seem to be tangling and untangling, retaining their tangliness in the process, until they become untangled, which is a wholesale different entity or status. In this way, a tangle is more than the sum of its parts or, at least, differs from the sum of its parts. We should also think about this in terms of entanglement, or the process through which not mutually exclusive objects or entities become somehow different in their interactions among one another (see Barad or Haraway on 'intra-activity'). A blunt and mundane example is the frontend's intra-action with a server or function or service -- they become different: an app, the exposure of data.

tangle, the project, takes these ideas as foundational in an anti-foundational way. I cannot know in advance what tangle will need or become, instead, I'm interested in allowing tangle to grow itself out as needed. Having a minimal, bootstrapped project allows for easy and speedy development that doesn't assume everything a developer would need. As something coalesces into a feature, it can become part of that boilerplate, or a more permanent part of the tangling. Yet, this is also an anti-foundational stance that refuses mastery -- of a set of practices or tool(ing)s -- in favor of humility and learning. tangle attempts to refuse assumption in an effort never to fully congeal. Instead, it'll just tangle on.

What I'm trying to outline here is a way of thinking about development and boilerplates less as full stop solutions to discrete problems than as process driven projects. In time, I want to think about what it would mean to take this stance further beyond the immediate realm of development (as coding or making a thing) into development as a set of relational practices among myriad people, technologies, and social forces.
