Integrating the EBRAINS Design System

Build Your First Page showed what an EBRAINS page is made of, and Start Your Own App walks through one project from start to deploy. This guide is the reference for each framework: installing from npm, styles, and using the components in React, Angular, Vue or plain JavaScript.

It is for apps outside the ebrains-ui-ecosystem monorepo. By the end, your app has the components, the design tokens and layout primitives, and the brand assets.

What’s Available

The design system is published to the @ebrains organization on npm:

PackageWhat it provides
@ebrains/components45+ Stencil web components (framework-agnostic)
@ebrains/assetsCSS framework, design tokens, fonts
@ebrains/svgsBrand assets as inline SVG strings: the EBRAINS logo and the EU emblem (icons come from the Carbon set in eds-icon-wrapper)
@ebrains/reactReact wrappers for all components
@ebrains/angularAngular wrappers for all components
@ebrains/vueVue wrappers for all components

You only install what you need. Most apps will use @ebrains/components (or a framework wrapper) plus @ebrains/assets.

Step 1: Install Packages

React App

Angular App

Vue App

Plain HTML / Vanilla JS

Step 2: Load Styles

You have two options for styling: the pre-built CSS file or a custom Tailwind build.

Option A: Pre-built CSS (simplest)

Import the full framework in your entry point:

Or via CDN in your HTML:

This gives you all utility classes (bg-*, text-*, f-heading-*, p-*, flex, grid-layout, etc.), design tokens as CSS variables, and font-face declarations. See CSS Framework for the full reference.

Option B: Tailwind Build (tree-shaken)

If you want only the classes your app actually uses, set up a custom Tailwind build. Tailwind Migration covers this for apps inside the ebrains-ui-ecosystem monorepo only; external apps can use the pre-built CSS from Option A.

Option C: Variables Only (lightweight)

If you just need CSS variables and fonts (about 11 KB), including the semantic --eds-* tokens:

Semantic tokens and dark theme

Both stylesheets define the light semantic tokens: colour roles (--eds-color-surface-*, --eds-color-text-*, --eds-color-border-*, status and data colours), --eds-radius-*, --eds-shadow-1|2|3, the type scale and motion. Use them in your own CSS instead of raw hex values. The dark theme is only in output.css (and tokens.css), not in vars.css: put data-eds-theme="dark" on <html> or any container to switch the roles to the dark theme; components built on the tokens follow. See Tokens.

Step 3: Use Components

In React

Import components from @ebrains/react — they auto-register the underlying web components:

In Angular

Import standalone components from @ebrains/angular:

In Vue

Import components from @ebrains/vue:

In Plain HTML

Load the Stencil loader and use native custom elements:

Build Inside the Monorepo has the Vite configuration for apps inside the ebrains-ui-ecosystem monorepo.

Step 4: Use SVG Assets

The @ebrains/svgs package exports the brand SVGs as inline strings. UI and social icons are not in it: use <eds-icon-wrapper name="…"> (IBM Carbon icon set; social logos: twitter, linkedin, facebook, youtube, mastodon, bluesky, gitlab).

@ebrains/components 3.2.0 and earlier: this import does not resolve in bundlers such as Vite (fixed in the next release). Until then, load the loader from the CDN: import { defineCustomElements } from 'https://unpkg.com/@ebrains/components@3/loader/index.js'. See Start Your Own App.

Available exports:

ExportDescription
logoPositiveEBRAINS logo for light backgrounds
logoNegativeEBRAINS logo for dark backgrounds
euSvgEU emblem (for “funded by” notices)

In React

In Vue

In Angular

In Plain HTML

Step 5: Lay Out Pages with the Primitives

With the stylesheet loaded, lay out pages with the layout primitives: Container, Grid, Stack, Text and Box. They are plain classes, so they work the same in every framework:

In React use className instead of class. Build Your First Page walks through a full page; CSS Framework lists every class.

Quick Reference

Component Naming

ContextConventionExample
ReactPascalCase<EdsButton>
Angularkebab-case (in template)<eds-button>
VuePascalCase or kebab-case<EdsButton> or <eds-button>
Plain HTMLkebab-case<eds-button>

Prop Naming

ContextConventionExample
ReactcamelCasepressableLabel="..."
AngularcamelCase (property binding)[pressableLabel]="..."
Vuekebab-case (in template):pressable-label="..."
Plain HTMLkebab-casepressable-label="..."

Passing Complex Data

Objects and arrays can be passed as JSON strings in HTML attributes, or set as JS properties. The framework wrappers set properties, so pass plain objects there:

Event Handling

ContextHow
ReactonEdsalert={handler} or onClick={handler}
Angular(edsalert)="handler($event)"
Vue@edsalert="handler"
Plain HTMLelement.addEventListener('edsalert', handler)

Minimal Example: New React App

Create a fresh React app and integrate the design system in minutes:

Then in src/main.tsx:

And in src/App.tsx:

That’s it — components, styles, and SVGs working in a standalone project with zero monorepo dependencies.

Reference Examples

The UI Ecosystem monorepo includes sandbox apps that demonstrate the full integration for each framework:

AppFrameworkWhat it tests
apps/sandbox/test-reactReact + ViteReact wrappers + Tailwind factory build
apps/sandbox/test-webPlain HTML + ViteStencil loader + native custom elements
apps/sandbox/test-angularAngularAngular standalone wrappers
apps/sandbox/test-react-nativeReact NativeDesign tokens via StyleSheet (no web components)