Colors
Collection of semantic color tokens built on the Shadcn model.
Installation
npx oward-ui add colorsOnce the plugin is installed, import the CSS in your main Tailwind CSS file:
@import "./tailwind/semantic-colors.css";Conventions
Apart from shades, semantic tokens use a simple convention of background and foreground colors. The background variable defines the component's background color, while the foreground variable determines the text color.
Each token is a background variable except for tokens with the -foreground suffix which are text color variables.
Semantic tokens
Branding tokens
Branding tokens are used for key UI elements that represent the brand, such as primary buttons, links, and accents. They are designed to attract attention and guide users towards important actions.
Status tokens
Status tokens are used to indicate specific states in the user interface, such as success, information, warning, and danger. Ideal for alerts, notifications, and error messages.
Shade tokens
Neutral: the tonal reference
Describes a grayscale (or near-grayscale) serving as the base for contrast, separators, and generic backgrounds. This shade serves as a tonal reference and is not intended to be used directly but rather consumed by other tokens (surface, border, muted, outline, etc.), and does not change in dark mode.
Surface
Describes the different surface layers in the user interface, ranging from light backgrounds to darker backgrounds. These tokens are used to create depth and visual hierarchy. The shade is inverted in dark mode to adapt to different usage contexts.
Example of using surface shades to create nested cards with different depth levels:
UI tokens
Background, Foreground and headings
The background and foreground tokens define the default background and
text colors for the user interface. They are used to ensure good readability
and sufficient contrast between text and its background. Both are based by
default on the surface-50 and surface-900 shades.
The heading token is specifically designed for titles and headers,
providing a distinctive token. It can have the same value as foreground
or a different value to create a clear visual hierarchy.
Accent and Accent Foreground
The accent and accent-foreground tokens are used for interactive elements and visual accents in the user interface. They help draw attention to specific elements such as form elements.
By default, the accent color is defined by the surface-200 shade, while accent-foreground uses the surface-400 shade.
Border, Ring and Input
The border and ring tokens are used for borders and focus rings around interactive elements. The input token is specifically intended for form fields and user input elements.
The border and input colors are defined by default by the surface-300 shade.
Muted and Muted Foreground
The muted and muted-foreground tokens are used for less important or
disabled elements in the user interface. They help reduce attention on these
elements while maintaining good readability.
Global rules
By default, certain CSS rules are applied globally with semantic tokens in the user interface.
For example, borders and outlines have colors set to border and ring. Therefore, it is not necessary to specify these colors manually for each element: border will be colored by default with border-border and outlines with outline-ring/50.
Similarly, the body's background and text colors are defined with the background and foreground tokens.
@layer base {
* {
@apply border-border outline-ring/50 accent-accent;
}
body {
@apply bg-background text-foreground;
}
}Tailwind-Merge
Tailwind-Merge is used to merge Tailwind classes and handle class conflicts. For example, if you apply both text-sm and text-xl to an element, tailwind-merge will ensure that only the last applied class is taken into account.
However, tailwind-merge does not automatically recognize custom tokens defined in your CSS file. Without proper configuration, it cannot correctly handle conflicts between your custom classes.
Example problem: With the classes bg-primary bg-accent, Tailwind-Merge does not recognize primary and accent as colors and may therefore keep both classes instead of keeping only the last one.
Automatic solution
To solve this problem, use the Generate TwMerge Config script which automatically generates the tailwind-merge configuration from your custom tokens. This script analyzes your CSS file and creates a type-safe configuration that allows tailwind-merge to correctly recognize and handle all your custom tokens.