Skip to documentation content

Colors

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.

Honest UI foreground color tokens
PreviewTokenValue
--hui-color-foreground-base-primaryHeadings, labels, and primary contentTheme-aware
--hui-color-foreground-base-secondarySupporting copy and secondary iconsTheme-aware
--hui-color-foreground-base-tertiaryMuted metadata and placeholder textTheme-aware
--hui-color-foreground-base-emphasisHigh-contrast content on a neutral emphasis backgroundTheme-aware
--hui-color-foreground-accent-primaryAccent links and interactive contentTheme-aware
--hui-color-foreground-accent-primary-hoverHover state for accent foreground contentTheme-aware
--hui-color-foreground-accent-emphasisContent on an accent emphasis backgroundTheme-aware
--hui-color-foreground-attention-primaryWarning and attention contentTheme-aware
--hui-color-foreground-attention-primary-hoverHover state for attention foreground contentTheme-aware
--hui-color-foreground-attention-emphasisContent on an attention emphasis backgroundTheme-aware
--hui-color-foreground-danger-primaryError messages and destructive actionsTheme-aware
--hui-color-foreground-danger-primary-hoverHover state for danger foreground contentTheme-aware
--hui-color-foreground-danger-emphasisContent on a danger emphasis backgroundTheme-aware
--hui-color-foreground-success-primarySuccess and positive-state contentTheme-aware
--hui-color-foreground-success-primary-hoverHover state for success foreground contentTheme-aware
--hui-color-foreground-success-emphasisContent on a success emphasis backgroundTheme-aware

Background colors

Background tokens define page surfaces, containers, selection states, and semantic emphasis.

Honest UI background color tokens
PreviewTokenValue
--hui-color-background-base-primaryMain page and component surfaceTheme-aware
--hui-color-background-base-primary-hoverHover state on a base surfaceTheme-aware
--hui-color-background-base-secondarySecondary page, card, or panel surfaceTheme-aware
--hui-color-background-neutral-primarySubtle neutral highlightTheme-aware
--hui-color-background-neutral-secondaryNeutral control and grouped-content surfaceTheme-aware
--hui-color-background-neutral-secondary-hoverHover state for a neutral secondary surfaceTheme-aware
--hui-color-background-neutral-tertiaryStrong neutral surfaceTheme-aware
--hui-color-background-neutral-tertiary-hoverHover state for a strong neutral surfaceTheme-aware
--hui-color-background-neutral-emphasisHighest-contrast neutral surfaceTheme-aware
--hui-color-background-accent-primarySubtle accent highlight or selectionTheme-aware
--hui-color-background-accent-emphasisAccent-filled control or prominent stateTheme-aware
--hui-color-background-accent-emphasis-hoverHover state for accent emphasisTheme-aware
--hui-color-background-attention-primarySubtle warning or attention surfaceTheme-aware
--hui-color-background-attention-emphasisStrong attention surfaceTheme-aware
--hui-color-background-attention-emphasis-hoverHover state for attention emphasisTheme-aware
--hui-color-background-danger-primarySubtle error or destructive surfaceTheme-aware
--hui-color-background-danger-emphasisDestructive filled control or strong error stateTheme-aware
--hui-color-background-danger-emphasis-hoverHover state for danger emphasisTheme-aware
--hui-color-background-success-primarySubtle success surfaceTheme-aware
--hui-color-background-success-emphasisStrong success surfaceTheme-aware
--hui-color-background-success-emphasis-hoverHover state for success emphasisTheme-aware

Border colors

Border tokens define separators, control boundaries, focus treatment, and semantic states.

Honest UI border color tokens
PreviewTokenValue
--hui-color-border-base-primarySubtle boundaries and separatorsTheme-aware
--hui-color-border-base-secondaryClearer dividers and control boundariesTheme-aware
--hui-color-border-base-tertiaryStrong base border for inputs and cardsTheme-aware
--hui-color-border-base-tertiary-hoverHover treatment for a strong base borderTheme-aware
--hui-color-border-base-focusNeutral focus or active boundaryTheme-aware
--hui-color-border-base-emphasisHighest-contrast neutral borderTheme-aware
--hui-color-border-accent-primarySubtle accent boundaryTheme-aware
--hui-color-border-accent-emphasisStrong accent and default focus boundaryTheme-aware
--hui-color-border-accent-emphasis-hoverHover state for accent emphasis bordersTheme-aware
--hui-color-border-attention-primarySubtle warning boundaryTheme-aware
--hui-color-border-attention-emphasisStrong warning boundaryTheme-aware
--hui-color-border-attention-emphasis-hoverHover state for attention emphasis bordersTheme-aware
--hui-color-border-danger-primarySubtle error or invalid boundaryTheme-aware
--hui-color-border-danger-emphasisStrong danger boundaryTheme-aware
--hui-color-border-danger-emphasis-hoverHover state for danger emphasis bordersTheme-aware
--hui-color-border-success-primarySubtle success boundaryTheme-aware
--hui-color-border-success-emphasisStrong success boundaryTheme-aware
--hui-color-border-success-emphasis-hoverHover state for success emphasis bordersTheme-aware

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.

