‎‎Develop

Atlassian Design System is a collection of UI components, foundations, and standards that help teams build beautiful product experiences.

This page lists how to use Atlassian's design system components and developer tools.

The Atlassian Design System is implemented with React 16 and TypeScript. Make sure you have React and optionally TypeScript installed before you start.

You’ll also need a package manager like NPM. We use yarn in our examples:

yarn add react@16.8 react-dom@16.8 typescript@4.5

Atlassian Design System packages are available on npm under the @atlaskit scope, along with other Atlassian platform components.

You can view source code for our public packages in Bitbucket (Atlassians can view these in the private Atlassian Frontend repository).

1. Copy the following into your terminal to install our dependencies: CSS reset, design tokens, and ESLint plugin.

yarn add @atlaskit/css-reset @atlaskit/tokens

2. Import these stylesheets at the root of your application. These are required for our components to work as expected in light and dark mode.

import '@atlaskit/css-reset';

The Atlassian Design System will start distributing CSS files via our packages soon, and your bundler must support this. We additionally highly recommend you configure Babel as well as either Webpack or Parcel with the following configurations to keep your app performant and styled consistently. This is required if you plan on using @atlaskit/css or have visual regressions.

At this time, Compiled does not support any bundlers other than Webpack or Parcel, though any bundler that loads CSS files will work, we just cannot guarantee performance or consistency.

Setting up Babel

At a minimum, you should have @atlaskit/tokens/babel-plugin running via Babel to make sure tokens are performant and working correctly.

yarn add @atlaskit/tokens
yarn add --dev @compiled/babel-plugin @compiled/babel-plugin-strip-runtime

Plugin order matters, your @atlaskit/tokens/babel-plugin must come before other CSS-in-JS plugins, otherwise you may experience errors.

// babel.config.js
module.exports = {
  plugins: [
    '@atlaskit/tokens/babel-plugin',
    // ↓↓ Compiled should run last ↓↓
    ['@compiled/babel-plugin', { transformerBabelPlugins: ['@atlaskit/tokens/babel-plugin'] }],
    // OPTIONAL: If you are distributing packages with Compiled styles, you should remove the runtime:
    [
      '@compiled/babel-plugin-strip-runtime',
      {
        sortShorthand: true,
        // Your `extractStylesToDirectory` config may vary
        extractStylesToDirectory: { source: 'src', dest: 'dist' }
      },
    ],
  ],
};

For full documentation, refer to https://compiledcssinjs.com/docs/installation#babel

Setting up Parcel (recommended)

Parcel is the recommended bundler used across Atlassian.

yarn add @atlaskit/tokens
yarn add --dev @compiled/parcel-config

Assuming you already have Parcel running, add a .compiledcssrc file and modify your .parcelrc file:

// .compiledcssrc
{
  "transformerBabelPlugins": [["@atlaskit/tokens/babel-plugin"]],
  "extract": true,
  "inlineCss": true,
  "sortShorthand": true
}

// .parcelrc
{
  "extends": ["@parcel/config-default", "@compiled/parcel-config"]
}

For full documentation, refer to https://compiledcssinjs.com/docs/installation#(recommended)-parcel

Setting up Webpack

Your configuration may vary, this is a typical minimal configuration for a production-like environment should look like:

yarn add @atlaskit/tokens
yarn add --dev @compiled/webpack-loader mini-css-extract-plugin

// webpack.config.js
const { CompiledExtractPlugin } = require('@compiled/webpack-loader');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        use: [
          { loader: 'babel-loader' },
          {
            // ↓↓ Compiled should run last ↓↓
            loader: '@compiled/webpack-loader',
            options: {
              transformerBabelPlugins: ['@atlaskit/tokens/babel-plugin'],
              extract: true,
              inlineCss: true,
            },
          },
        ],
      },
      {
        test: /compiled-css\.css$/i,
        use: [MiniCssExtractPlugin.loader, 'css-loader'],
      },
      {
        test: /(?<!compiled-css)(?<!\.compiled)\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin(),
    new CompiledExtractPlugin({ sortShorthand: true }),
  ],
};

For full documentation, refer to https://compiledcssinjs.com/docs/installation#webpack

Turn on the ESLint plugin to see in-context help in your IDE. This includes accessibility pointers, deprecation notices, and other helpful tips.

Note that @atlaskit/eslint-plugin-ui-styling-standard is optional, but highly recommended.

First, install our ESlint plugin(s):

yarn add --dev @atlaskit/eslint-plugin-design-system

Second, add our plugin to your ESlint config. For example, your .eslintrc.js file may look like this:

module.exports = {
  plugins: [
    '@atlaskit/design-system',
  ],
  extends: [
    'plugin:@atlaskit/design-system/recommended',
  ],
};

More about ESlint configuration.

If you’re using CSS modules, we recommend installing the Stylelint plugin too.

Now you’re ready to install and use components. For example, here’s a button:

yarn add @atlaskit/button

import Button from '@atlaskit/button';

const App = () => <Button>Hello world</Button>;

To see if your setup matches ours, view this Codesandbox of a working button with everything installed.

Now you should be ready to install and use all design system packages. See each component’s code documentation for individual package installation instructions.

Also see the design recommendations in each component (for example, button usage guidelines).

How to contact us.