WritedocsWritedocs

Colors and backgrounds

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Every site has a light and a dark theme, and a button in the topbar to switch between them - it follows the reader’s system setting until they choose, unless styles.appearance says otherwise. Colors are set in styles, with a separate value for dark mode wherever one makes sense.

{
  "styles": {
    "colors": {
      "primary": "#0f766e",
      "text": "#0f172a",
      "dark": { "primary": "#2dd4bf", "text": "#e2e8f0" }
    },
    "navbar": { "light": "#ffffff", "dark": "#042f2e" },
    "background": {
      "colors": { "light": "#f8fafc", "dark": "#021716" }
    }
  }
}

Any CSS color works: #0f766e, rgb(15 118 110), hsl(175 77% 26%), teal.

styles.colors

primary string default: #6366f1

The brand color: links, the current page in the sidebar, the current tab, buttons, step numbers and other highlights.

text string default: #404045

The color of body text, and of the links in the sidebar and the table of contents.

dark.primary string default: primary

The brand color in dark mode. Without it, dark mode uses primary.

dark.text string default: #a0a0a5

The same, in dark mode. It doesn’t follow text: a text color for a light background rarely works on a dark one.

Headings, bold text, the titles of components like cards and accordions, and the sidebar’s group titles use a stronger color than body text - #18191d in light mode, #e0e0e5 in dark - so they stand out over the text around them.

Set dark.primary whenever your brand color is dark: a deep blue that reads well on white is hard to read on a dark background. writedocs a11y checks the contrast of these colors, in both themes.

styles.background

The page’s background: a color, and optionally an image over it.

{
  "styles": {
    "background": {
      "colors": { "light": "#f8fafc", "dark": "#0f172a" },
      "images": { "light": "/images/background-light.png", "dark": "/images/background-dark.png" }
    }
  }
}
colors.light string default: #ffffff

The background color in light mode.

colors.dark string default: #0b1120

The background color in dark mode.

images.light string

An image behind the page in light mode: a path in your project (/images/background-light.png) or a URL.

images.dark string

The same, for dark mode.

Each one is optional - set only the ones you need.

The background color is also the color of menus, dialogs, the footer, and the topbar unless styles.navbar sets its own. An image covers the whole window and stays in place as the page scrolls. It shows behind the content, the sidebar and the table of contents; the topbar and footer keep the plain background color, so the image never sits behind them.

styles.navbar

The topbar’s own background color, in light and dark mode. Without it, the topbar matches the page’s background.

{
  "styles": {
    "navbar": {
      "light": "#0f766e",
      "dark": "#042f2e"
    }
  }
}
light string | object

The topbar’s color in light mode: a color, or { "background", "accent" }.

dark string | object

The same, for dark mode.

Set only one side to change just that theme. The menu that opens on a phone uses the same color.

On a navbar with its own color, the text and icons on it - the site name, tabs, switchers, links, search box and theme button - are black or white, whichever reads better on that color. There’s nothing to set: even a navbar in your brand color stays readable.

The current tab’s color

The current tab is underlined in styles.colors.primary. On a navbar in your brand color that underline disappears - use the object form to pick another color for it, with accent:

{
  "styles": {
    "navbar": {
      "light": { "background": "#0f766e", "accent": "#fbbf24" },
      "dark": { "background": "#042f2e", "accent": "#fbbf24" }
    }
  }
}
background string required

The topbar’s color.

accent string

The color that marks the current tab. Without it, styles.colors.primary.

styles.appearance

Which theme pages open in, and whether readers can switch. Without it, pages follow the reader’s system setting and the topbar has the button to switch.

{
  "styles": {
    "appearance": { "default": "dark" }
  }
}
default "system" | "light" | "dark" default: system

The theme a page opens in. system follows the reader’s device setting; light and dark open every page in that theme, whatever the device says. A reader who picks a theme with the topbar button keeps their choice on every page and on their next visit.

strict boolean default: false

Removes the button to switch themes, from the topbar and from the menu on phones, so every reader sees default. A choice a reader made before you turned this on no longer counts.

To show only one theme - a dark-only site, say - set both:

{
  "styles": {
    "appearance": { "default": "dark", "strict": true }
  }
}

Things to know:

  • With "strict": true and default left at system, there’s still no button, but each reader gets the theme their device asks for.
  • A light or dark default works for readers with JavaScript turned off, too. With system, they get the light theme.
  • On a site locked to one theme, only that theme’s colors matter: with "default": "dark", "strict": true, set the dark values (colors.dark, background.colors.dark, navbar.dark and so on) and leave out the light ones.
  • The link preview images are drawn in the light theme either way.