Honest UI overlay color tokens
PreviewTokenValue
--hui-color-overlay-base-a1Theme-aware overlay at 5% opacityTheme-aware
--hui-color-overlay-base-a2Theme-aware overlay at 10% opacityTheme-aware
--hui-color-overlay-base-a3Theme-aware overlay at 15% opacityTheme-aware
--hui-color-overlay-base-a4Theme-aware overlay at 20% opacityTheme-aware
--hui-color-overlay-base-a5Theme-aware overlay at 30% opacityTheme-aware
--hui-color-overlay-base-a6Theme-aware overlay at 40% opacityTheme-aware
--hui-color-overlay-base-a7Theme-aware overlay at 50% opacityTheme-aware
--hui-color-overlay-base-a8Theme-aware overlay at 60% opacityTheme-aware
--hui-color-overlay-base-a9Theme-aware overlay at 70% opacityTheme-aware
--hui-color-overlay-base-a10Theme-aware overlay at 80% opacityTheme-aware
--hui-color-overlay-base-a11Theme-aware overlay at 90% opacityTheme-aware
--hui-color-overlay-base-a12Theme-aware overlay at 95% opacityTheme-aware
--hui-color-overlay-black-a1Black overlay at 5% opacityblack, 5% opacity
--hui-color-overlay-black-a2Black overlay at 10% opacityblack, 10% opacity
--hui-color-overlay-black-a3Black overlay at 15% opacityblack, 15% opacity
--hui-color-overlay-black-a4Black overlay at 20% opacityblack, 20% opacity
--hui-color-overlay-black-a5Black overlay at 30% opacityblack, 30% opacity
--hui-color-overlay-black-a6Black overlay at 40% opacityblack, 40% opacity
--hui-color-overlay-black-a7Black overlay at 50% opacityblack, 50% opacity
--hui-color-overlay-black-a8Black overlay at 60% opacityblack, 60% opacity
--hui-color-overlay-black-a9Black overlay at 70% opacityblack, 70% opacity
--hui-color-overlay-black-a10Black overlay at 80% opacityblack, 80% opacity
--hui-color-overlay-black-a11Black overlay at 90% opacityblack, 90% opacity
--hui-color-overlay-black-a12Black overlay at 95% opacityblack, 95% opacity
--hui-color-overlay-white-a1White overlay at 5% opacitywhite, 5% opacity
--hui-color-overlay-white-a2White overlay at 10% opacitywhite, 10% opacity
--hui-color-overlay-white-a3White overlay at 15% opacitywhite, 15% opacity
--hui-color-overlay-white-a4White overlay at 20% opacitywhite, 20% opacity
--hui-color-overlay-white-a5White overlay at 30% opacitywhite, 30% opacity
--hui-color-overlay-white-a6White overlay at 40% opacitywhite, 40% opacity
--hui-color-overlay-white-a7White overlay at 50% opacitywhite, 50% opacity
--hui-color-overlay-white-a8White overlay at 60% opacitywhite, 60% opacity
--hui-color-overlay-white-a9White overlay at 70% opacitywhite, 70% opacity
--hui-color-overlay-white-a10White overlay at 80% opacitywhite, 80% opacity
--hui-color-overlay-white-a11White overlay at 90% opacitywhite, 90% opacity
--hui-color-overlay-white-a12White overlay at 95% opacitywhite, 95% 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.

