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
- Tailwind Factory API: every option and what the configuration contains
- Tailwind Class Reference
- Layout Primitives on the design system site