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:
| Package | What it provides |
|---|---|
@ebrains/components | 45+ Stencil web components (framework-agnostic) |
@ebrains/assets | CSS framework, design tokens, fonts |
@ebrains/svgs | Brand assets as inline SVG strings: the EBRAINS logo and the EU emblem (icons come from the Carbon set in eds-icon-wrapper) |
@ebrains/react | React wrappers for all components |
@ebrains/angular | Angular wrappers for all components |
@ebrains/vue | Vue 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:
| Export | Description |
|---|---|
logoPositive | EBRAINS logo for light backgrounds |
logoNegative | EBRAINS logo for dark backgrounds |
euSvg | EU 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
| Context | Convention | Example |
|---|---|---|
| React | PascalCase | <EdsButton> |
| Angular | kebab-case (in template) | <eds-button> |
| Vue | PascalCase or kebab-case | <EdsButton> or <eds-button> |
| Plain HTML | kebab-case | <eds-button> |
Prop Naming
| Context | Convention | Example |
|---|---|---|
| React | camelCase | pressableLabel="..." |
| Angular | camelCase (property binding) | [pressableLabel]="..." |
| Vue | kebab-case (in template) | :pressable-label="..." |
| Plain HTML | kebab-case | pressable-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
| Context | How |
|---|---|
| React | onEdsalert={handler} or onClick={handler} |
| Angular | (edsalert)="handler($event)" |
| Vue | @edsalert="handler" |
| Plain HTML | element.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:
| App | Framework | What it tests |
|---|---|---|
apps/sandbox/test-react | React + Vite | React wrappers + Tailwind factory build |
apps/sandbox/test-web | Plain HTML + Vite | Stencil loader + native custom elements |
apps/sandbox/test-angular | Angular | Angular standalone wrappers |
apps/sandbox/test-react-native | React Native | Design tokens via StyleSheet (no web components) |