[SUR-397] [ForceUI] Migrate TailwindCSS v3.x.x to v4.x.x#470
Open
jaieds wants to merge 5 commits into
Open
Conversation
BREAKING CHANGE: @bsf/force-ui now targets Tailwind CSS v4, which is CSS-first. The JS `withTW()` helper is deprecated in favor of a shipped CSS theme, and consumers must update their CSS entry + PostCSS setup. - Add src/theme/theme.css: @theme port of all design tokens + the `not-rtl` custom variant (@custom-variant) and a `border-0.5` utility. Spacing/size/leading/z-index/fraction-widths are omitted — v4's dynamic utility scale reproduces them at identical values (verified by compile). - src/tailwind.css: @tailwind directives -> @import "tailwindcss" + theme. - postcss.config.cjs: tailwindcss + autoprefixer -> @tailwindcss/postcss. - package.json: v2.0.0; tailwindcss ^4.3.2; add @tailwindcss/postcss; drop @tailwindcss/container-queries, autoprefixer, tailwindcss-scoped- preflight; expose ./theme.css export. - vite.config.ts: emit theme.css to dist on build. - withTW.js: mark @deprecated (kept as legacy @config shim, removed in 3.0.0). - Delete tailwind.config.js (v4 auto-detects sources; not auto-loaded). - Rename renamed-in-v4 utilities across component/story source: shadow-sm->shadow-xs, outline-none->outline-hidden, rounded-sm->rounded-xs, bare rounded->rounded-sm, bare shadow->shadow-sm. - README: add v2.0.0 migration guide (before/after + removed-keys table). Refs #1830 / SUR-397
List every @theme token shipped in theme.css (162 tokens across colors, shadows, font-size and letter-spacing), grouped by category in a collapsible section, so developers can see exactly which variables to override. Generated from src/theme/theme.css. Refs #1830 / SUR-397
Issues found while migrating SureRank/SureRank Pro onto 2.0.0:
- theme.css: add per-side border-*-0.5 and divide-{x,y}-0.5 utilities
(v3's borderWidth {0.5} theme key generated these variants; without
them, border-style falls back to the browser 'medium' width because
preflight is excluded).
- Move the v3 important prefix to the v4 suffix in remaining component
and story classes (!x -> x!); v4 does not recognize the prefix form.
- Bump tailwind-merge to ^3 — v2 predates the v4 trailing-! syntax and
can drop such classes when merging.
- README: add consumer upgrade checklist and WordPress/webpack notes
(standalone PostCSS pass for the Tailwind entry, no @layer inside
wp-admin, preflight-off border compat, space-* selector change).
Refs #1830 / SUR-397
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| @@ -1,12 +1,12 @@ | |||
| { | |||
| "name": "@bsf/force-ui", | |||
There was a problem hiding this comment.
What: Version upgrade from 1.7.13 to 2.0.0 is a breaking change. Ensure that all parts of the application that rely on this library handle the new version correctly.
Why: Breaking changes can lead to significant issues in dependent components if not properly managed. It is crucial to document any adjustments required.
How: To manage this, update the documentation to include migration steps, particularly highlighting the breaking changes introduced in this release.
ravindrakele
approved these changes
Jul 10, 2026
ravindrakele
left a comment
ravindrakele
left a comment
Contributor
There was a problem hiding this comment.
Verified in SureRank!
by linking it using
npm link @bsf/force-ui
Looks good to me!
mohitsbsftester
approved these changes
Jul 12, 2026
mohitsbsftester
left a comment
mohitsbsftester
left a comment
There was a problem hiding this comment.
Reviewed the Tailwind CSS v4 migration, including the exported theme asset, PostCSS/Vite build path, legacy withTW() compatibility, component class updates, and existing review thread. I did not find a concrete functional regression or a high-confidence issue worth blocking this PR on.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes brainstormforce/surerank#1830 (SUR-397)
Summary
Migrates
@bsf/force-uifrom TailwindCSS v3.4 to v4.3.2 as a CSS-first library, released as 2.0.0 (breaking).withTW()is deprecated (kept as a legacy@configshim, removed in 3.0.0). The theme now ships as CSS: consumers@import "@bsf/force-ui/theme.css"and override tokens in their own@themeblock.src/theme/theme.css— all design tokens as@themevariables, thenot-rtlvariant as@custom-variant, and v3-parity hairline utilities (border-*-0.5,divide-x/y-0.5). No preflight — consumers keep control of the base layer.tailwindcss+autoprefixer→@tailwindcss/postcss; dropped@tailwindcss/container-queries(in core) andtailwindcss-scoped-preflight; deletedtailwind.config.js.shadow-sm→shadow-xs,rounded→rounded-sm,outline-none→outline-hidden, bareshadow/rounded, and the important modifier moved from prefix to suffix (!x→x!).tailwind-merge^2 → ^3 (v2 can drop v4 trailing-!classes when merging).Token parity was verified by compiling probes against the v3 output (byte-identical values), plus Storybook visual checks and full integration testing against SureRank/SureRank Pro.
Consumer impact (breaking)
Every consumer must update its CSS entry, PostCSS config, and drop v4-removed config keys (
corePlugins, selector-stringimportant,variants,safelist). The exact steps and gotchas are documented in the README's "Migrating to v2.0.0" section.Test plan
npm run buildgreen (dual ESM/CJS +dist/theme.css)npm run lint:js/lint:csscleannpm run test— 234/234 passingnot-rtl, Alert, tables)