---
title: Styles, fonts, and CSS | Stainless
---

Change the look and feel of your documentation by changing colors, fonts, and more.

## Colors

The Stainless Docs Platform uses `--stl-color` variables to define the colors used on your site. You can override these with your own values in your `theme.css` file by setting new values on the `:root`.

Use the [`light-dark()` CSS function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark) in order to specify different values for light mode and dark mode.

### Accent color

The accent color is used for theming brightly colored elements on your site such as links, buttons, and other UI details.

Start by changing the base `--stl-color-accent`:

theme.css

```
:root {
  --stl-color-accent: light-dark(#155dfc, #2b7fff);
  /* Green accent color */
  --stl-color-accent: light-dark(#1eb281, #11cc8d);
}
```

By default, text that appears on an accent-colored background (such as on buttons) is white. To change this default, set `--stl-color-accent-inverse-foreground`:

theme.css

```
:root {
  --stl-color-accent: light-dark(#1eb281, #11cc8d);
  /* Use black text against an accent-colored background in dark mode */
  --stl-color-accent-inverse-foreground: light-dark(#ffffff, #000000);
```

If your accent color provides insufficient contrast against the background when used to color text, consider also overriding `--stl-color-accent-foreground` to specify a different color to use for accent-colored text:

theme.css

```
:root {
  --stl-color-accent: light-dark(#1eb281, #11cc8d);
  /* Use a darker green for text against a light background
   * in order to ensure sufficient contrast */
  --stl-color-accent-foreground: light-dark(#008659, #11cc8d);
}
```

Make sure everything looks correct in both light and dark mode when you change these colors.

You can quickly switch between light and dark mode using the switcher at the top right on your site.

### Background and foreground

The inputs for the base palette consist of a *background color* for the page and a *foreground color* used for text:

```
:root {
  --stl-color-background: light-dark(#ffffff, #0a0a0a);
  --stl-color-foreground: light-dark(#262626, #f5f5f5);
}
```

### Light and dark mode

Specify different colors for light and dark mode using the [`light-dark()` CSS function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark).

```
:root {
  --stl-color-background: light-dark(#ffffff, #0a0a0a);
}
```

Additionally, you can target the `data-theme` attribute on the `:root` element to apply styles conditionally based on the page’s current theme:

```
:root[data-theme="dark"] {
  /* Dark mode specific styles */
}
```

#### Always-dark or always-light sections

You can use the [`color-scheme` CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme) to override the color scheme for a specific section of your page. For example, to keep the page header in dark mode even when the rest of the page is in light mode, you can add the following rule:

```
header {
  color-scheme: dark;
}
```

### Advanced overrides

#### Base palette

