# Light & dark mode

A shared identity in two appearances.

Light and dark themes should preserve meaning while adapting contrast and surfaces. Frontfriend uses semantic tokens so a component can keep its intent without embedding a light or dark color in page code.

## Use semantic pairs

Pair a branded background with its matching foreground role, such as `bg-brand-mid` and `text-onbrand-mid`. Keep content on raised surfaces readable through the neutral foreground family.

The generated theme and your application’s theme mechanism must agree on how dark mode is activated. Follow the theme-provider setup already used by your application rather than adding a second independent provider.

## Preview both modes

In Theme Studio, edit linked Light and Dark semantic families and inspect the component previews. Review hover, active, focus, invalid and disabled states in both appearances. A palette that looks balanced on a large panel can fail on a small icon or thin border.

## Prevent a flash on load

For server-rendered applications, use your framework’s established theme-provider pattern and apply the initial mode before paint. Keep server and client markup consistent. Do not store a separate theme preference in each component.

## Respect user preferences

Offer an explicit mode choice and, where the application supports it, a system preference option. Check keyboard focus, native controls and overlays; modal content often renders outside the component’s immediate DOM subtree.

See [Accessibility](/docs/accessibility/) for contrast and motion guidance, and [Theming](/docs/theming/) for generated configuration.