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 guide.

Configure to use GitHub Packages​

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

Authenticate to GitHub Packages​

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

Install dependencies​

Install dependencies:

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

Tailwind​

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: [],
};

Usage​

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>
);