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

OptionTypeDefaultDescription
appNamestring'unknown'Printed when Tailwind loads the config (<appName> Tailwind Config), so you can tell which app’s config ran.
contentPathsstring[][]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.
extendobject{}Merged into theme.extend, after the factory’s own extensions. Same-named keys replace the factory’s.
safelistarray[]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 typeset
  • bg-*, text-* and border-* for every semantic colour, and the bg-* gradients
  • rounded-*, aspect-* and shadow-* for every token
  • h-* for the system spacing tokens
  • grid-cols-1 to grid-cols-12 and grid-col-start-1 to grid-col-start-12
  • grid-col-span-2/3/4/6/8/10/12/full
  • line-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 keySourceGives you
screensstructure.breakpointsmd: 750px, lg: 900px, xl: 1024px, xxl: 1280px, xxxl: 2200px
mainColWidths, innerGutters, outerGutters, columnCountstructurecontainer and the 12-column grid-layout
typesets, fontFamiliestypographyf-heading-01 … f-label
spacing, spacingGroupsspacingthe pixel scale (p-16) and section spacing (pt-space-01)
colors, backgroundColor, textColor, borderColor, divideColor, textDecorationColor, outlineColor, ringColorcolorssemantic colour classes (bg-strongest, text-light, border-softer)

Theme extensions

KeyValues
fontFamilysans: IBM Plex Sans, mono: IBM Plex Mono
borderRadius, aspectRatio, boxShadow, dropShadowthe radius, ratio and shadow tokens
maxWidthmax-w-default (1440px), max-w-reader and max-w-sidebar (1224px), max-w-xxxl (2200px), max-w-120, max-w-192
minHeightthe spacing scale, plus 156, 400, 600, 800
heighth-screen uses --vh, for mobile browsers
spacingsafe-top/bottom/left/right (safe-area insets), gutter, outer-gutter
gridColumnspan-2 … span-12, span-full
zIndex1–10, focus (99), banner (9999), on-top (99999)
ariaaria-current-page: variant
transitionTimingFunctionthe easing tokens
borderWidth, outlineWidth3

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 to extend, so every app gets them.
  • The prebuilt stylesheet. @ebrains/assets/styles/output.css is 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.css in styles instead; see Build Inside the Monorepo.

Related