Equinor Design System

The EDS is the official design system of Equinor and is to be used when designing, prototyping and developing internal digital interfaces. The EDS provides structure, guidance and tools that enable designers and developers to efficiently build consistent, inclusive and flexible solutions.

While the design system itself lives in [Figma][], this repository contains implementations of the EDS in code.

Quick links

• Storybook (prod)
• Storybook (dev) – latest from main
• Figma
• Storefront
• Slack
• Architecture Decision Records – documented architecture decisions

Repository structure

This is a monorepo containing both published packages and applications:

apps/                    # Applications (not published to npm)
  design-system-docs/    # Documentation website (Docusaurus)
  eds-demo/              # Component demo application (Next.js)
  eds-color-palette-generator/  # Color palette generation tool
packages/                # Published npm packages
  eds-core-react/        # React component library
  eds-tokens/            # Design tokens
  eds-icons/             # Icon library
  eds-lab-react/         # Experimental components
  eds-data-grid-react/   # Data grid component (deprecated)
  eds-utils/             # Utility functions
  eds-tailwind/          # Tailwind CSS plugin

Architecture

System Context

EDS serves three personas and delivers through four channels: Figma assets for designers, npm packages for developers, a documentation hub for both, and a CDN that provides fonts and CSS to all Equinor web applications utilizing EDS. The system is built as a monorepo with CI/CD pipelines that automate testing, building and publishing to npm and the CDN.

C4Context
  title System Context diagram for Equinor Design System
Person(designer, "Designer", "Creates and maintains UI designs following the Equinor design language")
  Person(developer, "Developer", "Builds web applications using EDS components and tokens")
  Person(enduser, "End User", "Uses Equinor web applications built with EDS")
System_Ext(figma, "Figma", "Source of truth for design tokens, components and assets")
  System(eds, "Equinor Design System", "Documentation hub, GitHub monorepo and CI/CD pipelines delivering reusable UI components, design tokens, icons and typography")
  System_Ext(app, "Equinor Web Applications", "Internal web apps built with EDS")
System_Ext(npm, "npm Registry", "Distributes EDS packages: eds-core-react, eds-tokens, eds-icons, etc.")
  System_Ext(cdn, "CDN", "Serves font files, icons and logo for Equinor web applications")
Rel(designer, eds, "Uses design assets and documentation")
  Rel(developer, eds, "Uses documentation and developer tools")
  Rel(designer, figma, "Uses EDS components in", "Figma")
BiRel(eds, figma, "Syncs assets and tokens with")
  Rel(eds, npm, "Publishes packages to")
  Rel(eds, cdn, "Publishes fonts and static assets to")
Rel(developer, npm, "Installs EDS packages from")
  Rel(developer, app, "Builds")
  Rel(enduser, app, "Uses")
  Rel(app, cdn, "Loads fonts from", "HTTPS")
UpdateRelStyle(app, cdn, $offsetX="250", $offsetY="0")
  UpdateRelStyle(eds, figma, $offsetX="0", $offsetY="30")
  UpdateRelStyle(developer, npm, $offsetX="0", $offsetY="-60")
  UpdateRelStyle(designer, eds, $offsetX="-150", $offsetY="0")
  UpdateRelStyle(developer, eds, $offsetX="-80", $offsetY="-30")
  UpdateRelStyle(eds, cdn, $offsetX="-100", $offsetY="0")
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")

Table of contents

• Equinor Design System

Status

| Package | Status | Version | |--|--|--| | Core React | | | | Tokens | | | | Icons | | | | Lab React | | | | Data Grid React (deprecated) | | | | Utils | | |

| Application | Purpose | Start Command | |-------------|---------|---------------| | Documentation | EDS documentation website built with Docusaurus | pnpm docu:start | | Demo | Component showcase and examples using Next.js | pnpm demo:dev | | Color Palette Generator | Tool for generating accessible color palettes | pnpm palette:dev |

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js — Version 24.22.1 or compatible
• pnpm — Version 11.27.0, pinned via the packageManager field (install globally with npm install -g [email protected])
• Git — For version control

How to run

Would you like to contribute? Awesome! 👏

We use a fork and pull-request workflow, so start with forking the repository on Github, then either open it in Gitpod or clone your fork locally. Check out Github docs on how to work with forks

Use Gitpod and develop in the browser

