Colors

Color palette and theming system for Elemnts UI.

Elemnts UI uses the OKLCH color space for its palette, ensuring smooth transitions and consistent brightness across all colors. This approach outperforms traditional RGB or HSL models by providing more natural and visually uniform color variations.

How the Color System Works

The color system is inspired by Tailwind CSS v4 but optimized for OKLCH. When you import @elemnts-ui/core/colors, you unlock a comprehensive set of primitive palettes. These palettes are automatically mapped to semantic variables, ensuring a cohesive and adaptable theming experience.

Primitive Tokens

Primitive tokens are the raw materials of Elemnts UI’s color system. They provide direct access to the foundational colors used in the design system.

Format: {color}.{step}
Steps: 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 100 (Light to Dark)
Alpha Variants: Add an a prefix for transparency, e.g., {color}.a10 to {color}.a100.

/* Examples */
green.10   /* The lightest shade of green */
green.100  /* The darkest shade of green */
blue.a50   /* Semi-transparent blue */

Semantic Tokens

Semantic tokens bridge the gap between raw colors and their intended use in the UI. They abstract color values into meaningful categories, making it easier to maintain consistency and adapt to different themes (like Dark Mode).

Format: {group}.{importance}

Common Groups

Token Group	Description
surface	Background colors (e.g., page backgrounds, cards)
fg	Foreground and text colors (e.g., primary text, secondary text)
stroke	Border and divider colors (e.g., dividers, input borders)
icon	Icon colors (e.g., icon fills, icon strokes)

Functional Groups

Token Group	Description
accent	Primary brand or action colors (e.g., buttons, links)
success	Positive feedback (e.g., success messages, confirmations)
warning	Cautionary feedback (e.g., warnings, alerts)
destructive	Error or dangerous actions (e.g., destructive buttons, errors)

/* Examples */
surface.1      /* Main background of the application */
fg.secondary   /* Secondary text or less prominent elements */
accent.primary /* Primary action color (e.g., buttons) */

Dark Mode Support

Semantic tokens in Elemnts UI are theme-aware, meaning they automatically adapt to the active theme. For example, surface.1 will switch from a light value (like white) to a dark value (like neutral.95) when Dark Mode is enabled—no manual overrides needed!

Semantic Token	Light Mode Value	Dark Mode Value
`surface.1`	`white`	`neutral.95`
`fg.primary`	`neutral.100`	`neutral.10`
`accent.primary`	`blue.80`	`blue.70`

Best Practices

Use Semantic Tokens: Always prefer semantic tokens for styling components. They ensure consistency and make theme switching effortless.
Use Primitive Tokens Sparingly: Only use primitive tokens for unique cases where a specific color doesn’t fit a semantic category.
Leverage Alpha Tokens: Use alpha variants (a10 to a100) for overlays, subtle borders, or layered designs where transparency is needed.