Troubleshooting

Overview

This guide covers common problems you might encounter when using Luminescent UI and their solutions.

Installation Issues

Package Not Found

Error: Cannot find package '@luminescent/ui'

Problem:

Error: Cannot find package '@luminescent/ui'

Solution:

Verify package name

Ensure you’re using the correct package name:

npm install @luminescent/ui

For Qwik-specific components:

npm install @luminescent/ui-qwik

Clear npm cache

npm cache clean --force
npm install

Check npm registry

Ensure you’re connected to npm registry:

npm config get registry
# Should return: https://registry.npmjs.org/

Peer Dependency Warnings

Warning: Peer dependency version mismatch

Problem:

WARNING: peer dependencies not met

Solution:Luminescent UI requires Tailwind CSS v4. Update your dependencies:

npm install tailwindcss@next @tailwindcss/postcss@next

If using Qwik:

npm install @builder.io/qwik@latest

Tailwind CSS v4 Issues

Utilities Not Working

lum-bg-* or other utilities not applying

Problem: Luminescent UI utilities like lum-bg-*, lum-btn, or lum-card are not being applied.Solution:

Verify Tailwind CSS v4

Ensure you’re using Tailwind CSS v4:

package.json

{
  "dependencies": {
    "tailwindcss": "^4.0.0",
    "@tailwindcss/postcss": "^4.0.0"
  }
}

Check CSS imports

Verify your CSS file includes the correct import:

global.css

@import '@luminescent/ui/css';

For versions before 4.0.0, you also needed:

@plugin '@luminescent/ui/lum-bg';

This is no longer required in v4.0.0+

Configure PostCSS

Ensure PostCSS is configured:

postcss.config.js

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Restart dev server

After configuration changes, restart your development server:

# Stop the server (Ctrl+C)
npm run dev

CSS Import Errors

Error: Cannot find module '@luminescent/ui/css'

Problem:

Error: Cannot find module '@luminescent/ui/css'

Solution:

Check package installation

npm list @luminescent/ui

If not installed:

npm install @luminescent/ui

Verify import path

The correct import for v4.0.0+ is:

@import '@luminescent/ui/css';

For v3.x:

@import '@luminescent/ui';

Clear build cache

rm -rf node_modules/.cache
rm -rf .next  # or your build directory
npm run dev

Theme Variables Not Applied

Custom theme variables not working

Problem: Custom theme variables defined in @theme are not being applied.Solution:

Use @theme directive

With Tailwind CSS v4, use the @theme directive:

global.css

@import '@luminescent/ui/css';

@theme {
  --lum-border-radius: 12px;
  --color-lum-card-bg: var(--color-gray-900);
  --lum-depth: 1;
}

Don't use :root

In Tailwind CSS v4, don’t use :root for theme variables:

Wrong

:root {
  --lum-border-radius: 12px; /* Won't work */
}

Check variable names

Ensure you’re using the correct variable names. See available variables:

@theme {
  /* Spacing & Layout */
  --lum-btn-p-x: 2;
  --lum-input-p-x: 1.5;
  --lum-border-radius: var(--radius-lg);
  --lum-border-superellipse: 1;
  
  /* Visual Effects */
  --lum-border-mix: 20%;
  --lum-depth: 0;
  --lum-gradient-mix: 20%;
  --lum-gradient-angle: 180deg;
  
  /* Colors */
  --color-lum-border: var(--color-gray-300);
  --color-lum-gradient: var(--color-gray-950);
  --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);
  --color-lum-text: var(--color-gray-50);
  --color-lum-text-secondary: var(--color-gray-400);
}

Component Issues

Components Not Rendering

Component imports not working

Problem:

import { Button } from '@luminescent/ui';
// Error: Module not found

Solution:

Use framework-specific packages

Luminescent UI components are framework-specific. For Qwik:

Qwik

import { Toggle, SelectMenu } from '@luminescent/ui-qwik';

The base @luminescent/ui package only provides CSS utilities, not React/Qwik components.

Build your own components

Alternatively, build custom components using the utilities:

export function Button({ children, ...props }) {
  return (
    <button className="lum-btn rounded-lum" {...props}>
      {children}
    </button>
  );
}

Toggle Component Issues

Toggle not working after upgrade

