HTTPS SSH

IMPORTANT NOTICE

This repository is now a legacy repository. The maintained components have been moved to a new repository.

Packages that have been left in this repository are likely not actively maintained.


Atlaskit

Commitizen friendly node npm yarn

Atlaskit is the technical implementation of the Atlassian Design Guidelines. It is a collection of reusable components that can be downloaded independently into your projects. Each component is also independently versioned and published to npm.

The full list of components can be found in the Atlaskit Registry.

This project is bound by a Code of Conduct.

Usage

Pre-requisites

It's strongly advised to use the Atlaskit CSS reset in your whole project, or some Atlaskit components may diverge in appearance:

import "@atlaskit/css-reset";

In general, you should avoid directly styling base elements (ex. p, h1, h2…) and uses classes instead.

Example for React projects

Atlaskit components are built for React. Here's an example of using the Avatar component:

  1. First, you specify a component into your project as a dependency using npm: npm install @atlaskit/avatar
  2. Then you can use it in your React projects like this:
import React from 'react';
import Avatar from '@atlaskit/avatar';

export default (
  <Avatar
    src="https://design.atlassian.com/images/avatars/project-128.png"
    presence="online"
    size="large"
  />
);

Check out the Atlaskit Registry to learn more.

Example for non-React projects

There is a subset of components available as styles called the Reduced UI pack. To use:

  1. You include these into your the HTML projects.
<link rel="stylesheet" href="//unpkg.com/@atlaskit/css-reset@latest" />
<link rel="stylesheet" href="//unpkg.com/@atlaskit/reduced-ui-pack@latest" />
  1. Then you can style HTML with

<button class="ak-button ak-button__appearance-primary">Submit</button>

Check out the Reduced UI pack for more examples and details.

Upgrades

When upgrading an Atlaskit component, all changelogs can be found in the Atlaskit Registry.

Installation

Before you start

  • node version should be 6 or above (to check node -v) or use nvm
  • npm version should be 3 or above (to check npm --version)
  • yarn should be installed globally (see yarn website for installation instructions)
  • watchman should be installed to enable running tests in watch mode

Clone the repo and install

git clone git@bitbucket.org:atlassian/atlaskit.git
cd atlaskit
yarn

You're now ready to start developing in Atlaskit!

Each component/util lives in it's own package under the packages directory. You can build those all at once or individually using

yarn run bootstrap
# cleans, installs and links all packages in the repository
yarn run bootstrap/single @atlaskit/packageName
# cleans, installs and links only a single package
yarn run bootstrap/single/with-deps @atlaskit/packageName
# cleans, installs and links a single package AND all of it's dependencies

Once you made some changes, stage them and then commit them using yarn run commit (This will use Commitizen under the covers).

Documentation

A comprehensive list of components and detailed usage of each can be found in the Atlaskit Registry.

You can also find how each component is meant to be used from a design perspective on the Atlassian Design Guidelines website.

Tests

Running unit tests with jest

For packages that use Jest (every package except those used by the Fabric team), we are using Jest as a test runner. These tests live inside a packages packages/<packageName>/test/unit folder. Every file in this folder is considered a test and must have at least one test function in it, unless the filename begins with an underscore.

While developing, it is useful to run jest in watch-mode. We recommend running Jest in watch-mode from the root, so it runs all the tests affected by a change. Since the tests run so quickly, this is going to give you the best possible coverage of any of your changes.

  • To run the full unit test suite: run yarn run test:unit from the repository root
  • To run the tests for a single package:
    • run (cd packages/<packageName>; yarn run test:unit)
    • run yarn run lerna -- run test:unit --stream --scope=@atlaskit/<packageName> from the repository root
  • To run the unit tests in watch mode for development/tdd: run yarn run test:unit -- --watch from the repository root. Note: This might require the installation of Watchman. If this command fails, please install watchman and retry.

Running tests in the browser

For the packages that require karma to run tests in the browser (at preset, the editor-* packages), the following commands apply:

  • To run all browser tests: run yarn run test:browser from the repository root
  • To run the tests for a single package:
    • run (cd packages/<packageName>; yarn run test:browser)
    • run yarn run lerna -- run test:browser --stream --scope=@atlaskit/<packageName> from the repository root
  • To continuously run tests for a single component: cd packages/<packageName>; yarn run test:browser -- --watch

Reporting issues

We believe in open contributions and the power of a strong development community. Please read our Contributing guidelines on how to contribute back and report issues to Atlaskit.

Contributors

Pull requests, issues and comments are welcomed. For pull requests:

  • Add tests for new features and bug fixes
  • Follow the existing style
  • Separate unrelated changes into multiple pull requests
  • Read Contributing guidelines for more details

See the existing issues for things to start contributing.

For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.

Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).

Prior to accepting your contributions we ask that you please follow the appropriate link below to digitally sign the CLA. The Corporate CLA is for those who are contributing as a member of an organization and the individual CLA is for those contributing as an individual.

License

This is a mono-repo, which means that different parts of this repository can have different licenses.

The base level of the repository is licensed under Apache 2.0. There are separate license files (LICENSE) for each component under /packages that specify the license restrictions for each component. While most components are licensed under the Apache 2.0 license, please note packages containing styles, assets & icons are most likely licensed under the Atlassian Design Guidelines license.

If you fork this repository you can continue to use those Atlassian Design Guidelines licensed components only under the given license restrictions. If you want to redistribute this repository, you will need to replace these Atlassian Design Guidelines licensed components with your own implementation.

Copyright (c) 2018 Atlassian and others.