@locktech/atomic-mixins v0.4.5

Atomic: PostCSS Mixins

atomic-mixins is a library providing PostCSS mixins to generate Atomic's UI components using TailwindCSS' utility-classes.

On this page:

• Storybook Documentation + Examples
• Installation
• Usage

Installation

• 0) Setting up TailwindCSS and PostCSS
• 1) Downloading the library
• 2) Setting up PostCSS plugins
• 3) Importing Atomic's mixins
• 4) Use Atomic's TailwindCSS Preset (Optional)

0) Setting up TailwindCSS and PostCSS

Installing TailwindCSS and PostCSS is well beyond this document.

How you do so will largely depend upon your environment, libraries, and/or framework of choice.

1) Downloading the library

Downloading the library will depend upon your environment of choice. I'll be using Yarn below:

yarn add --dev @locktech/atomic-mixins

2) Setting up PostCSS plugins

To make getting started easier, Atomic takes care of ensuring the required PostCSS plugins are available through a single plugin of its own. These opinionations will be a down-stream benefit to your application: the plugins Atomic makes use of are fully available to you in your application's styling.

Plugins Atomic will provide you:

• postcss-import
• postcss-mixins
• postcss-simple-vars

In addition to Atomic's plugin, you'll also need to add the tailwindcss/nesting plugin. All said and done, your postcss.config.js file should resemble:

// postcss.config.js
module.exports = {
  plugins: [
    // Notice how we've loaded them *before* Tailwind.
    require("@locktech/atomic-mixins/postcss"),
    require("tailwindcss/nesting"),
    require("tailwindcss"),
    require("autoprefixer"),
  ],
};

3) Importing Atomic's mixins

Finally, you'll need to @import Atomic's mixins into your application's CSS file - the same you've used to setup Tailwind.

Below I'm using Tailwind's @import syntax.

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

@import "@locktech/atomic/mixins";

/* Your styling... */

4) Use Atomic's TailwindCSS Preset (Optional)

Provided is Atomic's TailwindCSS preset, you may choose to use this in your project's tailwind.config.js file or not - its up to you.

module.exports = {
  presets: [require("@locktech/atomic-mixins/preset")],
  purge: [
    /* ... */
  ],
};

This preset will:

• Configure TailwindCSS in JIT mode.
• Enable dark mode, using the 'media' setting.
• Add a spin animation
• Add Atomic's gray color pallete.

Usage

• Basic Use
• Nested Styling
• Extending Mixins

Basic Use

Let's use the btn mixin as an example. It provides a call signature resembling:

@mixin btn $color;

To make use of this mixin, your class would invoke it as such:

Note: It is highly recommended you organize your custom-classes using Tailwind's @layer directive, to ensure any styling you don't use is not included in your final CSS.

.btn-red {
  @mixin btn red;
}

You are free to @apply any of Tailwind's classes to your own, customizing the mixin to your liking:

.btn-red-ghost-lg {
  @mixin btn red;
  @apply px-3 py-2; /* Increase the apparent size of our button */
  @apply bg-transparent; /* Remove the mixin's "resting" background. */
  @apply border-transparent; /* Remove the mixin's "resting" border. */
  @apply text-gray-900 dark:text-gray-50; /* Ensure our button's text contrasts our app's background. */
}

Nested Styling

Some components offer styling spread throughout many classes. These classes are often styled using Tailwind's nesting wrapper. Your customizations should, much like the classes themselves, be nested under the invocation of the mixin defining them.

Component's which provide this functionality will have a code-block in their documentation, highlighting how you may go about applying your customizations. For the purpose of demonstration, let's look at how you might go about customizing the 'menu-items' class - which is created when using the Menu mixin:

.menu {
  @mixin menu;

  & > .menu-items {
    @apply bg-gray-300;
  }
}

Extending Mixins

As the installation document would tell you, the plugins which power Atomic are available to you - this includes the mixin plugin.

Let's take advantage of it to extend one of Atomic's mixins to make our own, which we may reuse:

@define-mixin btn-raised $color {
  @mixin btn $color;
  @apply shadow hover:shadow-md active:shadow-sm;
}

.btn-raised-green {
  @mixin btn-raised green;
}

.btn-raised-red {
  @mixin btn-raised red;
}