Skip to main content

​
Overview

This guide covers breaking changes and migration steps between major versions of Luminescent UI. Always read the full changelog before upgrading.

​
Version 6.x to Latest

​
6.4.21 - Alpha Variable Removal

The --lum-default-alpha variable has been removed. Alpha values are now set directly in color variables.
What Changed:
  • Removed --lum-default-alpha CSS variable
  • Alpha values now use Tailwind’s --alpha() helper directly
Migration Steps:
1

Update CSS variables

Remove any references to --lum-default-alpha:
Before
@theme {
  --lum-default-alpha: 80;
}
After
/* No longer needed - remove this variable */
2

Use alpha in color utilities

Apply alpha directly using the / syntax:
{/* Alpha is now part of the color utility */}
<div className="lum-bg-gray-800/80">
  Semi-transparent background
</div>

​
6.1.0 - Depth System Introduction

What’s New:
  • Added --lum-depth variable for depth-based styling
  • lum-bg-* classes now support depth-aware borders and shadows
  • Enhanced lum-toggle-bg utility with depth effects
Migration: No breaking changes, but you can now enable depth effects:
global.css
@theme {
  --lum-depth: 0; /* Default - no depth effects */
}

/* Or enable depth */
@theme {
  --lum-depth: 1; /* Depth effects enabled */
}
Depth effects include:
  • Borders that fade out based on depth value
  • Inset shadows for depth perception
  • Drop shadows for elevation

​
Version 5.x to 6.x

​
5.2.0 - Toggle Component Label Change

The Toggle component’s label prop has been removed. Labels are now passed as children.
Migration Steps: 
<Toggle id="toggle-input" label="Enable notifications" />
Why This Change?
  • More flexible content in labels (icons, badges, etc.)
  • Consistent with other component APIs
  • Better TypeScript type inference

​
Version 4.x to 5.x

​
5.0.0 - Text Color Variables

What Changed:
  • Updated text color variables to use semantic naming
  • New variables: --color-lum-text and --color-lum-text-secondary
Migration Steps:
1

Update theme variables

Before
@theme {
  --color-text-primary: var(--color-gray-50);
  --color-text-muted: var(--color-gray-400);
}
After
@theme {
  --color-lum-text: var(--color-gray-50);
  --color-lum-text-secondary: var(--color-gray-400);
}
2

Update utility classes

Replace old text color classes:
Before
<p className="text-gray-50">Primary text</p>
<p className="text-gray-400">Secondary text</p>
After
<p className="text-lum-text">Primary text</p>
<p className="text-lum-text-secondary">Secondary text</p>

​
5.0.0 - Additional Color Variables

New Variables Added: 
@theme {
  --color-lum-card-bg: var(--color-gray-900);
  --color-lum-input-bg: var(--color-gray-800);
  --color-lum-input-hover-bg: var(--color-gray-700);
  --color-lum-accent: var(--color-blue-500);
}
Benefits:
  • Easier theme customization
  • Consistent color usage across components
  • Better dark/light mode support

​
Version 3.x to 4.x

​
4.2.0 - SelectMenu Full Width

The SelectMenu component now takes full width of its parent by default.
What Changed:
  • SelectMenu is now width: 100% by default
  • Added align prop: 'left', 'center', or 'right'
  • Added theme colors to formatting
Migration Steps:
1

Update width if needed

If you want the old behavior (auto width):
Before
<SelectMenu options={options} />
After
<SelectMenu className="w-auto" options={options} />
2

Use align prop for positioning

<SelectMenu 
  options={options} 
  align="right" {/* or 'left', 'center' */}
/>

​
4.0.0 - lum-bg Import Change

Major change: lum-bg plugin no longer requires separate import.
What Changed:
  • lum-bg utilities are now included in the main CSS file
  • Simplified import structure
  • Toggle component rewritten to use new lum-bg classes
Migration Steps:
1

Update CSS imports

Before
@import '@luminescent/ui/css';
@plugin '@luminescent/ui/lum-bg';
After
@import '@luminescent/ui/css';
2

Update Toggle components

The Toggle component now uses utility classes for styling:
Before
<Toggle 
  id="toggle-input" 
  label="Toggle" 
  onColor="green" 
  offColor="slate" 
/>
After
<Toggle 
  id="toggle-input" 
  className="lum-toggle-bg-slate-600 peer-checked:lum-toggle-bg-green-600"
>
  Toggle
</Toggle>
3

Configure theme variables

New customization options available:
global.css
@theme {
  --lum-btn-p-x: 2;
  --lum-input-p-x: 1.5;
  --lum-border-radius: var(--radius-md);
  --lum-border-mix: 20%;
  --color-lum-border: var(--color-gray-400);
}
New Features in 4.0.0:
Apply the default border radius to any element:
<div className="rounded-lum">
  Uses theme border radius
</div>

{/* Nested elements */}
<div className="rounded-lum p-2">
  <div className="rounded-lum-2">
    Adjusted for padding
  </div>
