Skip to main content

Contributing to the Component Library

The main UI building block for a frontend developer at Adjust is Atlas's component library. In this section, you will learn how to contribute to the Atlas components: development, documentation and pull request.

Overview​

In order to successfully contribute to the Atlas components you should be familiar with ATLAS working process and follow some rules during your contribution.

ATLAS Boards​

ATLAS team is using Jira boards to manage the working items, you are recommended to use following boards to update the working progress.

Contribution workflow​

Contribution workflow is a part of ATLAS team workflow, it helps ATLAS team acknowledge the progress of the tasks and offer the support to contributors if needed. Hence, the contributors are requested to follow this workflow

Contribution Workflow

You can create a new ticket which you would like to contribute or take an existing item in ATLAS Board. And you are strongly recommended to communicate with ATLAS team before your starting via slack channel #atlas_design_team or our weekly meeting.

Groom Meeting is a weekly meeting to clarify the new tickets and estimate them. You are recommended to join this meeting to share with ATLAS team about your contribution and you can discuss with team if any concern about the implementation.

Setup Project​

To start your development, you should setup ATLAS project locally.

Clone ATLAS repo​

You need to first fork the Atlas repository from github:

git clone [your fork SSH/HTTPS]
cd atlas

Make sure to have a compatible Node.js and Yarn version installed. You can find these under the engines key in the root package.json

Authentication​

To install and publish private NPM packages of the design system you have to be authenticated with the @adjust organisation.

Create a copy of .npmrc.template, fill in your personal access token and save the file as .npmrc.

note

If you are not sure what personal access token is please refer to Github tutorial.

Start development server​

tip

For a comprehensive list of useful scripts, please check our repos Readme section

To install all of the dependencies for the component library as well as the website package (this website) run:

yarn

To start the development server and watcher over the component library, run:

yarn start

tip

If you use VSCode as your source-code editor, it's recommended to use the workspace configuration settings in .vscode/settings.template.json

Git Branch​

  • master is main branch and recommended to checkout for new changes.
  • The name branch should be named as ticket number (eg. ATLAS-XXX)

Development​

During your development, you should pay attention to following sections:

Design Token​

You’re required to use design-tokens instead of hard-coded colors, sizes or spacing values.

Accessibility​

At Adjust we aim to provide an accessible UI. Each component in the Atlas library must meet all accessibility requirements according to our accessibility guidelines.

Unit Tests​

You’re recommended to write the unit test for your change. At the root directory, run:

yarn test

Package version​

  • Your change may be required to add a new package version in components/src/package.json.
  • The version naming should be followed the version schema.
  • And you also need to update @adjust/components dependency in docusaurus with new package version in docusaurus/package.json.

Release note​

Your change is required to update the Release Note (docusaurus/docs/components/release.md)

note

Leave the release date to undefined, ATLAS team will update it when release.

Documentation​

You’re requested to contribute Component documentation when:

  • Your change needs to provide some examples.
  • Your change adds or updates the props of components.

Create new page (new component)​

In case you are contributing a new component, you need to create a new page to Components section.

Please add MDX files describing the functionality of the new component in docusaurus/docs/components based on the component documentation template:

Link new documentation file to the sidebar:

  • In docusaurus/sidebars.json add the path to your new documentation file in Components object.

Edit existing page (existing component)​

In case you are contributing an existing component, you need to add more or update the examples.

You're recommended to add examples for each component's feature to present information and the usage.

These examples contain the title, description of the feature's purpose, usage and code snippets for this example.

You can check the 📄 Component Documentation Template, Variants section to see how you can put examples of the new feature.

