Tutorial: Add the EBRAINS Design System to Your App

In this tutorial you connect the hello-ebrains app from Build Your First Application to the EBRAINS Design System: its stylesheet, its Tailwind configuration and its components. By the end, your page uses EBRAINS type, colour, layout and components, with no CSS of your own.

Time to complete: 30 minutes

What you’ll learn: what the design system gives an app in the monorepo, how to wire it into a Vite app, and how to use your first components.

What You’ll Build

By the end of this tutorial, you’ll have:

  • The design system’s stylesheet and Tailwind configuration in your app
  • The components registered and ready to use from React
  • A page with a heading, buttons, an alert and a row of cards, laid out with the design system’s classes

The finished page: heading, two buttons, a green alert and three cards

Prerequisites

Before starting, make sure you have:

  • Completed Build Your First Application: apps/sandbox/hello-ebrains exists and nx serve hello-ebrains works
  • Basic React and TypeScript knowledge

What the design system gives you

Inside the monorepo you use the design system from source, so you always get the latest version and nothing needs installing:

PackageWhat it isHow you use it
@ebrains/componentsThe components, as web components (<eds-button>)Registered once at start-up
@ebrains/reactReact wrappers (<EdsButton>)Imported in your components
@ebrains/assetsTokens and the stylesheetImported in styles.css
tailwind.factory.jsThe shared Tailwind configurationCalled from your tailwind.config.js

Vue and Angular apps use @ebrains/vue and @ebrains/angular the same way; the Build Inside the Monorepo guide covers both.

Step 1: Build the design system with your app

Your app uses the built components in dist/packages/components. Make Nx build them, and the stylesheet, before it serves or builds your app. Replace apps/sandbox/hello-ebrains/project.json:

What you just did: Nx infers serve, build, test and lint from vite.config.ts. You only added a dependency, so nx serve hello-ebrains now builds components and assets first. Nx caches them, so only the first run takes a minute.

Step 2: Add the styles and the Tailwind configuration

Import the design system’s stylesheet

Replace apps/sandbox/hello-ebrains/src/styles.css (the generated index.html already links it):

Create the Tailwind configuration

Create apps/sandbox/hello-ebrains/tailwind.config.js:

Point Vite at both

In apps/sandbox/hello-ebrains/vite.config.ts, add the imports and the resolve and css blocks:

What you just did:

  • main.css brings in the tokens (as CSS variables) and the base styles.
  • The Tailwind factory gives Tailwind the EBRAINS theme. contentPaths tells it which files to scan for class names, relative to the repository root.
  • The resolve alias points the components’ loader at the built package.

Step 3: Register the components before rendering

The components are web components: the browser has to learn them before React renders. Replace apps/sandbox/hello-ebrains/src/main.tsx:

What you just did: rendered only once every <eds-*> element is defined. React can then pass arrays and objects (header links, form fields, table rows) to the components as properties. Rendering earlier turns them into the text "[object Object]".

Step 4: Use your first components

Replace apps/sandbox/hello-ebrains/src/app/app.tsx:

What you just did:

  • Components from @ebrains/react: props are camelCase (titleSize), events are on + the event name (onClick), and booleans are plain JSX booleans (pill).
  • Layout classes, the design system’s layout primitives: container max-w-default mx-auto centres the content with the EBRAINS gutters, flex flex-col gap-* stacks it, and grid grid-cols-1 md:grid-cols-3 lays out the cards.
  • Type and colour classes: f-heading-02 and f-body-01 set the whole type style; text-light is the secondary text colour.
  • as const keeps icon as the literal 'template' rather than string, which is what the component’s icon type accepts. TypeScript catches a misspelled icon name.

Verify It Works

Expected result:

  • http://localhost:4200 shows the page above: content centred with margins, three cards side by side on a wide window and stacked on a narrow one
  • Clicking Get started logs clicked in the browser console, with no errors
  • typecheck and test succeed

What You Learned

In this tutorial, you:

  • Made Nx build the design system before your app
  • Added the stylesheet, the Tailwind factory and the loader alias to a Vite app
  • Registered the components before rendering, so data reaches them as properties
  • Used components, layout classes and type classes together

Next Steps

Troubleshooting

Problem: Rollup failed to resolve import "@ebrains/components/loader". Solution: the components aren’t built, or the alias is missing. Check the resolve.alias in vite.config.ts, and that dist/packages/components/loader exists (nx build components).

Problem: the components show, but there’s no spacing, centring or grid. Solution: Tailwind isn’t scanning your files. Check contentPaths in tailwind.config.js, and the css.postcss block in vite.config.ts.

Problem: components render empty, or the console shows "[object Object]" is not valid JSON. Solution: React rendered before the components registered. Render inside defineCustomElements().then(...) (step 3).

Problem: TypeScript: Property 'then' does not exist on type 'void'. Solution: your components build predates the Promise<void> type (3.2.0 and earlier). Rebuild with nx build components.

Problem: TypeScript: Type 'string' is not assignable to type '"code" | "menu" | ...'. Solution: add as const to the data. If it still fails, the icon doesn’t exist: the names are the keys of ICONS in packages/components/src/utils/icons.ts (your editor also autocompletes them).

Problem: Warning: Failed to load the ES module: packages/assets/frontend.config.js. Solution: harmless; the configuration still loads.

Additional Resources