Honest UI visualization color tokens
PreviewTokenValue
--hui-color-viz-sky-6Sky visualization family, step 6Theme-aware
--hui-color-viz-sky-8Sky visualization family, step 8Theme-aware
--hui-color-viz-sky-9Sky visualization family, step 9Theme-aware
--hui-color-viz-sky-11Sky visualization family, step 11Theme-aware
--hui-color-viz-mint-6Mint visualization family, step 6Theme-aware
--hui-color-viz-mint-8Mint visualization family, step 8Theme-aware
--hui-color-viz-mint-9Mint visualization family, step 9Theme-aware
--hui-color-viz-mint-11Mint visualization family, step 11Theme-aware
--hui-color-viz-lime-6Lime visualization family, step 6Theme-aware
--hui-color-viz-lime-8Lime visualization family, step 8Theme-aware
--hui-color-viz-lime-9Lime visualization family, step 9Theme-aware
--hui-color-viz-lime-11Lime visualization family, step 11Theme-aware
--hui-color-viz-grass-6Grass visualization family, step 6Theme-aware
--hui-color-viz-grass-8Grass visualization family, step 8Theme-aware
--hui-color-viz-grass-9Grass visualization family, step 9Theme-aware
--hui-color-viz-grass-11Grass visualization family, step 11Theme-aware
--hui-color-viz-green-6Green visualization family, step 6Theme-aware
--hui-color-viz-green-8Green visualization family, step 8Theme-aware
--hui-color-viz-green-9Green visualization family, step 9Theme-aware
--hui-color-viz-green-11Green visualization family, step 11Theme-aware
--hui-color-viz-jade-6Jade visualization family, step 6Theme-aware
--hui-color-viz-jade-8Jade visualization family, step 8Theme-aware
--hui-color-viz-jade-9Jade visualization family, step 9Theme-aware
--hui-color-viz-jade-11Jade visualization family, step 11Theme-aware
--hui-color-viz-cyan-6Cyan visualization family, step 6Theme-aware
--hui-color-viz-cyan-8Cyan visualization family, step 8Theme-aware
--hui-color-viz-cyan-9Cyan visualization family, step 9Theme-aware
--hui-color-viz-cyan-11Cyan visualization family, step 11Theme-aware
--hui-color-viz-blue-6Blue visualization family, step 6Theme-aware
--hui-color-viz-blue-8Blue visualization family, step 8Theme-aware
--hui-color-viz-blue-9Blue visualization family, step 9Theme-aware
--hui-color-viz-blue-11Blue visualization family, step 11Theme-aware
--hui-color-viz-iris-6Iris visualization family, step 6Theme-aware
--hui-color-viz-iris-8Iris visualization family, step 8Theme-aware
--hui-color-viz-iris-9Iris visualization family, step 9Theme-aware
--hui-color-viz-iris-11Iris visualization family, step 11Theme-aware
--hui-color-viz-purple-6Purple visualization family, step 6Theme-aware
--hui-color-viz-purple-8Purple visualization family, step 8Theme-aware
--hui-color-viz-purple-9Purple visualization family, step 9Theme-aware
--hui-color-viz-purple-11Purple visualization family, step 11Theme-aware
--hui-color-viz-pink-6Pink visualization family, step 6Theme-aware
--hui-color-viz-pink-8Pink visualization family, step 8Theme-aware
--hui-color-viz-pink-9Pink visualization family, step 9Theme-aware
--hui-color-viz-pink-11Pink visualization family, step 11Theme-aware
--hui-color-viz-crimson-6Crimson visualization family, step 6Theme-aware
--hui-color-viz-crimson-8Crimson visualization family, step 8Theme-aware
--hui-color-viz-crimson-9Crimson visualization family, step 9Theme-aware
--hui-color-viz-crimson-11Crimson visualization family, step 11Theme-aware
--hui-color-viz-orange-6Orange visualization family, step 6Theme-aware
--hui-color-viz-orange-8Orange visualization family, step 8Theme-aware
--hui-color-viz-orange-9Orange visualization family, step 9Theme-aware
--hui-color-viz-orange-11Orange visualization family, step 11Theme-aware
--hui-color-viz-gold-6Gold visualization family, step 6Theme-aware
--hui-color-viz-gold-8Gold visualization family, step 8Theme-aware
--hui-color-viz-gold-9Gold visualization family, step 9Theme-aware
--hui-color-viz-gold-11Gold visualization family, step 11Theme-aware

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 for chart-specific color setup.

Change the palette

Blue 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
  data-theme="dark"
  data-accent-color="orange"
  data-gray-color="slate"
>

Supported accent overrides are indigo, 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:

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 (
    <span
      className={`rounded-[var(--hui-radius-full)] border px-[var(--hui-space-3)] py-[var(--hui-space-1)] ${statusClass[status]}`}
    >
      {children}
    </span>
  )
}

Do not interpolate a token fragment into a class name. Tailwind must see the complete class string in source. Read Tailwind CSS 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.