Develop
Set up your environments, and learn how to use components and compose code.
How engineers use the design system
Atlassian Design System (ADS) is the core system that powers Atlassian app user interfaces. Most engineers use ADS alongside other app-specific code packages that are documented in Atlaskit (for example, Confluence Editor). ADS is also the basis of pattern libraries used by multiple teams, such as the AI pattern library.
Install React before you begin setup
The Atlassian Design System is implemented with React 18 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@^18.2.0 react-dom@^18.2.0
yarn add --dev @types/react@^18.2.0 @types/react-dom@^18.2.0 typescript@~5.4.0Atlassian Design System packages are available on npm under the @atlaskit scope, along with other Atlassian platform components.
View source code for our public packages in Bitbucket (Atlassians can view these in the private Atlassian Frontend repository).
Steps to set up your environments
Get started using Atlassian's design system components and developer tools. If you’re already set up, learn about composing code at Atlassian.
1. Set up your style environment
Install our dependencies: CSS reset and design tokens.
yarn add @atlaskit/css-reset @atlaskit/tokensThen import these stylesheets at the root of your application.
import '@atlaskit/css-reset';2. Set up your bundling environment
Atlassian Design System packages distribute both regular CSS assets and pre-extracted Compiled styles. Your bundler must load this CSS.
Applications that consume Platform UI packages from @atlaskit/* or @atlassian/* must also
configure the Compiled integration for their bundler, even if the application does not author
Compiled styles itself. This ensures atomic styles from those packages are combined and ordered
correctly. Compiled provides supported integrations for Parcel and Webpack. Its Vite integration is
experimental and is not tested or supported for key Atlassian products.
Setting up Babel
Configure @atlaskit/tokens/babel-plugin before other CSS-in-JS transforms, and run
@compiled/babel-plugin last as shown below.
yarn add @atlaskit/tokens
yarn add --dev @compiled/babel-pluginPlugin 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'] }],
],
};Distributing packages with Compiled styles
@compiled/babel-plugin-strip-runtime is optional and only for packages that build and distribute
their own extracted Compiled CSS. Applications that consume those packages should not configure it.
Add it after the required Compiled Babel configuration above.
yarn add --dev @compiled/babel-plugin-strip-runtime// Add after @compiled/babel-plugin in babel.config.js
[
'@compiled/babel-plugin-strip-runtime',
{
sortShorthand: true,
extractStylesToDirectory: {
source: 'src',
dest: 'dist',
},
},
]Setting up Parcel (recommended)
Parcel is the recommended bundler used across Atlassian.
yarn add @atlaskit/tokens
yarn add --dev @compiled/parcel-configAssuming 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"]
}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({
// This is a common configure to ensure this is a unique file between builds
filename: '[name].[contenthash].css',
}),
new CompiledExtractPlugin({ sortShorthand: true }),
],
};Setting up Vite (experimental)
The Vite integration is not tested or supported for key Atlassian products. In a Vite React application, add the experimental Compiled plugin before the React plugin so Compiled transforms run first.
yarn add @atlaskit/tokens
yarn add --dev @compiled/vite-plugin// vite.config.js
import compiled from '@compiled/vite-plugin';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
compiled({
transformerBabelPlugins: [['@atlaskit/tokens/babel-plugin']],
extract: true,
}),
react(),
],
});3. Set up your developer tooling environment
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.
yarn add --dev @atlaskit/eslint-plugin-design-systemSecond, 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',
],
};If you’re using CSS modules, we recommend installing the Stylelint plugin too.
4. Install and use a component
Now you’re ready to install and use components. For example, here’s a button:
yarn add @atlaskit/buttonimport Button from '@atlaskit/button';
const App = () => <Button>Hello world</Button>;To see if your setup matches ours, view this code sandbox. CodeSandbox of a working button
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).
Explore 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.
Atlaskit packages come with limited support for developers outside Atlassian.