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

LayerWhat it isWhere it lives
TokensNamed values for colour, type, spacing, radii, shadows and breakpointspackages/assets/tokens, published as @ebrains/assets
StylesThe tokens as CSS variables and Tailwind classes: layout, type and colour utilitiestailwind.factory.js, and the prebuilt @ebrains/assets/styles/output.css
Components45+ web components (buttons, forms, tables, dialogs, charts, header, footer)packages/components, published as @ebrains/components
WrappersThe same components as React, Vue and Angular components@ebrains/react, @ebrains/vue, @ebrains/angular
GuidanceFoundations, patterns, templates and tutorialsdesign.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

GuideTypeUse it when
How to Integrate the Design SystemHow-toYou’re adding the design system to an app
Build an App with Vite and ReactTutorialYour app lives in its own repository and uses npm
Customise Your App’s Tailwind ConfigHow-toClasses are missing, or your app needs an extra theme value
Tailwind Factory APIReferenceYou need every option of the shared Tailwind configuration
Tailwind Class ReferenceReferenceYou’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