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. 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.