@onereach/styles 27.0.2-beta.6110.0 → 27.0.2-beta.6112.0

package/MIGRATION_TAILWIND_V4.md

@@ -2,6 +2,8 @@
 
 Toolchain and config migration is required.
 Template and Tailwind class rewrites are not required.
+UI Next supports Tailwind CSS 4 at runtime; the Tailwind CSS 3 compiler is not
+supported after the library upgrade.
 
 Both `!class` and `class!` remain supported; `class!` is preferred for new code.
 
@@ -30,11 +32,11 @@ module.exports = {
 };
 ```
 
-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.
+The OneReach compatibility plugin runs after Tailwind CSS 4. It preserves the
+established semantic-state importance, selector composition, and legacy 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
 
@@ -67,6 +69,7 @@ The following example assumes this file is `src/tailwind.css` and the Tailwind
 config is at the project root:
 
 ```css
+@import "@onereach/styles/compat/tailwind-v3-utilities.css";
 @import "tailwindcss";
 @import "@onereach/styles/main-v4.css";
 
@@ -84,27 +87,14 @@ 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
+## 5. Keep 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.
+UI Next components and existing consumers still use classes such as `px-sm+`,
+`px-sm+*`, and `-m-sm+`, so the compatibility stylesheet in the standard
+entrypoint is required. It is kept separate from `main-v4.css` because the
+application owns import order. Import it before `tailwindcss` so responsive
+utilities retain their established cascade precedence.
 
 The artifact includes the legacy variant combinations used by UI Next and the
 audited workspace consumers: important, dark, hover, mobile, desktop,
@@ -141,9 +131,8 @@ required.
 
 - Replace Tailwind CSS 3 with Tailwind CSS 4 and `@tailwindcss/postcss`.
 - Replace the preset import with `tailwind.config.preset.v4.js`.
+- Import `@onereach/styles/compat/tailwind-v3-utilities.css` before Tailwind.
 - 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

