@keboola/tailwind-config 0.8.0 → 1.0.0

package/README.md

@@ -1,9 +1,9 @@
 # @keboola/tailwind-config
 
-Shared Tailwind CSS v3 configuration for the Keboola UI platform —
-the same semantic color palette, plugins, and `tw-` class prefix that
+Shared Tailwind CSS design tokens for the Keboola UI platform — the same
+semantic color palette, type scale, radii and shadows that
 [`@keboola/design`](https://github.com/keboola/ui/tree/main/packages/design)
-is built on.
+is built on, shaped as a Tailwind `theme` object.
 
 Use this when you want your Tailwind-styled app to inherit the platform's
 visual primitives — most relevant for audiences B (Keboola-branded external
@@ -13,57 +13,63 @@ branded) typically supplies its own tokens; this package is optional then.
 ## Install
 
 ```bash
-npm install -D @keboola/tailwind-config tailwindcss@^3
+npm install -D @keboola/tailwind-config tailwindcss@^4
 # or
-pnpm add -D @keboola/tailwind-config tailwindcss@^3
+pnpm add -D @keboola/tailwind-config tailwindcss@^4
 ```
 
+Tailwind v3 is no longer supported — stay on `@keboola/tailwind-config@0.9.x`
+if you need it.
+
 ## Use
 
-Extend or reuse the config from your own `tailwind.config.{js,ts}`:
+The package exports **tokens only**: `{ theme }`. Everything a v4 build owns in
+CSS — the class prefix, the `@import`ed layers, preflight, plugins — belongs in
+your stylesheet, not in this object.
+
+Load it through v4's `@config` bridge from your own `tailwind.config.{js,ts}`:
 
 ```js
 import keboolaConfig from '@keboola/tailwind-config';
 
-/** @type {import('tailwindcss').Config} */
 export default {
-  ...keboolaConfig,
-  content: ['./src/**/*.{ts,tsx,mdx}'],
+  theme: keboolaConfig.theme,
+  plugins: [
+    /* your own plugins */
+  ],
 };
 ```
 
-### Class prefix (`tw-`)
-
-The default config prefixes every utility with `tw-` (`tw-flex`, `tw-bg-background`, …). `@keboola/design` components ship with those `tw-`-prefixed class names baked into their compiled JS, and those classes only render if a stylesheet the app loads actually **defines** them. How you load that stylesheet decides whether you can drop the prefix:
-
-1. **Build-from-source** (the monorepo / `apps/boilerplate` pattern) — the app imports the source stylesheet `@keboola/design/styles` and runs its **own** Tailwind `@tailwind utilities` pass over design's `dist/` plus its own markup. That pass emits the components' classes _using this config's prefix_, so it only produces `tw-*` when the prefix is `tw-`. **If you flip this setup to `prefix: ''`, design components render UNSTYLED** — your build emits `flex`, never `tw-flex`, so the `tw-flex` baked into the components matches nothing. **Keep `tw-` for build-from-source setups.**
-
-2. **Precompiled CSS** — the app imports `@keboola/design/styles/compiled` (the shipped `dist/styles.css`, which already contains every `tw-*` utility the components use, prebuilt). Design components are then styled by that stylesheet regardless of your app's own Tailwind prefix, so `createKeboolaConfig({ prefix: '' })` is safe **for your own markup**: `tw-flex` (design's) and `flex` (yours) live in the same cascade without colliding.
-
-Prefix-less recipe (consume design precompiled, author your own utilities unprefixed):
-
 ```css
-@import '@keboola/design/styles/compiled'; /* design components, pre-styled with tw-* */
-@tailwind base;
-@tailwind components;
-@tailwind utilities; /* your own unprefixed utilities */
+/* styles.css */
+@import 'tailwindcss/theme.css' layer(theme) prefix(tw);
+@import 'tailwindcss/utilities.css' layer(utilities) prefix(tw);
+@config './tailwind.config.js';
 ```
 
-**Bottom line: prefix-less is safe only when you consume design via `/styles/compiled`, not when you build design's utilities from source.**
+### Class prefix (`tw-` in v3, `tw:` in v4)
 
-Opt out of the prefix (or set a custom one) with the `createKeboolaConfig` factory:
+`@keboola/design` components ship with prefixed class names baked into their
+compiled JS, and those classes only render if a stylesheet the app loads
+actually **defines** them. In v4 the prefix is declared in CSS
+(`prefix(tw)` on the `@import`, producing `tw:flex`), not in this config — so
+whether you can drop it depends on how you load design's stylesheet:
 
