Color usage

The shorthand utility classes below simplify our full color palette by providing sensible, contrast-checked defaults. Use them whenever possible to ensure accessible text colors and balanced background fills.

Primary and brand colors

Primary is the theme's functional accent. Changing --primary-hue updates primary text, buttons, selected controls, and focus rings. Brand is the fixed Supabase palette for product identity.

Primary ink

--primary is for readable UI: links, labels, radios, step dots, and other small indicators. Utilities include text-primary, bg-primary, and border-primary.

In light mode it is darkened to meet WCAG AA for normal text. In dark mode it stays bright so those controls remain visible on dark surfaces.

Primary solid

--primary-solid is the deeper fill for primary buttons. In dark mode it is darker than --primary so buttons do not read as lime. In light mode it matches --primary, so ink and buttons share one green. Primary Button uses bg-primary-solid / text-primary-solid-foreground.

Bright primary

--primary-bright gives focus rings, selected controls, and other interactive chrome a brighter version of the primary hue. It stays vivid when light-mode --primary is darkened for readable text. Use bg-primary-bright, border-primary-bright, and the shared ring-ring focus treatment.

Brand green

brand-default remains the fixed Supabase green for explicitly branded surfaces.

Toggle the theme to compare the swatches below. Light mode collapses primary and primary-solid; dark mode separates bright ink from the deeper button plate:

See also Typography (text-primary) and Accessibility (shared focus ring).

Text

Use accent text colors (e.g. text-destructive, text-warning) sparingly to avoid visual overload.

Use text-primary for readable branded text such as links, labels, and statuses. It meets WCAG AA for normal text on the surfaces used by the apps: darkened in light mode, bright in dark mode. Primary buttons use a separate solid plate in dark mode; focus chrome uses the brighter primary hue. See Primary and brand colors.

Background

Use bg-primary-bright for selected controls that need a vivid fill, and bg-primary for smaller indicators such as radios and step dots. Use bg-brand-default only when the canonical Supabase green is required. Details in Primary and brand colors.

App backgrounds

We use backgrounds in 2 different ways. In the ./www and ./docs sites, we use a darker background, so we have an extra background color we can use

/**
 * ./www background color
 * ./docs background color
 */
<body className="bg">{children}</body>
 
/**
 * ./studio background color
 */
<body className="bg-studio">{children}</body>

Backgrounds and surfaces

./apps/www + ./apps/docs

We use surfaces in 2 different ways. In the ./www and ./docs sites, we use a darker background, so we have an extra surface color we can use

./apps/studio

For the studio (dashboard) we can use bg-surface-100, bg-surface-200, bg-surface-300

Data grid and frame space

Data grids use an alternative background color for empty space to add depth to the layout. The background of the empty space is the same background as used in ./apps/docs and ./apps/www - although; the color has been mapped to bg-alternative so it works well across different themes.

Dealing with large areas of empty space in data display should also be catered for. You can use the bg-200 or bg class to fill the space.

Overlays

We use the ./bg-overlay background color for overlays. This is not to be confused with Dialogs, they require to use the same app background color as the site.

Border

Other colors

These can also be accessed with foreground. Like text-foreground-light.

Color palette

Every Radix scale exposed via --colors-{name}{1..12}. Click a swatch to copy the CSS variable reference. The colors are taken from @radix-ui/colors v0.1.9 except the Brand and Scale colors.

The Brand colors issue of not being uniform across the whole scale is known, they need to be refactored. The brand-200 variable in the dark themes is also bad.