Documentation
Guide
Customization

Customization & Themes

Customization allows our uses to personalize the appearance of UI by theming.

Sira comes with a default theme that you can use to build your website or application with no customization, in this section you will see how to customize the theme.

Use Sira will apply some base layer style on your site automatically.

Theme

The theme is a collection of properties to customize the appearance of your sira.

You can also create your own theme or remove the built-in themes.

To use this feature go to your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  plugins: [
    require('@sira-ui/tailwind')({
      ...config,
    }),
  ],
};

Themes

Use the themes array property to control all sira themes.

Theme Object

The themes array property accept such object value:

  • name name of this theme, which will be used in root element attribute data-theme for switching between themes.
  • colorScheme actual color scheme of this theme, light or dark, decide what built-in theme will be merged to it.
  • colors color names of this theme, choose your own (default built-in colors merged), sira will generate 50-1100 palette for this color name, and className for styling.
  • prefersColorScheme boolean property, set a preference theme in specified colorScheme, will enable the preference theme in such media query @media (prefers-color-scheme:${theme.colorScheme || "light"}). (only work for one theme, multiple themes enable this property will only work for the last theme.)
module.exports = {
  plugins: [
    require('@sira-ui/tailwind')({
      themes: [
        {
          name: 'custom',
          colorScheme: 'dark' | 'light',
          prefersColorScheme: true,
          colors: {
            primary: '#634673',
            secondary: '#583533',
          },
        },
      ],
    }),
  ],
};

Colors

Sira uses RadixUI Colors (opens in a new tab) as the base for the default theme, you can see how to use the colors below.

We follow color reference below:

ScaleDescription
50App background
100Subtle background
200UI element background
300Hovered UI element background
400Active / Selected UI element background
500Subtle borders and separators
600UI element border and focus rings
700Hovered UI element border
800Solid backgrounds
900Hovered solid backgrounds
1000Low-contrast text
1100High-contrast text

If you need more information about how to use the colors you can check the RadixUI Colors Usage (opens in a new tab) documentation.

The 50~1100 scale works fine in both "light" or "dark" mode. For example: the app background color is controled by var(--sira-colors-bw-50) css varible which will be "#000" in dark mode, but the var(--sira-colors-bw-50) css variable will be "#FFF" in light mode.

Here we list our built-in colors:

Try to toggle color scheme options on the bottom of page to see what will happen.

Built-in Colors

bw-50
bw-100
bw-200
bw-300
bw-400
bw-500
bw-600
bw-700
bw-800
bw-900
bw-1000
bw-1100
info-50
info-100
info-200
info-300
info-400
info-500
info-600
info-700
info-800
info-900
info-1000
info-1100
success-50
success-100
success-200
success-300
success-400
success-500
success-600
success-700
success-800
success-900
success-1000
success-1100
warn-50
warn-100
warn-200
warn-300
warn-400
warn-500
warn-600
warn-700
warn-800
warn-900
warn-1000
warn-1100
danger-50
danger-100
danger-200
danger-300
danger-400
danger-500
danger-600
danger-700
danger-800
danger-900
danger-1000
danger-1100

Color BW bw means a palette from Black to White (or white to black, depending on color schema), the difference from other colors is that it has a kind of obvious mutation between white and black color scales which is caused by satisfy Radix color reference.

So, if you append some custom colors (just need to give a single middle color value, sira will handle others for you) in your sira theme config like below.

module.exports = {
  plugins: [
    require('@sira-ui/tailwind')({
      themes: [
        {
          name: 'light',
          colorScheme: 'light',
          colors: {
            yourowncolorname: '#7118e0',
          },
        },
      ],
    }),
  ],
};

Actually Sira will calculate the color value you give (mainly use hue & sat) to generate a palette to satisfy Radix color reference automatically.

Or your can customize the whole color palette by given a array of colors (12 hex shades from 50 to 1100) like below.

module.exports = {
  plugins: [
    require('@sira-ui/tailwind')({
      themes: [
        {
          name: 'light',
          colorScheme: 'light',
          colors: {
            yourowncolorname: [
              // fill these color value (12 hex shades from 50 to 1100)
              // or just give a single color hex string instead of array. (Sira will generate 12 shades for u by this single value)
              '#fffcfc',
              '#fff8f8',
              '#ffefef',
              '#ffe5e5',
              '#fdd8d8',
              '#f9c6c6',
              '#f3aeaf',
              '#eb9091',
              '#e5484d',
              '#dc3d43',
              '#cd2b31',
              '#381316',
            ],
          },
        },
      ],
    }),
  ],
};

You will get your custom colors available in your code like below

<div class="bg-primary-300 text-primary-800">Primary</div>
Primary

And also, you can use your custom color name as a class to apply theme color for sira components like below

<button class="btn solid primary">Primary</button>

Built-in themes

We offer some default built-in themes which is light and dark.

To customize them you can use the themes array property to override its names like below

module.exports = {
  plugins: [
    require('@sira-ui/tailwind')({
      themes: [
        {
          name: 'light',
          colorScheme: 'light',
          colors: {
            success: '#7118e0',
            danger: '#5955f1',
          },
        },
        {
          name: 'dark',
          colorScheme: 'dark',
          colors: {
            success: '#7118e0',
            danger: '#5955f1',
          },
        },
      ],
    }),
  ],
};

Disable themes

To remove a theme you can use the excludedThemes array property:

module.exports = {
  plugins: [
    require('@sira-ui/tailwind')({
      excludedThemes: ['dark', 'light', 'whateverTheme'],
    }),
  ],
};

Prefix

To add a prefix to each Sira components class you can use the prefix string property:

⚠️

This prefix will only be applied to components class rather than base or utilities classes.

default no any prefix

module.exports = {
  plugins: [
    require('@sira-ui/tailwind')({
      prefix: 'prefix-',
    }),
  ],
};

Now your components classes will be prefixed like this example:

BeforeAfter
.btn.prefix-btn
.input.prefix-input