@discussify/styleguide

Discussify's living styleguide.

Installation

$ npm install @discussify/styleguide

Setup

It's assumed that you will consume this package in an application bundled with Webpack. Follow the steps below:

1. Activate CSS modules

   Activate CSS modules for this package directory (or for your whole project if you like):

   {
       test: /\.css$/,
       include: path.resolve(__dirname, 'node_modules/@discussify/styleguide'),
       loader: [
           {
               loader: require.resolve('style-loader'),
           },
           {
               loader: require.resolve('css-loader'),
               options: {
                   modules: true,
                   sourceMap: true,
                   importLoaders: 1,
                   localIdentName: '[name]__[local]___[hash:base64:5]!',
               },
           },
       ],
   },

   If you are going to use any of the CSS variables or mixins, please add postcss-loader after css-loader:

   {
       loader: require.resolve('postcss-loader'),
       options: require('postcss-preset-moxy')({
           url: 'rebase',
       }),
   }

2. Add SVG rule

   Support inline SVGs by using raw-loader for this package directory (or for your whole project if you like):

   {
       test: /\.svg$/,
       include: path.resolve(__dirname, 'node_modules/@discussify/styleguide'),
       use: [
           require.resolve('raw-loader'),
           {
               loader: require.resolve('svgo-loader'),
               options: {
                   plugins: [
                       { removeTitle: true },
                       { removeDimensions: true },
                       { cleanupIDs: false },
                   ],
               },
           },
           // Uniquify classnames and ids so they don't conflict with each other
           {
               loader: require.resolve('svg-css-modules-loader'),
               options: {
                   transformId: true,
               },
           },
       ],
   },

   Alternatively, you may setup external-svg-sprite-loader for performance reasons. Check out this project storybook webpack config for an example.

3. Import base styles

   Import the styleguide base styles in the app's entry CSS file:

   /* src/index.css */
   @import "@discussify/styleguide/styles";

   ..or in your entry JavaScript file:

   // src/index.js
   import "@discussify/styleguide/styles/index.css";

4. Wrap your app

   Wrap your app with KeyboardOnlyOutlines components to disable outlines when using a pointer device, such as a mouse:

   import { KeyboardOnlyOutlines } from '@discussify/styleguide';
   
   <KeyboardOnlyOutlines>
     <MyApp />
   </KeyboardOnlyOutlines>

5. Use the components

   import { TypingIndicator } from '@discussify/styleguide';
   
   <TypingIndicator />

   You may take a look at all the components by running the Storybook.

   If you are using the Modal component, please call Modal.setAppElement with your app element.

Base technology

• React
• CSS modules
• PostCSS with MOXY's preset
• SVG spriting support with external-svg-sprite-loader

Commands

start

$ npm start

Starts Storybook.

build

$ npm run build

Builds the project.

test

$ npm test

Runs the project tests.

lint

$ npm run lint

Checks if the project has any linting errors.

release

$ npm run release

Releases a new version of the package. Runs tests, lints and builds the project beforehand. If successful, you may publish the release to npm by running $ npm publish.

This command uses standard-version underneath. The version is automatically inferred from the conventional commits.

Using a linked version of discussify-styleguide

In some cases, you may want to make changes to Discussify's styleguide at the same time as you work on your project which uses the styleguide. In order to use a local version of @discussify-styleguide and have any styleguide modifications be reflected live on your project, some pages have to be made in our main project.

Install and update dependencies

Run the following command in your main project to install postcss-import-webpack-resolver.

$ npm i postcss-import-webpack-resolver

NOTE: if using postcss-preset-moxy, it should be of version '^3.0.0' or older.

Make required changes to your Webpack config

Add two new dependencies. fs and postcss-import-webpack-resolver.

const fs = require('fs');
const createResolver = require('postcss-import-webpack-resolver');

Before exporting the webpack configuration, add the following line to the file. This will check if there is a linked version of discussify-styleguide.

const existsStyleguideSrc = fs.existsSync(path.join(projectDir, 'node_modules/@discussify/styleguide/src'));

In the resolve option of your webpack configuration, insert the following. This will allow your project to update when changes occur to js files in the styleguide, without requiring a new styleguide build.

alias: process.env.NODE_ENV === 'development' && existsStyleguideSrc ? {
    '@discussify/styleguide': path.join(projectDir, 'node_modules/@discussify/styleguide/src'),
} : undefined,

Pass a resolve option to postcss-import plugin. This option will create a new alias for the styles folder in the styleguide's src/ directory. This will have a similar effect as the previous bit of code, but for CSS imports.

resolve: createResolver({
    alias: process.env.NODE_ENV === 'development' && existsStyleguideSrc ? {
        '@discussify/styleguide/styles': path.join(projectDir, 'node_modules/@discussify/styleguide/src/styles'),
        } : undefined,
})

NOTE: if using postcss-preset-moxy, this resolve option should be wrapped in the import option.

Link discussify-styleguide to your main project

Link the projects by running npm link inside the root directory of the discussify-styleguide project, then run npm link @discussify/styleguide inside your main project. NOTE: this step has to be retaken every time you run an npm i command in your main project, because npm i will replace your linked version with an installed version.

Contributing

If you want to contribute for the project, we encourage you to read over the discussify repository README.