RubyUI1.0

Theming

Using CSS variables for theming.

Introduction

RubyUI uses CSS Variables like --primary: oklch(0.205 0 0) for theming. This approach is inspired by shadcn/ui and 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: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);

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

<div className="bg-primary text-primary-foreground">We love Ruby</div>
RubyUI uses oklch color format, the same format used by shadcn/ui. 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: oklch(1 0 0);
--foreground: oklch(0.145 0 0);

Muted backgrounds such as TabsList

--muted: oklch(0.97 0 0);
--muted-foreground: oklch(0.556 0 0);

Default border color

--border: oklch(0.922 0 0);

Border color for inputs such as Input, Select or Textarea

--input: oklch(0.922 0 0);

Primary colors for Button

--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);

Secondary colors for Button

--secondary: oklch(0.97 0 0);
--secondary-foreground: oklch(0.205 0 0);

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

--accent: oklch(0.97 0 0);
--accent-foreground: oklch(0.205 0 0);

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

--destructive: oklch(0.577 0.245 27.325);
--destructive-foreground: oklch(0.577 0.245 27.325);

Used for focus ring

--ring: oklch(0.708 0 0);

Border radius for card, input and buttons

--radius: 0.625rem;

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: oklch(0.75 0.18 85);
  --contrast-foreground: oklch(0.25 0.05 85);
}

.dark {
  --contrast: oklch(0.85 0.15 85);
  --contrast-foreground: oklch(0.2 0.05 85);
}

application.tailwind.css (inside @theme inline)

@theme inline {
  --color-contrast: var(--contrast);
  --color-contrast-foreground: 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>

Color format (oklch)

RubyUI uses oklch colors as the default color format. This is the same format used by shadcn/ui and provides better perceptual uniformity and wider color gamut support.

While oklch is recommended, you can also use other color formats such as hsl, rgb, or rgba. See the Tailwind CSS documentation for more information.

shadcn/ui themes

RubyUI themes use the same CSS variable convention as shadcn/ui. This means you can copy themes directly from shadcn/ui themes and use them in your RubyUI application.

Visit the RubyUI themes page to preview and copy themes, just like you would on shadcn/ui.