Getting Started

The following guide shows how you can use the Earth Design System in your app.

To find out how to get started contributing to the design system, see the Contributing setup guide.

Earth Design System packages are published on GitHub Packages under the adaptavant organisation. If you haven’t already, you will need to set up your project to use GitHub Packages.

In the same directory as your package.json file, create or edit an .npmrc file to include the following line:

@adaptavant:registry=https://npm.pkg.github.com

To authenticate to a GitHub Packages registry, you will need a personal access token with at least packages:read scope to install packages.

To generate a new token, go here and ensure the read:packages scope is checked.

When your personal access token has been generated, ensure you make a copy as you won’t be able to access it after you navigate away from the page.

Login to the registry with the following command, and when prompted, provide your GitHub username and the newly generated token as the password.

For more information on authentication with personal tokens check the official documentation.

npm login --scope=@adaptavant --registry=https://npm.pkg.github.com

Once you can install from GitHub Packages, edscli can do the rest of this guide for you. Run it from the directory that holds your package.json:

npm install -g @adaptavant/edscli
edscli init
edscli info

edscli init installs the packages, sets up Tailwind and PostCSS, adds the Tailwind directives to your stylesheet and wraps your app in Root. It writes the Tailwind and PostCSS configs and the directives only once Tailwind v3 is installed. On a project without it, edscli init prints the install command; run it, then run edscli init again. edscli info then checks the result. The sections below walk through the same steps by hand.

While you build, edscli icons <query> finds an icon and its import from @adaptavant/eds-icons, which edscli init does not install, so add it yourself, and edscli tokens lists the Tailwind classes EDS adds and the ones it removes, with what to use instead.

Install dependencies:

npm install @adaptavant/eds-brands @adaptavant/eds-core @adaptavant/eds-fonts @adaptavant/eds-icons @adaptavant/eds-translations

⚠️ Note: Currently, we only support Tailwind CSS v3. We will update the documentation soon once we officially support v4

For styling purposes, Tailwind is required. Please visit their installation guide for instructions on how to set up Tailwind in your app. Then adapt the config to use utility classes correctly with Earth components and custom templates:

/* tailwind.config.js */

const { tokens } = require('@adaptavant/eds-brands/setmore');
const { createPreset } = require('@adaptavant/eds-core/tailwind');

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}', // update this to provide the location of your templates
    './node_modules/@adaptavant/eds-core/dist/**/*.{js,ts,jsx,tsx}', // this is the location of the React components for Earth
  ],
  presets: [createPreset(tokens)], // using the Earth preset configures Tailwind to use our custom classes
  theme: {
    extend: {},
  },
  plugins: [],
};

Tailwind v3 runs as a PostCSS plugin, so your project also needs a PostCSS config that loads it. Without one, the build still passes but ships no Earth styles:

/* postcss.config.cjs */

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

Then add the Tailwind directives to the stylesheet your app imports, at the top but below any @charset or @import lines:

@tailwind base;
@tailwind components;
@tailwind utilities;

Wrap your application with the Root context provider and provide it with a brand, colorScheme and translations.

import "@adaptavant/eds-fonts/inter/index.css";
import "./tailwind.css"; // CSS file with the Tailwind directives

import brand from '@adaptavant/eds-brands/setmore';
import { Root } from '@adaptavant/eds-core';
import translations from '@adaptavant/eds-translations/english';

export default function AppWrapper({ children }: { children: React.ReactNode }) {
  return (
    <Root
      brand={brand} // brand config and tokens
      colorScheme="light" // preferred color scheme
      translations={translations} // preferred language for text that is built into components
    >
      {children}
    </Root>
  );
}

All set! You can now import and use Earth components anywhere in your application. For example:

import { Button } from '@adaptavant/eds-core';

export default () => (
  <Button
    onClick={() => alert('Button clicked!')}
    size="standard"
    variant="accentPrimary"
  >
    Click me!
  </Button>
);