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
The Atlassian Design System distributes CSS files alongside our packages, and your bundler must support this.
We 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.
Compiled does not support any bundlers other than Webpack or Parcel. While any bundler that loads CSS files will work, we can’t 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-runtimePlugin 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 your own packages with Compiled styles (eg. to NPM/etc), you want to convert runtime Compiled to distribute `compiled.css` files for consumers to load:
[
'@compiled/babel-plugin-strip-runtime',
{
sortShorthand: true,
// Your `extractStylesToDirectory` config is relative to where you build your output distributions for NPM/etc
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/parcel-config// 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 }),
],
};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.