@lynx-js/tailwind-preset-canary 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @lynx-js/tailwind-preset
 
+## 0.2.0
+
+### Minor Changes
+
+- Add support for Lynx UI plugin system with configurable options. ([#1363](https://github.com/lynx-family/lynx-stack/pull/1363))
+
+  - Introduced `lynxUIPlugins` option in `createLynxPreset`, allowing userland opt-in to Lynx UI specific plugins.
+
+  - Implemented `uiVariants` plugin as the first UI plugin, supporting `ui-*` variant prefixes (e.g. `ui-checked`, `ui-open`) with customizable mappings.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -1,13 +1,21 @@
 # Lynx Tailwind Preset (V3)
 
-A [Tailwind V3](https://v3.tailwindcss.com/) CSS preset specifically designed for Lynx, ensuring that only CSS properties supported by Lynx are available as Tailwind utilities.
+A [Tailwind CSS v3](https://v3.tailwindcss.com/) preset for the Lynx ecosystem.
+
+This preset is not a 1:1 port of Tailwind's core. Instead, it provides a **Lynx-native Tailwind experience** tailored for the platform's rendering model and ecosystem needs by:
+
+- Including only CSS utilities that Lynx supports
+
+- Reimagining certain utilities to align with Lynx's styling constraints and runtime behavior
+
+- Enabling ecosystem extensions such as UI state variants, animation presets, and design token integration
 
 > **⚠️ Experimental**\
 > This preset is currently in experimental stage as we are still exploring the best possible DX to write Tailwind upon Lynx. We welcome and encourage contributions from the community to help shape its future development. Your feedback, bug reports, and pull requests are invaluable in making this preset more robust and feature-complete.
 
 ## Basic Usage
 
-```typescript
+```ts
 // tailwind.config.ts
 import preset from '@lynx-js/tailwind-preset';
 
@@ -17,7 +25,7 @@ export default {
 };
 ```
 
-```typescript
+```ts
 // tailwind.config.ts
 import { createLynxPreset } from '@lynx-js/tailwind-preset';
 
@@ -31,80 +39,7 @@ export default {
 };
 ```
 
-## Structure
-
-- `src/lynx.ts`: Main preset configuration that reverse-engineered [Tailwind's core plugins](https://github.com/tailwindlabs/tailwindcss/blob/v3/src/corePlugins.js).
-- `src/plugins/lynx/`: Custom plugins as replacement when per-class customization are needed.
-- `src/__tests__/`: Test files to ensure correct utility generation
-
-## Contributing
-
-### Getting Started
-
-```bash
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
-```
-
-### Adding New Utilities
-
-#### 1. Check if the CSS property is supported by Lynx
-
-This can be verified in three ways:
-
-1. [`@lynx-js/css-defines`](https://www.npmjs.com/package/@lynx-js/css-defines), this is the most accurate list of CSS properties supported by Lynx, directly generated from the source of Lynx internal definitions and released along with each Lynx releases.
-2. `csstype.d.ts` in `@lynx-js/types`, this is used as the types of inline styles (e.g. `<view style>`) but this is currently maintained manually.
-3. Lynx's runtime behaviors.
-
-#### 2. Add/Remove it from the preset
-
-##### 2.1 If enabling a Tailwind core plugin
-
-- Add it to `DEFAULT_CORE_PLUGINS` array in `src/core.ts`
-
-##### 2.2 If it requires custom handling
-
-###### Lynx core plugins
-
-For plugins that are considered **part of the Lynx core preset** — either implementing Tailwind core utilities or providing Lynx-specific functionality
-
-- Create a new plugin in `src/plugins/lynx/`
-- Use shared helpers from `src/helpers.ts` and `src/plugin-utils/` where applicable
-- Export it from `src/plugins/lynx/index.ts`
-- Register it in `src/plugins/lynx/plugin-registry.ts`\
-  _(This ensures a stable sorting order for the core set)_
-- It will be automatically included in `src/core.ts` via the Lynx plugin registry
-
-###### Non-core / Custom plugin categories
-
-For plugins that are **not part of the Lynx core preset** — such as experimental features, app-specific utilities, or standalone plugin groups:
-
-- These plugins require explicit registration and ordering
-- Create a new category folder under `src/plugins/` (e.g. `src/plugins/experimental/`)
-- Add the plugin in that folder, and optionally extract shared logic into `plugin-utils/`
-- Export the plugin from `src/plugins/{category}/index.ts`
-- Define a `plugin-registry.ts` in the same folder to control plugin order
-- Import the registry in `src/core.ts` and include it in the appropriate position
-
-#### 3. Adding Tests
-
-We test by using Tailwind CLI to build `src/__tests__/` demo project with our preset, then extracting all properties used in the generated utilities and verify if all used properties are allowed according to `@lynx-js/types`.
-
-To test new Tailwind utilities:
-
-1. Modify `testClasses` in `src/__tests__/test-content.tsx`
-2. Modify `supportedProperties` or `allowedUnsupportedProperties` in `config.test.ts`
-3. Run tests with `pnpm test` to verify with Vitest.
-
-To test new plugins:
-
-1. Add new test file in `src/__tests__/plugins`. Import `runPlugin` test util function from `src/__tests__/utils/run-plugin.ts`. Mock theme values.
-2. Run tests with `pnpm test` to verify with Vitest.
-
-## Integration notes
+## Integration Notes
 
 ### tailwind-merge & rsbuild-plugin-tailwindcss
 
@@ -128,3 +63,43 @@ export default {
   ],
 };
 ```
+
+## Ecosystem Extensions
+
+Beyond core utility coverage, this preset supports ecosystem-level extensions to improve component styling DX and support common Tailwind ecosystem patterns adapted for Lynx.
+
+### Enabling Lynx UI Plugins
+
+UI plugins are not enabled by default. You can enable all plugins with:
+
+```ts
+createLynxPreset({
+  lynxUIPlugins: true,
+});
+```
+
+Or enable individual plugins with their default options:
+
+```ts
+createLynxPreset({
+  lynxUIPlugins: { uiVariants: true },
+});
+```
+
+Or configure each plugin individually — see each plugin's documentation for available options:
+
+```ts
+createLynxPreset({
+  lynxUIPlugins: {
+    uiVariants: {
+      prefixes: {
+        ui: ['open', 'checked'],
+      },
+    },
+  },
+});
+```
+
+#### Available Plugins
+
+- [uiVariants](https://github.com/lynx-family/lynx-stack/tree/main/packages/third-party/tailwind-preset/docs/plugins/lynx-ui/uiVariants.md) — Class-based variants for expressing component state or structure using `ui-*` prefixes (e.g. `.ui-open:`, `.ui-side-left:`).

package/dist/core.d.ts

@@ -1,13 +1,22 @@
 import { LYNX_PLUGIN_MAP, ORDERED_LYNX_PLUGIN_NAMES } from './plugins/lynx/plugin-registry.js';
 import type { LynxPluginName } from './plugins/lynx/plugin-types.js';
+import { LYNX_UI_PLUGIN_MAP, ORDERED_LYNX_UI_PLUGIN_NAMES } from './plugins/lynx-ui/plugin-registry.js';
+import type { LynxUIPluginName, LynxUIPluginOptionsMap } from './plugins/lynx-ui/plugin-registry.js';
 import type { CorePluginsConfig } from './types/tailwind-types.js';
 export declare const DEFAULT_CORE_PLUGINS: CorePluginsConfig;
 export type LynxPluginsOption = boolean | LynxPluginName[] | Partial<Record<LynxPluginName, boolean>>;
+export type LynxUIPluginsOption = boolean | LynxUIPluginName[] | Partial<{
+    [K in LynxUIPluginName]: boolean | LynxUIPluginOptionsMap[K];
+}>;
 export declare function toEnabledSet(opt?: LynxPluginsOption): Set<LynxPluginName>;
+export declare function toEnabledLynxUIPluginSet(opt?: LynxUIPluginsOption): Set<LynxUIPluginName>;
+export declare function resolveUIPluginEntries(raw: LynxUIPluginsOption): {
+    [K in LynxUIPluginName]: [K, LynxUIPluginOptionsMap[K] | undefined];
+}[LynxUIPluginName][];
 export declare const getReplaceablePlugins: () => readonly LynxPluginName[];
 export declare const isPluginReplaceable: (p: string) => p is LynxPluginName;
-export type { LynxPluginName };
-export { LYNX_PLUGIN_MAP, ORDERED_LYNX_PLUGIN_NAMES };
+export type { LynxPluginName, LynxUIPluginName, LynxUIPluginOptionsMap };
+export { LYNX_PLUGIN_MAP, ORDERED_LYNX_PLUGIN_NAMES, LYNX_UI_PLUGIN_MAP, ORDERED_LYNX_UI_PLUGIN_NAMES, };
 /** svg-related plugins */
 /** filter-related plugins, only gradyscale and blur are supported*/
 /** backdrop-related plugins */

package/dist/helpers.d.ts

@@ -1,20 +1,13 @@
 import { formatBoxShadowValue, parseBoxShadowValue } from 'tailwindcss/lib/util/parseBoxShadowValue.js';
 import type { ShadowPart } from 'tailwindcss/lib/util/parseBoxShadowValue.js';
 import type { ThemeKey, ValueTransformer } from 'tailwindcss/lib/util/transformThemeValue.js';
-import type { Bound, BoundedPluginCreator, PluginFn, UtilityPluginOptions, UtilityVariations } from './types/plugin-types.js';
-import type { Config, Plugin, PluginCreator } from './types/tailwind-types.js';
+import type { Bound, CreatePluginFunction, PluginWithOptions, UtilityPluginOptions, UtilityVariations } from './types/plugin-types.js';
+import type { Plugin, PluginCreator } from './types/tailwind-types.js';
+declare const createPlugin: CreatePluginFunction;
 /**
- * Wraps a Tailwind PluginCreator and auto-binds all function properties of the API.
+ * Type guard
  */
-declare function createPlugin(fn: BoundedPluginCreator, cfg?: Partial<Config>): {
-    handler: PluginCreator;
-    config?: Partial<Config> | undefined;
-};
-declare function createPluginWithName(name: string, fn: BoundedPluginCreator, cfg?: Partial<Config>): {
-    handler: PluginCreator;
-    config?: Partial<Config> | undefined;
-};
-export declare const plugin: PluginFn;
+declare function isPluginWithOptions<T = unknown>(plugin: unknown): plugin is PluginWithOptions<T>;
 /**
  * Returns a shallow clone of the object where all function values
  * are bound with `this` set to `undefined`,
@@ -31,8 +24,8 @@ declare function autoBind<T extends object>(obj: T): Bound<T>;
  * For internal use in Lynx plugin system.
  */
 declare function createUtilityPlugin(themeKey: string, utilityVariations?: UtilityVariations, options?: UtilityPluginOptions): PluginCreator;
-export { createUtilityPlugin, createPlugin, createPluginWithName, autoBind };
-export type { Plugin };
+export { createUtilityPlugin, createPlugin, autoBind, isPluginWithOptions };
+export type { Plugin, PluginWithOptions };
 export declare const transformThemeValue: (key: ThemeKey) => ValueTransformer;
 export { parseBoxShadowValue, formatBoxShadowValue };
 export type { ShadowPart };

package/dist/lynx.cjs

@@ -41,28 +41,27 @@ var createUtilityPlugin_js_default = /*#__PURE__*/ __webpack_require__.n(createU
 require("tailwindcss/lib/util/parseBoxShadowValue.js");
 const transformThemeValue_js_namespaceObject = require("tailwindcss/lib/util/transformThemeValue.js");
 var transformThemeValue_js_default = /*#__PURE__*/ __webpack_require__.n(transformThemeValue_js_namespaceObject);
-function createPlugin(fn, cfg) {
+function createPluginImpl(fn, cfg) {
     return {
         handler: (api)=>fn(autoBind(api)),
         config: cfg
     };
 }
-function basePlugin(pluginFn, cfg) {
-    return {
-        handler: pluginFn,
-        config: cfg
+createPluginImpl.withOptions = withOptions;
+const createPlugin = createPluginImpl;
+function withOptions(pluginFn, configFn = ()=>({})) {
+    const optionsFunction = function(options) {
+        return {
+            __options: options,
+            handler: (api)=>pluginFn(options)(autoBind(api)),
+            config: configFn(options)
+        };
     };
+    optionsFunction.__isOptionsFunction = true;
+    optionsFunction.__pluginFunction = pluginFn;
+    optionsFunction.__configFunction = configFn;
+    return optionsFunction;
 }
-function pluginImpl(pluginFn, cfg) {
-    const wrapped = (api)=>pluginFn(autoBind(api));
-    return basePlugin(wrapped, cfg);
-}
-function withOptions(factory, cfgFactory) {
-    const optionsFn = (options)=>basePlugin((api)=>factory(options)(autoBind(api)), cfgFactory?.(options));
-    optionsFn.__isOptionsFunction = true;
-    return optionsFn;
-}
-pluginImpl.withOptions = withOptions;
 function autoBind(obj) {
     return Object.fromEntries(Object.entries(obj).map(([k, v])=>isFunction(v) ? [
             k,
@@ -929,6 +928,69 @@ const LYNX_PLUGIN_ENTRIES = [
 const plugin_registry_LYNX_PLUGIN_MAP = Object.fromEntries(LYNX_PLUGIN_ENTRIES);
 const ORDERED_LYNX_PLUGIN_NAMES = LYNX_PLUGIN_ENTRIES.map(([n])=>n);
 const plugin_registry_REPLACEABLE_LYNX_PLUGINS = ORDERED_LYNX_PLUGIN_NAMES.filter((n)=>'defaults' !== n);
+const DEFAULT_PREFIXES = {
+    ui: [
+        'active',
+        'disabled',
+        'readonly',
+        'checked',
+        'selected',
+        'open',
+        'leaving',
+        'entering',
+        'animating',
+        'busy'
+    ],
+    'ui-side': [
+        'left',
+        'right',
+        'top',
+        'bottom'
+    ],
+    'ui-align': [
+        'start',
+        'end',
+        'center'
+    ]
+};
+const uiVariants = createPlugin.withOptions((options)=>({ matchVariant })=>{
+        options = options ?? {};
+        const resolvedPrefixes = normalizePrefixes(options?.prefixes);
+        const entries = Object.entries(resolvedPrefixes);
+        for (const [prefix, states] of entries){
+            const stateEntries = Array.isArray(states) ? states.map((k)=>[
+                    k,
+                    k
+                ]) : Object.entries(states);
+            const valueMap = Object.fromEntries(stateEntries);
+            matchVariant(prefix, (value, { modifier } = {})=>{
+                const mapped = valueMap[value];
+                if (!mapped || 'string' != typeof mapped) return '';
+                const selector = `&.${prefix}-${mapped}`;
+                return modifier && 'string' == typeof modifier ? `${selector}\\/${modifier}` : selector;
+            }, {
+                values: valueMap
+            });
+        }
+    });
+function normalizePrefixes(input) {
+    if ('function' == typeof input) return input(DEFAULT_PREFIXES);
+    if (Array.isArray(input)) return Object.fromEntries(input.map((prefix)=>[
+            prefix,
+            DEFAULT_PREFIXES[prefix] ?? []
+        ]));
+    return input ?? {
+        ui: DEFAULT_PREFIXES.ui
+    };
+}
+const LYNX_UI_PLUGIN_ENTRIES = [
+    [
+        'uiVariants',
+        uiVariants
+    ]
+];
+const LYNX_UI_PLUGIN_MAP = Object.fromEntries(LYNX_UI_PLUGIN_ENTRIES);
+const ORDERED_LYNX_UI_PLUGIN_NAMES = LYNX_UI_PLUGIN_ENTRIES.map(([n])=>n);
 const DEFAULT_CORE_PLUGINS = [
     'animation',
     'aspectRatio',
@@ -997,6 +1059,39 @@ function toEnabledSet(opt = true) {
     else if (true === on) set.add(k);
     return set;
 }
+function toEnabledLynxUIPluginSet(opt = true) {
+    if (true === opt) return new Set(ORDERED_LYNX_UI_PLUGIN_NAMES);
+    if (false === opt) return new Set();
+    if (Array.isArray(opt)) return new Set(opt);
+    const set = new Set(ORDERED_LYNX_UI_PLUGIN_NAMES);
+    for (const [k, on] of Object.entries(opt))if (false === on) set.delete(k);
+    else if (true === on) set.add(k);
+    return set;
+}
+function resolveUIPluginEntries(raw) {
+    if (false === raw) return [];
+    if (true === raw) return ORDERED_LYNX_UI_PLUGIN_NAMES.map((n)=>[
+            n,
+            {}
+        ]);
+    if (Array.isArray(raw)) return ORDERED_LYNX_UI_PLUGIN_NAMES.filter((n)=>raw.includes(n)).map((n)=>[
+            n,
+            {}
+        ]);
+    const out = [];
+    for (const name of ORDERED_LYNX_UI_PLUGIN_NAMES){
+        const val = raw[name];
+        if (false !== val) if (true === val || void 0 === val) out.push([
+            name,
+            {}
+        ]);
+        else out.push([
+            name,
+            val
+        ]);
+    }
+    return out;
+}
 const lynxTheme = {
     boxShadow: {
         sm: '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
@@ -1093,18 +1188,24 @@ const lynxTheme = {
         }
     }
 };
-function createLynxPreset({ lynxPlugins = true, debug = false, theme } = {}) {
-    const enabled = toEnabledSet(lynxPlugins);
+function createLynxPreset({ lynxPlugins = true, lynxUIPlugins = false, debug = false, theme } = {}) {
+    const coreSetEnabled = toEnabledSet(lynxPlugins);
+    const uiSetEnabled = toEnabledLynxUIPluginSet(lynxUIPlugins);
     const defaultPluginName = 'defaults';
     const plugins = [
         plugin_registry_LYNX_PLUGIN_MAP[defaultPluginName]
     ];
     for (const name of ORDERED_LYNX_PLUGIN_NAMES)if ('defaults' !== name) {
-        if (enabled.has(name)) {
+        if (coreSetEnabled.has(name)) {
             plugins.push(plugin_registry_LYNX_PLUGIN_MAP[name]);
-            if (debug) console.debug(`[Lynx] enabled plugin: ${name}`);
+            if (debug) console.debug(`[Lynx] enabled core plugin: ${name}`);
         }
     }
+    for (const [name, options] of resolveUIPluginEntries(lynxUIPlugins))if (uiSetEnabled.has(name)) {
+        const fn = LYNX_UI_PLUGIN_MAP[name];
+        plugins.push(fn(options));
+        if (debug) console.debug(`[Lynx] enabled UI plugin: ${name}`);
+    }
     return {
         plugins,
         corePlugins: DEFAULT_CORE_PLUGINS,

package/dist/lynx.d.ts

@@ -1,11 +1,12 @@
 import type { Config } from 'tailwindcss';
-import type { LynxPluginName, LynxPluginsOption } from './core.js';
+import type { LynxPluginName, LynxPluginsOption, LynxUIPluginsOption } from './core.js';
 /**
  * Should be used with Tailwind v3+ (JIT is enabled by default) and configured with `content`,
  * otherwise the generated CSS bundle may include unused utilities.
  */
-declare function createLynxPreset({ lynxPlugins, debug, theme, }?: {
+declare function createLynxPreset({ lynxPlugins, lynxUIPlugins, debug, theme, }?: {
     lynxPlugins?: LynxPluginsOption;
+    lynxUIPlugins?: LynxUIPluginsOption;
     debug?: boolean;
     theme?: Config['theme'];
 }): Partial<Config>;

package/dist/lynx.js

@@ -1,28 +1,27 @@
 import createUtilityPlugin from "tailwindcss/lib/util/createUtilityPlugin.js";
 import "tailwindcss/lib/util/parseBoxShadowValue.js";
 import transformThemeValue from "tailwindcss/lib/util/transformThemeValue.js";
-function createPlugin(fn, cfg) {
+function createPluginImpl(fn, cfg) {
     return {
         handler: (api)=>fn(autoBind(api)),
         config: cfg
     };
 }
-function basePlugin(pluginFn, cfg) {
-    return {
-        handler: pluginFn,
-        config: cfg
+createPluginImpl.withOptions = withOptions;
+const createPlugin = createPluginImpl;
+function withOptions(pluginFn, configFn = ()=>({})) {
+    const optionsFunction = function(options) {
+        return {
+            __options: options,
+            handler: (api)=>pluginFn(options)(autoBind(api)),
+            config: configFn(options)
+        };
     };
+    optionsFunction.__isOptionsFunction = true;
+    optionsFunction.__pluginFunction = pluginFn;
+    optionsFunction.__configFunction = configFn;
+    return optionsFunction;
 }
-function pluginImpl(pluginFn, cfg) {
-    const wrapped = (api)=>pluginFn(autoBind(api));
-    return basePlugin(wrapped, cfg);
-}
-function withOptions(factory, cfgFactory) {
-    const optionsFn = (options)=>basePlugin((api)=>factory(options)(autoBind(api)), cfgFactory?.(options));
-    optionsFn.__isOptionsFunction = true;
-    return optionsFn;
-}
-pluginImpl.withOptions = withOptions;
 function autoBind(obj) {
     return Object.fromEntries(Object.entries(obj).map(([k, v])=>isFunction(v) ? [
             k,
@@ -889,6 +888,69 @@ const LYNX_PLUGIN_ENTRIES = [
 const plugin_registry_LYNX_PLUGIN_MAP = Object.fromEntries(LYNX_PLUGIN_ENTRIES);
 const ORDERED_LYNX_PLUGIN_NAMES = LYNX_PLUGIN_ENTRIES.map(([n])=>n);
 const plugin_registry_REPLACEABLE_LYNX_PLUGINS = ORDERED_LYNX_PLUGIN_NAMES.filter((n)=>'defaults' !== n);
+const DEFAULT_PREFIXES = {
+    ui: [
+        'active',
+        'disabled',
+        'readonly',
+        'checked',
+        'selected',
+        'open',
+        'leaving',
+        'entering',
+        'animating',
+        'busy'
+    ],
+    'ui-side': [
+        'left',
+        'right',
+        'top',
+        'bottom'
+    ],
+    'ui-align': [
+        'start',
+        'end',
+        'center'
+    ]
+};
+const uiVariants = createPlugin.withOptions((options)=>({ matchVariant })=>{
+        options = options ?? {};
+        const resolvedPrefixes = normalizePrefixes(options?.prefixes);
+        const entries = Object.entries(resolvedPrefixes);
+        for (const [prefix, states] of entries){
+            const stateEntries = Array.isArray(states) ? states.map((k)=>[
+                    k,
+                    k
+                ]) : Object.entries(states);
+            const valueMap = Object.fromEntries(stateEntries);
+            matchVariant(prefix, (value, { modifier } = {})=>{
+                const mapped = valueMap[value];
+                if (!mapped || 'string' != typeof mapped) return '';
+                const selector = `&.${prefix}-${mapped}`;
+                return modifier && 'string' == typeof modifier ? `${selector}\\/${modifier}` : selector;
+            }, {
+                values: valueMap
+            });
+        }
+    });
+function normalizePrefixes(input) {
+    if ('function' == typeof input) return input(DEFAULT_PREFIXES);
+    if (Array.isArray(input)) return Object.fromEntries(input.map((prefix)=>[
+            prefix,
+            DEFAULT_PREFIXES[prefix] ?? []
+        ]));
+    return input ?? {
+        ui: DEFAULT_PREFIXES.ui
+    };
+}
+const LYNX_UI_PLUGIN_ENTRIES = [
+    [
+        'uiVariants',
+        uiVariants
+    ]
+];
+const LYNX_UI_PLUGIN_MAP = Object.fromEntries(LYNX_UI_PLUGIN_ENTRIES);
+const ORDERED_LYNX_UI_PLUGIN_NAMES = LYNX_UI_PLUGIN_ENTRIES.map(([n])=>n);
 const DEFAULT_CORE_PLUGINS = [
     'animation',
     'aspectRatio',
@@ -957,6 +1019,39 @@ function toEnabledSet(opt = true) {
     else if (true === on) set.add(k);
     return set;
 }
+function toEnabledLynxUIPluginSet(opt = true) {
+    if (true === opt) return new Set(ORDERED_LYNX_UI_PLUGIN_NAMES);
+    if (false === opt) return new Set();
+    if (Array.isArray(opt)) return new Set(opt);
+    const set = new Set(ORDERED_LYNX_UI_PLUGIN_NAMES);
+    for (const [k, on] of Object.entries(opt))if (false === on) set.delete(k);
+    else if (true === on) set.add(k);
+    return set;
+}
+function resolveUIPluginEntries(raw) {
+    if (false === raw) return [];
+    if (true === raw) return ORDERED_LYNX_UI_PLUGIN_NAMES.map((n)=>[
+            n,
+            {}
+        ]);
+    if (Array.isArray(raw)) return ORDERED_LYNX_UI_PLUGIN_NAMES.filter((n)=>raw.includes(n)).map((n)=>[
+            n,
+            {}
+        ]);
+    const out = [];
+    for (const name of ORDERED_LYNX_UI_PLUGIN_NAMES){
+        const val = raw[name];
+        if (false !== val) if (true === val || void 0 === val) out.push([
+            name,
+            {}
+        ]);
+        else out.push([
+            name,
+            val
+        ]);
+    }
+    return out;
+}
 const lynxTheme = {
     boxShadow: {
         sm: '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
@@ -1053,18 +1148,24 @@ const lynxTheme = {
         }
     }
 };
-function createLynxPreset({ lynxPlugins = true, debug = false, theme } = {}) {
-    const enabled = toEnabledSet(lynxPlugins);
+function createLynxPreset({ lynxPlugins = true, lynxUIPlugins = false, debug = false, theme } = {}) {
+    const coreSetEnabled = toEnabledSet(lynxPlugins);
+    const uiSetEnabled = toEnabledLynxUIPluginSet(lynxUIPlugins);
     const defaultPluginName = 'defaults';
     const plugins = [
         plugin_registry_LYNX_PLUGIN_MAP[defaultPluginName]
     ];
     for (const name of ORDERED_LYNX_PLUGIN_NAMES)if ('defaults' !== name) {
-        if (enabled.has(name)) {
+        if (coreSetEnabled.has(name)) {
             plugins.push(plugin_registry_LYNX_PLUGIN_MAP[name]);
-            if (debug) console.debug(`[Lynx] enabled plugin: ${name}`);
+            if (debug) console.debug(`[Lynx] enabled core plugin: ${name}`);
         }
     }
+    for (const [name, options] of resolveUIPluginEntries(lynxUIPlugins))if (uiSetEnabled.has(name)) {
+        const fn = LYNX_UI_PLUGIN_MAP[name];
+        plugins.push(fn(options));
+        if (debug) console.debug(`[Lynx] enabled UI plugin: ${name}`);
+    }
     return {
         plugins,
         corePlugins: DEFAULT_CORE_PLUGINS,

package/dist/plugins/lynx-ui/index.d.ts

@@ -0,0 +1 @@
+export { uiVariants } from './uiVariants.js';

package/dist/plugins/lynx-ui/plugin-registry.d.ts

@@ -0,0 +1,20 @@
+import type { UIVariantsOptions } from './uiVariants.js';
+import type { PluginWithOptions } from '../../helpers.js';
+type Entry<K extends LynxUIPluginName> = readonly [
+    K,
+    PluginWithOptions<LynxUIPluginOptionsMap[K]>
+];
+interface LynxUIPluginOptionsMap {
+    uiVariants: UIVariantsOptions;
+}
+type LynxUIPluginName = keyof LynxUIPluginOptionsMap;
+export declare const LYNX_UI_PLUGIN_ENTRIES: readonly [
+    Entry<'uiVariants'>
+];
+type EntryUnion = typeof LYNX_UI_PLUGIN_ENTRIES[number];
+type PluginMap = {
+    [K in EntryUnion[0]]: Extract<EntryUnion, readonly [K, any]>[1];
+};
+export declare const LYNX_UI_PLUGIN_MAP: PluginMap;
+export declare const ORDERED_LYNX_UI_PLUGIN_NAMES: readonly LynxUIPluginName[];
+export type { LynxUIPluginName, LynxUIPluginOptionsMap };

package/dist/plugins/lynx-ui/uiVariants.d.ts

@@ -0,0 +1,32 @@
+import type { PluginWithOptions } from '../../helpers.js';
+import type { KeyValuePairOrList } from '../../types/plugin-types.js';
+declare const DEFAULT_PREFIXES: {
+    readonly ui: readonly ["active", "disabled", "readonly", "checked", "selected", "open", "leaving", "entering", "animating", "busy"];
+    readonly 'ui-side': readonly ["left", "right", "top", "bottom"];
+    readonly 'ui-align': readonly ["start", "end", "center"];
+};
+type DefaultPrefixMap = typeof DEFAULT_PREFIXES;
+type PrefixConfig = string[] | Record<string, KeyValuePairOrList> | ((defaults: DefaultPrefixMap) => Record<string, KeyValuePairOrList>);
+interface UIVariantsOptions {
+    /**
+     * Configures state-based variant prefixes.
+     *
+     * You can provide:
+     * - An array of prefixes to use their default states
+     * - Or an object mapping each prefix to an array or map of custom states.
+     * - An explicit object of prefix → values (array or map)
+     *
+     * @example
+     * prefixes: ['ui'] // → `ui-checked:*`, `ui-open:*` using default states
+     *
+     * @example
+     * prefixes: {
+     *   ui: ['checked', 'open'],
+     *   aria: { expanded: 'expanded', pressed: 'pressed' },
+     * }
+     */
+    prefixes?: PrefixConfig;
+}
+declare const uiVariants: PluginWithOptions<UIVariantsOptions>;
+export type { UIVariantsOptions };
+export { uiVariants };

package/dist/types/plugin-types.d.ts

@@ -1,4 +1,6 @@
 import type { Config, PluginAPI, PluginCreator, ValueType } from './tailwind-types.js';
+/** A flat structure of possible variant values, either list or key-value form. */
+type KeyValuePairOrList = Record<string, string> | string[] | ReadonlyArray<string>;
 /** Anything that is legal on the right-hand side of a CSS-in-JS object. */
 type CSSStatic = string | number | string[] | Record<string, unknown> | null | undefined;
 /**
@@ -27,24 +29,16 @@ type Bound<T> = {
     [K in keyof T]: T[K] extends (...args: infer _A) => infer _R ? OmitThisParameter<T[K]> : T[K];
 };
 type BoundedPluginCreator = (api: Bound<PluginAPI>) => void;
-interface OptionsFn<T> {
-    (options: T): {
-        handler: PluginCreator;
-        config?: Partial<Config>;
-    };
+interface PluginWithConfig {
+    handler: PluginCreator;
+    config?: Partial<Config> | undefined;
+}
+interface PluginWithOptions<T> {
+    (options?: T): PluginWithConfig;
     __isOptionsFunction: true;
 }
-interface PluginFn {
-    (pluginFn: BoundedPluginCreator, cfg?: Partial<Config>): {
-        handler: PluginCreator;
-        config?: Partial<Config> | undefined;
-    };
-    withOptions<T>(factory: (opts: T) => BoundedPluginCreator, cfgFactory?: (opts: T) => Partial<Config>): {
-        (opts: T): {
-            handler: PluginCreator;
-            config?: Partial<Config> | undefined;
-        };
-        __isOptionsFunction: true;
-    };
+interface CreatePluginFunction {
+    (pluginFn: BoundedPluginCreator, cfg?: Partial<Config>): PluginWithConfig;
+    withOptions<T>(pluginFn: (options?: T) => BoundedPluginCreator, configFn?: (options?: T) => Partial<Config>): PluginWithOptions<T>;
 }
-export type { CSSStatic, PropertyEntry, UtilityEntry, UtilityGroup, UtilityVariations, UtilityPluginOptions, BoundedPluginCreator, OptionsFn, PluginFn, Bound, };
+export type { CSSStatic, KeyValuePairOrList, PropertyEntry, UtilityEntry, UtilityGroup, UtilityVariations, UtilityPluginOptions, BoundedPluginCreator, Bound, CreatePluginFunction, PluginWithConfig, PluginWithOptions, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynx-js/tailwind-preset-canary",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "A tailwindcss preset for ReactLynx",
   "keywords": [
     "Lynx",