Tailwind Factory API
createTailwindConfig() in tailwind.factory.js, at the root of the UI Ecosystem monorepo, builds a complete Tailwind 3 configuration from the EBRAINS design tokens. Every app in the monorepo uses it, so they all share the same colours, type, spacing and grid.
For a step-by-step guide, see Customise Your App’s Tailwind Config. For the classes it generates, see the Tailwind Class Reference.
Signature
Returns a Tailwind configuration object. Use it as the whole of your app’s tailwind.config.js.
Options
| Option | Type | Default | Description |
|---|---|---|---|
appName | string | 'unknown' | Printed when Tailwind loads the config (<appName> Tailwind Config), so you can tell which app’s config ran. |
contentPaths | string[] | [] | Files Tailwind scans for class names. Relative paths are resolved from the repository root, whatever folder the build runs from; absolute paths are used as given. packages/components/**/*.{html,ts,tsx} is always included. |
extend | object | {} | Merged into theme.extend, after the factory’s own extensions. Same-named keys replace the factory’s. |
safelist | array | [] | Extra classes or patterns to always generate, in Tailwind’s safelist format. Added after the factory’s safelist. |
What the configuration contains
Content
packages/components/**/*.{html,ts,tsx} plus your contentPaths.
Safelist
Always generated, even if no scanned file uses them:
f-*for every typesetbg-*,text-*andborder-*for every semantic colour, and thebg-*gradientsrounded-*,aspect-*andshadow-*for every tokenh-*for the system spacing tokensgrid-cols-1togrid-cols-12andgrid-col-start-1togrid-col-start-12grid-col-span-2/3/4/6/8/10/12/fullline-clamp-1,line-clamp-3,line-clamp-4- your
safelist
Core plugins
preflight on; Tailwind’s container off. The container class comes from the EBRAINS Container plugin, with the EBRAINS gutters.
Plugins
From @area17/a17-tailwind-plugins: Setup, ColorTokens, Components, Container, DevTools, FullBleedScroller, GridGap, GridLayout, GridLine, InteractionMediaQueries, Keyline, Layout, PseudoElements, RatioBox, Scrollbar, Spacing, Typography, Underline. Plus @tailwindcss/container-queries.
Theme
Built from packages/assets/tokens (via packages/assets/frontend.config.js):
| Theme key | Source | Gives you |
|---|---|---|
screens | structure.breakpoints | md: 750px, lg: 900px, xl: 1024px, xxl: 1280px, xxxl: 2200px |
mainColWidths, innerGutters, outerGutters, columnCount | structure | container and the 12-column grid-layout |
typesets, fontFamilies | typography | f-heading-01 … f-label |
spacing, spacingGroups | spacing | the pixel scale (p-16) and section spacing (pt-space-01) |
colors, backgroundColor, textColor, borderColor, divideColor, textDecorationColor, outlineColor, ringColor | colors | semantic colour classes (bg-strongest, text-light, border-softer) |
Theme extensions
| Key | Values |
|---|---|
fontFamily | sans: IBM Plex Sans, mono: IBM Plex Mono |
borderRadius, aspectRatio, boxShadow, dropShadow | the radius, ratio and shadow tokens |
maxWidth | max-w-default (1440px), max-w-reader and max-w-sidebar (1224px), max-w-xxxl (2200px), max-w-120, max-w-192 |
minHeight | the spacing scale, plus 156, 400, 600, 800 |
height | h-screen uses --vh, for mobile browsers |
spacing | safe-top/bottom/left/right (safe-area insets), gutter, outer-gutter |
gridColumn | span-2 … span-12, span-full |
zIndex | 1–10, focus (99), banner (9999), on-top (99999) |
aria | aria-current-page: variant |
transitionTimingFunction | the easing tokens |
borderWidth, outlineWidth | 3 |
Examples
Minimal
Vue app with an extension and a safelist
Notes
- Tokens, not values. Add colours, sizes or fonts to
packages/assets/tokens(a design-system change, reviewed with the design team) rather than toextend, so every app gets them. - The prebuilt stylesheet.
@ebrains/assets/styles/output.cssis this configuration compiled once. Apps outside the monorepo use it instead of the factory. - Angular builds Tailwind per CSS file and can’t compile the multi-file source stylesheet. Angular apps in the monorepo list
dist/packages/assets/styles/output.cssinstylesinstead; see Build Inside the Monorepo.
Related
- Customise Your App’s Tailwind Config
- Tailwind Class Reference
- Layout Primitives on the design system site