@@ -4,11 +4,12 @@ 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`.
+UI Next uses Tailwind CSS 4 at runtime. Use `main-v4.css` and
+`tailwind.config.preset.v4.js`.
+
+Existing template classes remain supported through the compatibility layer.
+The Tailwind CSS 3 compiler is not supported.
 
 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.
+dependency, PostCSS, config, CSS, source-scanning, dark-mode, and legacy
+utility compatibility setup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onereach/styles",
-  "version": "27.0.2-beta.6110.0",
+  "version": "27.0.2-beta.6112.0",
   "description": "Styles for or-ui-next",
   "license": "Apache-2.0",
   "files": [
@@ -13,7 +13,6 @@
     "base.layer.css",
     "font.css",
     "legacy-ui-warning.scss",
-    "main-v3.css",
     "main-v4.css",
     "postcss",
     "preflight-revert.css",
@@ -23,6 +22,7 @@
     "tailwind.config.json",
     "tailwind.config.preset.js",
     "tailwind.config.preset.v4.js",
+    "tailwind.reference.css",
     "temporary-dark-v2.css",
     "tokens.css",
     "tokens-v3.css",
@@ -41,7 +41,7 @@
     "test:contract": "node --test tests/*.test.cjs"
   },
   "dependencies": {
-    "@onereach/font-icons": "^27.0.2-beta.6110.0",
+    "@onereach/font-icons": "^27.0.2-beta.6112.0",
     "postcss-nested": "6.2.0",
     "tailwindcss": "4.3.2"
   },

package/postcss/tailwind-v4-compat.cjs

@@ -10,6 +10,10 @@ const {
 const {
   legacySpacingAliasEntries,
 } = require('../tailwind/compatibility/legacy-spacing');
+const {
+  componentEndMarker,
+  componentMarker,
+} = require('../tailwind/plugins/component-marker');
 const coreVariants = require('../tailwind/plugins/core').variants;
 const themePresetValues = require('../tailwind/plugins/theme-preset').values;
 const spacing = require('../tailwind.config.preset.v4').theme.spacing;
@@ -48,6 +52,12 @@ const legacyTransformValue = [
   'scaleY(var(--tw-scale-y, 1))',
 ].join(' ');
 const legacyComponentFactories = [
+  ['layout', require('../tailwind/plugins/layout').values],
+  ['typography', require('../tailwind/plugins/typography').values],
+  ['iconography', {
+    ...require('../tailwind/plugins/iconography').values,
+    'onereach': 'onereach',
+  }],
   ['theme-outline', require('../tailwind/plugins/theme-outline').values],
   ['theme-background', require('../tailwind/plugins/theme-background').values],
   ['theme-foreground', require('../tailwind/plugins/theme-foreground').values],
@@ -63,20 +73,6 @@ const legacyComponentFactories = [
     new Map(Object.keys(values).map((value, index) => [value, index])),
   ])
   .sort(([left], [right]) => right.length - left.length);
-const legacyComponentFactoryNames = [
-  'theme-background',
-  'theme-foreground',
-  'theme-preset-1',
-  'theme-preset-2',
-  'theme-preset-3',
-  'theme-preset-4',
-  'theme-divider',
-  'theme-outline',
-  'theme-border',
-  'iconography',
-  'typography',
-  'layout',
-].sort((left, right) => right.length - left.length);
 const legacyComponentFactoryOrder = new Map([
   'layout',
   'typography',
@@ -265,7 +261,10 @@ function utilityLayers(root) {
   const layers = [];
 
   root.walkAtRules('layer', (layer) => {
-    if (layer.params.trim() === 'utilities') layers.push(layer);
+    if (
+      layer.params.trim() === 'utilities'
+      && isTailwindGenerated(layer)
+    ) layers.push(layer);
   });
 
   return layers;
@@ -275,12 +274,28 @@ function componentLayers(root) {
   const layers = [];
 
   root.walkAtRules('layer', (layer) => {
-    if (layer.params.trim() === 'components') layers.push(layer);
+    if (
+      layer.params.trim() === 'components'
+      && isTailwindGenerated(layer)
+    ) layers.push(layer);
   });
 
   return layers;
 }
 
+function isTailwindGenerated(container) {
+  const sources = [container.source?.input?.file];
+
+  container.walk?.((node) => {
+    sources.push(node.source?.input?.file);
+  });
+
+  return sources.some((file) => (
+    typeof file === 'string'
+    && file.replaceAll('\\', '/').endsWith('/tailwindcss/index.css')
+  ));
+}
+
 function restoreLegacyComponentLayers(root) {
   utilityLayers(root).forEach((utilityLayer) => {
     const componentNodes = extractLegacyComponentNodes(utilityLayer);
@@ -302,8 +317,8 @@ function extractLegacyComponentNodes(container) {
     if (node.type === 'rule') {
       const isLegacyComponent = classNames(node.selector)
         .map(baseUtility)
-        .some((utility) => legacyComponentFactoryNames
-          .some((factory) => utility.startsWith(`${factory}-`)));
+        .some((utility) => legacyComponentFactoryForUtility(utility))
+        && removeComponentMarker(node);
 
       if (!isLegacyComponent) return [];
 
@@ -332,6 +347,19 @@ function extractLegacyComponentNodes(container) {
   });
 }
 
+function removeComponentMarker(container) {
+  let found = false;
+
+  [componentMarker, componentEndMarker].forEach((marker) => {
+    container.walkDecls(marker, (declaration) => {
+      found = true;
+      declaration.remove();
+    });
+  });
+
+  return found;
+}
+
 function reorderLegacyComponentValueSiblings(container) {
   const groups = new Map();
 
@@ -345,8 +373,7 @@ function reorderLegacyComponentValueSiblings(container) {
       }))
       .map((entry) => ({
         ...entry,
-        factory: legacyComponentFactories
-          .find(([factory]) => entry.utility.startsWith(`${factory}-`)),
+        factory: legacyComponentFactoryForUtility(entry.utility),
       }))
       .find(({ factory }) => factory);
 
@@ -399,8 +426,9 @@ function reorderLegacyComponentFactorySiblings(container) {
     const selectorClassNames = selectors.flatMap(classNames);
     const factory = selectorClassNames
       .map(baseUtility)
-      .flatMap((utility) => [...legacyComponentFactoryOrder.keys()]
-        .filter((candidate) => utility.startsWith(`${candidate}-`)))
+      .map(legacyComponentFactoryForUtility)
+      .filter(Boolean)
+      .map(([name]) => name)
       .at(0);
 
     if (!factory) return [];
@@ -487,7 +515,11 @@ function restoreLegacySpacingClassNames(root) {
 
         restoredLegacyClass = true;
 
-        return `.${escapedClassName.slice(0, aliasStart)}-${escapeClassName(legacyName)}${escapedClassName.slice(aliasStart + alias.length + 1)}`;
+        return [
+          `.${escapedClassName.slice(0, aliasStart)}`,
+          `-${escapeClassName(legacyName)}`,
+          escapedClassName.slice(aliasStart + alias.length + 1),
+        ].join('');
       },
     );
 
@@ -871,7 +903,14 @@ function classNames(selector) {
 }
 
 function baseUtility(className) {
-  return className.split(':').at(-1).replace(/^!|!$/g, '');
+  return classSegments(className).at(-1).replace(/^!|!$/g, '');
+}
+
+function legacyComponentFactoryForUtility(utility) {
+  return legacyComponentFactories.find(([factory, values]) => (
+    utility.startsWith(`${factory}-`)
+    && values.has(utility.slice(factory.length + 1))
+  ));
 }
 
 function descendantContainers(rule) {
@@ -1088,7 +1127,7 @@ function responsiveVariantForNode(node) {
 
   return selectors
     .flatMap(classNames)
-    .flatMap((className) => className.split(':'))
+    .flatMap(classSegments)
     .find((segment) => responsiveVariantOrder.has(segment));
 }
 

package/tailwind/plugins/component-marker.js

@@ -0,0 +1,22 @@
+const componentMarker = '--or-tailwind-component';
+const componentEndMarker = '--or-tailwind-component-end';
+
+function markComponent(styles) {
+  if (Array.isArray(styles)) return styles.map(markComponent);
+  if (!styles || typeof styles !== 'object') return styles;
+
+  return Object.fromEntries([
+    [componentMarker, '1'],
+    ...Object.entries(styles).map(([key, value]) => [
+      key,
+      markComponent(value),
+    ]),
+    [componentEndMarker, '1'],
+  ]);
+}
+
+module.exports = {
+  componentEndMarker,
+  componentMarker,
+  markComponent,
+};

package/tailwind/plugins/iconography.js

@@ -1,5 +1,7 @@
 const plugin = require('tailwindcss/plugin');
 
+const { markComponent } = require('./component-marker');
+
 const values = {
   'outlined': '"opsz" 24, "wght" 400, "FILL" 0, "GRAD" 0',
   'outlined-bold': '"opsz" 24, "wght" 700, "FILL" 0, "GRAD" 0',
@@ -11,18 +13,20 @@ const values = {
 };
 
 module.exports = {
+  values,
+
   plugin: plugin(({ matchComponents, addComponents }) => {
     matchComponents({
-      'iconography': (value) => ({
+      'iconography': (value) => markComponent({
         fontFamily: '"Material Symbols Outlined"',
         fontVariationSettings: value,
       }),
     }, { values });
 
     addComponents({
-      '.iconography-onereach': {
+      '.iconography-onereach': markComponent({
         fontFamily: '"OneReach Icons"',
-      },
+      }),
     });
   }),
 };

package/tailwind/plugins/layout.js

@@ -1,5 +1,7 @@
 const plugin = require('tailwindcss/plugin');
 
+const { markComponent } = require('./component-marker');
+
 const values = {
   'row': 'row',
   'row-reverse': 'row-reverse',
@@ -22,7 +24,7 @@ module.exports = {
       'layout': (value) => {
         const { prefix = '', direction, suffix = '' } = /^(?:(?<prefix>inline-)\.\.)?(?<direction>row|column)(?<suffix>-reverse)?$/.exec(value).groups;
 
-        return {
+        return markComponent({
           flexGrow: prefix === 'inline-' ? '0' : null,
           flexShrink: prefix === 'inline-' ? '0' : null,
           flexBasis: prefix === 'inline-' ? 'auto' : null,
@@ -37,7 +39,7 @@ module.exports = {
 
           minWidth: prefix === 'inline-' ? 'auto' : null,
           maxWidth: prefix === 'inline-' ? '100%' : null,
-        };
+        });
       },
     }, { values });
   }),

package/tailwind/plugins/theme-background.js

@@ -3,6 +3,7 @@ const plugin = require('tailwindcss/plugin');
 const { markImportant } = require('../compatibility/important');
 const { resolveThemeValue } = require('../utils');
 
+const { markComponent } = require('./component-marker');
 const { variants } = require('./core');
 
 const values = {
@@ -201,7 +202,7 @@ module.exports = {
       'theme-background': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           backgroundColor: resolveThemeValue(theme, `backgroundColor.${token}` + suffix, token),
 
           [variants['disabled']]: ['white', 'black', 'transparent'].includes(token) ? null : markImportant({
@@ -211,7 +212,7 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
     }, { values });
   }),

package/tailwind/plugins/theme-border.js

@@ -3,6 +3,7 @@ const plugin = require('tailwindcss/plugin');
 const { markImportant } = require('../compatibility/important');
 const { resolveThemeValue } = require('../utils');
 
+const { markComponent } = require('./component-marker');
 const { variants } = require('./core');
 
 const values = {
@@ -51,7 +52,7 @@ module.exports = {
       'theme-border': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           borderStyle: 'solid',
           borderColor: resolveThemeValue(theme, `borderColor.${token}` + suffix, token),
 
@@ -62,7 +63,7 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
     }, { values });
   }),

package/tailwind/plugins/theme-divider.js

@@ -3,6 +3,7 @@ const plugin = require('tailwindcss/plugin');
 const { markImportant } = require('../compatibility/important');
 const { resolveThemeValue } = require('../utils');
 
+const { markComponent } = require('./component-marker');
 const { variants } = require('./core');
 
 const values = {
@@ -51,7 +52,7 @@ module.exports = {
       'theme-divider': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           [variants['children']]: {
             '&:not(:first-child)': markImportant({
               borderInlineStartStyle: 'none',
@@ -75,7 +76,7 @@ module.exports = {
               }),
             },
           },
-        };
+        });
       },
     }, { values });
   }),

package/tailwind/plugins/theme-foreground.js

@@ -3,6 +3,7 @@ const plugin = require('tailwindcss/plugin');
 const { markImportant } = require('../compatibility/important');
 const { resolveThemeValue } = require('../utils');
 
+const { markComponent } = require('./component-marker');
 const { variants } = require('./core');
 
 const values = {
@@ -198,7 +199,7 @@ module.exports = {
       'theme-foreground': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           color: resolveThemeValue(theme, `textColor.${token}` + suffix, token),
 
           [variants['disabled']]: ['white', 'black', 'transparent'].includes(token) ? null : markImportant({
@@ -208,7 +209,7 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
     }, { values });
   }),

package/tailwind/plugins/theme-outline.js

@@ -3,6 +3,7 @@ const plugin = require('tailwindcss/plugin');
 const { markImportant } = require('../compatibility/important');
 const { resolveThemeValue } = require('../utils');
 
+const { markComponent } = require('./component-marker');
 const { variants } = require('./core');
 
 const values = {
@@ -42,7 +43,7 @@ module.exports = {
       'theme-outline': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           outlineStyle: 'solid',
           outlineColor: resolveThemeValue(theme, `outlineColor.${token}` + suffix, token),
 
@@ -53,7 +54,7 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
     }, { values });
   }),

package/tailwind/plugins/theme-preset.js

@@ -3,6 +3,7 @@ const plugin = require('tailwindcss/plugin');
 const { markImportant } = require('../compatibility/important');
 const { resolveThemeValue } = require('../utils');
 
+const { markComponent } = require('./component-marker');
 const { variants } = require('./core');
 
 const values = {
@@ -33,7 +34,7 @@ module.exports = {
       'theme-preset-1': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           color: resolveThemeValue(theme, `textColor.on-${token}` + suffix),
           backgroundColor: resolveThemeValue(theme, `backgroundColor.${token}` + suffix),
 
@@ -68,13 +69,13 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
 
       'theme-preset-2': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           color: resolveThemeValue(theme, `textColor.${token}` + suffix),
           backgroundColor: resolveThemeValue(theme, `backgroundColor.${token}-opacity-0-08` + suffix),
 
@@ -109,13 +110,13 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
 
       'theme-preset-3': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           color: resolveThemeValue(theme, `textColor.${token}` + suffix),
           backgroundColor: 'transparent',
 
@@ -150,13 +151,13 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
 
       'theme-preset-4': (value) => {
         const [token, suffix = ''] = value.split('..');
 
-        return {
+        return markComponent({
           color: resolveThemeValue(theme, `textColor.${token}` + suffix),
           backgroundColor: 'transparent',
 
@@ -191,7 +192,7 @@ module.exports = {
           transitionProperty: 'color, background-color, border-color, outline-color',
           transitionDuration: theme('transitionDuration.short'),
           transitionTimingFunction: theme('transitionTimingFunction.standard'),
-        };
+        });
       },
     }, { values });
   }),

package/tailwind/plugins/typography.js

@@ -1,6 +1,9 @@
 const plugin = require('tailwindcss/plugin');
+
 const screens = require('../../screens.json');
 
+const { markComponent } = require('./component-marker');
+
 const values = {
   'display-large': 'display-large',
   'display-medium': 'display-medium',
@@ -39,7 +42,7 @@ module.exports = {
         const [fontSizeDesktop, optionsDesktop] = fontSizeConfig[value] ?? [];
         const [fontSizeMobile, optionsMobile] = fontSizeConfig[`mobile-${value}`] ?? [];
 
-        return {
+        return markComponent({
           fontFamily: theme(`fontFamily.mobile-${value}`) ?? theme(`fontFamily.${value}`),
           fontWeight: theme(`fontWeight.mobile-${value}`) ?? theme(`fontWeight.${value}`),
           fontSize: fontSizeMobile ?? fontSizeDesktop,
@@ -66,7 +69,7 @@ module.exports = {
             fontSize: fontSizeDesktop,
             lineHeight: optionsDesktop?.lineHeight,
           },
-        };
+        });
       },
     }, { values });
   }),

package/tailwind.reference.css

@@ -0,0 +1,4 @@
+/* stylelint-disable scss/at-rule-no-unknown */
+@import "tailwindcss" source(none);
+
+@config "./tailwind.config.preset.v4.js";

package/main-v3.css

@@ -1,9 +0,0 @@
-/* stylelint-disable scss/at-rule-no-unknown */
-@import "tailwindcss";
-@import "./tokens-v3.css";
-@import "./font.css";
-
-@import "./base.layer.css";
-@import "./compat/tailwind-v3-utilities.css";
-
-@config "./tailwind.config.js";