Just prepend the url to your fork with https://gitpod.io/#, so for example https://gitpod.io/#https://github.com/yourusername/design-system. Dependencies will be installed automatically, then tests and linting will run, and finally the storybook will open in it’s own preview window ready to start coding.

Clone and develop locally

git clone [email protected]:your-github-username/design-system

We use [pnpm][] as the package manager, because it's fast, space efficient, and has some very useful commands when working with a monorepo.

npm install -g [email protected]

Install dependencies and build all packages using our init script:

cd design-system
pnpm run init

[pnpm]: https://pnpm.js.org

Common development commands

# Build all packages
pnpm build
Run all tests
pnpm test
Lint entire codebase, except packages/eds-mobile-components and
apps/mobile-storybook (they ship their own eslint.config.js)
pnpm lint:all
pnpm --filter @equinor/eds-mobile-components run lint
pnpm --filter @equinor/mobile-storybook run lint
Start Storybook for component development
pnpm storybook
Start documentation site
pnpm docu:start
Start demo application
pnpm demo:dev
Start color palette generator
pnpm palette:dev

Work with the React components

We use Storybook as a development environment.

Start Storybook on localhost:9000 by running the following command from root:

pnpm run storybook

Run tests once or by watching:

pnpm run test:core-react 
pnpm run test:watch:core-react

Figma

The EDS in Figma is the single source of truth. You can apply for access to Figma in [AccessIT]. The EDS Core team has workshops and demos on using Figma from time to time, these are announced in Slack and Teams (see «Get in touch»)

[accessit]: https://accessit.equinor.com/Search/Search?term=figma

Storefront

The [storefront][] is the official documentation for the EDS.

[storefront]: https://eds.equinor.com [Figma]: https://www.figma.com/

React

This is the main implementation of the EDS, and will eventually contain accessible React components of each and every EDS component in Figma.

Installation

npm install @equinor/eds-core-react styled-components

npm install typescript --save-dev

Usage

import { Button } from '@equinor/eds-core-react'
<Button variant="outlined" color="secondary">
  Click me!
</Button>

See our storybook for more examples.

Beta Components (EDS 2.0 / Next)

We're developing the next generation of EDS components under the /next entry point. These components are available as beta releases for early testing and feedback.

Note on naming: "EDS 2.0" is the design system name; eds-core-react is the package version (semver). They are separate; the numbers line up by coincidence. See Versioning for the full explanation.

Installation

# Install the beta version
npm install @equinor/eds-core-react@beta

Usage

// Import from the /next entry point
import { ComponentName } from '@equinor/eds-core-react/next'
// Import CSS separately (required for SSR compatibility)
import '@equinor/eds-core-react/next/index.css'

Important Notes

• Safe to adopt alongside EDS 1.0 - the API may still change in small ways before EDS 2.0 becomes stable, and every such change is listed in the changelog below
• EDS 1.0 stays supported until EDS 2.0 becomes stable (published as [email protected]), and mixing EDS 1.0 and /next components in one application is expected
• Visible in Storybook - browse components at storybook.eds.equinor.com under "EDS 2.0"
• Requires beta installation - viewing in Storybook doesn't enable usage, you must install @beta
• Separate changelog - see src/components/next/CHANGELOG.md for beta changes
• Feedback welcome - help us improve before stable release!

Icons

Built on a copy of the Outlined Material Design icons, the icons have been customised and renamed for Equinor’s use and supplemented with our own icons for Equinor specific domains.

All the icons are available in our Storybook, and can also be installed from NPM.

The following example uses the component from @equinor/eds-core-react – but the icons package can also be used without React.

Installation

npm install @equinor/eds-icons @equinor/eds-core-react

npm install typescript --save-dev

Usage

import { Icon } from '@equinor/eds-core-react'
import { info_circle } from '@equinor/eds-icons'
<Icon data={info_circle} size={24} />

Tokens

Design tokens are design decisions from Figma extracted into code, and form the basis for the EDS Core React library. For projects that don’t use React, the tokens are available as an independent NPM package that can be used to build your own implementation of the EDS in your technology of choice. The following example uses vanilla javascript.

Installation

npm install @equinor/eds-tokens

npm install typescript --save-dev

Usage

import { tokens } from '@equinor/eds-tokens'
const {
  typography: {
    heading: { h1 },
  },
} = tokens
const header = document.createElement('h1')
Object.keys(h1).forEach((token) => {
  header.style[token] = h1[token]
})
header.textContent = 'Some header'
document.body.appendChild(header)

