Skip to main content

Designing a Warmer Documentation Theme

· 3 min read
AI-in-a-Box Team

We wanted the AI-in-a-Box documentation to feel purpose-built rather than like a default Docusaurus theme with a color swap. This post describes the early design pass that gave the docs a warmer dark palette, denser tables, and more readable code blocks.

Choosing the values​

We used browser inspection and side-by-side screenshots to compare headings, body text, code blocks, tables, sidebar links, and the navbar. That let us tune actual rendered values instead of guessing from a screenshot.

The key values we captured:

  • Page background: rgb(14, 12, 13), nearly black with a warm undertone, not pure #000
  • Body text: #a6a1a0 on dark, Inter font, 16px, line-height 1.75
  • Headings: #e6e1e0, DM Sans, varying weights from 600 to 700
  • Primary accent: A warm amber, adapted to #d4a574 to give the docs their own identity while staying readable on dark backgrounds.

The warm dark theme​

The default Docusaurus dark theme uses cool grays and blues. We wanted a warmer neutral range, so the backgrounds have a slight red/brown shift:

[data-theme='dark'] {
  --ifm-background-color: #0e0c0d;
  --ifm-background-surface-color: #131112;
  --ifm-font-color-base: #a6a1a0;
  --ifm-heading-color: #e6e1e0;
  --ifm-navbar-background-color: #0e0c0d;
  --ifm-footer-background-color: #0a0909;
}

The difference between #0e0c0d and Docusaurus's default #1b1b1d is subtle in isolation but obvious side by side. The warm background makes text feel less harsh and reduces eye strain during long reading sessions.

Table styling​

This was the biggest visual improvement. Default Docusaurus tables have alternating row backgrounds, visible borders on all sides, and a distinct header background color. The revised tables use just separator lines:

.markdown table thead tr {
  border-bottom: 1px solid rgba(70, 65, 64, 0.5) !important;
  background: transparent !important;
}

.markdown table tbody tr {
  background: transparent !important;
  border-bottom: 1px solid rgba(45, 40, 38, 0.5) !important;
}

We had to use !important liberally because Docusaurus injects table styles at a high specificity through its theme. Killing the striped row backgrounds (--ifm-table-stripe-background: transparent) and the default border color (--ifm-table-border-color: transparent) handles most of it, but some rules needed the override.

Code blocks​

The code blocks use a 16px border radius and a #1f1f1f background that is slightly lighter than the page background, giving them subtle contrast without a visible border:

.prism-code {
  border-radius: 16px !important;
  border: none !important;
  font-size: 14px;
  line-height: 1.7;
  padding: 14px 16px !important;
}

[data-theme='dark'] .prism-code {
  background-color: #1f1f1f !important;
}

The monospace font is JetBrains Mono, which has better readability at small sizes than most monospace options and includes programming ligatures.

The result​

The total CSS override is about 500 lines. The visual impact is significant: the documentation feels like a purpose-built site rather than a template with swapped colors. Three fonts (Inter for body, DM Sans for headings, JetBrains Mono for code) provide clear hierarchy. The warm palette reduces the clinical feel common in technical documentation.

The result is still Docusaurus underneath, but it reads more like a focused product manual than a generated documentation shell.