Migrating to the EBRAINS Tailwind Framework

This guide walks you through integrating the EBRAINS design system’s Tailwind CSS framework into an existing application. Whether you’re starting from scratch or migrating from custom styles, this process gives you access to all EBRAINS utility classes generated from the shared design tokens.

Prerequisites

Your app must live inside the EBRAINS UI Ecosystem monorepo (or have access to the tailwind.factory.js and packages/assets/tokens/ files).

Step 1: Create a Tailwind Config

Create a tailwind.config.js in your app root that uses the shared factory:

The factory reads all design tokens from packages/assets/tokens/ (colors, typography, spacing, shadows, radii, etc.) and generates the full EBRAINS Tailwind configuration including all Area17 plugins.

Important: Use absolute paths via path.join(root, ...) for content paths. Relative paths may not resolve correctly depending on how your build tool invokes Tailwind.

Step 2: Create a PostCSS Config

Create a postcss.config.js in your app root:

For production builds, you can add CSS minification:

Step 3: Set Up Your CSS Entry Point

Replace or update your main CSS file with Tailwind directives:

This generates the full EBRAINS utility framework at build time, including all design token-based classes.

Step 4: Build Tool Configuration

Vite: Auto-discovers postcss.config.js — no extra configuration needed in vite.config.ts. Your CSS entry point is typically already linked in index.html:

Webpack: Add postcss-loader to your CSS rule and it will pick up postcss.config.js automatically.

Other bundlers: Configure PostCSS according to your bundler’s documentation, pointing it to your postcss.config.js.

Step 5: Start Replacing Inline Styles

Now you can replace inline styles and custom CSS with EBRAINS utility classes.

Colors

Typography

Available type classes: f-heading-01 through f-heading-06, f-body-01 through f-body-03, f-ui-01 through f-ui-05, f-code, f-caption, f-display-01, f-display-02.

Spacing

Available spacing values: 0, 2, 4, 8, 12, 16, 24, 32, 40, 48, 64, 96, 128, 160, 196. Use with p-, m-, px-, py-, mt-, mb-, ml-, mr-, gap-.

Layout

Grid

Border Radius

Values: rounded-xxs (2px), rounded-xs (4px), rounded-sm (8px), rounded-md (12px), rounded-lg (16px), rounded-full (pill).

Shadows

Values: shadow-sm, shadow-md, shadow-hover, shadow-accent, shadow-elevated, shadow-overlay.

Dark Backgrounds

Step 6: Responsive Classes

All utility classes support responsive prefixes based on the EBRAINS breakpoints:

What You Get

The factory generates classes from these token files:

Example: Full Migration

See the test React app at apps/sandbox/test-react/ for a complete working example with:

• tailwind.config.js — factory-based config
• postcss.config.js — PostCSS pipeline
• styles.css — Tailwind directives
• app.tsx — all components styled with utility classes

Alternative: Pre-built CSS

If you don’t need Tailwind’s build pipeline (e.g. for a static site or quick prototype), you can import the pre-built CSS directly:

This gives you all the same utility classes without the build setup. The trade-off is that unused classes aren’t tree-shaken, so the file is larger (~252KB vs a purged build).

For more details on what’s included, see the CSS Framework page.