How to Integrate the Design System

This guide helps you choose how to bring the EBRAINS Design System into an app, and shows the essentials of each setup. Each setup links to a complete, tested guide.

Choose your setup

Your appSetupFull guide
Lives in the UI Ecosystem monorepo, or you’re starting one thereInside the monorepo: use the design system from source, with the shared Tailwind configurationAdd the Design System to Your App (tutorial), Build Inside the Monorepo (Vue, React, Angular)
Has its own repository and a bundler (Vite, webpack, Angular CLI)From npm: install the packages and import the prebuilt stylesheetBuild an App with Vite and React (tutorial, React), Start Your Own App (Vue, plain JavaScript)
Is a static page, a CMS template or a server-rendered siteFrom a CDN: two tags in the page <head>Integration Guide

Recommended: inside the monorepo for new EBRAINS apps, since you get design-system changes as soon as they merge and share the build and release tooling. Use npm when the app must stay in its own repository.

Inside the monorepo

Nothing to install. In a Vite app:

  1. Build order: in project.json, make serve and build depend on { "target": "build", "projects": ["components", "assets"] }.
  2. Styles: @import '../../../../packages/assets/styles/main.css'; in the app’s styles.css, plus a tailwind.config.js that calls createTailwindConfig().
  3. Vite: alias @ebrains/components/loader to dist/packages/components/loader, and pass the Tailwind config to PostCSS.
  4. Register, then render:

Angular differs: list dist/packages/assets/styles/output.css in project.json styles, and import the standalone components from @ebrains/angular. They register themselves.

From npm

Then use the tags (<eds-header>, <eds-button>) in your markup. Set objects and arrays as properties from JavaScript (header.links = [...]).

FrameworkUse
Plain JavaScript, VueThe web components directly, as above. In Vue, mount the app after defineCustomElements() resolves.
Reactnpm install @ebrains/react@^3.3 @ebrains/assets@~0.9.1, then import { EdsHeader } from '@ebrains/react'. No registration step: see Build an App with Vite and React
Angularnpm install @ebrains/angular@^3, then import the standalone components into your component’s imports

From a CDN

Pin the major version (@3, @0.9), so you get fixes but never a breaking change.

Check it works

  • The components render with EBRAINS styles, and the browser console shows no errors.
  • Data passed to components (header links, table rows) shows up. If it reads [object Object] or stays empty, the app rendered before the components registered.
  • Layout classes (container, grid-layout, gap-16) take effect. If not, inside the monorepo, check the Tailwind contentPaths.

Related