How to Customise Your App’s Tailwind Config

Every app in the UI Ecosystem gets its Tailwind configuration from the Tailwind factory, so it shares the EBRAINS colours, type, spacing and grid. This guide covers the changes an app makes on top: where Tailwind looks for classes, extra theme values, and classes it must always generate.

Before you start: your app has a tailwind.config.js that calls createTailwindConfig(). If not, follow Add the Design System to Your App first.

Make Tailwind find your classes

Tailwind only generates classes it finds in the files listed in contentPaths. List every kind of file that contains class names, relative to the repository root:

Check it: if a class has no effect in the browser, search for it in the generated CSS (DevTools › Sources, or the built file in dist/). If it isn’t there, its file isn’t in contentPaths.

Class names must appear whole in the source. Tailwind can’t see classes you build from pieces:

Always generate classes Tailwind can’t see

Classes that only exist at runtime (from a CMS, an API, or a string built in code) go in safelist:

The factory already safelists the colour, type, radius, shadow and ratio classes and the grid spans; see Always available. Keep your list short: every pattern adds CSS to every page.

Add a value for your app only

Use extend for values that only your app needs:

This gives you max-w-prose and min-h-480.

extend replaces factory keys with the same name. extend: { maxWidth: { prose: '68ch' } } removes max-w-default and the other factory widths. To add to them, spread the factory’s value:

Connect the config to your build

Vite apps point PostCSS at the app’s config in vite.config.ts:

Angular apps don’t run the factory: Angular’s builder compiles each CSS file on its own and can’t build the design system’s source stylesheet. List the prebuilt dist/packages/assets/styles/output.css in project.json styles instead.

Troubleshooting

Problem: layout classes (container, grid-layout, gap-*) do nothing, but f-* and colour classes work. Solution: Tailwind isn’t scanning your files: the safelisted classes still work, everything else is missing. Check contentPaths, and that vite.config.ts passes your tailwind.config.js to PostCSS.

Problem: Warning: Failed to load the ES module: packages/assets/frontend.config.js. Solution: harmless. Node warns before falling back to another loader; the config still loads.

Problem: a class from the docs doesn’t exist. Solution: check the Tailwind Class Reference, which is generated from the tokens. Tailwind’s default spacing (p-14, mt-2.5, gap-0.5) isn’t on the EBRAINS scale, where the number is pixels: use p-16 or mt-8.

Related