@designsystemsinternational/style-setup

Style Setup

PostCSS plugin to provide some basic structure to set up tokens, help with fluid scales and optionally generating utility classes.

• Generate Custom Properties from tokens
• Easily create fluid type and space scales using fluid
• Optional utility class generator

Usage

Step 1: Install plugin:

npm install --save-dev postcss @designsystemsinternational/style-setup

Step 2: Check you project for existed PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.

If you do not use PostCSS, add it according to [official docs] and set this plugin in settings.

Step 3: Add the plugin to plugins list:

module.exports = {
  plugins: [
+   require('@designsystemsinternational/style-setup')(config),
    require('postcss-preset-env')
  ]
}

Step 4: Add configuration, either inline or import it and pass it to the function.

module.exports = {
  colors: {
    black: '#000000',
    white: '#ffffff',
  },

  // In your config you can use the fluid function to define your font sizes and
  // spaces. It expects you to pass unitless px values for lower and upper
  // bound. It will be turned into a fluid clamp statement following the
  // calculation of utopia.fyi
  //
  // See: https://utopia.fyi/ for more information on this approach.
  fontSize: {
    s: 'fluid(14, 18)',
    m: 'fluid(16, 28)',
    l: 'fluid(22, 36)',
  },

  // If you don't want to use fluid scales you can also pass in any valid CSS
  // size unit here.
  space: {
    s: '4px',
    m: '8px',
    l: '12px',
  },
  fonts: {
    base: '"AkzidenzGrotesk", sans-serif',
  },
  breakpoints: {
    small: '640px',
    medium: '1024px',
    large: '1440px',
    xlarge: '1920px',
    max: '9999px',
  },
  // You can also add arbitray key value entries, that you need to be turned
  // into custom properties
  greetings: {
    hello: 12,
  },
};

Step 5: Add @custom-properties; to your main.css file to serve as the entry point for the plugin.

/* In your main.css */
@custom-properties;

The above config will replace @custom-properties with the following CSS.

@custom-media --bp-small (max-width: 640px);
@custom-media --bp-medium (max-width: 1024px);
@custom-media --bp-large (max-width: 1440px);
@custom-media --bp-xlarge (max-width: 1920px);
@custom-media --bp-max (max-width: 9999px);

:root {
  --color-black: #000000;
  --color-white: #ffffff;
  --text-s: clamp(0.875rem, 0.792rem + 0.333vw, 1.125rem);
  --text-m: clamp(1rem, 0.75rem + 1vw, 1.75rem);
  --text-l: clamp(1.375rem, 1.083rem + 1.167vw, 2.25rem);
  --space-s: 4px;
  --space-m: 8px;
  --space-l: 12px;
  --font-base: 'AkzidenzGrotesk', sans-serif;
  --greetings-hello: 12;
}

Recommended plugins

This plugin uses custom-media for media queries, so it's recommended to use a postcss plugin for this. We recommend just going with postcss-preset-env.

Configuration in depth

Responsive Custom Property Overwrites

To responsively overwrite the value of a custom property you can add it to the responsive config key.

...
responsive: {
  small: { // name of the breakpoint
    space: {
      s: 2px,
    }
  },
},
...

This will generate the following CSS.

@media (--bp-small) {
  :root {
    --space-s: 2px;
  }
}

Providing viewport information

The fluid function needs to know the viewport bounds of your design to correctly calculate the clamp statement. The plugin assumes some sensible defaults that you can overwrite in the config you pass.

...
  // Typically your lowest breakpoint value
  viewportMin: 400,

  // Typically your biggest breakpoint value
  viewportMax: 1600,

  // Needed for px to rem conversion. You'll likely don't need
  // to provide this value if you go with one of the popular
  // reset/preflight stylesheets.
  baseFontSize: 16,
...

Generating Utility Classes

To generate utility classes you need to tell your config which utility classes you want.

...
  utilities: {
    bg: { // This will become the classname
      items: {
        // The variants you want to generate
        'black', '#000000',
        'white': '#ffffff',
      },
      property: 'background-color',
    },
    // The above will generate the following CSS
    //
    // .bg-black { background-color: #000000; }
    // .bg-white { background-color: #ffffff; }

    m: {
      items: {
        xl: '100px',
      },
      property: 'margin',
      responsive: true, // will generate responsive variants of the utility class
    },
    // The above will generate the following CSS
    //
    // .m-xl { margin: 100px; }
    // @media (--bp-small) {
    //  .small\:m-xl { margin: 100px; }
    // }
    // ...
  }
...

Next add @utility-classes to the CSS file you want to render the utility classes to.

Heads up! When generating a lot of utility classes make sure to include something like PurgeCSS in your build step.