# Colors
> Use Honest UI's semantic foreground, background, border, overlay, and visualization color tokens across light and dark themes.
Source: https://www.honestui.com/docs/theme/colors
---
title: Colors
description: Use Honest UI's semantic foreground, background, border, overlay, and visualization color tokens across light and dark themes.
---
Honest UI names colors by purpose. Components ask for a primary foreground, an accent background, or a danger border; the theme then resolves that role to an appropriate value. This keeps the code understandable and lets light, dark, accent, and neutral palettes change without renaming component classes.
Use the `--hui-color-*` tokens on this page in application and component code. The lower-level `--hui-neutral-*`, `--hui-accent-*`, `--hui-danger-*`, `--hui-attention-*`, and `--hui-success-*` scales feed these roles and are intended for building the theme itself.
## Foreground colors
Foreground tokens are for text, icons, and other content placed over a background.
## Background colors
Background tokens define page surfaces, containers, selection states, and semantic emphasis.
## Border colors
Border tokens define separators, control boundaries, focus treatment, and semantic states.
## Overlay colors
Overlay scales provide 12 opacity steps. `base` follows the active theme—black in light mode and white in dark mode. The `black` and `white` scales keep their hue fixed, which is useful for media scrims and effects whose direction must not change with the theme.
[5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 95].map((opacity, index) => ({
name: `--hui-color-overlay-${family}-a${index + 1}`,
value: family === "base" ? "Theme-aware" : `${family}, ${opacity}% opacity`,
description: `${family === "base" ? "Theme-aware" : family[0].toUpperCase() + family.slice(1)} overlay at ${opacity}% opacity`,
})),
),
]}
/>
Choose the lightest step that still communicates the layer and preserves contrast for content above and below it. An overlay does not replace dialog semantics, focus management, or an accessible name.
## Visualization colors
Four steps are available in each of 14 visualization families. Step `6` is the lightest supplied value, `8` provides more separation, `9` is the main solid color, and `11` is suited to stronger foreground use. Their exact appearance changes between light and dark themes.
[6, 8, 9, 11].map((step) => ({
name: `--hui-color-viz-${family}-${step}`,
description: `${family[0].toUpperCase() + family.slice(1)} visualization family, step ${step}`,
})),
),
]}
/>
Visualization colors are not a promise that every pair has sufficient contrast or is distinguishable for every form of color vision. Label series directly where possible, keep a stable series-to-color mapping, and add shapes, line styles, patterns, or text when color would otherwise carry the meaning alone. See [Chart configuration](/docs/charts/chart-config) for chart-specific color setup.
## Change the palette
Indigo and gray are the defaults provided by `data-theme`. Set optional palette attributes on the same element to switch the accent or neutral source values:
```html
```
Supported accent overrides are `orange` and `mint`. Supported neutral choices are `gray`, `mauve`, `slate`, and `sage`. An unsupported value does not create a fallback palette; use one of the documented values or define the complete source scale yourself.
## Tailwind usage
Map each product state to complete, static class strings so Tailwind can detect them at build time:
```tsx
const statusClass = {
success:
"border-[var(--hui-color-border-success-primary)] bg-[var(--hui-color-background-success-primary)] text-[var(--hui-color-foreground-success-primary)]",
warning:
"border-[var(--hui-color-border-attention-primary)] bg-[var(--hui-color-background-attention-primary)] text-[var(--hui-color-foreground-attention-primary)]",
error:
"border-[var(--hui-color-border-danger-primary)] bg-[var(--hui-color-background-danger-primary)] text-[var(--hui-color-foreground-danger-primary)]",
} as const
export function Status({ status, children }) {
return (
{children}
)
}
```
Do not interpolate a token fragment into a class name. Tailwind must see the complete class string in source. Read [Tailwind CSS](/docs/theme/tailwind) for typed shorthand and optional aliases.
## Color checks before release
- Pair emphasis backgrounds with the matching emphasis foreground token. Mint intentionally resolves to dark accent-contrast text, while indigo and orange resolve to light text.
- Keep default, hover, active, focus, disabled, invalid, warning, success, and destructive states distinct in both themes.
- Check WCAG contrast with the rendered color pair. A semantic name describes intent; it does not prove contrast in every custom combination.
- Never rely on color alone for status, validation, selection, or chart meaning. Add text, icons, patterns, or another persistent cue.
- Verify forced-colors mode and avoid overriding system colors when doing so would hide native accessibility behavior.
- Prefer semantic tokens over raw OKLCH values in component code. Override the palette or semantic role in one owned location when the whole product needs to change.