CSS Style Guide

Much the same way ink is always changing, so too are our styles. Presently, ink is using Styled Components to build component visuals, and is in the process of adding visual tokens to help with scalability and consistency. These initiatives help not only to avoid the usage of internal APIs outside of ink, but will make it easier to add future visual features like dark mode.

This document outlines some of the rules we have for creating new components, refactoring visual code or iterating on new visuals.

Help your peers by writing code in a way that's easy to be read.

We are fans of linting. Make sure ESLint working on your editor of choice. If you're unfamiliar with code editors and/or linting, please reach out in the ink channel.

Every component should have these files:

We're introducing tokens help us scale design decisions by offering abstraction layers that allow for us to have more control over hard coded and primitive values.

There are currently 3 abstraction layers for tokens

All design decisions are stored in json before they get consolidated into tokens by running:

$ yarn tokens

Which generates many .tokens.js files that can be imported and used in a component's styles.ts file.

IMPORTANT .tokens.js files are not be edited directly! If you want to make changes to the tokens you should be doing them in the ./src/tokens/ folder.

Tokens are primarily values that can be reused and are created with visual intention. Reset values for example, should not be tokens since they are not visual choices we've made, but a margin set to 17px might be a good candidate for a token.

Core tokens store the hardcoded primitive values for properties. They are only accessible inside of ink and should be rarely changed because of their potential to affect the whole library.

These tokens can be found in the ./src/tokens/core folder

Global tokens are the main layer of abstraction referenced by components. This layer is responsible for turning the hardcoded tokens into tokens with semantical meaning.

To use core tokens in your global token, find the best nomenclature and add them with dot notation inside quotes and brackets:

{
  "color": {
    "global": {
      "background": {
        "danger": { "value": "{color.core.red.base.value}" }
      }
    }
  }
}

These tokens can be found in the ./src/tokens/global folder

Component tokens are the third layer of abstraction, utilizing global tokens to create consistency throughout ink.

Not all values for properties in the component css should be turned into tokens. Visual choices such as color, font, spacing properties should be a token. Resetting a css value should not unless its an interactive state transition.

{
  "button": {
    "core": {
      "background": {
        "color": { "value": "{color.global.background.transparent.value}" }
      },
      "border": {
        "radius": { "value": "{size.global.radius.small.value}" },
        "style": { "value": "solid" },
        "width": { "value": "{size.global.border.small.value}" },
        "color": { "value": "{color.global.background.transparent.value}" }
      },
      "font": {
        "size": { "value": "{font.global.size.body.value}" },
        "weight": { "value": "{font.global.weight.medium.value}" }
      }
    }
  }
}

These tokens can be found in the ./src/tokens/global folder

To add comments in your tokens you just need to add a second key/value pair. When you run yarn tokens this key/value pair will be added as a comment alongside the specific token:

{
  "size": {
    "global": {
      "border": {
        "small": { "value": "{size.core.border.1.value}" },
        "medium": {
          "value": "{size.core.border.3.value}",
          "comment": "we will revisit these naming conventions"
        }
      }
    }
  }
}

output:

export const sizeTokens = {
  GlobalBorderSmall: "1px",
  GlobalBorderMedium: "3px", // we will revisit these naming conventions
}

const PaginationWrapper = styled.div`
  ${paginationCore}

  ${({ theme }) =>
    theme.trim &&
    css`
      margin: 0;
    `}
`

We currently use pixels for several reasons:

For images, only use SVG images for interface elements.