Problem: Toggle component stopped working after upgrading to v5.2.0+Solution:The label prop was changed to use children in v5.2.0:

Before (v5.1.x)

<Toggle id="my-toggle" label="Enable feature" />

After (v5.2.0+)

<Toggle id="my-toggle">
  Enable feature
</Toggle>

For v4.0.0, Toggle also requires utility classes:

v4.0.0+

<Toggle 
  id="my-toggle"
  className="lum-toggle-bg-gray-600 peer-checked:lum-toggle-bg-blue-600"
>
  Enable feature
</Toggle>

SelectMenu Styling Issues

SelectMenu taking full width unexpectedly

Problem: After upgrading to v4.2.0, SelectMenu takes full width.Solution:This is intentional behavior in v4.2.0+. To restore auto width:

<SelectMenu className="w-auto" options={options} />

Or set a specific width:

<SelectMenu className="w-64" options={options} />

Styling Issues

Styles Not Applied

Utility classes not working

Problem: Utility classes like lum-btn, lum-card, etc. have no effect.Solution:

Ensure CSS is imported

Check that your global CSS file is imported in your app:

_app.tsx / layout.tsx

import './globals.css';

Verify import order

Luminescent UI CSS should be imported before your custom styles:

globals.css

@import '@luminescent/ui/css';

@theme {
  /* Your customizations */
}

/* Your custom CSS */
.my-custom-class {
  /* ... */
}

Check for CSS conflicts

Ensure no other CSS is overriding Luminescent UI styles:

/* Bad - too specific, will override lum-btn */
button.my-button {
  padding: 10px;
}

/* Good - use utility classes */
<button className="lum-btn my-button" />

Border Radius Not Applied

rounded-lum not working

Problem: The rounded-lum utility is not applying border radius.Solution:

Set border radius variable

Ensure --lum-border-radius is defined:

global.css

@theme {
  --lum-border-radius: var(--radius-lg);
}

Check browser support

The corner-shape: superellipse() property may not be supported in all browsers. It degrades gracefully to regular border-radius.

Verify class application

Use browser DevTools to check if the class is applied:

.rounded-lum {
  border-radius: var(--lum-border-radius);
  corner-shape: superellipse(var(--lum-border-superellipse));
}

Depth Effects Not Visible

Depth effects not showing

Problem: Depth effects (shadows, borders) are not visible on components.Solution:Depth is disabled by default. Enable it:

global.css

@theme {
  --lum-depth: 1; /* Enable depth effects */
}

To disable:

@theme {
  --lum-depth: 0; /* Disable depth effects */
}

Depth effects include:

Fading borders
Inset shadows
Drop shadows for elevation

Build & Production Issues

Production Build Failures

Build fails with Tailwind CSS errors

Problem:

Error: PostCSS plugin @tailwindcss/postcss failed

Solution:

Verify PostCSS config

postcss.config.js

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Check for version conflicts

npm list tailwindcss
# Should show only v4.x

If multiple versions:

npm dedupe

Clear cache and rebuild

rm -rf node_modules/.cache
rm -rf .next  # or your build directory
npm run build

Purged CSS in Production

Styles work in dev but not production

Problem: Styles work in development but are missing in production builds.Solution:

Check dynamic class names

Avoid dynamic class names:

Bad

const color = 'blue';
<div className={`lum-bg-${color}-600`} /> {/* Won't work */}

Good

const colorClass = color === 'blue' 
  ? 'lum-bg-blue-600' 
  : 'lum-bg-gray-600';
<div className={colorClass} />

Use safelist for dynamic classes

If you must use dynamic classes, add them to safelist:

tailwind.config.js

export default {
  safelist: [
    'lum-bg-blue-600',
    'lum-bg-green-600',
    'lum-bg-red-600',
  ],
};

TypeScript Issues

Type Errors

TypeScript errors for component props

Problem:

Property 'customProp' does not exist on type 'IntrinsicAttributes'

Solution:

Check component props

Ensure you’re passing valid props. Check component documentation for available props.

Extend component types

For custom components, properly type your props:

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'default' | 'primary' | 'danger';
  size?: 'sm' | 'md' | 'lg';
}

export function Button({ variant = 'default', size = 'md', ...props }: ButtonProps) {
  // ...
}