Lab React

Experimental React components that are still in development. These components may undergo breaking changes and are not recommended for production use until they are moved to the Core React library.

Installation

npm install @equinor/eds-lab-react styled-components

npm install typescript --save-dev

Usage

import { Stepper } from '@equinor/eds-lab-react'
<Stepper activeStepIndex={0}>
  <Stepper.Step>Step 1</Stepper.Step>
  <Stepper.Step>Step 2</Stepper.Step>
</Stepper>

See our Storybook for more examples and available components.

Data Grid

⚠️ Deprecated: no longer maintained. @equinor/eds-data-grid-react stays on npm and

keeps working, but it receives no bug fixes, new features or security updates. We do not

have the resources to maintain a component of this size. A recommendation for what to use

instead is being worked out, see

#5649. Background:

#5390.

A powerful data grid component built with TanStack Table, providing sorting, filtering, and other advanced table features.

Installation

npm install @equinor/eds-data-grid-react @equinor/eds-core-react

npm install typescript --save-dev

Usage

import { EdsProvider } from '@equinor/eds-core-react'
import { EdsDataGrid } from '@equinor/eds-data-grid-react'
import { createColumnHelper } from '@tanstack/react-table'
const helper = createColumnHelper()
const columns = [
  helper.accessor('name', { header: 'Name' }),
  helper.accessor('age', { header: 'Age' }),
]
const rows = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
]
<EdsProvider>
  <EdsDataGrid columns={columns} rows={rows} />
</EdsProvider>

See the package documentation for more details.

Fonts

EDS uses two font families: Equinor for headings and Inter for UI/body text. Both are available from the EDS CDN as variable fonts:

Recommended (includes both Equinor and Inter)

<link rel="stylesheet" href="https://cdn.eds.equinor.com/font/eds-uprights-vf.css" />

Note: If you use EDS 2.0 (next) components, this stylesheet is required. The older equinor-font.css only includes Equinor, so UI components will fall back to a generic sans-serif.

Individual fonts

<link rel="stylesheet" href="https://cdn.eds.equinor.com/font/equinor-regular.css" />

Logo

When it comes to the Equinor logo, we have two versions – primary and horizontal – and you pick the color with a fragment identifier in the url. The following example uses the primary logo in red, other color options are white and black – with black being the default if you omit the fragment identifier.

Usage

<img src="https://cdn.eds.equinor.com/logo/equinor-logo-primary.svg#red" alt="Equinor" />

Browser support

We support the most up to date version of evergreen browsers (browsers that auto-update), which means Chrome, Safari, Firefox and (Chromium) Edge.

Troubleshooting

Port already in use

If you get an error that port 9000 (Storybook), 3000 (demo/docs), or other ports are already in use, you can either:

• Stop the process using that port
• Change the port in the respective configuration file

Build failures

If you encounter build failures:

1. Ensure all dependencies are up to date: pnpm install
2. Clean and rebuild: pnpm clean && pnpm build
3. Make sure you're using the correct Node.js version (24.22.1, see .nvmrc)

Module not found errors

If you see "Module not found" errors:

• Run pnpm run init to install all dependencies and build packages
• Ensure workspace dependencies are built before consuming packages

License

The Equinor Design System is licensed under the MIT License.

Contributions

Contributions are welcome and encouraged! Here's how to contribute:

1. Report issues — File bug reports and feature requests in GitHub issues
2. Fork and develop — Follow the fork and pull-request workflow outlined above
3. Submit a pull request — All changes must be reviewed and approved by the EDS team before merging
4. Follow conventions — Use conventional commits for your commit messages

Get in touch

We use [#eds-design-system][slack] on Slack as our main communication channel – but we have an [internal team][teams] on Teams as well that you can join if you want to get in touch with us. If you’re outside Equinor and want to get in touch with the team, then please create an issue.

[teams]: https://teams.microsoft.com/l/team/19%3a08081ac3d7134608b312d8480aa87efc%40thread.tacv2/conversations?groupId=204b36ea-ba52-4cee-aeac-895f675e91b0&tenantId=3aa4a235-b6e2-48d5-9195-7fcf05b459b0 [slack]: https://equinor.slack.com/archives/CJT20H1B9