Theming Overview & Architecture

RapiDoc features a streamlined, token-driven theming architecture inspired by modern design systems. Built as a standard W3C Web Component, its markup and stylesheets reside inside an encapsulated Shadow DOM, ensuring that external application styles never clash with your API documentation.

Why Shadow DOM Encapsulation Matters

In modern web applications, global CSS rules (such as CSS resets, utility frameworks like Tailwind, or UI library stylesheets) frequently collide with embedded API documentation. With Shadow DOM: - External CSS rules cannot accidentally alter RapiDoc’s internal elements. - Internal RapiDoc styles will never leak out into your host application.

Upgrading from RapiDoc v10?

RapiDoc v11 deprecated legacy styling attributes such as bg-color, text-color, header-color, primary-color, regular-font, and nav-* in favor of standard CSS custom properties and ::part() selectors. Refer to our v10 to v11 Migration Guide for full mapping tables and migration examples.

---

1. Streamlined Declarative Attributes

RapiDoc consolidates visual customization into four primary attributes:

<rapi-doc
  spec-url="https://api.example.com/openapi.json"
  theme="emerald"
  color-scheme="dark"
  radius="md"
  scale="default"
  nav-item-spacing="default"
></rapi-doc>

Core Attribute Reference

Attribute	Allowed Values	Default	Description
theme	amber, blue, graphite, modern, emerald, violet, rose, slate, default, or any #hex code	"amber"	Color palette preset matching shadcn/ui color tokens, or a custom brand color hex code.
color-scheme	dark, light, system	"dark"	Base surface mode. "system" automatically tracks the user’s OS prefers-color-scheme preference.
radius	none, sm, md, lg, full	"sm"	Corner radius scale applied across cards, buttons, badges, inputs, and modal dialogs.
scale	sm, default, lg	"default"	Proportional scale factor for UI base dimensions, body typography, code blocks, and sidebar width.
nav-item-spacing	compact, default, relaxed	"default"	Vertical density and padding of sidebar navigation links, decoupled from font size scaling.
load-fonts	true, false	"true"	When set to "false", prevents automatic loading of Open Sans from Google Fonts (for air-gapped or offline networks).

---

2. Custom Brand Hex Colors & Contrast Engine

You can supply your corporate brand color directly into the theme attribute without writing external CSS:

<rapi-doc spec-url="https://api.example.com/openapi.json" theme="#2563eb" color-scheme="dark" radius="md"></rapi-doc>

How the Contrast Engine Works

When a hex color is supplied:

1. Primary Token: Sets --primary to your exact hex color.
2. Focus Ring: Sets --ring to match the brand color.
3. Contrast Foregrounds: Evaluates the perceived luminance (YIQ color space) of your brand color. If your brand color is light, RapiDoc dynamically sets --primary-foreground: #000000; if dark, it sets --primary-foreground: #ffffff. This guarantees accessible, high-contrast button and badge labels automatically.

---

3. UI Geometry: Radius & Scale

Corner Radius (radius)

The radius attribute controls roundness across the entire documentation interface:

• radius="none": Sharp 0px corners for brutalist or dense terminal-style layouts.
• radius="sm" (default): Subtle 4px (0.25rem) radius for clean, modern interfaces.
• radius="md": Balanced 6px (0.375rem) radius matching contemporary web apps.
• radius="lg": Pronounced 8px (0.5rem) radius for playful, consumer-facing portals.
• radius="full": Pill-shaped buttons and inputs (9999px) with rounded 8px cards.

Scaling Factor (scale)

The scale attribute controls typography, base sizing, and proportional margins:

• scale="sm": Compact scale (13px base font, 17rem sidebar width). Ideal for embedded documentation cards or split-screen consoles.
• scale="default" (default): Standard desktop scale (14px base font, 18.75rem sidebar width). Optimal for full-page documentation portals.
• scale="lg": Generous scale (16px base font, 21rem sidebar width). Optimal for large monitors, accessibility compliance, and presentations.

Sidebar Item Density (nav-item-spacing)

Adjust sidebar link density without altering the global font size:

• nav-item-spacing="compact": 5px vertical padding for large APIs with hundreds of endpoints.
• nav-item-spacing="default" (default): 7px vertical padding for balanced readability.
• nav-item-spacing="relaxed": 10px vertical padding for touchscreens and clean navigation.

---

4. Typography & Custom Web Fonts

RapiDoc natively supports standard design system typography tokens. You can configure custom fonts by setting CSS variables on <rapi-doc>:

• --font-sans or --font-regular: Primary font family for body text, headings, and navigation links.
• --font-mono: Monospace font family for code blocks, HTTP methods, route paths, and schema models.

HTML & CSS

<head>
  <!-- 1. Load your preferred Google Fonts -->
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
  <link
    href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
    rel="stylesheet"
  />

  <style>
    /* 2. Bind typography tokens directly to <rapi-doc> */
    rapi-doc {
      --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
      --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
    }
  </style>

</head>

<body>
  <rapi-doc
    spec-url="https://petstore.swagger.io/v2/swagger.json"
    theme="emerald"
    color-scheme="dark"
    load-fonts="false"
  ></rapi-doc>
</body>

Tailwind / Framework Global CSS

/* Inherit from parent application font variables */
rapi-doc {
  --font-sans: var(--font-inter, sans-serif);
  --font-mono: var(--font-jetbrains, monospace);
}

---

5. Dynamic Runtime Theme Switching

Because <rapi-doc> is a standard DOM element, you can dynamically switch themes, toggle light/dark modes, or adjust scale at runtime using standard JavaScript:

const doc = document.querySelector('rapi-doc');

// Switch brand preset or custom hex color
function setBrandColor(themeValue) {
  doc.setAttribute('theme', themeValue); // e.g., 'violet' or '#2563eb'
}

// Toggle between dark and light modes
function toggleDarkMode() {
  const current = doc.getAttribute('color-scheme') || 'dark';
  doc.setAttribute('color-scheme', current === 'dark' ? 'light' : 'dark');
}

// Adjust corner radius dynamically
function updateRadius(radiusValue) {
  doc.setAttribute('radius', radiusValue); // 'none', 'sm', 'md', 'lg', 'full'
}

---

Next Steps

CSS Parts (::part)

Pierce the Shadow DOM to customize sidebars, action buttons, and containers with gradients and backdrop filters. Explore CSS Parts Guide

Pre-built Themes & Recipes

Copy-paste production presets for Fintech, Cloud, Web3, and Developer Portals. View Theme Recipes