Framework-Specific Issues

Qwik Issues

Hoverable effect not working

Problem: The lum-hoverable mouse tracking effect doesn’t work.Solution:

The mouse-tracking hover effect is Qwik-only. It requires Qwik’s signal system.

Qwik Only

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)}
>
  Content
</div>

For React/Next.js, use the CSS-only lum-hoverable class which provides a simple scale effect.

Next.js Issues

Styles flashing on page load

Problem: Unstyled content flashes before styles are applied.Solution:

Ensure CSS is in layout

Import CSS in your root layout:

app/layout.tsx

import './globals.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Use CSS modules for critical styles

For above-the-fold content, consider CSS modules to ensure styles are bundled.

Performance Issues

Slow Build Times

Tailwind CSS build is slow

Problem: Build times are significantly slower after adding Luminescent UI.Solution:

Limit content scanning

In tailwind.config.js, only scan necessary files:

export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Don't scan node_modules unnecessarily
  ],
};

Enable JIT mode

Tailwind CSS v4 uses JIT by default, but ensure it’s not disabled.

Consider caching

Use build caching in your CI/CD pipeline:

.github/workflows/build.yml

- name: Cache node modules
  uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Still Having Issues?

Enable Debug ModeAdd debug output to see what Tailwind is processing:

DEBUG=* npm run dev

Check Browser ConsoleOpen browser DevTools (F12) and check:

Console for errors
Network tab for failed CSS loads
Elements tab to inspect applied styles

Minimal ReproductionCreate a minimal example to isolate the issue:

Start with a fresh project
Install only Luminescent UI
Add the minimal code that reproduces your issue
Share the reproduction when asking for help

Getting Help

If you’ve tried these solutions and still have issues:

Search existing issues: Check GitHub Issues
Create a new issue: Include:
- Luminescent UI version
- Framework and version (Qwik, Next.js, etc.)
- Minimal code reproduction
- Error messages
- Steps to reproduce
Join the community: Ask in community forums or discussions

Installation Guide - Initial setup
Migration Guide - Version upgrade instructions
GitHub Issues - Report bugs

Styling

Advanced

Overview

Installation Issues

Package Not Found

Peer Dependency Warnings

Tailwind CSS v4 Issues

Utilities Not Working

CSS Import Errors

Theme Variables Not Applied

Component Issues

Components Not Rendering

Toggle Component Issues

SelectMenu Styling Issues

Styling Issues

Styles Not Applied

Border Radius Not Applied

Depth Effects Not Visible

Build & Production Issues

Production Build Failures

Purged CSS in Production

TypeScript Issues

Type Errors

Framework-Specific Issues

Qwik Issues

Next.js Issues

Performance Issues

Slow Build Times

Still Having Issues?

Getting Help

Build docs developers (and LLMs) love

Styling

Advanced

​Overview

​Installation Issues

​Package Not Found

​Peer Dependency Warnings

​Tailwind CSS v4 Issues

​Utilities Not Working

​CSS Import Errors

​Theme Variables Not Applied

​Component Issues

​Components Not Rendering

​Toggle Component Issues

​SelectMenu Styling Issues

​Styling Issues

​Styles Not Applied

​Border Radius Not Applied

​Depth Effects Not Visible

​Build & Production Issues

​Production Build Failures

​Purged CSS in Production

​TypeScript Issues

​Type Errors

​Framework-Specific Issues

​Qwik Issues

​Next.js Issues

​Performance Issues

​Slow Build Times

​Still Having Issues?

​Getting Help

​Related Resources

Build docs developers (and LLMs) love

Overview

Installation Issues

Package Not Found

Peer Dependency Warnings

Tailwind CSS v4 Issues

Utilities Not Working

CSS Import Errors

Theme Variables Not Applied

Component Issues

Components Not Rendering

Toggle Component Issues

SelectMenu Styling Issues

Styling Issues

Styles Not Applied

Border Radius Not Applied

Depth Effects Not Visible

Build & Production Issues

Production Build Failures

Purged CSS in Production

TypeScript Issues

Type Errors

Framework-Specific Issues

Qwik Issues

Next.js Issues

Performance Issues

Slow Build Times

Still Having Issues?

Getting Help

Related Resources