RubyUIPre Release

Theming

Using CSS variables for theming.

Introduction

Phlex UI uses CSS Variables like --primary: 0 0% 9% for theming. This allows you to easily customize the look and feel of your application.

There are two main benefits to this approach:

  • Easily customisable design by updating CSS variables, without having to update the RubyUI component.
  • Simpler implementation for both light and dark mode, by not having to duplicate the TailwindCSS class (e.g. bg-primary will work for both light and dark mode, without having to define both bg-primary and dark:bg-primary-dark - Or something else like that).

Convention

We use a simple background and foreground convention for colors. The background variable is used for the background color of the component and the foreground variable is used for the text color. This is similar to other component libraries that are popular in React and elsewhere, and it works well in our experience.

The background suffix is omitted when the variable is used for the background color of the component.

Given the following CSS variables:

--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;

The background color of the following component will be hsl(var(--primary)) and the foreground color will be hsl(var(--primary-foreground)).

<div className="bg-primary text-primary-foreground">We love Ruby</div>
CSS variables must be defined without color space function. See the Tailwind CSS documentation for more information.

List of variables

Here's the list of variables available for customization:

Default background color of <body>...etc

--background: 0 0% 100%;
--foreground: 222.2 47.4% 11.2%;

Muted backgrounds such as TabsList

--muted: 210 40% 96.1%;
--muted-foreground: 215.4 16.3% 46.9%;

Default border color

--border: 214.3 31.8% 91.4%;

Border color for inputs such as Input, Select or Textarea

--input: 214.3 31.8% 91.4%;

Primary colors for Button

--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;

Secondary colors for Button

--secondary: 210 40% 96.1%;
--secondary-foreground: 222.2 47.4% 11.2%;

Used for accents such as hover effects on DropdownMenu::Item, Select::Item... etc

--accent: 210 40% 96.1%;
--accent-foreground: 222.2 47.4% 11.2%;

Used for destructive actions such as Button.new(variant: :destructive)

--destructive: 0 100% 50%;
--destructive-foreground: 210 40% 98%;

Used for focus ring

--ring: 215 20.2% 65.1%;

Border radius for card, input and buttons

--radius: 0.5rem;

Adding new colors

To add new colors, you need to add them to your application.tailwind.css file and to your tailwind.config.js file.

app/stylesheets/application.tailwind.css

:root {
  --contrast: 38 92% 50%;
  --contrast-foreground: 48 96% 89%;
}

.dark {
  --contrast: 48 96% 89%;
  --contrast-foreground: 38 92% 50%;
}

tailwind.config.js

module.exports = {
  theme: {
    extend: {
      colors: {
        contrast: "hsl(var(--contrast))",
        "contrast-foreground": "hsl(var(--contrast-foreground))",
      },
    },
  },
}

You can now use the contrast and contrast-foreground variables in your application.

<div className="bg-contrast text-contrast-foreground">We love Ruby</div>

Other color formats

It's recommended to use HSL colors for your application. However, you can also use other color formats such as rgb or rgba.

See Tailwind CSS documentation for more information on how to use rgb, rgba or hsl colors.