The [background and foreground colors](#background-and-foreground) are blended to create a full palette of light/dark shades that are used throughout the site. By default, these shades will adapt to whatever background and foreground colors you’ve configured. For advanced customization, you can override any of the default shades:

Base palette defaults

These variables blend the foreground color using CSS [relative colors](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Colors/Using_relative_colors), abbreviated here as comments for readability.

```
:root {
  /* Text colors */
  --stl-color-foreground-reduced: /* foreground at 80% opacity */;
  --stl-color-foreground-muted: /* foreground at 40% opacity */;
  /* Background shades */
  --stl-color-muted-background: light-dark(/* foreground 8% */, /* foreground 16% */);
  --stl-color-faint-background: light-dark(/* foreground 4% */, /* foreground 8% */);
  --stl-color-ui-background: light-dark(var(--stl-color-background), /* foreground 4% */);
  /* Border colors */
  --stl-color-border: /* foreground at 16% opacity */;
  --stl-color-border-faint: /* foreground at 8% opacity */;
  --stl-color-border-strong: /* foreground at 40% opacity */;
  /* “Inverted” elements like buttons */
  --stl-color-inverse-background: var(--stl-color-foreground);
  --stl-color-inverse-foreground: var(--stl-color-background);
}
```

#### Color palettes

The named color palettes `accent`, `red`, `green`, `blue`, `yellow`, `orange`, `purple`, `cyan`, and `pink` can be overridden with new shades:

```
:root {
  --stl-color-accent: light-dark(#155dfc, #2b7fff);
  --stl-color-red: light-dark(#d01e22, #e34041);
  --stl-color-green: light-dark(#16a34a, #22c55e);
  --stl-color-blue: light-dark(#155dfc, #2b7fff);
  --stl-color-yellow: light-dark(#ca8a04, #eab308);
  --stl-color-orange: light-dark(#ea580c, #f97316);
  --stl-color-purple: light-dark(#9333ea, #a855f7);
  --stl-color-cyan: light-dark(#0891b2, #06b6d4);
  --stl-color-pink: light-dark(#ec4899, #ec4899);
}
```

Each of these palettes—as with [accent](#accent-color) above—has additional variables to ensure legible text contrast. For example, when overriding `--stl-color-red`, you can configure foreground and background colors as needed:

```
:root {
  --stl-color-red: light-dark(#d01e22, #e34041);


  /* Text color should be legible against a plain --stl-color-background */
  --stl-color-red-foreground: var(--stl-color-red);


  /* red background behind text (e.g. buttons) */
  /* red-inverse-foreground text should be legible against a red-inverse-background */
  --stl-color-red-inverse-background: var(--stl-color-red);
  --stl-color-red-inverse-foreground: rgb(255 255 255);
}
```

## Typography

Your site uses the following CSS variables for fonts and typography which you can override with your own values:

custom-styles.css

```
:root {
  --stl-typography-font: 'Geist', system-ui, sans-serif;
  --stl-typography-font-heading: 'Geist', system-ui, sans-serif;
  --stl-typography-font-mono: 'Geist Mono', ui-monospace, monospace;
  --stl-typography-line-height: 1.5;
  --stl-typography-line-height-heading: 1.2;


  --stl-typography-text-body: var(--stl-typography-scale-base);
  --stl-typography-text-body-sm: var(--stl-typography-scale-sm);
  --stl-typography-text-body-xs: var(--stl-typography-scale-xs);


  --stl-typography-text-code: var(--stl-typography-scale-sm);
  --stl-typography-text-code-sm: var(--stl-typography-scale-xs);


  --stl-typography-text-h1: var(--stl-typography-scale-5xl);
  --stl-typography-text-h2: var(--stl-typography-scale-4xl);
  --stl-typography-text-h3: var(--stl-typography-scale-3xl);
  --stl-typography-text-h4: var(--stl-typography-scale-2xl);
  --stl-typography-text-h5: var(--stl-typography-scale-xl);


  --stl-typography-scale-xs: 12px;
  --stl-typography-scale-sm: 14px;
  --stl-typography-scale-base: 16px;
  --stl-typography-scale-lg: 18px;
  --stl-typography-scale-xl: 20px;
  --stl-typography-scale-2xl: 24px;
  --stl-typography-scale-3xl: 29px;
  --stl-typography-scale-4xl: 35px;
  --stl-typography-scale-5xl: 42px;
  --stl-typography-scale-6xl: 64px;
}
```

### Custom fonts

By default, Stainless Docs uses the [Geist](https://vercel.com/font/) font family. To use your own fonts, you can use the `fonts` configuration option. Our fonts API is an extension of Astro’s [experimental font API](https://docs.astro.build/en/reference/experimental-flags/fonts/) with some framework specific additions.

astro.config.ts

```
...
import { defineConfig, fontProviders } from 'astro/config';
import { stainlessDocs } from "@stainless-api/docs";
...


export default defineConfig({
  ...
  integrations: [
    stainlessDocs({
      ...
      fonts: {
        // The default font family
        primary: {
          provider: fontProviders.google(),
          name: 'Roboto',
          display: 'swap',
          preload: [{ style: 'normal' }],
        },
        // The font family for headings. Defaults to the primary font if not specified
        heading: {
          provider: fontProviders.google(),
          name: 'Inter',
          display: 'swap',
        },
        // The font family for monospaced text
        mono: {
          provider: fontProviders.fontsource(),
          name: "JetBrains Mono",
        },
        // Any additional fonts you want to load
        additional: [
          {
            cssVariable: '--custom-font',
            provider: fontProviders.google(),
            name: 'BBH Bartle',
            display: 'swap',
          },
        ],
      },
    }),
  ],
  ...
});
```

Specifying fonts in this way will automatically add the necessary [`<Font />`](https://docs.astro.build/en/reference/experimental-flags/fonts/#font--component-reference) components to your site’s head. You can provide a [`preload`](https://docs.astro.build/en/reference/experimental-flags/fonts/#preload) array to specify which font styles should be preloaded.

The `cssVariable` field in the `additional` fonts section allows you to specify a custom CSS variable name that you can use in your stylesheets to reference the font. By default, the primary, heading, and mono fonts are assigned to the following CSS variables:

- `--stl-typography-font` for the primary font
- `--stl-typography-font-heading` for the heading font
- `--stl-typography-font-mono` for the monospaced font

## Add custom CSS

Refer to [Starlight’s documentation for adding custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) to your site.