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 app | Setup | Full guide |
|---|---|---|
| Lives in the UI Ecosystem monorepo, or you’re starting one there | Inside the monorepo: use the design system from source, with the shared Tailwind configuration | Add 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 stylesheet | Build 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 site | From 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:
- Build order: in
project.json, makeserveandbuilddepend on{ "target": "build", "projects": ["components", "assets"] }. - Styles:
@import '../../../../packages/assets/styles/main.css';in the app’sstyles.css, plus atailwind.config.jsthat callscreateTailwindConfig(). - Vite: alias
@ebrains/components/loadertodist/packages/components/loader, and pass the Tailwind config to PostCSS. - 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 = [...]).
| Framework | Use |
|---|---|
| Plain JavaScript, Vue | The web components directly, as above. In Vue, mount the app after defineCustomElements() resolves. |
| React | npm 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 |
| Angular | npm 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 TailwindcontentPaths.
Related
- Customise Your App’s Tailwind Config
- Components: props, events and examples for each component
- Storybook: try every component and variant