Velora UI - Modern React Component Library

Velora UI is built with customization in mind, leveraging the power of Tailwind CSS and CSS variables. This approach gives you granular control over the look and feel of your components without ejecting from the library.

Understanding CSS Variables

The primary way to customize Velora UI's colors and other design tokens is through CSS variables defined in your `app/globals.css` file. These variables are used by Tailwind CSS to generate the utility classes that style the components.

Default CSS Variables in `app/globals.css`

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%; /* This is your primary color */
    --primary-foreground: 210 40% 98%;
    /* ... other variables */
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%; /* Primary color for dark mode */
    --primary-foreground: 222.2 84% 4.9%;
    /* ... other variables */
  }
}
/* ... */

Each variable represents a specific design token (e.g., `--primary` for the main brand color). The values are HSL (Hue, Saturation, Lightness) color values.

Modifying Existing Colors

To change the default colors, simply update the HSL values for the corresponding CSS variables in your `app/globals.css`. For example, to change the primary color:

Example: Changing Primary Color

Let's change the primary color to a shade of green:

@layer base {
  :root {
    --primary: 142.1 76.2% 36.3%; /* A nice green */
    --primary-foreground: 355.7 100% 97.3%; /* Adjust foreground for contrast */
    /* ... */
  }

  .dark {
    --primary: 142.1 70.2% 45.3%; /* Darker green for dark mode */
    --primary-foreground: 355.7 100% 97.3%;
    /* ... */
  }
}

After saving, all components using `bg-primary`, `text-primary`, etc., will automatically reflect the new color.

Adding New Colors

You can also extend your Tailwind CSS configuration to add entirely new colors or shades.

Extend `tailwind.config.js`

First, define your new CSS variables in `app/globals.css`:

@layer base {
  :root {
    /* ... existing variables */
    --my-custom-color: 200 50% 50%;
  }
  .dark {
    /* ... existing variables */
    --my-custom-color: 200 50% 70%;
  }
}

Then, extend the `colors` object in your `tailwind.config.js`:

/** @type {import('tailwindcss').Config} */
module.exports = {
  // ...
  theme: {
    extend: {
      colors: {
        // ... existing colors
        'my-custom-color': 'hsl(var(--my-custom-color))',
      },
    },
  },
  // ...
}

Now you can use `bg-my-custom-color`, `text-my-custom-color`, etc., in your components.

Dark Mode Implementation

Velora UI comes with built-in dark mode support, leveraging `next-themes` and the CSS variables approach. The `ThemeProvider` component handles the theme switching.

Using `ThemeProvider` in `app/layout.tsx`

Ensure your `app/layout.tsx` wraps your application with `ThemeProvider`:

import { ThemeProvider } from "@/components/theme-provider"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

The `attribute="class"` prop tells `next-themes` to apply the `dark` class to the `html` element when dark mode is active, which then triggers the `--dark` CSS variables.

Component-Specific Customization

For more granular control, you can always override styles directly on components using Tailwind CSS utility classes.

Example: Overriding Button Styles

import { Button } from '@velora/ui'

export default function CustomButton() {
  return (
    <Button className="bg-purple-500 hover:bg-purple-600 text-white rounded-full px-6 py-3">
      Custom Purple Button
    </Button>
  )
}

Tailwind's utility-first approach makes it easy to apply custom styles directly to any component.

Conclusion

Velora UI's theming system provides a flexible and powerful way to ensure your application's UI perfectly matches your brand. By understanding and utilizing CSS variables and Tailwind CSS, you can create unique and consistent designs with ease.

Theming Guide: Customizing Velora UI