</div>
Create gradient borders:
<div className="border-gradient-1 before:from-blue-500 before:to-purple-500">
  Gradient border
</div>

<div className="border-gradient-2 before:bg-gradient-to-r before:from-blue-500 before:to-purple-500">
  Directional gradient
</div>
Mouse-tracking effect for interactive cards:
import { Hoverable } from '@luminescent/ui-qwik';

<div 
  className="lum-card lum-hoverable" 
  onMouseMove$={(e, el) => Hoverable.onMouseMove$(e, el)} 
  onMouseLeave$={(e, el) => Hoverable.onMouseLeave$(e, el)}
>
  Follows mouse cursor
</div>
Pop-out effect on hover:
<div className="lum-card lum-hoverable">
  Scales up on hover
</div>

​
Version 2.x to 3.x

​
3.0.1 - Import Restructuring

What Changed:
  • Renamed imports for clarity
  • New formatting import for default element styling
  • Icon size property renamed from width to size
  • Dropdown renamed to SelectMenu
Migration Steps:
1

Update CSS imports

Before
@import '@luminescent/ui/css';
@plugin '@luminescent/ui';
After
@import '@luminescent/ui';
@plugin '@luminescent/ui/lum-bg';
2

Add formatting (optional)

For default element styling:
@import '@luminescent/ui/formatting';
3

Update icon components

Before
<LogoLuminescent width={20} />
After
<LogoLuminescent size={20} />
4

Migrate Dropdown to SelectMenu

Before
<Dropdown display={<p>Dropdown uwu</p>}>
  Dropdown
  <button q:slot="extra-buttons" className="lum-btn lum-bg-transparent">
    Option 4
  </button>
</Dropdown>
After
<SelectMenu customDropdown>
  Select Menu
  <p q:slot="dropdown">
    Select Menu uwu
  </p>
  <button q:slot="extra-buttons" className="lum-btn lum-bg-transparent">
    Option 4
  </button>
</SelectMenu>
5

Update to Lucide icons

Icons now use Lucide. Update any custom icon usage accordingly.

​
Version 1.x to 2.x

​
2.1.0 - Header Component Removal

The Header component has been removed. Use semantic HTML with utility classes instead.
Migration Steps:
Before
<Header>
  This is a header
</Header>
After
<h2 className="text-xl font-bold whitespace-nowrap text-white sm:text-2xl">
  This is a header
</h2>
Before
<Header id="anchor" anchor>
  This is a header with an anchor
</Header>
After
<Anchor id="anchor">
  <h2 className="text-xl font-bold whitespace-nowrap text-white sm:text-2xl">
    This is a header with an anchor
  </h2>
</Anchor>
Before
<Header subheader="This is a subheader">
  This is a header with a subheader
</Header>
After
<h2 className="text-xl font-bold whitespace-nowrap text-white sm:text-2xl">
  This is a header with a subheader
</h2>
<h3 className="text-sm text-lum-text-secondary">
  This is a subheader
</h3>

​
2.0.0 - Tailwind CSS v4 Migration

This is a major breaking change requiring Tailwind CSS v4.
What Changed:
  • Updated to Tailwind CSS v4
  • Replaced lum-pad classes with numeric values
  • New padding utility naming convention
Migration Steps:
1

Upgrade Tailwind CSS

npm install tailwindcss@next @tailwindcss/postcss@next
2

Update padding utilities

Replace old lum-pad classes:
BeforeAfterSuggested
lum-pad-xspx-2.5 py-1.5lum-btn-p-1
lum-pad-smpx-3 py-2lum-btn-p-2
lum-pad-md-lum-btn-p-2
lum-pad-lgpx-7 py-4lum-btn-p-3
lum-pad-xl-lum-btn-p-4
lum-pad-2xl-lum-btn-p-5
lum-pad-3xl-lum-btn-p-6
lum-pad-4xl-lum-btn-p-7
lum-pad-5xl-lum-btn-p-8
3

Update equal padding classes

BeforeAfter
lum-pad-equal-xsp-1.5
lum-pad-equal-smp-2
lum-pad-equal-mdp-2
lum-pad-equal-lgp-4
lum-pad-equal-xlp-4
lum-pad-equal-2xlp-5
lum-pad-equal-3xlp-6
lum-pad-equal-4xlp-7
lum-pad-equal-5xlp-8

​
General Migration Tips

Test IncrementallyDon’t migrate everything at once. Update components one at a time and test thoroughly.
Use Search & ReplaceMany migrations can be automated with find-and-replace across your codebase:
# Example: Update Toggle labels
find . -name "*.tsx" -exec sed -i 's/label="\([^"]*\)"/>{\1}</g' {} +
Check the ChangelogAlways review the full changelog at the GitHub repository for additional context and minor changes.
Update DependenciesAfter migrating, ensure all related packages are up to date:
npm update @luminescent/ui @luminescent/ui-qwik

​
Need Help?

If you encounter issues during migration:
  1. Check the GitHub Issues
  2. Review component-specific documentation
  3. Join the community discussions
  4. Create a new issue with your migration problem

​
Related Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us