-```js
-import { createKeboolaConfig } from '@keboola/tailwind-config';
+1. **Build-from-source** (the monorepo / `apps/boilerplate` pattern) — the app
+   imports the source stylesheet `@keboola/design/styles` and runs its **own**
+   Tailwind pass over design's `dist/` plus its own markup. That pass emits the
+   components' classes using **your** prefix, so dropping `prefix(tw)` renders
+   design components UNSTYLED. **Keep the prefix for build-from-source setups.**
 
-/** @type {import('tailwindcss').Config} */
-export default {
-  ...createKeboolaConfig({ prefix: '' }), // unprefixed: `flex`, not `tw-flex`
-  content: ['./src/**/*.{ts,tsx,mdx}'],
-};
-```
+2. **Precompiled CSS** — the app imports `@keboola/design/styles/compiled` (the
+   shipped `dist/styles.css`, which already contains every prefixed utility the
+   components use, prebuilt). Design components are then styled by that
+   stylesheet regardless of your own prefix, so authoring your utilities
+   unprefixed is safe: design's classes and yours live in the same cascade
+   without colliding.
 
-Pass any string to `prefix` for a custom prefix (e.g. `createKeboolaConfig({ prefix: 'kbc-' })`). The default export is `createKeboolaConfig()` (i.e. `prefix: 'tw-'`), so existing `import keboolaConfig from '@keboola/tailwind-config'` consumers are unaffected.
+**Bottom line: prefix-less is safe only when you consume design via
+`/styles/compiled`, not when you build design's utilities from source.**
 
 ### Subpath imports
 
