Tutorial: Configure Tailwind CSS with EBRAINS Design Tokens

In this hands-on tutorial, you’ll learn to use Tailwind CSS with EBRAINS design tokens to build beautiful, consistent UIs using utility classes. You’ll replace custom CSS with pre-built utilities that match the EBRAINS brand.

What you’ll achieve: A Tailwind-powered app using EBRAINS colors, typography, and spacing tokens

Time required: 20-30 minutes

Prerequisites:

What is Tailwind CSS? A utility-first CSS framework that lets you build UIs by composing small, single-purpose classes directly in your HTML/JSX. Instead of writing custom CSS, you use classes like bg-blue-500 and p-4.

Introduction: Why Tailwind + EBRAINS Design Tokens?

The Power of Utility-First CSS

Traditional approach:

Tailwind + EBRAINS approach:

Benefits You’ll Experience

  • EBRAINS brand built-in - Colors, fonts, spacing pre-configured
  • No CSS files - Style directly in your components
  • IntelliSense support - Auto-complete for classes
  • Consistent spacing - Use the same spacing scale everywhere
  • Responsive design - Built-in breakpoints (md:, lg:, xl:)
  • Small bundles - Only used classes included in production
  • Type-safe tokens - Design system values available as utilities

What’s Included

The EBRAINS Tailwind setup provides:

  • Color tokens - bg-primary, text-inverse, border-subtle
  • Typography tokens - f-heading-01, f-body-01
  • Spacing tokens - p-24, m-16, gap-8 (EBRAINS scale)
  • Grid utilities - grid-cols-12, grid-col-span-6
  • Custom plugins - A17 Tailwind plugins for advanced layouts
  • Design system integration - Works seamlessly with @ebrains/react components

Part 1: Set Up Tailwind in a Monorepo App (10 minutes)

Let’s configure Tailwind for your hello-ebrains app using the EBRAINS factory.

Step 1: Create Your App’s Tailwind Config

Navigate to your app directory and create tailwind.config.js:

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

What this does:

  • Imports the factory from the monorepo root
  • Configures content paths so Tailwind knows where to find classes
  • Inherits all EBRAINS design tokens automatically
  • Allows optional custom extensions

Step 2: Import Tailwind Styles

Open apps/sandbox/hello-ebrains/src/main.tsx and add the CSS import at the very top:

Important: This import must come before any component imports to ensure proper CSS cascade.

Step 3: Verify Setup

Start your development server:

Open http://localhost:4200 and check the browser console. You should see:

  • ✅ No CSS errors
  • ✅ Hello EBRAINS Tailwind Config logged (from the factory)

Checkpoint: Tailwind is configured and ready to use!

Part 2: Use EBRAINS Color Tokens (5 minutes)

Let’s replace custom colors with EBRAINS design tokens.

Step 1: Try Background Colors

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

Save and watch your browser update! You should see three sections with official EBRAINS colors.

Step 2: Explore Available Color Classes

Background colors:

  • bg-primary - EBRAINS teal (#00A595)
  • bg-secondary - EBRAINS navy blue
  • bg-dark - Dark background
  • bg-light - Light background
  • bg-inverse - Inverse/white background
  • bg-subtle - Subtle/muted background

Text colors:

  • text-primary - Primary text color
  • text-inverse - Inverse text (white on dark)
  • text-light - Light/muted text
  • text-dark - Dark text

Border colors:

  • border-primary - Primary border color
  • border-subtle - Subtle border
  • border-dark - Dark border

See the complete list in the Tailwind Reference

Part 3: Use EBRAINS Typography Tokens (5 minutes)

EBRAINS provides pre-configured typography classes that match the design system.

Step 1: Try Typography Typesets

Update your app with typography classes:

Step 2: Understanding Typography Classes

Heading classes:

  • f-heading-01 - 48px, bold (page titles)
  • f-heading-02 - 36px, bold (section titles)
  • f-heading-03 - 28px, semibold (subsections)
  • f-heading-04 - 24px, semibold
  • f-heading-05 - 20px, semibold

Body text classes:

  • f-body-01 - 16px, regular (default body text)
  • f-body-02 - 14px, regular (secondary text)

Font families:

  • font-sans - Inter (EBRAINS default)
  • font-mono - JetBrains Mono (code)

Checkpoint: You’re using official EBRAINS typography!

Part 4: Use EBRAINS Spacing Tokens (5 minutes)

EBRAINS uses a custom spacing scale aligned with the design system.

Step 1: Try Spacing Classes

Step 2: Understanding EBRAINS Spacing Scale

EBRAINS spacing uses actual pixel values (not Tailwind’s default rem-based scale):

  • p-8 → 8px padding
  • p-16 → 16px padding
  • p-24 → 24px padding
  • p-32 → 32px padding
  • p-48 → 48px padding
  • p-64 → 64px padding

All spacing utilities work:

  • p-* - Padding (all sides)
  • px-* - Horizontal padding
  • py-* - Vertical padding
  • pt-*, pr-*, pb-*, pl-* - Individual sides
  • m-* - Margin (same values)
  • gap-* - Grid/flex gap (same values)

Part 5: Build a Complete Layout (10 minutes)

Let’s combine everything to build a real page.

Step 1: Create a Dashboard Layout

Step 2: Add Responsive Behavior

Notice the responsive classes:

  • grid-cols-1 - 1 column on mobile
  • md:grid-cols-2 - 2 columns on medium screens (768px+)
  • lg:grid-cols-3 - 3 columns on large screens (1024px+)

Try resizing your browser! The layout adapts automatically.

Step 3: Explore Interactive States

We’re using:

  • hover:shadow-lg - Larger shadow on hover
  • hover:opacity-90 - Slight transparency on hover
  • transition-shadow - Smooth shadow transition
  • transition-opacity - Smooth opacity transition

Checkpoint: You’ve built a complete, responsive page with Tailwind!

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

Skip this if you’re working in the monorepo. This section is for developers with apps in separate repositories.

Step 1: Install Dependencies

In your external React project:

Step 2: Create Tailwind Config

For external projects, you need to manually import and configure tokens.

Create tailwind.config.js in your project root:

Step 3: Create PostCSS Config

Create postcss.config.js:

Step 4: Import CSS in Your Entry File

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

Step 5: Use Tailwind Classes

Now you can use all EBRAINS Tailwind classes just like in the monorepo:

  • External projects can now use EBRAINS Tailwind utilities!

What You’ve Learned

You can now:

  • Configure Tailwind - Using the EBRAINS factory for monorepo apps
  • Use color tokens - bg-primary, text-inverse, border-subtle
  • Use typography tokens - f-heading-01, f-body-01
  • Use spacing tokens - p-24, m-16, gap-8
  • Build responsive layouts - grid-cols-1 md:grid-cols-2 lg:grid-cols-3
  • Add interactivity - hover:, transition-* utilities
  • Set up external projects - Manual token configuration
  • Enable IntelliSense - Auto-complete for all classes

Next Steps

1. Explore Advanced Tailwind Features

Try more powerful utilities:

  • Grid layouts - grid grid-cols-12, grid-col-span-6
  • Flexbox - flex justify-between items-center

See the Tailwind Reference for complete class list.

2. Combine with Design System Components

Mix Tailwind utilities with @ebrains/react components:

Additional Resources

Documentation

Related Tutorials

Community

You’re now ready to build beautiful UIs with Tailwind and EBRAINS design tokens!

Edit this page on GitLab ↗