@keboola/tailwind-config 0.9.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +61 -48
  2. package/index.js +14 -49
  3. package/package.json +5 -10
package/README.md CHANGED
@@ -1,9 +1,9 @@
1
1
  # @keboola/tailwind-config
2
2
 
3
- Shared Tailwind CSS v3 configuration for the Keboola UI platform —
4
- the same semantic color palette, plugins, and `tw-` class prefix that
3
+ Shared Tailwind CSS design tokens for the Keboola UI platform — the same
4
+ semantic color palette, type scale, radii and shadows that
5
5
  [`@keboola/design`](https://github.com/keboola/ui/tree/main/packages/design)
6
- is built on.
6
+ is built on, shaped as a Tailwind `theme` object.
7
7
 
8
8
  Use this when you want your Tailwind-styled app to inherit the platform's
9
9
  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.
13
13
  ## Install
14
14
 
15
15
  ```bash
16
- npm install -D @keboola/tailwind-config tailwindcss@^3
16
+ npm install -D @keboola/tailwind-config tailwindcss@^4
17
17
  # or
18
- pnpm add -D @keboola/tailwind-config tailwindcss@^3
18
+ pnpm add -D @keboola/tailwind-config tailwindcss@^4
19
19
  ```
20
20
 
21
+ Tailwind v3 is no longer supported — stay on `@keboola/tailwind-config@0.9.x`
22
+ if you need it.
23
+
21
24
  ## Use
22
25
 
23
- Extend or reuse the config from your own `tailwind.config.{js,ts}`:
26
+ The package exports **tokens only**: `{ theme }`. Everything a v4 build owns in
27
+ CSS — the class prefix, the `@import`ed layers, preflight, plugins — belongs in
28
+ your stylesheet, not in this object.
29
+
30
+ Load it through v4's `@config` bridge from your own `tailwind.config.{js,ts}`:
24
31
 
25
32
  ```js
26
33
  import keboolaConfig from '@keboola/tailwind-config';
27
34
 
28
- /** @type {import('tailwindcss').Config} */
29
35
  export default {
30
- ...keboolaConfig,
31
- content: ['./src/**/*.{ts,tsx,mdx}'],
36
+ theme: keboolaConfig.theme,
37
+ plugins: [
38
+ /* your own plugins */
39
+ ],
32
40
  };
33
41
  ```
34
42
 
35
- ### Class prefix (`tw-`)
36
-
37
- 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:
38
-
39
- 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.**
40
-
41
- 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.
42
-
43
- Prefix-less recipe (consume design precompiled, author your own utilities unprefixed):
44
-
45
43
  ```css
46
- @import '@keboola/design/styles/compiled'; /* design components, pre-styled with tw-* */
47
- @tailwind base;
48
- @tailwind components;
49
- @tailwind utilities; /* your own unprefixed utilities */
44
+ /* styles.css */
45
+ @import 'tailwindcss/theme.css' layer(theme) prefix(tw);
46
+ @import 'tailwindcss/utilities.css' layer(utilities) prefix(tw);
47
+ @config './tailwind.config.js';
50
48
  ```
51
49
 
52
- **Bottom line: prefix-less is safe only when you consume design via `/styles/compiled`, not when you build design's utilities from source.**
50
+ ### Class prefix (`tw-` in v3, `tw:` in v4)
53
51
 
54
- Opt out of the prefix (or set a custom one) with the `createKeboolaConfig` factory:
52
+ `@keboola/design` components ship with prefixed class names baked into their
53
+ compiled JS, and those classes only render if a stylesheet the app loads
54
+ actually **defines** them. In v4 the prefix is declared in CSS
55
+ (`prefix(tw)` on the `@import`, producing `tw:flex`), not in this config — so
56
+ whether you can drop it depends on how you load design's stylesheet:
55
57
 
56
- ```js
57
- import { createKeboolaConfig } from '@keboola/tailwind-config';
58
+ 1. **Build-from-source** (the monorepo / `apps/boilerplate` pattern) — the app
59
+ imports the source stylesheet `@keboola/design/styles` and runs its **own**
60
+ Tailwind pass over design's `dist/` plus its own markup. That pass emits the
61
+ components' classes using **your** prefix, so dropping `prefix(tw)` renders
62
+ design components UNSTYLED. **Keep the prefix for build-from-source setups.**
58
63
 
59
- /** @type {import('tailwindcss').Config} */
60
- export default {
61
- ...createKeboolaConfig({ prefix: '' }), // unprefixed: `flex`, not `tw-flex`
62
- content: ['./src/**/*.{ts,tsx,mdx}'],
63
- };
64
- ```
64
+ 2. **Precompiled CSS** — the app imports `@keboola/design/styles/compiled` (the
65
+ shipped `dist/styles.css`, which already contains every prefixed utility the
66
+ components use, prebuilt). Design components are then styled by that
67
+ stylesheet regardless of your own prefix, so authoring your utilities
68
+ unprefixed is safe: design's classes and yours live in the same cascade
69
+ without colliding.
65
70
 
66
- 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.
71
+ **Bottom line: prefix-less is safe only when you consume design via
72
+ `/styles/compiled`, not when you build design's utilities from source.**
67
73
 
68
74
  ### Subpath imports
69
75
 
@@ -75,27 +81,34 @@ import typography from '@keboola/tailwind-config/typography';
75
81
  ```
76
82
 
77
83
  > **Heads up — `colors` and `typography` are shipped as `.ts` source.**
78
- > Resolution works when the consumer is **Tailwind v3.3+** (uses
79
- > [jiti](https://github.com/unjs/jiti) under the hood for config loading)
80
- > or any bundler that's TypeScript-aware (Vite, esbuild, swc, tsx, ts-node
81
- > via `--loader`). Plain Node ESM **cannot** load these files without a TS
82
- > loader. A pre-compiled `.js` variant is planned — track or open an issue
83
- > if your toolchain hits this.
84
+ > Resolution works when the consumer loads the config through Tailwind (which
85
+ > uses [jiti](https://github.com/unjs/jiti) under the hood) or any bundler
86
+ > that's TypeScript-aware (Vite, esbuild, swc, tsx, ts-node via `--loader`).
87
+ > Plain Node ESM **cannot** load these files without a TS loader. A
88
+ > pre-compiled `.js` variant is planned — track or open an issue if your
89
+ > toolchain hits this.
84
90
 
85
91
  ## Layout
86
92
 
87
- - `index.js` — the config entry; consumed via `import` (ESM).
93
+ - `index.js` — the token entry (`{ theme }`); consumed via `import` (ESM).
88
94
  - `colors.ts` — semantic palette (`primary`, `background`, `foreground`,
89
95
  `muted`, `border`, `destructive`, etc.) wired to the CSS variables
90
96
  shipped by `@keboola/design`.
91
97
  - `typography.ts` — typography scale (used by the `@tailwindcss/typography`
92
- plugin).
93
-
94
- ## Tailwind v4
95
-
96
- Tailwind v4 migration is tracked in
97
- [UT-3997](https://linear.app/keboola/issue/UT-3997). For now this package
98
- ships a v3-shaped config; the v4 migration moves tokens to CSS `@theme`.
98
+ plugin, which you install and register yourself).
99
+ - `scrollFade.ts` — optional `scroll-fade` utility plugin.
100
+
101
+ ## Plugins
102
+
103
+ Earlier versions bundled `tailwindcss-animate`, `@tailwindcss/typography`,
104
+ `@tailwindcss/container-queries` and `tailwindcss-scoped-preflight` and
105
+ registered them for you. They are gone: in v4 container queries are core,
106
+ animations come from [`tw-animate-css`](https://github.com/Wombosvideo/tw-animate-css),
107
+ and preflight scoping is a `@plugin` directive in CSS. Register whatever you
108
+ still need in your own config — `@keboola/design`'s
109
+ [`tailwind.config.js`](https://github.com/keboola/ui/blob/main/packages/design/tailwind.config.js)
110
+ and [`styles.css`](https://github.com/keboola/ui/blob/main/packages/design/src/styles.css)
111
+ are the reference setup.
99
112
 
100
113
  ## License
101
114
 
package/index.js CHANGED
@@ -1,36 +1,15 @@
1
- import plugin from 'tailwindcss/plugin';
2
1
  import colors from './colors';
3
- import animatePlugin from 'tailwindcss-animate';
4
- import { scopedPreflightStyles, isolateInsideOfContainer } from 'tailwindcss-scoped-preflight';
5
- import typographyPlugin from '@tailwindcss/typography';
6
- import containerQueriesPlugin from '@tailwindcss/container-queries';
7
2
  import { typography } from './typography';
8
- import { scrollFadePlugin } from './scrollFade';
9
3
 
10
4
  /**
11
- * Build the Keboola Tailwind config, optionally overriding the class prefix.
5
+ * The Keboola token surface as a Tailwind `theme`, loaded through v4's `@config`
6
+ * bridge (see `packages/design/src/styles.css`). Everything a v4 build owns in
7
+ * CSS — the class prefix, `@import`ed layers, the scoped preflight, plugins — is
8
+ * intentionally absent: declare those in your stylesheet, not here.
12
9
  *
13
- * `@keboola/design` and the in-monorepo apps are built with the `tw-` prefix
14
- * (the default), so the design system's compiled CSS assumes it. External
15
- * consumers that don't extend design's stylesheet — and want unprefixed
16
- * utilities (`flex`, not `tw-flex`) — can opt out with `createKeboolaConfig({ prefix: '' })`.
17
- *
18
- * @param {{ prefix?: string }} [options]
19
- * @returns {import('tailwindcss').Config}
10
+ * @type {Pick<import('tailwindcss').Config, 'theme'>}
20
11
  */
21
- export function createKeboolaConfig({ prefix = 'tw-' } = {}) {
22
- return {
23
- ...baseConfig,
24
- prefix,
25
- };
26
- }
27
-
28
- /** @type {import('tailwindcss').Config} */
29
- const baseConfig = {
30
- content: ['./src/**/*.{js,jsx,ts,tsx,mdx}', '../../packages/design/src/**/*.{ts,tsx}'],
31
- corePlugins: {
32
- preflight: false,
33
- },
12
+ const config = {
34
13
  theme: {
35
14
  extend: {
36
15
  fill: {
@@ -67,9 +46,15 @@ const baseConfig = {
67
46
  'caret-blink': 'caret-blink 1.25s ease-out infinite',
68
47
  },
69
48
  keyframes: {
49
+ // Animate the `translate` property, NOT `transform`. In v4 the `-translate-x-*`
50
+ // utilities (Skeleton's `before:-translate-x-full` start position) set the CSS
51
+ // `translate` property, not `transform`. A `transform`-based keyframe composes
52
+ // as a SEPARATE property, so the static `translate:-100%` pins the shimmer
53
+ // off-screen and the sweep is invisible. Matching `translate` lets the keyframe
54
+ // override the start position and sweep -100% -> 100% as before.
70
55
  shimmer: {
71
56
  '100%': {
72
- transform: 'translateX(100%)',
57
+ translate: '100% 0',
73
58
  },
74
59
  },
75
60
  collapseDown: {
@@ -280,26 +265,6 @@ const baseConfig = {
280
265
  bold: 'var(--font-weight-bold, 700)',
281
266
  },
282
267
  },
283
- plugins: [
284
- animatePlugin,
285
- scopedPreflightStyles({
286
- isolationStrategy: isolateInsideOfContainer('.tailwindcss-preflight'),
287
- }),
288
- typographyPlugin,
289
- containerQueriesPlugin,
290
- plugin(function ({ addVariant, addUtilities }) {
291
- addVariant('hover|focus', ['&:enabled:hover', '&:enabled:focus']);
292
- addVariant('active|focus', ['&:enabled:active', '&:enabled:focus', '&:enabled:focus-within']);
293
- addVariant('not-disabled', ['&:not([data-disabled="true"]):not(:disabled)']);
294
- addUtilities({
295
- '.break-anywhere': {
296
- overflowWrap: 'anywhere',
297
- },
298
- });
299
- }),
300
- scrollFadePlugin,
301
- ],
302
268
  };
303
269
 
304
- /** @type {import('tailwindcss').Config} */
305
- export default createKeboolaConfig();
270
+ export default config;
package/package.json CHANGED
@@ -1,14 +1,15 @@
1
1
  {
2
2
  "name": "@keboola/tailwind-config",
3
- "version": "0.9.0",
4
- "description": "Shared Tailwind CSS v3 config for the Keboola UI platform — semantic color palette, plugins, and the `tw-` class prefix.",
3
+ "version": "1.0.0",
4
+ "description": "Shared Tailwind CSS v4 design tokens for the Keboola UI platform — semantic color palette, type scale, radii and shadows as a `theme` object.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "main": "./index.js",
8
8
  "exports": {
9
9
  ".": "./index.js",
10
10
  "./colors": "./colors.ts",
11
- "./typography": "./typography.ts"
11
+ "./typography": "./typography.ts",
12
+ "./scrollFade": "./scrollFade.ts"
12
13
  },
13
14
  "files": [
14
15
  "index.js",
@@ -41,13 +42,7 @@
41
42
  "node": ">=20"
42
43
  },
43
44
  "peerDependencies": {
44
- "tailwindcss": "^3.4.0"
45
- },
46
- "dependencies": {
47
- "@tailwindcss/container-queries": "^0.1.1",
48
- "@tailwindcss/typography": "^0.5.19",
49
- "tailwindcss-animate": "1.0.7",
50
- "tailwindcss-scoped-preflight": "3.5.2"
45
+ "tailwindcss": "^4.0.0"
51
46
  },
52
47
  "scripts": {
53
48
  "knip:check": "pnpm --dir ../.. exec knip --workspace packages/tailwind-config",