Skip to content

Theming

The default theme provides simple, elegant styles with support for light and dark modes and 21 built-in color presets. A number of CSS custom properties are exposed, giving you an easy way to make high-level changes to the library.

Using the default theme

To import the default theme from the CDN, add the following code to the <head> section of each page. 

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/themes/quiet.css">

Activating dark mode

Light mode "just works" once you import the default theme. To switch to dark mode, add the quiet-dark class to the <html> element as shown below. Removing the class will switch back to light mode. 

<html class="quiet-dark">
  ...
</html>

If you're using Quiet Restyle, the entire page will enter dark mode. If you're not using Restyle, only the components will change and it's up to you to style the rest of your app accordingly.

Using light and dark on the same page

Sometimes, it's desirable to have a contrasting theme for certain sections of the page. For example, a light-themed page might have a dark-themed sidebar or footer. You can achieve this by applying the quiet-light or quiet-dark class to any element on the page. Everything inside that element will use the specified theme.

This works for light and dark mode, but not for built-in presets. To keep the stylesheet small, built-in presets only redefine the primary seed color, not the entire theme.

Theme concepts

Quiet's default theme is designed to be highly customizable with minimal effort. The following seed colors are used to generate color palettes with pure CSS — one for each variant. 

:root {
  --quiet-primary-seed: #989cff;
  --quiet-neutral-seed: #a4a6b0;
  --quiet-constructive-seed: #7db664;
  --quiet-destructive-seed: #f86565;
}

This means you can customize an entire palette by setting a single custom property in your stylesheet. For example, this will change the primary color palette from violet to orange. 

:root {
  --quiet-primary-seed: #e98d61;
}

For best results, use midtone colors to seed palettes. Any of the 500-level colors from color.surf or similar palettes will work well.

Built-in presets

For convenience, Quiet's default theme ships with 21 color presets to alter the library's primary color. The theme picker at the top of the page allows you to preview them.

To use a preset in your app, add the quiet-{preset} class to the <html> element, where {preset} is one of the following values: default, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, slate, zinc, or stone. 

<html class="quiet-blue">
  ...
</html>

Adapting to existing brands

Using a preset is an easy way to change the library's overall appearance, but it probably won't be a perfect match if you already have brand guidelines to follow. In that case, it might be tempting to set --quiet-primary-seed to whatever your brand color is.

However, that will only work well if your brand color happens to be a midtone, otherwise the generated color tokens may not have enough contrast. A better approach is to use the nearest midtone color that fits with your brand.

"But my buttons don't match my brand color exactly…"

Components should absolutely be on brand, but that doesn't mean buttons have to be the exact hex color as your logo! However, if you insist on such a style, the correct way to achieve it is by overriding the generated palettes and/or component styles with CSS and ensuring proper contrast manually.

Color primitives

Four primitive color palettes are generated based on the aforementioned seed colors. These palettes correspond with the four variants used throughout the library and remain static in light and dark mode.

You should only use color primitives when you want a color that doesn't change in dark mode. For most styles, you probably want to use adaptive colors instead.

Syntax: --quiet-{variant}-{number}

Primary

This is your brand color. Use it for brand recognition and guiding attention through calls to action.

50 100 200 300 400 500 600 700 800 900 950
Neutral

Neutral is usually gray, representing surfaces, borders, and secondary objects.

50 100 200 300 400 500 600 700 800 900 950
Constructive

Constructive is often green, indicating creation or success.

50 100 200 300 400 500 600 700 800 900 950
Destructive

Destructive is often red, indicating deletion or danger.

50 100 200 300 400 500 600 700 800 900 950

While not recommended, it is possible to override primitives for even more control over your application's color palettes. Refer to quiet.css to see how colors are generated.

Adaptive colors

Adaptive colors automatically change between light and dark modes. Instead of numeric values, they use a scale that indicates their "volume" relative to the the app's background. Thus, "softer" colors have less contrast than "louder" ones. This approach lets you style things once, but have them look great in light and dark modes.

Fill colors

Fill colors are primarily used for backgrounds and surfaces. For example, certain buttons use midtone fills for their backgrounds.

Syntax: --quiet-{variant}-fill-{volume}

Primary fill colors

Used for calls to action and brand accents.

softer soft mid loud louder
Neutral fill colors

Used for secondary elements and UI chrome.

softer soft mid loud louder
Constructive fill colors

Used for successful operations such as creations.

softer soft mid loud louder
Destructive fill colors

Used for dangerous operations such as deletions.

softer soft mid loud louder

Text-on colors

Text-on colors provide adequate contrast when used on top of their respective fill colors. Soft works on soft and softer fills whereas loud works on loud and louder fills.

Syntax: --quiet-{variant}-text-on-{volume}

Primary text-on colors

Used for text that sits on top of primary fills.

soft mid loud
Neutral text-on colors

Used for text that sits on top of neutral fills.

soft mid loud
Constructive text-on colors