@@ -75,27 +81,34 @@ import typography from '@keboola/tailwind-config/typography';
 ```
 
 > **Heads up — `colors` and `typography` are shipped as `.ts` source.**
-> Resolution works when the consumer is **Tailwind v3.3+** (uses
-> [jiti](https://github.com/unjs/jiti) under the hood for config loading)
-> or any bundler that's TypeScript-aware (Vite, esbuild, swc, tsx, ts-node
-> via `--loader`). Plain Node ESM **cannot** load these files without a TS
-> loader. A pre-compiled `.js` variant is planned — track or open an issue
-> if your toolchain hits this.
+> Resolution works when the consumer loads the config through Tailwind (which
+> uses [jiti](https://github.com/unjs/jiti) under the hood) or any bundler
+> that's TypeScript-aware (Vite, esbuild, swc, tsx, ts-node via `--loader`).
+> Plain Node ESM **cannot** load these files without a TS loader. A
+> pre-compiled `.js` variant is planned — track or open an issue if your
+> toolchain hits this.
 
 ## Layout
 
-- `index.js` — the config entry; consumed via `import` (ESM).
+- `index.js` — the token entry (`{ theme }`); consumed via `import` (ESM).
 - `colors.ts` — semantic palette (`primary`, `background`, `foreground`,
   `muted`, `border`, `destructive`, etc.) wired to the CSS variables
   shipped by `@keboola/design`.
 - `typography.ts` — typography scale (used by the `@tailwindcss/typography`
-  plugin).
-
-## Tailwind v4
-
-Tailwind v4 migration is tracked in
-[UT-3997](https://linear.app/keboola/issue/UT-3997). For now this package
-ships a v3-shaped config; the v4 migration moves tokens to CSS `@theme`.
+  plugin, which you install and register yourself).
+- `scrollFade.ts` — optional `scroll-fade` utility plugin.
+
+## Plugins
+
+Earlier versions bundled `tailwindcss-animate`, `@tailwindcss/typography`,
+`@tailwindcss/container-queries` and `tailwindcss-scoped-preflight` and
+registered them for you. They are gone: in v4 container queries are core,
+animations come from [`tw-animate-css`](https://github.com/Wombosvideo/tw-animate-css),
+and preflight scoping is a `@plugin` directive in CSS. Register whatever you
+still need in your own config — `@keboola/design`'s
+[`tailwind.config.js`](https://github.com/keboola/ui/blob/main/packages/design/tailwind.config.js)
+and [`styles.css`](https://github.com/keboola/ui/blob/main/packages/design/src/styles.css)
+are the reference setup.
 
 ## License
 

package/colors.ts

@@ -100,6 +100,14 @@ export default {
   // than card/background in dark, so the block is perceptible in both schemes.
   skeleton: 'rgb(var(--color-skeleton) / <alpha-value>)',
 
+  // Table header surface — a chrome tint that sits clearly above the table
+  // body (card/background) in both schemes. `muted` is ~1.05:1 vs surfaces, so
+  // the header row was near-invisible; this separates it. Scheme-aware only
+  // (light fallback here + `[data-theme='dark']` override in styles.css) — like
+  // `--color-skeleton`, it is not a brand-registry `Colors` slot, so brands
+  // don't re-skin it; a consumer can still override `--color-table-header`.
+  'table-header': 'rgb(var(--color-table-header, 219 225 235) / <alpha-value>)',
+
   // Sidebar semantic colors
   sidebar: {
     DEFAULT: 'rgb(var(--color-sidebar) / <alpha-value>)',

package/index.js

@@ -1,36 +1,15 @@
-import plugin from 'tailwindcss/plugin';
 import colors from './colors';
-import animatePlugin from 'tailwindcss-animate';
-import { scopedPreflightStyles, isolateInsideOfContainer } from 'tailwindcss-scoped-preflight';
-import typographyPlugin from '@tailwindcss/typography';
-import containerQueriesPlugin from '@tailwindcss/container-queries';
 import { typography } from './typography';
-import { scrollFadePlugin } from './scrollFade';
 
 /**
- * Build the Keboola Tailwind config, optionally overriding the class prefix.
+ * The Keboola token surface as a Tailwind `theme`, loaded through v4's `@config`
+ * bridge (see `packages/design/src/styles.css`). Everything a v4 build owns in
+ * CSS — the class prefix, `@import`ed layers, the scoped preflight, plugins — is
+ * intentionally absent: declare those in your stylesheet, not here.
  *
- * `@keboola/design` and the in-monorepo apps are built with the `tw-` prefix
- * (the default), so the design system's compiled CSS assumes it. External
- * consumers that don't extend design's stylesheet — and want unprefixed
- * utilities (`flex`, not `tw-flex`) — can opt out with `createKeboolaConfig({ prefix: '' })`.
- *
- * @param {{ prefix?: string }} [options]
- * @returns {import('tailwindcss').Config}
+ * @type {Pick<import('tailwindcss').Config, 'theme'>}
  */
-export function createKeboolaConfig({ prefix = 'tw-' } = {}) {
-  return {
-    ...baseConfig,
-    prefix,
-  };
-}
-
-/** @type {import('tailwindcss').Config} */
-const baseConfig = {
-  content: ['./src/**/*.{js,jsx,ts,tsx,mdx}', '../../packages/design/src/**/*.{ts,tsx}'],
-  corePlugins: {
-    preflight: false,
-  },
+const config = {
   theme: {
     extend: {
       fill: {
@@ -67,9 +46,15 @@ const baseConfig = {
         'caret-blink': 'caret-blink 1.25s ease-out infinite',
       },
       keyframes: {
+        // Animate the `translate` property, NOT `transform`. In v4 the `-translate-x-*`
+        // utilities (Skeleton's `before:-translate-x-full` start position) set the CSS
+        // `translate` property, not `transform`. A `transform`-based keyframe composes
+        // as a SEPARATE property, so the static `translate:-100%` pins the shimmer
+        // off-screen and the sweep is invisible. Matching `translate` lets the keyframe
+        // override the start position and sweep -100% -> 100% as before.
         shimmer: {
           '100%': {
-            transform: 'translateX(100%)',
+            translate: '100% 0',
           },
         },
         collapseDown: {
@@ -280,26 +265,6 @@ const baseConfig = {
       bold: 'var(--font-weight-bold, 700)',
     },
   },
-  plugins: [
-    animatePlugin,
-    scopedPreflightStyles({
-      isolationStrategy: isolateInsideOfContainer('.tailwindcss-preflight'),
-    }),
-    typographyPlugin,
-    containerQueriesPlugin,
-    plugin(function ({ addVariant, addUtilities }) {
-      addVariant('hover|focus', ['&:enabled:hover', '&:enabled:focus']);
-      addVariant('active|focus', ['&:enabled:active', '&:enabled:focus', '&:enabled:focus-within']);
-      addVariant('not-disabled', ['&:not([data-disabled="true"]):not(:disabled)']);
-      addUtilities({
-        '.break-anywhere': {
-          overflowWrap: 'anywhere',
-        },
-      });
-    }),
-    scrollFadePlugin,
-  ],
 };
 
-/** @type {import('tailwindcss').Config} */
-export default createKeboolaConfig();
+export default config;

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@keboola/tailwind-config",
-  "version": "0.8.0",
-  "description": "Shared Tailwind CSS v3 config for the Keboola UI platform — semantic color palette, plugins, and the `tw-` class prefix.",
+  "version": "1.0.0",
+  "description": "Shared Tailwind CSS v4 design tokens for the Keboola UI platform — semantic color palette, type scale, radii and shadows as a `theme` object.",
   "license": "MIT",
   "type": "module",
   "main": "./index.js",
   "exports": {
     ".": "./index.js",
     "./colors": "./colors.ts",
-    "./typography": "./typography.ts"
+    "./typography": "./typography.ts",
+    "./scrollFade": "./scrollFade.ts"
   },
   "files": [
     "index.js",
@@ -41,13 +42,7 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "tailwindcss": "^3.4.0"
-  },
-  "dependencies": {
-    "@tailwindcss/container-queries": "^0.1.1",
-    "@tailwindcss/typography": "^0.5.19",
-    "tailwindcss-animate": "1.0.7",
-    "tailwindcss-scoped-preflight": "3.5.2"
+    "tailwindcss": "^4.0.0"
   },
   "scripts": {
     "knip:check": "pnpm --dir ../.. exec knip --workspace packages/tailwind-config",