EBRAINS Design System
The EBRAINS Design System is the shared visual language and toolkit for EBRAINS web interfaces: the brand’s colours, type and spacing as design tokens, a library of accessible components, and guidance on combining them. Apps that use it look and behave like one family, meet the accessibility baseline, and pick up brand and component updates by upgrading a package instead of redesigning.
This section explains how the design system is built and used at EBRAINS. For the components themselves, with live examples, go to design.ebrains.eu.
What it’s made of
| Layer | What it is | Where it lives |
|---|---|---|
| Tokens | Named values for colour, type, spacing, radii, shadows and breakpoints | packages/assets/tokens, published as @ebrains/assets |
| Styles | The tokens as CSS variables and Tailwind classes: layout, type and colour utilities | tailwind.factory.js, and the prebuilt @ebrains/assets/styles/output.css |
| Components | 45+ web components (buttons, forms, tables, dialogs, charts, header, footer) | packages/components, published as @ebrains/components |
| Wrappers | The same components as React, Vue and Angular components | @ebrains/react, @ebrains/vue, @ebrains/angular |
| Guidance | Foundations, patterns, templates and tutorials | design.ebrains.eu and Storybook |
The components are Stencil web components, so one implementation works in every framework and in plain HTML. The wrappers only add each framework’s conventions (props, events, refs) on top.
All of it lives in the UI Ecosystem monorepo, next to the apps that use it.
Where to start
Not sure which? How to Integrate the Design System compares the setups.
Use it
| Guide | Type | Use it when |
|---|---|---|
| How to Integrate the Design System | How-to | You’re adding the design system to an app |
| Build an App with Vite and React | Tutorial | Your app lives in its own repository and uses npm |
| Customise Your App’s Tailwind Config | How-to | Classes are missing, or your app needs an extra theme value |
| Tailwind Factory API | Reference | You need every option of the shared Tailwind configuration |
| Tailwind Class Reference | Reference | You’re looking for a class (generated from the tokens) |
On the design system site:
- Foundations: colour, typography, spacing, and the layout primitives for building pages
- Components: every component with examples, props, events and accessibility notes
- Patterns: proven answers to common problems: navigation, forms, notifications, empty and loading states
- Templates: whole page layouts
- Applications: building apps, from a first page to standalone and monorepo setups
For contributors
The design system grows from the apps that use it. When an app needs something the design system doesn’t have, add it to the design system instead of building it in the app.
Check and propose
Look for an existing component, variant or pattern first, in Storybook and on design.ebrains.eu. If nothing fits, open an issue describing the problem it solves and where it will be used.
Build it
Follow How to Develop Stencil Components: naming, structure, tests, stories and the acceptance criteria. New colours, sizes or fonts go into the tokens in packages/assets/tokens, not into one component.
Document it
The component’s readme.md is generated from its code and becomes its page on design.ebrains.eu. Add its sidebar name and one-line description to apps/live/eds-docs/data/components.yaml, and a usage example to the page if it needs one.
Record and release it
Add an entry to packages/components/CHANGELOG.md (how to keep a changelog), and version it following the Tagging Strategy.
Resources
- Documentation: design.ebrains.eu
- Playground: storybook.design.ebrains.eu
- Packages:
@ebrainson npm - Source: ebrains-ui-ecosystem on GitLab
- Release notes: design.ebrains.eu/appendices/release-notes