Design tokens

The Design tokens W3C Group describes the Design tokens format as is:

Design tokens are a methodology for expressing design decisions in a platform-agnostic way so that they can be shared across different disciplines, tools, and technologies. They help establish a common vocabulary across organisations.

Pinceau uses Design tokens as a standard format to describe values in its configuration file.

Most of the examples you may have already seen from the configuration file may seem like a plain key/value object, but here is what it looks like after being normalized:

defineTheme({
  media: {
    tablet: '(min-width: 768px)',
    desktop: '(min-width: 1024px)',
  },
  color: {
    white: '#FFFFFF',
    black: '#191919',
    primary: '#ED4D31',
    secondary: '#4560B0',
    tertiary: '#FBEFDE',
  },
  space: {
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem',
  }
})

const theme = {
  media: {
    tablet: {
      value: '(min-width: 768px)'
    },
    desktop: {
      value: '(min-width: 1024px)'
    }
  },
  color: {
    white: {
      value: '#FFFFFF'
    },
    black: {
      value: '#191919'
    },
    primary: {
      value: '#ED4D31'
    },
    secondary: {
      value: '#4560B0'
    },
    tertiary: {
      value: '#FBEFDE'
    }
  },
  space: {
    1: {
      value: '0.25rem'
    },
    2: {
      value: '0.5rem'
    },
    3: {
      value: '0.75rem'
    },
    4: {
      value: '1rem'
    }
  }
}

Why Design tokens ?

Design tokens are a methodology for expressing design decisions in a platform-agnostic way so that they can be shared across different disciplines, tools, and technologies. They help establish a common vocabulary across organisations.

Pinceau is a tool made to make it easier to implement styling coming from a global theme definition.

Having a standard format to store and expose your design decisions makes it a lot easier for us to build tooling on top of your theme without enforcing a structure for it.

It both enables you to write styling how it pleases you and us to create tooling that is future-proof.

Should I write my tokens with value ?

Most of the time, there should be no need for it.

Reaching for myColor: { value: 'red' } over myColor: 'red' has no impact on outputs.

What it might be useful for is:

• Using other Design tokens attributes for you to consume them later
• Using the $schema key for this specific token
• Creating a sync with tokens generated by tools like Figma Tokens
• You like it better this way 👩‍🎨