@locktech/atomic-tailwind v0.12.2

Atomic

Introduction

atomic-tailwind is a component-library built using TailwindCSS and @headlessui/react. Its stylistic opinionations take inspiration from Bootstrap and its API has been influenced by react-bootstrap.

Installation

Using NPM

$ npm install --save @locktech/atomic-tailwind

Using Yarn

$ yarn add @locktech/atomic-tailwind

Tailwind Configuration

The following configuration should be merged with/overwrite the default provided by Tailwind:

module.exports = {
  ...
  theme: {
    extend: {
      minWidth: {
        20: '5rem', // Same value as w-20
        72: '18rem', // Same value as w-60
      },
      maxWidth: {
        '2xs': '15rem', // 5rem less than max-w-xs
      }
    },
    },
  },
  variants: {
    extend: {
      backgroundColor: ['active'],
      backgroundOpacity: ['active'],
      borderWidth: ['active', 'hover'],
      fill: ['active', 'focus', 'hover'],
      textColor: ['active'],
    },
  },
}

LockTech's Grayscale

The default colors, provided by Tailwind, are quite pleasant on their own. The grayscale, however, is not the gray-est at its lower tones; the dark-end.

I use, and have developed Atomic Tailwind around, the following color configuration, added to the theme section of tailwind.config.js:

const colors = require('tailwindcss/colors')

module.exports = {
  ...
  theme: {
    colors: {
      black: colors.black,
      blue: colors.blue,
      gray: {
        50: '#F5F5F5',
        100: '#DBDBDB',
        200: '#C1C1C1',
        300: '#A7A7A7',
        400: '#8D8D8D',
        500: '#727272',
        600: '#585858',
        700: '#3E3E3E',
        800: '#242424',
        900: '#0A0A0A',
      },
      green: colors.green,
      indigo: colors.indigo,
      pink: colors.pink,
      purple: colors.purple,
      red: colors.red,
      yellow: colors.yellow,
      white: colors.white,
    },
    ...
  }
}

See tailwind.config.js for a full example.

Terminology

Though minimal and relatively simple, I'd like to explicitly define a few terms used throughout the source and API of this library.

• Style Helper - const string containing a number of taillwind utility-classes.
  • These are appropriately named accross all components, and every helper is exported by the component it is created by; making them reusable building blocks.
• Theme - Test
• Color Mode - one of two "modes" which determine the colors used by various components.
  • light will, by default, prompt the use of gray colors of a lighter shade, contrasted by darker-colors (red, green, ...).
  • night will prompt the use of gray colors of a darker shade, contrasted by lighter-colors (red, green, ...).
  • "Custom" components can make use of this toggling and synchronize with the useTheme(Mode) hook.
  • As most mode opinionations are implemented via Style Helpers, they can be re-used accross many components.

Components

Can be found in web/src/components/, where each directory contains a README.md detailing that components API and intended use-cases.

Components are always a React functional component. These components use HTML elements and other components, applying Tailwind's CSS-utilities-in the form of Style Helpers-to achieve some "goal". This goal should be clearly defined in the components README.md; this goal is explicitly defined to better promote reuse of the components building-blocks.

Style Helpers

Are ways in which I've structured applying Tailwind's CSS-utilities, done to promote their resuse accross other components. Most of these helpers have easily identifying names, such as "Shape", "Spacing", etc. Others are named based on their use, relative to the component in which they originate; for example, a component which contains a <Card>, but also other components, may define its implementation of the "Card" as CardBackgroundColor.

Within the src/components directory is a common.ts file; this file, among other things, contains Style Helpers shared among many components. The most notworthy is Focus. This helper removes the browser's default outline styling and applies one common to the library.

Many components which have sub-components contain a common.ts file, containing Style Helpers common to two or more of that components sub-components.

Theming

Should be done through TailwindCSS, by way of configuring the values which correlate with its utility-classes.

Additionally, library-specific theming can take place during the use of <ThemeProvider>.

Color Mode

By default, the library will attempt to gather the user's perferred display-type. This can be both disabled and overwritten by the developer.