To keep readability, please follow the guideline below:

  • Add your example in alphabetical order.

  • Don't name the variant titles with the component name. E.g., If you add an example for the disabled variant of the Button component. As a title, use Disabled instead of Button Disabled

  • In some cases, using the prop name as the title is better as we describe what the prop is doing in the description. E.g., OnSorting instead of Callback for on sorting.

  • Use warning tags for the props or features that will be deprecated before retiring them from the component.

    E.g,

    warning

    propX will soon be deprecated. Please use new propY instead.

  • Use info tags for the props or features that cause some exceptional cases with other props.

    E.g,

    info

    If you use the propX you need also provide propY for this feature.

  • The description of the feature should include information on all use cases regarding this prop. E.g,

    To disable a accordion item you need to add `isDisabled` property to your item object.
    If you prefer to make all accordion items disabled, you can use the `disabled` prop.

  • Please don't keep other optional props in your example if they are not releated. E.g., If you add example of a Disabled variant for the Button component

    Live Editor
    Result
    Loading...

    As size prop is optional and not related; use instead:

    Live Editor
    Result
    Loading...

  • Please keep data as short as possible for the components that render a list like Table, Accordion, etc. If you don't need to show a long list of data in your example, you can use 2 or 3 items.

  • Don't add unneccessary wrappers to component example.

    Live Editor
    Result
    Loading...

    As in this example, we don't use multiple components in the render, use instead:

    Live Editor
    Result
    Loading...

Update prop table​

If you need to add more or update props in Prop table. At the root project, run:

yarn gen-types

and you need to update the snapshot as well.

yarn test - u

Pull Request​

Ready for review​

Before creating a PR, you are recommended to follow the checklist:

  1. Lint style, yarn workspace @adjust/components lint:style 🌸
  2. Unit tests are passed and updated the snapshot, yarn test -u 🌸
  3. The changes is well-documented.
  4. New props are added or updated in Prop Table.
  5. UX follows the design guidelines, used design-tokens instead of hard-coded colors, sizes or spacing values.
  6. UX follows the accessibility checklist.
  7. Package version are updated (both component and docusaurus) 🌸
  8. Release note is updated 🌸
warning

🌸 they are mandatory check to help GitHub Actions run workflow successfully.

Create PR​

  • You’re required to create a new PR with ATLAS template and each ticket should have its own PR.
  • You’re recommended to add screenshot or recording.
  • If your ticket is high priority, please add label priority review.

Release​

warning

Release is responsible by ATLAS team, please contact ATLAS team if your changes need to be released as soon as possible.

References​

Definition of done for the new component​

  • ✅ Component UX follows the design guidelines
  • ✅ Component uses design-tokens instead of hard-coded colors, sizes or spacing values
  • ✅ Component follows the accessibility guidelines
  • ✅ Component supports the css prop, if applicable
  • ✅ Component is covered with unit tests and pipeline checks are green
  • ✅ Component is well documented (including realistic, real-world examples)
  • ✅ Component information is added under features section in release notes for the upcoming version

Tech stack design system website​

The foundation of the design system website is a static site generator from Facebook called Docusaurus.

Deployment and hosting of the website is done via Vercel. Vercel generates a preview URL for every pull request.

note

By default, Vercel automatically updates the production website if something is merged to the main branch (master). However, to keep control over what's published and when, we deactivated this behavior. We did this by setting a non-existing branch as our main branch in the Vercel domain settings.

Use the publish-documentation workflow to manually update the production website from master.

Versioning schema​

The component library follows the SemVer versioning scheme.

In brief, given a version number MAJOR.MINOR.PATCH we increment as such:

  • MAJOR Breaking API changes.
    • Examples: dark-mode support is deprecated, the iconOnly property of the Button component was removed, the icon Megafon is now called Megaphone
  • MINOR Added functionality that is backward compatible.
    • Examples: a new component is introduced, additional icons are added to the Icon component, the ActionMenu component now support sub menus
  • PATCH Bug fixes that are backward compatible.
    • Examples: Tooltips don't disappear in certain cases, the label of the Badge component is shifted in Firefox, the AppIcon component doesn't show a placeholder image if the actual icon is unavailable

CI/CD infrastructure​

GitHub Actions is used as to run tests and other workflows on every pull request. All workflows can be found here.