Used for text that sits on top of constructive fills.

soft mid loud
Destructive text-on colors

Used for text that sits on top of destructive fills.

soft mid loud
A note about WCAG 2

You might discover that some elements are reported to have insufficient contrast, according to WCAG 2 . This occurs due to the standard not accounting for perceptual contrast and only affects Quiet's text-on midtone colors.

Technically, black text has a higher contrast ratio than white text on these backgrounds, despite the former being harder for most people to see. While these color token combinations don't meet WCAG 2, they do meet the the forthcoming APCA standard, which is the likely candidate contrast method for WCAG 3.

Refer to this article to learn more about why WCAG 2 isn't a great standard for measuring perceptual contrast.

Stroke colors

Stroke colors are used to draw borders and outlines around elements and UI chrome.

Syntax: --quiet-{variant}-stroke-{volume}

Primary stroke colors

Used for outlining primary elements.

softer soft mid
Neutral stroke colors

Used for outlining secondary elements.

softer soft mid
Constructive stroke colors

Used for outlining constructive elements.

softer soft mid
Destructive stroke colors

Used for outlining destructive elements.

softer soft mid

Tinting & shading

These tokens represent pure black and white, but their values invert in dark mode. They're most commonly used to tint and shade existing colors with color-mix() .

Syntax: --quiet-silent, --quiet-strident

silent strident

Design tokens

The following design tokens are used to set the overall appearance of the default theme. You can customize tokens by reassigning them as shown below. More granular customizations can be made to components with CSS parts. 

/* Design token overrides */
:root {
  --quiet-background-color: white;
  --quiet-text-body: black;
}

/* Dark theme design token overrides */
.quiet-dark {
  --quiet-background-color: black;
  --quiet-text-body: white;
}

Always scope design token overrides to the :root node (i.e. <html> element), otherwise calculated values may not propagate as expected.

Application tokens

Custom property Description
--quiet-background-color The application's background color.
--quiet-paper-color An alternative background color for slightly lifted surfaces such as a card.
--quiet-text-body The default text color of the app.
--quiet-text-muted The color to use for muted text such as form control descriptions.
--quiet-font-family The default font.
--quiet-font-family-heading The font used for headings.
--quiet-font-family-code The font used for code and code blocks.
--quiet-font-size The base font size for the application. (The default theme is optimized for a 16px font size.)
--quiet-font-weight-normal The font weight for normal text.
--quiet-font-weight-semibold The font weight for semibold text.
--quiet-font-weight-bold The font weight for bold text.
--quiet-line-height The default line height for text.
--quiet-content-spacing The spacing between blocks of content. Used primarily in Restyle to space content consistently.
--quiet-focus-color The color of the focus ring.
--quiet-focus-ring The outline-friendly property used to show focus rings.
--quiet-selection-background-color The background color of selected text.
--quiet-selection-color The color of selected text.
--quiet-backdrop-color The color of backdrops for modal components such as dialog.
--quiet-backdrop-filter The filter to apply to dialog backdrops and similar overlays.
--quiet-border-style The default border style for most elements.
--quiet-border-width The default border width for most elements.
--quiet-border-radius The base border radius for elements. Often used with calc() to scale to smaller and larger elements.
--quiet-focus-width The width of the focus ring's border.
--quiet-focus-offset The outline offset of the focus ring.
--quiet-shadow-color The base color used in all shadows.
--quiet-shadow-softer The softest shadow, a box-shadow-friendly property.
--quiet-shadow-soft A soft shadow, a box-shadow-friendly property.
--quiet-shadow-mid A mid-level shadow, a box-shadow-friendly property.
--quiet-shadow-loud A loud shadow, a box-shadow-friendly property.
--quiet-shadow-louder The loudest shadow, a box-shadow-friendly property.

Form control tokens

Custom property Description
--quiet-form-control-height-xs The height of extra small form controls.
--quiet-form-control-height-sm The height of small form controls.
--quiet-form-control-height-md The height of medium form controls.
--quiet-form-control-height-lg The height of large form controls.
--quiet-form-control-height-xl The height of extra large form controls.
--quiet-form-control-font-size-xs The font size of extra small form controls.
--quiet-form-control-font-size-sm The font size of small form controls.
--quiet-form-control-font-size-md The font size of medium form controls.
--quiet-form-control-font-size-lg The font size of large form controls.
--quiet-form-control-font-size-xl The font size of extra large form controls.
--quiet-form-control-required-content The content to show next to the label when the form control is required.
--quiet-button-active-offset The amount of vertical shift to apply to buttons when they're pressed.

Creating a new theme

If you want to create an entirely new theme, the most efficient way is to fork ("copy") the default theme's CSS and modify it instead of writing everything from scratch. This method is faster, easier, and less prone to mistakes.

If you just want to change a few things here and there, it's usually better to leave the default theme intact and extend it by adding your own stylesheet with the specific rules you want.

Search this website Toggle dark mode Get the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X
    No results found