@onereach/styles 27.0.2-beta.6103.0 → 27.0.2-beta.6104.0

package/MIGRATION_TAILWIND_V4.md

@@ -0,0 +1,149 @@
+# Migrate to Tailwind CSS 4
+
+Toolchain and config migration is required.
+Template and Tailwind class rewrites are not required.
+
+Both `!class` and `class!` remain supported; `class!` is preferred for new code.
+
+## 1. Update dependencies
+
+Install Tailwind CSS 4 and its PostCSS plugin alongside the UI Next styles
+package:
+
+```sh
+pnpm add @onereach/styles tailwindcss@4.3.2
+pnpm add --save-dev @tailwindcss/postcss@4.3.2 postcss@^8.4.32
+```
+
+Remove Tailwind CSS 3 and `tailwindcss/nesting` from the consumer PostCSS
+plugins. Keep unrelated PostCSS plugins that the application still needs.
+
+## 2. Update PostCSS
+
+```js
+// postcss.config.cjs
+module.exports = {
+  plugins: [
+    require('@tailwindcss/postcss')({ optimize: false }),
+    require('@onereach/styles/postcss/tailwind-v4-compat.cjs'),
+  ],
+};
+```
+
+The OneReach compatibility plugin runs after Tailwind CSS 4. It restores the
+established semantic-state importance, selector composition, and Tailwind 3
+cascade order without changing template classes. Its nesting pass is scoped to
+generated `@layer utilities` rules and does not transform application CSS
+outside that layer.
+
+## 3. Update the Tailwind config
+
+Use the explicit Tailwind CSS 4 preset. Existing application theme extensions
+and plugins can remain in this config.
+
+```js
+// tailwind.config.cjs
+module.exports = {
+  presets: [
+    require('@onereach/styles/tailwind.config.preset.v4.js'),
+  ],
+  theme: {
+    extend: {
+      // Keep application theme extensions here.
+    },
+  },
+  plugins: [
+    // Keep application plugins here.
+  ],
+};
+```
+
+Tailwind CSS 4 source scanning is configured in CSS, so remove the Tailwind CSS
+3 `content` array after moving each path to an `@source` directive.
+
+## 4. Update the CSS entrypoint
+
+The following example assumes this file is `src/tailwind.css` and the Tailwind
+config is at the project root:
+
+```css
+@import "tailwindcss";
+@import "@onereach/styles/main-v4.css";
+
+@config "../tailwind.config.cjs";
+@source "./";
+@source "../node_modules/@onereach/ui-components/dist/esm";
+@source "../node_modules/@onereach/ui-components-vue2/dist/esm";
+```
+
+Remove the unused `@source` line when the application installs only Vue 2 or
+only Vue 3. Add an `@source` for every other installed package that renders
+Tailwind classes.
+
+The application owns the `@import "tailwindcss"`, `@config`, and `@source`
+directives. The `main-v4.css` entrypoint does not choose a consumer config or
+source tree.
+
+## 5. Opt in to legacy `+` and `*` utilities
+
+Tailwind CSS 4 rejects class candidates whose token names contain `+` or `*`.
+Applications that still use classes such as `px-sm+`, `px-sm+*`, or `-m-sm+`
+must import the compatibility stylesheet:
+
+```css
+@import "@onereach/styles/compat/tailwind-v3-utilities.css";
+@import "tailwindcss";
+@import "@onereach/styles/main-v4.css";
+
+@config "../tailwind.config.cjs";
+@source "./";
+@source "../node_modules/@onereach/ui-components/dist/esm";
+```
+
+This import is optional and is not included by `main-v4.css`. It preserves the
+legacy utility names without requiring template or class changes.
+Import the compatibility stylesheet before `tailwindcss` so responsive
+Tailwind utilities retain the same cascade precedence they had in Tailwind CSS
+3.
+
+The artifact includes the legacy variant combinations used by UI Next and the
+audited workspace consumers: important, dark, hover, mobile, desktop,
+breakpoints, children, and positional children utilities.
+
+If an application combines a legacy token with another custom variant, keep the
+template class and add its safe alias candidate to the CSS entrypoint. For
+example, `focus:px-sm+` uses:
+
+```css
+@source inline("focus:px-or-tw4-legacy-sm-b");
+```
+
+The compatibility plugin changes only the generated selector back to
+`focus:px-sm+`. The application template remains unchanged.
+
+## Dark mode
+
+The preset supports both existing dark-mode root selectors, `.dark` and
+`[data-theme="dark"]`:
+
+```html
+<html class="dark">
+```
+
+```html
+<html data-theme="dark">
+```
+
+Keep the root already used by the application. No dark-mode template rewrite is
+required.
+
+## Migration checklist
+
+- Replace Tailwind CSS 3 with Tailwind CSS 4 and `@tailwindcss/postcss`.
+- Replace the preset import with `tailwind.config.preset.v4.js`.
+- Import `@onereach/styles/main-v4.css`.
+- Move every Tailwind CSS 3 `content` path to an `@source` directive.
+- Keep application theme extensions, plugins, utilities, and dark-mode roots.
+- Add the optional compatibility import only when `+` or `*` token classes are
+  still present.
+- Keep existing templates and Tailwind classes unchanged.

package/README.md

@@ -0,0 +1,14 @@
+# @onereach/styles
+
+Shared UI Next design tokens, base styles, and Tailwind presets.
+
+## Tailwind CSS
+
+- Tailwind CSS 3 consumers use `main-v3.css` and
+  `tailwind.config.preset.js`.
+- Tailwind CSS 4 consumers use `main-v4.css` and
+  `tailwind.config.preset.v4.js`.
+
+See [Migrate to Tailwind CSS 4](./MIGRATION_TAILWIND_V4.md) for copyable
+dependency, PostCSS, config, CSS, source-scanning, dark-mode, and optional
+legacy utility setup.