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).
Build apps for Atlassian products with Forge
Forge is a serverless development environment that takes care of security, compute, and storage. It helps you build apps for Atlassian products, including for the Atlassian Marketplace.
Forge UI Kit is a native component library that offers most primitives and components from Atlassian Design System and Atlaskit.
Start building UI with Forge.
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';
We’re rolling out design tokens across Atlassian
With design tokens, your style choices align with system-level design decisions. Implementing tokens makes things like dark mode possible and scalable across Atlassian.
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).
Want more components?
The Atlassian Design System has components for core Atlassian experiences like forms, navigation, and more. Check out the rest of Atlaskit for other integrated experiences such as editor and media picker. Note that Atlaskit packages come with limited support for developers outside Atlassian.
How to contact us.