Colors
Learn how Fluxon UI's semantic color system works.
Starting with Fluxon v2, Fluxon UI uses semantic design tokens instead of hardcoded color values for consistent, maintainable theming across all components. This replaces all the specific color classes used in v1.
Tailwind Utilities
Fluxon extends Tailwind CSS with custom utility classes that use semantic color tokens. Instead of using specific color values like bg-blue-500, you'll use semantic utilities that describe the purpose of the color, such as
bg-primary
for primary actions, text-foreground
for main text, or bg-surface
for card backgrounds.
These utilities work just like regular Tailwind classes but reference semantic CSS variables instead of fixed colors. This means the actual color values automatically adapt based on the current theme.
How It Works
When you use a semantic utility class like bg-primary, Tailwind generates CSS that references a CSS variable:
Generated CSS
Copy
.bg-primary {
background-color: var(--primary);
}
.text-foreground {
color: var(--foreground);
}
These CSS variables are defined by default in Fluxon's theme.css
file (imported during installation) but can be customized to match your brand colors. The actual color values can change based on the active theme.
app.css
Copy
:root {
/* Semantic tokens reference actual color values */
--primary: var(--color-blue-500);
--foreground: var(--color-zinc-700);
--background-base: var(--color-white);
--surface: var(--color-zinc-50);
--border-base: var(--color-zinc-200);
}Components then use these semantic tokens through Tailwind classes:
page.html.heex
Copy
<!-- Primary button using semantic colors -->
<button class="bg-primary text-foreground-primary hover:opacity-90">
Click me
</button>
<!-- Card with semantic surface and border colors -->
<div class="bg-surface border border-base rounded-base">
<h3 class="text-foreground">Card Title</h3>
<p class="text-foreground-soft">Card description text</p>
</div>
<!-- Alert using semantic danger colors -->
<div class="bg-danger-soft text-danger border border-danger">
Error message here
</div>Color Tokens Reference
Below is the complete list of semantic color tokens available in Fluxon UI.
| Token | Tailwind Class |
|---|---|
| Brand | |
|
--primary
Primary brand color used in call-to-action buttons, active navigation, links, selected items, and key interactive elements.
|
bg-primarytext-primaryborder-primary
|
|
--primary-soft
Soft variant of the primary color for subtle highlights, badges, and gentle emphasis backgrounds.
|
bg-primary-softtext-primary-softborder-primary-soft
|
| Content | |
|
--foreground
Primary text color for headings, body text, and main content. Highest contrast for optimal readability.
|
text-foreground
|
|
--foreground-soft
Slightly muted text color for secondary content, captions, and supporting text.
|
text-foreground-soft
|
|
--foreground-softer
More muted text color for placeholder text, form labels, and tertiary content.
|
text-foreground-softer
|
|
--foreground-softest
Most muted text color for disabled states, subtle hints, and background text.
|
text-foreground-softest
|
|
--foreground-primary
Text color designed for use on primary colored backgrounds, ensuring proper contrast.
|
text-foreground-primary
|
| Background | |
|
--background-base
Main application background color for page layout, content areas, and foundation layer.
|
bg-base
|
|
--background-sunken
Recessed well that sits just below the page in dark mode. Used for segmented tracks, inset regions, and grouped control backgrounds.
|
bg-sunken
|
|
--background-control
Raised control fill that sits one step above the page in dark mode, so inputs, outline buttons, and key caps read as lifted.
|
bg-control
|
|
--surface
Surface background color for cards, panels, modal dialogs, and elevated components above the base layer.
|
bg-surface
|
|
--background-input
Background color for form inputs, text areas, select fields, and interactive form elements in default state.
|
bg-input
|
|
--background-input-disabled
Background color for disabled form inputs, read-only fields, and inactive form elements.
|
bg-input-disabled
|
|
--background-switch
Background color for the unchecked track of switch and toggle controls.
|
bg-switch
|
|
--background-tooltip
Background color for tooltips and small floating informational labels.
|
bg-tooltip
|
| Border | |
|
--border-base
Primary border color for form inputs, cards, table borders, dividers, and UI elements needing clear boundaries.
|
border-base
|
|
--border-subtle
Subtle border color for inner dividers, gentle separators, and elements that need quiet visual separation.
|
border-subtle
|
|
--border-input
Specific border color for form inputs, text fields, and interactive form elements.
|
border-input
|
| Semantic Colors | |
|
--danger
Danger color for error states, destructive actions, delete buttons, form validation errors, and critical alerts.
|
bg-dangertext-danger
|
|
--danger-soft
Soft variant of the danger color for subtle error backgrounds and highlights.
|
bg-danger-softtext-danger-soft
|
|
--danger-foreground
Text color designed for use on danger colored backgrounds, ensuring readability.
|
text-foreground-danger
|
|
--danger-soft-foreground
Text color designed for use on danger-soft backgrounds, ensuring proper contrast and readability.
|
text-foreground-danger-soft
|
|
--danger-border
Border color for invalid form inputs, error containers, and elements in error states.
|
border-danger
|
|
--success
Success color for completed actions, valid form states, success notifications, and positive feedback indicators.
|
bg-successtext-success
|
|
--success-soft
Soft variant of the success color for subtle success backgrounds and highlights.
|
bg-success-softtext-success-soft
|
|
--success-foreground
Text color designed for use on success colored backgrounds, ensuring readability.
|
text-foreground-success
|
|
--success-soft-foreground
Text color designed for use on success-soft backgrounds, ensuring proper contrast and readability.
|
text-foreground-success-soft
|
|
--success-border
Border color for valid form inputs, success containers, and elements in successful states.
|
border-success
|
|
--warning
Warning color for caution states, pending actions, form validation warnings, and alerts requiring attention.
|
bg-warningtext-warning
|
|
--warning-soft
Soft variant of the warning color for subtle warning backgrounds and highlights.
|
bg-warning-softtext-warning-soft
|
|
--warning-foreground
Text color designed for use on warning colored backgrounds, ensuring readability.
|
text-foreground-warning
|
|
--warning-soft-foreground
Text color designed for use on warning-soft backgrounds, ensuring proper contrast and readability.
|
text-foreground-warning-soft
|
|
--warning-border
Border color for warning form inputs, caution containers, and elements in warning states.
|
border-warning
|
|
--info
Info color for informational messages, help text, neutral notifications, and general information indicators.
|
bg-infotext-info
|
|
--info-soft
Soft variant of the info color for subtle informational backgrounds and highlights.
|
bg-info-softtext-info-soft
|
|
--info-foreground
Text color designed for use on info colored backgrounds, ensuring readability.
|
text-foreground-info
|
|
--info-soft-foreground
Text color designed for use on info-soft backgrounds, ensuring proper contrast and readability.
|
text-foreground-info-soft
|
|
--info-border
Border color for informational containers, help sections, and elements in informational states.
|
border-info
|
| Focus States | |
|
--focus
Primary focus outline color for interactive elements. Border uses this color directly, ring uses a semi-transparent version for the glow effect.
|
border-focusring-focus
|
|
--focus-danger
Danger state focus outline color for error states and invalid form inputs. Provides visual feedback when dangerous actions are focused.
|
border-focus-dangerring-focus-danger
|
| Layout | |
|
--radius-base
Base border radius used consistently across buttons, cards, inputs, and UI components to maintain visual harmony.
|
rounded-base
|
|
--radius-badge
Border radius used for badges and other small pill-shaped elements that need a tighter corner curve than the base radius.
|
rounded-badge
|
|
--shadow-base
Base shadow for cards, dropdowns, modals, and elevated components to create subtle depth and visual hierarchy.
|
shadow-base
|
For information on theme switching, dark mode, and creating custom themes, see the Themes guide.