Tutorial: Add the EBRAINS Design System to Your Application

In this hands-on tutorial, you’ll transform your basic React app into a polished EBRAINS application using the official design system. You’ll replace custom components with professional UI elements that match the EBRAINS brand.

What you’ll achieve: A styled application using EBRAINS design system components (buttons, cards, alerts, forms)

Time required: 30-40 minutes

Prerequisites:

Completed Build Your First Application tutorial
Running hello-ebrains app from that tutorial
OR any React application you want to style

About the EBRAINS Design System: A comprehensive UI component library built with Stencil.js Web Components. Works with React, Vue, Angular, or vanilla JavaScript. See design.ebrains.eu for full documentation.

Introduction: Why Use the Design System?

Benefits You’ll Get

Professional UI - Components designed by UX experts
Consistent branding - Matches all EBRAINS applications
Accessibility - WCAG 2.1 Level AA compliant
Time savings - No need to build from scratch
Automatic updates - Get new features and fixes
Built-in analytics - Matomo tracking integrated

What’s Included

The design system provides:

43+ UI components - Buttons, cards, forms, tables, modals, etc.
Design tokens - Colors, spacing, typography variables
CSS utilities - Tailwind-based helper classes
Icon library - EBRAINS SVG icons
Framework wrappers - React, Vue, Angular bindings

Part 1: Understand the Two Approaches (5 minutes)

You can use the design system in two ways:

Method 1: Inside the Monorepo (Recommended if you’re here)

When to use: Your app lives in ebrains-ui-ecosystem monorepo

Advantages:

Already installed - no npm install needed
Latest components - always in sync
Shared dependencies - smaller bundle sizes
Local development - see design system changes immediately

Method 2: External Project via npm

When to use: Your app is in a separate repository

Advantages:

Version control - lock to specific versions
Standard workflow - normal npm install
Any framework - React, Vue, Angular, vanilla JS

Part 2: Set Up the Design System (Monorepo Method) (10 minutes)

Let’s add the design system to your hello-ebrains app from the first tutorial.

Step 1: Verify Design System is Available

From the monorepo root, check that the design system packages exist:

You should see the design system packages. They’re already available in the monorepo!

Step 2: Import the CSS Framework and Configure Tailwind

For better integration and to use the full power of Tailwind utilities, set up a proper Tailwind configuration:

1. Create/Update your app’s styles.css

Open or create apps/sandbox/hello-ebrains/src/styles.css and add:

2. Import styles in main.tsx

Update apps/sandbox/hello-ebrains/src/main.tsx:

What this does:

Imports the design system CSS with all tokens (colors, typography, spacing)
Adds Tailwind directives for full utility class support (bg-primary, text-light, etc.)
Allows you to add app-specific custom styles

3. Create Tailwind Configuration (Important)

Create a tailwind.config.js file in your app root (apps/sandbox/hello-ebrains/tailwind.config.js):

What this does:

Uses the monorepo’s createTailwindConfig factory function
Automatically includes design system components and tokens
Scans your app’s source files for Tailwind classes
Allows app-specific theme customization in the extend object

Learn more: For advanced Tailwind configuration and customization options, see the Tailwind Factory API documentation.

Step 3: Verify It Works

Start your dev server if not already running:

Open http://localhost:4200 - your app should still work, but now has access to design system styles.

⚠️ Vite Bundler Issue: If you selected bundler=vite when generating your NX application and encounter a defineCustomElements import error, you need to add a resolve alias to your vite.config.ts:

This tells Vite where to find the components loader module in the monorepo structure.

Part 3: Use Your First Component (10 minutes)

Let’s replace a plain HTML element with a design system component.

Step 1: Import EdsButton

Open apps/sandbox/hello-ebrains/src/app/app.tsx and add the import:

Step 2: Replace HTML Button with EdsButton

Find any <button> or <a> tag and replace it with:

Step 3: See It in Action

Save the file. Your browser should update automatically. Click the button!

What you should see:

A styled EBRAINS button with the primary brand color
Hover effects
Proper spacing and typography
Alert when clicked

Step 4: Try Different Button Variants

The design system offers many options:

You can import and use design system components.

Part 4: Build with Multiple Components (15 minutes)

Let’s create a complete page using cards, alerts, and buttons.

Step 1: Import Multiple Components

Update your imports:

Step 2: Create a Dashboard Layout

Replace your App component with this complete example:

Step 3: View Your Dashboard

Save the file and check your browser. You should now have:

Professional header with EBRAINS styling
Info alert at the top
Three cards in a responsive grid
Properly styled buttons and links
Success alert at the bottom

Part 5: Use Design Tokens (5 minutes)

Design tokens are CSS variables for colors, spacing, and typography are all available on the EBRAINS Design System/Foundations

Using Tokens in Your Styles

Create a custom component with design tokens:

Use Tailwind classes (preferred):

Part 6: External Project Setup (Alternative Method) (10 minutes)

Skip this if you’re working in the monorepo. This is for developers with external projects.

Step 1: Install Packages

In your external React project:

For other frameworks:

Step 2: Import CSS in Your Entry File

In src/main.tsx (or main.js):

Step 3: Use Components

Same as monorepo - import and use:

Step 4: Framework-Specific Notes

Angular 18+ - Import in standalone components:

External projects can install and use the design system.

Problem: Components don’t have styles

Symptoms: Components appear but look unstyled

Solution: Import the predefined CSS framework

Make sure this is before any component imports.

What You’ve Learned

Excellent work! You can now:

Install the design system - Both monorepo and external methods
Import components - Use EdsButton, EdsCard, EdsAlert, etc.
Build professional UIs - Create dashboards and pages
Use design tokens - Apply consistent colors and spacing
Access 43+ components - Forms, tables, modals, and more
Follow EBRAINS branding - Match all EBRAINS applications

Key Concepts

Design system benefits:

Professional, accessible components
Consistent EBRAINS branding
Time-saving pre-built UI elements

Two installation methods:

Monorepo: Import from workspace packages
External: npm install framework-specific packages

Component usage:

Import from @ebrains/react (or Vue, Angular)
Use as JSX/HTML elements with props
Combine multiple components for complex UIs

Next Steps

1. Explore All Components

Browse the full component library:

EBRAINS Design System

Try:

Navigation - Header, sidebar, breadcrumbs
Forms - Input fields, dropdowns, switches
Data display - Tables, charts, timelines
Feedback - Toasts, alerts, progress bars

2. Build a Real Feature

Pick a feature to implement:

User profile page with cards and forms
Data dashboard with tables and charts
Settings page with form validation
Help center with accordions and tabs

3. Use Advanced Features

Analytics - Built-in Matomo event tracking
Accessibility - Screen reader support, keyboard navigation

4. Integrate with EBRAINS APIs

Combine design system with EBRAINS services:

Display Knowledge Graph data in tables
Create forms that submit to EBRAINS Forms API
Build authentication UI with IAM integration

Additional Resources

Official Documentation

EBRAINS Design System - Full component documentation
Storybook Examples - Interactive component playground
Design Tokens - All available tokens